@xemahq/kernel-contracts 0.29.0 → 0.31.0

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>;

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>;