@xemahq/kernel-contracts 0.29.0 → 0.30.0

package/dist/workspace-image/lib/schemas.d.ts

@@ -0,0 +1,103 @@
+import { z } from 'zod';
+import { ImageLayerKind, VariantStatus } from './enums';
+export declare const imageLayerKindSchema: z.ZodEnum<typeof ImageLayerKind>;
+export declare const variantStatusSchema: z.ZodEnum<typeof VariantStatus>;
+export declare const imageLayerSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    kind: z.ZodLiteral<ImageLayerKind.Apt>;
+    packages: z.ZodArray<z.ZodString>;
+}, z.core.$strip>, z.ZodObject<{
+    kind: z.ZodLiteral<ImageLayerKind.Dnf>;
+    packages: z.ZodArray<z.ZodString>;
+}, z.core.$strip>, z.ZodObject<{
+    kind: z.ZodLiteral<ImageLayerKind.Apk>;
+    packages: z.ZodArray<z.ZodString>;
+}, z.core.$strip>, z.ZodObject<{
+    kind: z.ZodLiteral<ImageLayerKind.Pip>;
+    packages: z.ZodArray<z.ZodString>;
+    pythonVersion: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>, z.ZodObject<{
+    kind: z.ZodLiteral<ImageLayerKind.NpmGlobal>;
+    packages: z.ZodArray<z.ZodString>;
+}, z.core.$strip>, z.ZodObject<{
+    kind: z.ZodLiteral<ImageLayerKind.Env>;
+    vars: z.ZodRecord<z.ZodString, z.ZodString>;
+}, z.core.$strip>, z.ZodObject<{
+    kind: z.ZodLiteral<ImageLayerKind.File>;
+    path: z.ZodString;
+    contentBase64: z.ZodString;
+    mode: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strip>], "kind">;
+export declare const workspaceImageManifestSchema: z.ZodObject<{
+    layers: z.ZodArray<z.ZodDiscriminatedUnion<[z.ZodObject<{
+        kind: z.ZodLiteral<ImageLayerKind.Apt>;
+        packages: z.ZodArray<z.ZodString>;
+    }, z.core.$strip>, z.ZodObject<{
+        kind: z.ZodLiteral<ImageLayerKind.Dnf>;
+        packages: z.ZodArray<z.ZodString>;
+    }, z.core.$strip>, z.ZodObject<{
+        kind: z.ZodLiteral<ImageLayerKind.Apk>;
+        packages: z.ZodArray<z.ZodString>;
+    }, z.core.$strip>, z.ZodObject<{
+        kind: z.ZodLiteral<ImageLayerKind.Pip>;
+        packages: z.ZodArray<z.ZodString>;
+        pythonVersion: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>, z.ZodObject<{
+        kind: z.ZodLiteral<ImageLayerKind.NpmGlobal>;
+        packages: z.ZodArray<z.ZodString>;
+    }, z.core.$strip>, z.ZodObject<{
+        kind: z.ZodLiteral<ImageLayerKind.Env>;
+        vars: z.ZodRecord<z.ZodString, z.ZodString>;
+    }, z.core.$strip>, z.ZodObject<{
+        kind: z.ZodLiteral<ImageLayerKind.File>;
+        path: z.ZodString;
+        contentBase64: z.ZodString;
+        mode: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strip>], "kind">>;
+    workdir: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export declare const workspaceImageVariantSchema: z.ZodObject<{
+    id: z.ZodString;
+    orgId: z.ZodString;
+    slug: z.ZodString;
+    description: z.ZodString;
+    runtimeKind: z.ZodEnum<typeof import("../../worker-runtime").WorkerRuntimeKind>;
+    baseImage: z.ZodString;
+    manifest: z.ZodObject<{
+        layers: z.ZodArray<z.ZodDiscriminatedUnion<[z.ZodObject<{
+            kind: z.ZodLiteral<ImageLayerKind.Apt>;
+            packages: z.ZodArray<z.ZodString>;
+        }, z.core.$strip>, z.ZodObject<{
+            kind: z.ZodLiteral<ImageLayerKind.Dnf>;
+            packages: z.ZodArray<z.ZodString>;
+        }, z.core.$strip>, z.ZodObject<{
+            kind: z.ZodLiteral<ImageLayerKind.Apk>;
+            packages: z.ZodArray<z.ZodString>;
+        }, z.core.$strip>, z.ZodObject<{
+            kind: z.ZodLiteral<ImageLayerKind.Pip>;
+            packages: z.ZodArray<z.ZodString>;
+            pythonVersion: z.ZodOptional<z.ZodString>;
+        }, z.core.$strip>, z.ZodObject<{
+            kind: z.ZodLiteral<ImageLayerKind.NpmGlobal>;
+            packages: z.ZodArray<z.ZodString>;
+        }, z.core.$strip>, z.ZodObject<{
+            kind: z.ZodLiteral<ImageLayerKind.Env>;
+            vars: z.ZodRecord<z.ZodString, z.ZodString>;
+        }, z.core.$strip>, z.ZodObject<{
+            kind: z.ZodLiteral<ImageLayerKind.File>;
+            path: z.ZodString;
+            contentBase64: z.ZodString;
+            mode: z.ZodOptional<z.ZodNumber>;
+        }, z.core.$strip>], "kind">>;
+        workdir: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>;
+    contentHash: z.ZodString;
+    registryRef: z.ZodOptional<z.ZodString>;
+    status: z.ZodEnum<typeof VariantStatus>;
+    isOrgDefault: z.ZodBoolean;
+    autoRebake: z.ZodBoolean;
+    regions: z.ZodArray<z.ZodString>;
+    buildLog: z.ZodOptional<z.ZodString>;
+    builtAt: z.ZodOptional<z.ZodString>;
+    createdAt: z.ZodString;
+}, z.core.$strip>;
+//# sourceMappingURL=schemas.d.ts.map

package/dist/workspace-image/lib/schemas.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"schemas.d.ts","sourceRoot":"","sources":["../../../src/workspace-image/lib/schemas.ts"],"names":[],"mappings":"AAQA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAGxB,OAAO,EAAE,cAAc,EAAE,aAAa,EAAE,MAAM,SAAS,CAAC;AAExD,eAAO,MAAM,oBAAoB,kCAA+B,CAAC;AACjE,eAAO,MAAM,mBAAmB,iCAA8B,CAAC;AAI/D,eAAO,MAAM,gBAAgB;;;;;;;;;;;;;;;;;;;;;;;;2BAoB3B,CAAC;AAEH,eAAO,MAAM,4BAA4B;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAGvC,CAAC;AAEH,eAAO,MAAM,2BAA2B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAiBtC,CAAC"}

package/dist/workspace-image/lib/schemas.js

@@ -0,0 +1,53 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.workspaceImageVariantSchema = exports.workspaceImageManifestSchema = exports.imageLayerSchema = exports.variantStatusSchema = exports.imageLayerKindSchema = void 0;
+const zod_1 = require("zod");
+const worker_runtime_1 = require("../../worker-runtime");
+const enums_1 = require("./enums");
+exports.imageLayerKindSchema = zod_1.z.nativeEnum(enums_1.ImageLayerKind);
+exports.variantStatusSchema = zod_1.z.nativeEnum(enums_1.VariantStatus);
+const packagesArray = zod_1.z.array(zod_1.z.string().min(1));
+exports.imageLayerSchema = zod_1.z.discriminatedUnion('kind', [
+    zod_1.z.object({ kind: zod_1.z.literal(enums_1.ImageLayerKind.Apt), packages: packagesArray }),
+    zod_1.z.object({ kind: zod_1.z.literal(enums_1.ImageLayerKind.Dnf), packages: packagesArray }),
+    zod_1.z.object({ kind: zod_1.z.literal(enums_1.ImageLayerKind.Apk), packages: packagesArray }),
+    zod_1.z.object({
+        kind: zod_1.z.literal(enums_1.ImageLayerKind.Pip),
+        packages: packagesArray,
+        pythonVersion: zod_1.z.string().min(1).optional(),
+    }),
+    zod_1.z.object({ kind: zod_1.z.literal(enums_1.ImageLayerKind.NpmGlobal), packages: packagesArray }),
+    zod_1.z.object({
+        kind: zod_1.z.literal(enums_1.ImageLayerKind.Env),
+        vars: zod_1.z.record(zod_1.z.string().min(1), zod_1.z.string()),
+    }),
+    zod_1.z.object({
+        kind: zod_1.z.literal(enums_1.ImageLayerKind.File),
+        path: zod_1.z.string().min(1),
+        contentBase64: zod_1.z.string().min(1),
+        mode: zod_1.z.number().int().nonnegative().optional(),
+    }),
+]);
+exports.workspaceImageManifestSchema = zod_1.z.object({
+    layers: zod_1.z.array(exports.imageLayerSchema),
+    workdir: zod_1.z.string().min(1).optional(),
+});
+exports.workspaceImageVariantSchema = zod_1.z.object({
+    id: zod_1.z.string().min(1),
+    orgId: zod_1.z.string().min(1),
+    slug: zod_1.z.string().min(1),
+    description: zod_1.z.string(),
+    runtimeKind: worker_runtime_1.workerRuntimeKindSchema,
+    baseImage: zod_1.z.string().min(1),
+    manifest: exports.workspaceImageManifestSchema,
+    contentHash: zod_1.z.string().min(1),
+    registryRef: zod_1.z.string().min(1).optional(),
+    status: exports.variantStatusSchema,
+    isOrgDefault: zod_1.z.boolean(),
+    autoRebake: zod_1.z.boolean(),
+    regions: zod_1.z.array(zod_1.z.string().min(1)),
+    buildLog: zod_1.z.string().optional(),
+    builtAt: zod_1.z.string().min(1).optional(),
+    createdAt: zod_1.z.string().min(1),
+});
+//# sourceMappingURL=schemas.js.map

package/dist/workspace-image/lib/schemas.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"schemas.js","sourceRoot":"","sources":["../../../src/workspace-image/lib/schemas.ts"],"names":[],"mappings":"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"}

package/dist/workspace-image/lib/types.d.ts

@@ -0,0 +1,50 @@
+import type { WorkerRuntimeKind } from '../../worker-runtime';
+import type { ImageLayerKind, VariantStatus } from './enums';
+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;
+};
+export interface WorkspaceImageManifest {
+    readonly layers: readonly ImageLayer[];
+    readonly workdir?: string;
+}
+export interface WorkspaceImageVariant {
+    readonly id: string;
+    readonly orgId: string;
+    readonly slug: string;
+    readonly description: string;
+    readonly runtimeKind: WorkerRuntimeKind;
+    readonly baseImage: string;
+    readonly manifest: WorkspaceImageManifest;
+    readonly contentHash: string;
+    readonly registryRef?: string;
+    readonly status: VariantStatus;
+    readonly isOrgDefault: boolean;
+    readonly autoRebake: boolean;
+    readonly regions: readonly string[];
+    readonly buildLog?: string;
+    readonly builtAt?: string;
+    readonly createdAt: string;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/workspace-image/lib/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/workspace-image/lib/types.ts"],"names":[],"mappings":"AAQA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,sBAAsB,CAAC;AAE9D,OAAO,KAAK,EAAE,cAAc,EAAE,aAAa,EAAE,MAAM,SAAS,CAAC;AAU7D,MAAM,MAAM,UAAU,GAClB;IAAE,QAAQ,CAAC,IAAI,EAAE,cAAc,CAAC,GAAG,CAAC;IAAC,QAAQ,CAAC,QAAQ,EAAE,SAAS,MAAM,EAAE,CAAA;CAAE,GAC3E;IAAE,QAAQ,CAAC,IAAI,EAAE,cAAc,CAAC,GAAG,CAAC;IAAC,QAAQ,CAAC,QAAQ,EAAE,SAAS,MAAM,EAAE,CAAA;CAAE,GAC3E;IAAE,QAAQ,CAAC,IAAI,EAAE,cAAc,CAAC,GAAG,CAAC;IAAC,QAAQ,CAAC,QAAQ,EAAE,SAAS,MAAM,EAAE,CAAA;CAAE,GAC3E;IACE,QAAQ,CAAC,IAAI,EAAE,cAAc,CAAC,GAAG,CAAC;IAClC,QAAQ,CAAC,QAAQ,EAAE,SAAS,MAAM,EAAE,CAAC;IACrC,QAAQ,CAAC,aAAa,CAAC,EAAE,MAAM,CAAC;CACjC,GACD;IAAE,QAAQ,CAAC,IAAI,EAAE,cAAc,CAAC,SAAS,CAAC;IAAC,QAAQ,CAAC,QAAQ,EAAE,SAAS,MAAM,EAAE,CAAA;CAAE,GACjF;IAAE,QAAQ,CAAC,IAAI,EAAE,cAAc,CAAC,GAAG,CAAC;IAAC,QAAQ,CAAC,IAAI,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAA;CAAE,GACtF;IACE,QAAQ,CAAC,IAAI,EAAE,cAAc,CAAC,IAAI,CAAC;IACnC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAC/B,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;CACxB,CAAC;AAUN,MAAM,WAAW,sBAAsB;IACrC,QAAQ,CAAC,MAAM,EAAE,SAAS,UAAU,EAAE,CAAC;IACvC,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;CAC3B;AAMD,MAAM,WAAW,qBAAqB;IACpC,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,WAAW,EAAE,iBAAiB,CAAC;IAExC,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,QAAQ,EAAE,sBAAsB,CAAC;IAE1C,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAE7B,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,MAAM,EAAE,aAAa,CAAC;IAC/B,QAAQ,CAAC,YAAY,EAAE,OAAO,CAAC;IAC/B,QAAQ,CAAC,UAAU,EAAE,OAAO,CAAC;IAE7B,QAAQ,CAAC,OAAO,EAAE,SAAS,MAAM,EAAE,CAAC;IAEpC,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAE3B,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;CAC5B"}

package/dist/workspace-image/lib/types.js

@@ -0,0 +1,3 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=types.js.map

package/dist/workspace-image/lib/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../../src/workspace-image/lib/types.ts"],"names":[],"mappings":""}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xemahq/kernel-contracts",
-  "version": "0.29.0",
+  "version": "0.30.0",
   "description": "Consolidated Xema OS kernel wire contracts — pure types + zod schemas for the kernel protocol surfaces. One package, one npm scope, wildcard per-surface subpath exports. No framework/runtime deps.",
   "license": "Apache-2.0",
   "author": "Neuralchowder Inc. <developer@xema.dev> (https://xema.dev)",

package/src/document-patch/index.ts

@@ -0,0 +1,25 @@
+// ═══════════════════════════════════════════════════════════════════════════
+// @xemahq/document-patch-contracts — Kernel layer
+//
+// Wire contracts for the per-hunk edits to a knowledge-base document page.
+//
+// Pending patches are NOT authored by the agent. They are platform-derived:
+// `document-sync` diffs the agent's working file against the accepted base
+// and re-derives the page's `PendingPatch` rows as contiguous line-range
+// hunks. Used by:
+//   - knowledge-base-api's pending-patches endpoints (DTO shapes)
+//   - the frontend hunk-decoration UI (type-only)
+//
+// Per-hunk accept/reject is the central UX primitive: the user can take any
+// subset of the agent's changes. To make that safe against concurrent user
+// edits, every hunk carries the base version it was computed against and a
+// line-range `anchor` describing WHERE it applies. The accept endpoint
+// refuses the apply if the surrounding text shifted out from under the
+// anchor (`PendingPatchStatus.STALE`), so silent drift is impossible.
+//
+// Pure types + Zod. Zero runtime adapter knowledge.
+// ═══════════════════════════════════════════════════════════════════════════
+
+export * from './lib/patch-enums';
+export * from './lib/patch-anchor';
+export * from './lib/pending-patch';

package/src/document-patch/lib/patch-anchor.ts

@@ -0,0 +1,22 @@
+import { z } from 'zod';
+
+/**
+ * Where a pending patch applies in the document: a 1-based inclusive
+ * line range in BASE. Pending patches are platform-derived by diffing
+ * the agent's working file against the accepted base — every hunk is a
+ * contiguous line range, so this is the only anchor shape.
+ *
+ * `endLine === startLine - 1` is the canonical encoding for a
+ * pure-insertion-before-line patch (zero-length range positioned just
+ * before `startLine`).
+ */
+export const LineRangeAnchorSchema = z
+  .object({
+    startLine: z.number().int().min(1),
+    endLine: z.number().int().min(0),
+  })
+  .refine((v) => v.endLine >= v.startLine - 1, {
+    message: 'LineRangeAnchor requires endLine >= startLine - 1',
+    path: ['endLine'],
+  });
+export type LineRangeAnchor = z.infer<typeof LineRangeAnchorSchema>;

package/src/document-patch/lib/patch-enums.ts

@@ -0,0 +1,36 @@
+/**
+ * Closed enums for the patch protocol. Real TS enums (not string-literal
+ * unions) so OpenAPI/Orval emit stable enum schemas — see
+ * `docs/API_STANDARDS.md` and.
+ */
+
+/**
+ * Where this pending patch came from.
+ *
+ *   - AGENT_SESSION   — derived from an interactive Document Buddy
+ *                       session's working-file edits (document-sync).
+ *   - WORKFLOW_REVIEW — a workflow activity proposing edits on the user's
+ *                       behalf.
+ */
+export enum PatchOrigin {
+  AGENT_SESSION = 'AGENT_SESSION',
+  WORKFLOW_REVIEW = 'WORKFLOW_REVIEW',
+}
+
+/**
+ * Lifecycle status for a single PendingPatch row.
+ *
+ *   - PENDING  — awaiting a user decision.
+ *   - ACCEPTED — applied to the page (terminal).
+ *   - REJECTED — discarded by the user (terminal).
+ *   - STALE    — the document moved out from under the patch's anchor
+ *                before a decision was made; the user must re-propose or
+ *                discard. Set fail-fast by the accept endpoint when the
+ *                anchor no longer matches current content.
+ */
+export enum PendingPatchStatus {
+  PENDING = 'PENDING',
+  ACCEPTED = 'ACCEPTED',
+  REJECTED = 'REJECTED',
+  STALE = 'STALE',
+}

package/src/document-patch/lib/pending-patch.ts

@@ -0,0 +1,31 @@
+import { PatchOrigin, PendingPatchStatus } from './patch-enums';
+
+import type { LineRangeAnchor } from './patch-anchor';
+
+/**
+ * Wire shape of a single PendingPatch row as returned by the
+ * knowledge-base-api list/get endpoints and broadcast over the KB
+ * realtime SSE stream. Pure type — no runtime validation needed because
+ * the producer is trusted server code.
+ */
+export interface PendingPatchDto {
+  readonly id: string;
+  readonly pageId: string;
+  readonly proposalId: string;
+  readonly sequence: number;
+  readonly origin: PatchOrigin;
+  readonly sessionId: string | null;
+  readonly workflowJobRunId: string | null;
+  readonly baseVersion: number;
+  readonly anchor: LineRangeAnchor;
+  readonly before: string;
+  readonly after: string;
+  readonly label: string | null;
+  readonly rationale: string | null;
+  readonly status: PendingPatchStatus;
+  readonly decidedBy: string | null;
+  /** ISO-8601 timestamp; null until terminal. */
+  readonly decidedAt: string | null;
+  /** ISO-8601 timestamp. */
+  readonly createdAt: string;
+}

package/src/output/index.ts

@@ -0,0 +1,20 @@
+// ═══════════════════════════════════════════════════════════════════════════
+// @xemahq/output-contracts — Layer 1 / Kernel
+//
+// Wire shapes for the run-detail Outputs panel and the per-kind renderer
+// registry. The legacy
+// JSON-dumping ArtifactContentViewer / OutputPreview pair are replaced by
+// a CLOSED-enum renderer registry. ESLint enforces that every OutputKind
+// value has a registered renderer (xema-fe/output-renderer-coverage).
+//
+// The user reviews deliverables on the canvas — they NEVER see raw JSON
+// unless they click "Show raw". Adding a new output kind is a deliberate
+// extension: enum value → contract type → renderer. No heuristic fallback.
+// ═══════════════════════════════════════════════════════════════════════════
+
+export * from './lib/output-kind';
+export * from './lib/output-render-hint';
+export * from './lib/output-deliverable-expectation';
+export * from './lib/output-version-dto';
+export * from './lib/output-item-dto';
+export * from './lib/payload-schemas';

package/src/output/lib/output-deliverable-expectation.ts

@@ -0,0 +1,25 @@
+import { OutputKind } from './output-kind';
+
+/**
+ * What the workflow EXPECTED to produce at this slot, derived from the
+ * deliverable spec. Compared against {@link OutputItemDto} to detect
+ * missing or unexpected outputs in the Overview "Latest deliverables"
+ * strip.
+ *
+ * The engine emits one expectation per declared deliverable slot at
+ * dispatch time. A run with `produced.length < expectations.length`
+ * is incomplete; the FE renders missing slots as placeholder cards
+ * with the expectation summary.
+ */
+export interface OutputDeliverableExpectation {
+  readonly slug: string;
+  readonly displayName: string;
+  readonly expectedKind: OutputKind;
+  /** Phase that's responsible for producing this slot. */
+  readonly stageKey: string;
+  /**
+   * Whether this deliverable is required for the run to succeed. When
+   * `false`, the FE renders a missing slot in muted styling.
+   */
+  readonly required: boolean;
+}

package/src/output/lib/output-item-dto.ts

@@ -0,0 +1,54 @@
+import { OutputKind } from './output-kind';
+import { OutputRenderHint } from './output-render-hint';
+import { OutputVersionDto } from './output-version-dto';
+
+/**
+ * One card in the run-detail Outputs panel.
+ *
+ * The CARD is the deliverable while reviewing: the user reads the
+ * rendered content
+ * directly, not a JSON dump. `contentRef` points at the lazy-loaded
+ * payload the kind-specific renderer fetches; `summary` is the
+ * always-loaded one-line preview shown collapsed.
+ *
+ * `kbPublishedAt` is set when the artifact-store has linked this
+ * output to a `KB_PAGE` link refType. The FE renders an "Open in
+ * Knowledge Base" affordance when present.
+ */
+export interface OutputItemDto {
+  readonly id: string;
+  readonly kind: OutputKind;
+  readonly title: string;
+  /** One-line collapsed-state preview. Always rendered; never JSON. */
+  readonly summary: string;
+  /** Phase that produced this output. */
+  readonly stageKey: string;
+  readonly renderHint: OutputRenderHint;
+  /** Versions in descending order; first row is current. */
+  readonly versions: readonly OutputVersionDto[];
+  /** Lazy-load handle the renderer dereferences. Format is renderer-specific. */
+  readonly contentRef: OutputContentRef;
+  /** ISO-8601 when the latest version was emitted. */
+  readonly latestEmittedAt: string;
+  /** ISO-8601 when published to the KB; `null` when not yet (or never to be) published. */
+  readonly kbPublishedAt: string | null;
+  /** Direct deep-link to the KB page; `null` when not yet published. */
+  readonly kbPageUrl: string | null;
+}
+
+/**
+ * A renderer-agnostic handle the FE dereferences when the user expands
+ * a card. Renderers narrow on `kind` to know which flavor of resolver
+ * to invoke — there are exactly two flavors:
+ *
+ * - INLINE — the payload is small enough to ship in the list response
+ *   and is already inlined (`payload`). Renderer reads directly.
+ * - REMOTE — the payload requires a separate fetch (`url`). Renderer
+ *   queries `useOutputContent({ url })`.
+ *
+ * Producers MUST pick one. Renderers MUST handle both (the registry
+ * provides this glue once per kind, not per renderer).
+ */
+export type OutputContentRef =
+  | { readonly kind: 'inline'; readonly payload: unknown }
+  | { readonly kind: 'remote'; readonly url: string; readonly contentType: string };

package/src/output/lib/output-kind.ts

@@ -0,0 +1,44 @@
+/**
+ * The CLOSED set of output renderer kinds. Adding a new kind:
+ *
+ *   1. Extend this enum.
+ *   2. Register a renderer component in the FE renderer-registry.
+ *   3. CI fails until both are done (xema-fe/output-renderer-coverage
+ *      lints the registry against this enum).
+ *
+ * No "unknown" fallback that silently dumps JSON — `UNKNOWN` is rendered
+ * by an explicit "we don't have a renderer for this yet" component
+ * with a "Show raw" toggle. Producers must NEVER emit `UNKNOWN` for a
+ * kind that has a real renderer; the engine refuses to materialize an
+ * output with `UNKNOWN` if the producer can derive a real kind from
+ * the deliverable spec.
+ */
+export enum OutputKind {
+  /** Markdown document — renders with TOC, code blocks, diagrams. */
+  MARKDOWN_DOC = 'markdown_doc',
+  /** Code diff — renders with side-by-side or unified view. */
+  CODE_DIFF = 'code_diff',
+  /** Architectural Decision Record — renders with status + decision context. */
+  DECISION_RECORD = 'decision_record',
+  /** Findings list from a reviewer agent — renders as severity-grouped table. */
+  REVIEW_FINDINGS = 'review_findings',
+  /** JSON Schema — renders as type tree with examples. */
+  SCHEMA = 'schema',
+  /** Manifest (workflow YAML, biome manifest, etc.) — renders as structured form. */
+  MANIFEST = 'manifest',
+  /** Test report — renders pass/fail summary + failing-case detail. */
+  TEST_REPORT = 'test_report',
+  /** Diagram (mermaid, drawio, etc.) — renders as SVG. */
+  DIAGRAM = 'diagram',
+  /**
+   * Generic structured JSON payload — used when the value IS the JSON
+   * envelope itself (e.g. `xema/http` / `xema/endpoint-fetch` results,
+   * or any producer emitting a free-form structured object that
+   * doesn't map onto a more specific kind). Rendered as a JSON tree.
+   */
+  JSON_PAYLOAD = 'json_payload',
+  /** External blob (image, binary, etc.) — renders as preview + download. */
+  EXTERNAL_BLOB = 'external_blob',
+  /** Fallback for outputs without a typed renderer. Renders "no renderer" notice. */
+  UNKNOWN = 'unknown',
+}

package/src/output/lib/output-render-hint.ts

@@ -0,0 +1,28 @@
+/**
+ * Per-kind rendering hint the engine attaches to an output. Optional —
+ * the renderer has sensible defaults — but lets producers steer
+ * presentation without freeform CSS.
+ *
+ * Closed enum so the renderer registry knows the full hint surface.
+ */
+export enum OutputRenderDensity {
+  COMPACT = 'compact',
+  COMFORTABLE = 'comfortable',
+  FULL = 'full',
+}
+
+export interface OutputRenderHint {
+  readonly density: OutputRenderDensity;
+  /**
+   * When true, the renderer expands inline by default (no click).
+   * When false, the renderer shows a one-line summary card and
+   * expands on click.
+   */
+  readonly expandByDefault: boolean;
+  /**
+   * Optional preferred starting tab when the renderer has multiple
+   * tabs (e.g. code-diff: "unified" vs "split"). The renderer
+   * validates this against its known tab set.
+   */
+  readonly preferredTab: string | null;
+}

package/src/output/lib/output-version-dto.ts

@@ -0,0 +1,21 @@
+/**
+ * One row in the version history of an output. The Outputs panel
+ * renders a dropdown when `versions.length > 1`; clicking a non-current
+ * version navigates to the inline VersionCompare view (NOT a drawer).
+ *
+ *: per-version metadata lives
+ * on `ArtifactVersion`. The engine populates this DTO from there.
+ * Consumers MUST NOT trust `OutputItemDto.title` for historical
+ * versions — read this row's `title` field instead.
+ */
+export interface OutputVersionDto {
+  readonly id: string;
+  readonly version: number;
+  readonly title: string;
+  readonly hash: string;
+  readonly createdAt: string;
+  /** Slug of the agent that produced this version. `null` for non-agent producers. */
+  readonly producerAgentSlug: string | null;
+  /** True when this row is the latest version. Exactly one row has this set. */
+  readonly isCurrent: boolean;
+}

package/src/output/lib/payload-schemas/code-diff.ts

@@ -0,0 +1,20 @@
+import { z } from 'zod';
+
+/**
+ * Payload shape for `OutputKind.CODE_DIFF` artifacts — unified-diff
+ * text produced by SCM-integration adapters and code-reviewing agents.
+ *
+ * The convention is a single `body` string carrying the diff in standard
+ * unified-diff format. The FE renders it through Monaco's diff-aware
+ * tokenizer (`language: 'diff'`) so additions/removals get syntax
+ * highlighting.
+ */
+export const CodeDiffPayloadSchema = z
+  .object({
+    body: z.string().min(1, 'code_diff.body must be non-empty'),
+    /** Optional: human-readable label for the change (e.g. "Refactor auth flow"). */
+    title: z.string().optional(),
+  })
+  .passthrough();
+
+export type CodeDiffPayload = z.infer<typeof CodeDiffPayloadSchema>;

package/src/output/lib/payload-schemas/decision-record.ts

@@ -0,0 +1,71 @@
+import { z } from 'zod';
+
+/**
+ * Architectural Decision Record (ADR) status — RFC-style lifecycle.
+ *
+ * Closed enum so the FE can render distinctive pills per state
+ * (`accepted` green, `superseded` strikethrough, etc.). Producers
+ * MUST pick one; freeform strings are rejected so we don't grow a
+ * long tail of bespoke statuses.
+ */
+export enum DecisionRecordStatus {
+  PROPOSED = 'proposed',
+  ACCEPTED = 'accepted',
+  REJECTED = 'rejected',
+  DEPRECATED = 'deprecated',
+  SUPERSEDED = 'superseded',
+}
+
+export const DecisionRecordStatusSchema = z.nativeEnum(DecisionRecordStatus);
+
+/**
+ * Payload shape for `OutputKind.DECISION_RECORD` artifacts.
+ *
+ * Follows the Michael Nygard ADR template — title, status, context,
+ * decision, consequences. Each field is markdown so the FE renderer
+ * can present them as separate sections with appropriate framing
+ * (status pill, headings, etc.).
+ *
+ * Backward-compat: producers that pre-date this schema emit a single
+ * `body` markdown string (legacy convention shared across all
+ * markdown-bearing kinds via `textViewOfPayload`). The schema
+ * tolerates that by making every structured field optional and
+ * requiring at-least-one-of via `superRefine`. New producers should
+ * emit the structured fields so the renderer's rich form lights up.
+ */
+export const DecisionRecordPayloadSchema = z
+  .object({
+    title: z.string().optional(),
+    status: DecisionRecordStatusSchema.optional(),
+    context: z.string().optional(),
+    decision: z.string().optional(),
+    consequences: z.string().optional(),
+    /**
+     * Legacy / fallback: a single markdown document holding the whole
+     * ADR. New producers SHOULD prefer the structured fields; this
+     * stays for backward-compatibility and for cases where the ADR
+     * doesn't map cleanly onto the four-section template.
+     */
+    body: z.string().optional(),
+  })
+  .passthrough()
+  .superRefine((value, ctx) => {
+    const structuredFields = [
+      value.context,
+      value.decision,
+      value.consequences,
+    ];
+    const hasStructured = structuredFields.some(
+      (v) => typeof v === 'string' && v.trim().length > 0,
+    );
+    const hasBody = typeof value.body === 'string' && value.body.trim().length > 0;
+    if (!hasStructured && !hasBody) {
+      ctx.addIssue({
+        code: 'custom',
+        message:
+          'decision_record payload must include at least one of `body` or the structured fields (`context`, `decision`, `consequences`).',
+      });
+    }
+  });
+
+export type DecisionRecordPayload = z.infer<typeof DecisionRecordPayloadSchema>;