@xemahq/kernel-contracts 0.28.0 → 0.30.0

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

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/output-surface-inspect/index.ts

@@ -0,0 +1,4 @@
+// Pure, zod-free contract — safe to bundle into the browser-side bridge.
+export * from './lib/output-surface-inspect';
+// Runtime zod validator — pulled in by agent-session-api's broker only.
+export * from './lib/step-schema';