@xemahq/kernel-contracts 0.29.0 → 0.31.0

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/question/index.ts

@@ -0,0 +1,24 @@
+// ═══════════════════════════════════════════════════════════════════════════
+// @xemahq/question-contracts — Layer 1 / Kernel
+//
+// User-facing wire shapes for the unified "Question" surface. The platform
+// internally has three overlapping primitives (decision_gate inquiries,
+// agent_tool_inquiry inquiries, human-recipient review jobs); the FE
+// collapses them into ONE concept the user sees: a "Question".
+//
+// Per the "one concept" model: never say
+// "approval", "review", "decision gate", "inquiry", or "task" in the UI.
+// Internal terms stay in code, schemas, logs, telemetry. The reply form
+// renders by `kind`, not by which backend primitive backs the row.
+//
+// Endpoints powered by this package:
+//   GET  /questions          → QuestionDto[] (paginated envelope)
+//   GET  /questions/badge    → { count: number }
+//   GET  /questions/:id      → QuestionDto (single envelope)
+//   POST /questions/:id/reply (body shape lives in user-hub-api DTOs)
+// ═══════════════════════════════════════════════════════════════════════════
+
+export * from './lib/question-enums';
+export * from './lib/question-dto';
+export * from './lib/question-action-context';
+export * from './lib/question-escalation';

package/src/question/lib/question-action-context.ts

@@ -0,0 +1,26 @@
+/**
+ * Every QuestionDto carries a stable
+ * "action context" that the FE's reply form, the bell dropdown's
+ * deep-links, and the email channel adapter all read.
+ *
+ * The contract: `runId` + `taskAnchor` are ALWAYS present. Without them
+ * the bell can't deep-link to the run+Work mode and the email link
+ * can't restore context — so the engine refuses to materialize a
+ * question without both fields. Fail-fast at the boundary, not in the
+ * FE.
+ */
+export interface QuestionActionContext {
+  /** The workflow run this question belongs to. */
+  readonly runId: string;
+  /** The workflow slug — used to construct the deep-link path. */
+  readonly workflowSlug: string;
+  /**
+   * A stable anchor for scrolling to the question's canvas section.
+   * The FE uses this as the URL fragment so refresh restores scroll
+   * position. Format: `q-<inquiryId>` or `q-<inquiryId>-r<recipientId>`
+   * for per-recipient framing.
+   */
+  readonly taskAnchor: string;
+  /** Optional checkpoint key when the question gates a phase boundary. */
+  readonly stageKey: string | null;
+}

package/src/question/lib/question-dto.ts

@@ -0,0 +1,143 @@
+import { QuestionActionContext } from './question-action-context';
+import { QuestionEscalationLevel } from './question-escalation';
+import { QuestionKind, QuestionSeverity, QuestionStatus } from './question-enums';
+
+/**
+ * The wire shape powering the global Questions bell, the run-detail
+ * Work-mode question canvas, and the question-detail standalone route.
+ *
+ * One row per (recipient, inquiry) pair. The same inquiry may produce
+ * N QuestionDto rows when it has N recipients — each recipient sees
+ * THEIR question with their own status. The aggregation policy lives
+ * server-side; the FE renders one row at a time.
+ *
+ * `kind` discriminates which Reply form variant renders. `kindPayload`
+ * carries the kind-specific render hints (choice options, default
+ * approval reason templates, etc). `subjects` carries the artifacts
+ * the question is about so the canvas can render them inline via the
+ * existing OutputCard renderer registry — no separate fetch needed
+ * beyond the run's Outputs list. `extras` is a closed-set bag for
+ * orchestrator-injected hints (review iteration, reviewer findings,
+ * past-iteration history) that the canvas renders conditionally.
+ */
+export interface QuestionDto {
+  readonly id: string;
+  readonly kind: QuestionKind;
+  readonly status: QuestionStatus;
+  readonly severity: QuestionSeverity;
+
+  /** The user-facing question — one sentence, never JSON. */
+  readonly title: string;
+  /** Optional detail line shown under the title. */
+  readonly detail: string | null;
+  /**
+   * Long-form context shown above the subjects in the canvas. Markdown.
+   * Distinct from `detail` (one-liner under the title) — `description`
+   * is the human-readable framing the engine pulled from the inquiry's
+   * prompt (e.g. DECISION_GATE.description, agent_tool_inquiry.context).
+   */
+  readonly description: string | null;
+
+  /**
+   * Engine-side `InquiryRecipient.id` PK for THIS recipient. Required by
+   * the FE reply-submit call; populated from the inquiry CloudEvent's
+   * `recipients[]` projection during materialization. Empty string for
+   * legacy rows that pre-date the wiring.
+   */
+  readonly recipientId: string;
+
+  /**
+   * Artifact references the question is asking about (the documents
+   * being reviewed, the proposed change, etc.). The FE renders each via
+   * the existing OutputCard renderer registry by matching `artifactId`
+   * against the run's Outputs list. Empty for questions without subject
+   * artifacts (e.g. agent_tool_inquiry asking "what should I do next?").
+   */
+  readonly subjects: readonly QuestionSubjectRef[];
+
+  /**
+   * Closed-set bag of orchestrator-injected render hints. Today the FE
+   * recognises:
+   *   - `reviewIteration` (number)
+   *   - `reviewerFindings` (array of {severity, message, location?})
+   *   - `pastIterations`   (array of {iteration, verdict, submittedAtIso})
+   *   - `reviewSubjects`   (array of `ReviewableSubject` entries from
+   *     `narrowReviewableContent` — post-unification this is the
+   *     closed set `{ kind: 'artifact-ref', … } | { kind: 'string',
+   *     value }`. The kernel narrower throws fail-fast on any other
+   *     shape, so consumers can `switch (subject.kind)` exhaustively.
+   *     Distinct from `subjects[]` above, which carries the strict
+   *     approval-time artifact pins consumed by `publish-kb`.)
+   * Unknown keys are ignored. The engine surfaces these from
+   * `prompt.passthrough()` extras authored by orchestrators like
+   * `xema/review@v3`.
+   */
+  readonly extras: Readonly<Record<string, unknown>>;
+
+  readonly action: QuestionActionContext;
+
+  /** Empty array when no escalation has fired. */
+  readonly escalationHistory: readonly QuestionEscalationLevel[];
+
+  /** ISO-8601 when the question became visible to the recipient. */
+  readonly occurredAt: string;
+  /** ISO-8601 deadline; `null` for non-timing-bound questions. */
+  readonly expiresAt: string | null;
+
+  /**
+   * Kind-specific render hints. Variant-typed by `kind`. The FE narrows
+   * via discriminated union before reading.
+   */
+  readonly kindPayload: QuestionKindPayload;
+}
+
+/**
+ * A pinned reference to an artifact this question is about. Mirrors
+ * `PinnedSubjectArtifact` from `@xemahq/decision-gate-contracts` —
+ * carried through verbatim from the inquiry prompt.
+ */
+export interface QuestionSubjectRef {
+  readonly artifactId: string;
+  readonly version: number;
+  /** Engine-resolved kind of the underlying artifact (markdown_doc,
+   * code_diff, decision_record, …). Optional — absent when the inquiry
+   * was created before the engine started pinning the kind. */
+  readonly kind?: string;
+  /** Engine-resolved title at pin time. Optional for the same reason. */
+  readonly title?: string;
+}
+
+/** Discriminated union over `kind`. */
+export type QuestionKindPayload =
+  | { readonly kind: QuestionKind.APPROVAL; readonly approval: ApprovalKindPayload }
+  | { readonly kind: QuestionKind.CHOICE; readonly choice: ChoiceKindPayload }
+  | { readonly kind: QuestionKind.FREEFORM; readonly freeform: FreeformKindPayload };
+
+export interface ApprovalKindPayload {
+  /** Whether the reply form should expose a "Revise with note" CTA. */
+  readonly allowRevise: boolean;
+  /**
+   * Optional reasons the FE pre-populates in the reject dropdown.
+   * Empty array → reason is free-text only.
+   */
+  readonly suggestedRejectReasons: readonly string[];
+}
+
+export interface ChoiceKindPayload {
+  readonly options: readonly QuestionChoiceOptionDto[];
+  /** True if the recipient can pick more than one option. */
+  readonly multiSelect: boolean;
+}
+
+export interface QuestionChoiceOptionDto {
+  readonly value: string;
+  readonly label: string;
+  readonly description: string | null;
+}
+
+export interface FreeformKindPayload {
+  /** Hint text rendered as the textarea placeholder. */
+  readonly placeholder: string | null;
+  /** Optional cap; FE enforces, server re-validates. */
+  readonly maxLength: number | null;
+}

package/src/question/lib/question-enums.ts

@@ -0,0 +1,67 @@
+/**
+ * The three reply-shape families a Question can take. Drives which
+ * Reply form the FE renders below the canvas.
+ *
+ * - `APPROVAL` — Approve / Reject (+ optional reason). Renders the
+ *   3-button row used by checkpoint reviews and decision gates.
+ * - `CHOICE` — pick one of N predefined options. Renders a radio list.
+ * - `FREEFORM` — open-ended textarea. Renders a single textarea +
+ *   submit. Used for agent_tool_inquiry "what should I do next?".
+ *
+ * The reply shape is enforced server-side by the inquiry kind's Zod
+ * schema (per `@xemahq/inquiry-contracts` `KindSchemaRegistry`); this
+ * enum is the FE-facing projection.
+ */
+export enum QuestionKind {
+  APPROVAL = 'approval',
+  CHOICE = 'choice',
+  FREEFORM = 'freeform',
+}
+
+/**
+ * Lifecycle status of a question from the recipient's perspective.
+ *
+ * - `PENDING` — recipient must reply; counts toward badge.
+ * - `RESPONDED` — this recipient replied but the inquiry as a whole
+ *   hasn't yet aggregated to a verdict. Stays in the list (to show
+ *   what was answered) but does NOT count toward badge.
+ * - `RESOLVED` — terminal, verdict reached. Hidden from the bell.
+ * - `EXPIRED` — terminal via timeout (no verdict reached, escalation
+ *   chain exhausted).
+ * - `CANCELLED` — terminal via run cancel or admin override.
+ *
+ * Maps server-side from inquiry-recipient status + inquiry status.
+ * The FE never derives terminality on its own.
+ */
+export enum QuestionStatus {
+  PENDING = 'pending',
+  RESPONDED = 'responded',
+  RESOLVED = 'resolved',
+  EXPIRED = 'expired',
+  CANCELLED = 'cancelled',
+}
+
+/** Statuses that are TERMINAL — no further transitions accepted. */
+export const TERMINAL_QUESTION_STATUSES: readonly QuestionStatus[] = [
+  QuestionStatus.RESOLVED,
+  QuestionStatus.EXPIRED,
+  QuestionStatus.CANCELLED,
+] as const;
+
+/** Statuses that count toward the badge in the global Questions header button. */
+export const BADGE_COUNTING_QUESTION_STATUSES: readonly QuestionStatus[] = [
+  QuestionStatus.PENDING,
+] as const;
+
+/**
+ * Severity of a question — used to sort the bell + decide whether to
+ * pop a toast. The engine maps from inquiry policy + escalation level.
+ *
+ * `URGENT` toasts immediately; `NORMAL` toasts on first arrival only;
+ * `INFO` never toasts (badge-only).
+ */
+export enum QuestionSeverity {
+  URGENT = 'urgent',
+  NORMAL = 'normal',
+  INFO = 'info',
+}

package/src/question/lib/question-escalation.ts

@@ -0,0 +1,22 @@
+/**
+ * Escalation breadcrumb shown under the question header in Work mode
+ * when escalation has fired at least once.
+ *
+ * Rendered as a level chain, for example:
+ *   "Level 1 (Alice) · expired · → Level 2 (Bob)"
+ *
+ * The engine emits the full level history; the FE renders the chain
+ * left-to-right with a strikethrough on expired levels. The CURRENT
+ * level (where the recipient sits) is the last entry with `expired:
+ * false`.
+ */
+export interface QuestionEscalationLevel {
+  readonly level: number;
+  readonly recipientDisplayName: string;
+  /** True when this level timed out and advanced to the next. */
+  readonly expired: boolean;
+  /** ISO-8601 when the level entered. */
+  readonly enteredAt: string;
+  /** ISO-8601 when the level expired (only set if `expired === true`). */
+  readonly expiredAt: string | null;
+}

package/src/review-inquiry/index.ts

@@ -0,0 +1,19 @@
+// ═══════════════════════════════════════════════════════════════════════════
+// @xemahq/review-inquiry-contracts — Kernel layer
+//
+// Abstract types for the REVIEW InquiryKind: a comment-only review surface
+// that pins one or more artifact versions and asks recipients to leave
+// free-form commentary. Distinct from DECISION_GATE — there is no
+// approve/reject verdict and no policy aggregation. Reviewers are heard;
+// the workflow continues regardless of what they say.
+//
+// Compose with DECISION_GATE when both review-and-gate semantics are
+// needed: emit a REVIEW first (collect comments), then a DECISION_GATE
+// over the same `subjectArtifacts` (collect verdicts). The two stay
+// orthogonal at the contract level.
+//
+// Pure types + Zod. Zero runtime adapter knowledge.
+// ═══════════════════════════════════════════════════════════════════════════
+
+export * from './lib/review-inquiry';
+export * from './lib/web-annotation';

package/src/review-inquiry/lib/review-inquiry.ts

@@ -0,0 +1,76 @@
+import { z } from 'zod';
+
+import { PinnedSubjectArtifactSchema } from '../../decision-gate';
+
+import { WebAnnotationTargetSchema } from './web-annotation';
+
+/**
+ * Prompt payload for a REVIEW inquiry.
+ *
+ * A REVIEW inquiry is a comment-only review surface: it pins one or more
+ * artifact versions and asks recipients to leave free-form comments. It is
+ * intentionally distinct from DECISION_GATE — there is NO approve/reject
+ * verdict, no policy aggregation, no terminal "approved/rejected" outcome.
+ * Reviewers are heard; the workflow continues regardless of what they say.
+ *
+ * `subjectArtifacts` mirrors the DECISION_GATE prompt and uses the same
+ * pinned-reference primitive so downstream consumers (KB ingest, audit)
+ * can resolve "what was reviewed at v3" via the same machinery they use
+ * for approval gates. `subjectArtifacts` may be empty: a "freeform review
+ * thread" on the run as a whole is a legitimate use case.
+ *
+ * `passthrough()` keeps unknown keys on the parsed object so orchestrators
+ * (e.g. `xema/review-thread@v1`) can inject extra render context (past
+ * iteration links, reviewer rubrics) that the FE picks up by field
+ * presence without contract drift.
+ */
+export const ReviewInquiryPromptSchema = z
+  .object({
+    subjectArtifacts: z.array(PinnedSubjectArtifactSchema),
+    description: z.string().optional(),
+  })
+  .passthrough();
+export type ReviewInquiryPrompt = z.infer<typeof ReviewInquiryPromptSchema>;
+
+/**
+ * One comment submitted as part of a REVIEW reply.
+ *
+ * - `body` is required and non-empty — a "review" with no content is a
+ *   no-op and should be suppressed at the UI rather than persisted.
+ *
+ * - `anchor` is an optional W3C Web Annotation target
+ *   (https://www.w3.org/TR/annotation-model/) pinning the comment to a
+ *   specific artifact version and optionally a sub-region of it via a
+ *   selector (text quote, text position, fragment, range, JSON pointer).
+ *   We standardise on Web Annotation so downstream tools — including
+ *   redraft agents and SCM adapters — receive a vocabulary they already
+ *   know, instead of a Xema-bespoke string format. The engine
+ *   round-trips the structured value opaquely; only the FE and the
+ *   redraft agent need to interpret selector kinds.
+ *
+ *   When the reviewer leaves a document-level remark (no specific span
+ *   highlighted), `anchor` is omitted entirely — the LLM briefing
+ *   translator groups those as "general notes" without needing a
+ *   second sentinel field.
+ */
+export const ReviewInquiryCommentSchema = z.object({
+  body: z.string().trim().min(1),
+  anchor: WebAnnotationTargetSchema.optional(),
+});
+export type ReviewInquiryComment = z.infer<typeof ReviewInquiryCommentSchema>;
+
+/**
+ * Reply payload for a REVIEW inquiry. At least one comment is required —
+ * an empty review is a no-op and should be modelled as "didn't reply"
+ * instead.
+ *
+ * NOTE: no `verdict` field. The whole point of the REVIEW kind is that
+ * reviewers leave commentary without being forced into an approve/reject
+ * binary. If a workflow needs both ("review then gate"), it composes a
+ * REVIEW inquiry followed by a DECISION_GATE that pins the same
+ * `subjectArtifacts`.
+ */
+export const ReviewInquiryReplySchema = z.object({
+  comments: z.array(ReviewInquiryCommentSchema).min(1),
+});
+export type ReviewInquiryReply = z.infer<typeof ReviewInquiryReplySchema>;

package/src/review-inquiry/lib/web-annotation.ts

@@ -0,0 +1,136 @@
+import { z } from 'zod';
+
+/**
+ * W3C Web Annotation Data Model — Zod schemas for the subset we use as
+ * anchor references on REVIEW inquiry comments.
+ *
+ * Spec: https://www.w3.org/TR/annotation-model/ (W3C Recommendation,
+ * 2017). The standard models commentary on web resources via a
+ * { body, target, selector } triple and is the de-facto substrate for
+ * Hypothesis-style anchored comments.
+ *
+ * We adopt the standard rather than inventing a custom shape so the
+ * platform can integrate with annotation-aware tools (Hypothesis,
+ * Apache Annotator, web-annotation-js) without translation, and so a
+ * downstream LLM redraft agent receives a vocabulary it already knows.
+ *
+ * The selector vocabulary below carries every anchor kind a markdown /
+ * code / JSON document reasonably needs:
+ *
+ *   - `TextQuoteSelector`    — anchor by literal text + prefix/suffix
+ *                              context. Robust against minor edits.
+ *   - `TextPositionSelector` — char-offset range. Precise but fragile.
+ *   - `FragmentSelector`     — anchor by fragment id (heading slug).
+ *   - `RangeSelector`        — composite (start + end selectors).
+ *   - `xema:JsonPointerSelector` — RFC 6901 pointer for structured JSON
+ *                              artifacts. Namespaced per W3C extension
+ *                              rules (custom selector `type` strings
+ *                              MUST be IRIs or namespaced identifiers).
+ *
+ * All selectors carry a discriminating `type` field so the FE / agent
+ * can branch on shape without sniffing other fields — standard
+ * pattern for the W3C JSON serialisation.
+ */
+
+export const TextQuoteSelectorSchema = z.object({
+  type: z.literal('TextQuoteSelector'),
+  exact: z.string().min(1),
+  prefix: z.string().optional(),
+  suffix: z.string().optional(),
+});
+export type TextQuoteSelector = z.infer<typeof TextQuoteSelectorSchema>;
+
+export const TextPositionSelectorSchema = z
+  .object({
+    type: z.literal('TextPositionSelector'),
+    start: z.number().int().min(0),
+    end: z.number().int().min(0),
+  })
+  .refine((v) => v.end >= v.start, {
+    message: 'TextPositionSelector requires end >= start',
+    path: ['end'],
+  });
+export type TextPositionSelector = z.infer<typeof TextPositionSelectorSchema>;
+
+export const FragmentSelectorSchema = z.object({
+  type: z.literal('FragmentSelector'),
+  value: z.string().min(1),
+  /**
+   * Optional `conformsTo` per W3C We only emit two values
+   * today: the RFC 3986 IRI for generic fragments and a Xema-specific
+   * marker for GFM heading slugs (so consumers know to slugify
+   * candidate headings the same way).
+   */
+  conformsTo: z
+    .union([
+      z.literal('https://tools.ietf.org/html/rfc3986'),
+      z.literal('gfm-heading-slug'),
+    ])
+    .optional(),
+});
+export type FragmentSelector = z.infer<typeof FragmentSelectorSchema>;
+
+export const JsonPointerSelectorSchema = z.object({
+  /**
+   * Xema-namespaced custom selector type. NOT a core W3C type — but
+   * the spec explicitly permits extension types as long as `type`
+   * is an IRI or namespaced identifier. Documenting the
+   * extension URI is on us.
+   */
+  type: z.literal('xema:JsonPointerSelector'),
+  /** RFC 6901-compliant JSON Pointer (e.g. `/decisions/2/rationale`). */
+  pointer: z.string().min(1),
+});
+export type JsonPointerSelector = z.infer<typeof JsonPointerSelectorSchema>;
+
+/**
+ * Non-recursive selector — everything except RangeSelector. Exported
+ * so RangeSelector can use it as its start/end child without inviting
+ * arbitrary nesting (a Range of Ranges is technically valid per the
+ * W3C spec but adds no expressive power for our use case).
+ */
+export const NonRangeSelectorSchema = z.discriminatedUnion('type', [
+  TextQuoteSelectorSchema,
+  TextPositionSelectorSchema,
+  FragmentSelectorSchema,
+  JsonPointerSelectorSchema,
+]);
+export type NonRangeSelector = z.infer<typeof NonRangeSelectorSchema>;
+
+export const RangeSelectorSchema = z.object({
+  type: z.literal('RangeSelector'),
+  startSelector: NonRangeSelectorSchema,
+  endSelector: NonRangeSelectorSchema,
+});
+export type RangeSelector = z.infer<typeof RangeSelectorSchema>;
+
+export const WebAnnotationSelectorSchema = z.discriminatedUnion('type', [
+  TextQuoteSelectorSchema,
+  TextPositionSelectorSchema,
+  FragmentSelectorSchema,
+  JsonPointerSelectorSchema,
+  RangeSelectorSchema,
+]);
+export type WebAnnotationSelector = z.infer<typeof WebAnnotationSelectorSchema>;
+
+/**
+ * W3C Web Annotation Target.
+ *
+ * Identifies WHICH artifact version the comment refers to and
+ * (optionally) WHERE inside it. We model the W3C `source` IRI as the
+ * concrete identity triple `{artifactId, versionId, version}` because
+ * the platform's artifact-store identity is what downstream consumers
+ * actually need — emitting a synthetic URI here would just push
+ * parsing complexity onto every reader.
+ *
+ * `selector` is optional: a whole-document anchor (the reviewer
+ * commented on the artifact in general, not a specific span) is a
+ * legitimate shape.
+ */
+export const WebAnnotationTargetSchema = z.object({
+  artifactId: z.string().min(1),
+  versionId: z.string().min(1),
+  version: z.number().int().min(1),
+  selector: WebAnnotationSelectorSchema.optional(),
+});
+export type WebAnnotationTarget = z.infer<typeof WebAnnotationTargetSchema>;

package/src/run-detail/index.ts

@@ -0,0 +1,22 @@
+// ═══════════════════════════════════════════════════════════════════════════
+// @xemahq/run-detail-contracts — Layer 1 / Kernel
+//
+// Wire shapes for the workflow run detail surface (FE) and the engine's
+// `GET /workflows/:slug/runs/:id/full` endpoint that powers it.
+//
+// The run detail page collapses into
+// THREE modes — Overview / Work / Developer. The contracts here define what
+// each mode reads, the deterministic mode-default rules, the phase rail, the
+// outcome strip for terminal runs, and the revision-state discriminator that
+// tells the FE which (if any) of the three revision UIs to render.
+//
+// Runtime-agnostic. Pure types. Zero NestJS / Prisma / framework imports.
+// ═══════════════════════════════════════════════════════════════════════════
+
+export * from './lib/run-mode';
+export * from './lib/run-outcome';
+export * from './lib/run-revision-state';
+export * from './lib/run-phase-rail';
+export * from './lib/run-detail-dto';
+export * from './lib/wait-windows';
+