@xemahq/kernel-contracts 0.30.0 → 0.31.0

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

package/src/run-detail/lib/run-detail-dto.ts

@@ -0,0 +1,84 @@
+import { WorkflowRunStatus } from '../../workflow';
+
+import { RunOutcomeDto } from './run-outcome';
+import { RunPhaseRailDto } from './run-phase-rail';
+import { RunRevisionPayload } from './run-revision-state';
+import { WaitWindow } from './wait-windows';
+
+/**
+ * The single payload `GET /workflows/:slug/runs/:id/full` returns. Replaces
+ * the legacy `useRunSummary` + `useRunDescribe` + first-page `useRunHistory`
+ * + `useRunJobs` quad-query with one coalesced call.
+ *
+ * Conventions:
+ *   - Every nested list is bounded — the FE never asks for "all events".
+ *     Detail/history surfaces page through the timeline endpoint.
+ *   - Every closed-domain field uses an enum from this package or
+ *     `../../workflow`. No free-form strings except labels.
+ *   - The payload is shaped for the user-visible view, not internal
+ *     state. Internal Temporal IDs are exposed only in DEVELOPER mode.
+ *
+ * Wire envelope: this DTO is the `data` member of the standard envelope
+ *. The FE's envelope-assert util validates the
+ * shape end-to-end.
+ */
+export interface RunDetailDto {
+  readonly id: string;
+  readonly workflowSlug: string;
+  readonly workflowDisplayName: string;
+  readonly status: WorkflowRunStatus;
+  /** Initiator displayName — `null` for system-triggered runs (schedules, webhooks). */
+  readonly initiatorDisplayName: string | null;
+  readonly startedAt: string;
+  /** ISO-8601 when the run reached a terminal state, else `null`. */
+  readonly endedAt: string | null;
+  /** Engine ETA for in-flight runs. `null` when terminal or unknown. */
+  readonly etaAt: string | null;
+
+  readonly phaseRail: RunPhaseRailDto;
+  readonly waitWindows: readonly WaitWindow[];
+
+  /** What's actively running right now — feeds the Overview "Activity now" strip. */
+  readonly activityNow: readonly RunActivityNowDto[];
+
+  /** Last 6 events (coarse milestones). Click-through navigates to Developer mode. */
+  readonly recentTail: readonly RunRecentEventDto[];
+
+  /**
+   * Revision-state discriminator + payload (see {@link RunRevisionPayload}).
+   * Drives whether/which of the 3 revision UIs renders.
+   */
+  readonly revision: RunRevisionPayload;
+
+  /** Outcome strip for terminal runs. `null` for in-flight. */
+  readonly outcome: RunOutcomeDto | null;
+
+  /**
+   * One-line "what's blocking" callout for in-flight runs. Server-computed
+   * from waitWindows + escalation state. `null` when nothing is blocking.
+   */
+  readonly blockingSummary: string | null;
+}
+
+/**
+ * One row in the Overview "Activity now" strip — coarse "who is doing
+ * what right now". Updated via SSE incremental patches; one sentence
+ * per active job, no timestamps (they're current).
+ */
+export interface RunActivityNowDto {
+  readonly jobKey: string;
+  readonly agentDisplayName: string | null;
+  readonly summary: string;
+}
+
+/**
+ * One row in the Overview "Recent" tail — the last 6 coarse milestones
+ * (phase entered, deliverable emitted, agent paused, decision needed).
+ */
+export interface RunRecentEventDto {
+  readonly id: string;
+  readonly at: string;
+  readonly summary: string;
+  /** Optional deep-link anchor for the Developer-mode timeline. */
+  readonly developerAnchor: string | null;
+}

package/src/run-detail/lib/run-mode.ts

@@ -0,0 +1,65 @@
+import { WorkflowRunStatus, TERMINAL_WORKFLOW_RUN_STATUSES } from '../../workflow';
+
+/**
+ * The calm modes that replace the legacy 10-tab run detail.
+ *
+ * - `OVERVIEW` — coarse status + latest deliverables (links) + last 6
+ *   events. Default for running and terminal runs.
+ * - `WORK` — the question canvas + reply form. Default when the run has
+ *   a question waiting on the current user.
+ * - `OUTPUTS` — full deliverables surface. One sub-tab per artifact;
+ *   each sub-tab renders the artifact's CONTENT (markdown rendered as
+ *   an A4 page, code diff via the diff viewer, diagram via mermaid,
+ *   etc.) with a `Show raw` toggle that reveals the underlying artifact
+ *   JSON. Never the default — opened from the Overview deliverables
+ *   strip or directly via the mode switcher.
+ * - `DEVELOPER` — full activity console + Temporal history + Mounts /
+ *   Pending / Query diagnostic cards. Behind a user-pref + role gate.
+ *
+ * Mode-default selection is deterministic — see {@link selectDefaultRunMode}.
+ * Free-text strings are forbidden; consumers route on this enum.
+ */
+export enum RunMode {
+  OVERVIEW = 'overview',
+  WORK = 'work',
+  OUTPUTS = 'outputs',
+  DEVELOPER = 'developer',
+}
+
+/**
+ * Inputs the deterministic mode-default selector consumes. Keeping this
+ * narrow (no full RunDetailDto reference) lets callers pre-compute it
+ * without holding the whole run payload in scope.
+ */
+export interface RunModeSelectionInputs {
+  readonly status: WorkflowRunStatus;
+  readonly hasQuestionForCurrentUser: boolean;
+  /** User-pref override; wins if set. */
+  readonly userPreferredMode?: RunMode;
+}
+
+/**
+ * Deterministic mode-default rules:
+ *
+ *   status == waiting_on_human && hasQuestionForMe(runId)  → WORK
+ *   status terminal                                        → OVERVIEW
+ *   otherwise                                              → OVERVIEW
+ *   user pref override                                     → wins
+ *
+ * No timing, no probabilities, no fuzzy matching. The FE calls this once
+ * per render and routes accordingly; reverse calls are not supported.
+ */
+export function selectDefaultRunMode(input: RunModeSelectionInputs): RunMode {
+  if (input.userPreferredMode !== undefined) {
+    return input.userPreferredMode;
+  }
+  const isTerminal = TERMINAL_WORKFLOW_RUN_STATUSES.includes(input.status);
+  if (
+    !isTerminal &&
+    input.status === WorkflowRunStatus.WAITING_ON_HUMAN &&
+    input.hasQuestionForCurrentUser
+  ) {
+    return RunMode.WORK;
+  }
+  return RunMode.OVERVIEW;
+}

package/src/run-detail/lib/run-outcome.ts

@@ -0,0 +1,66 @@
+import { WorkflowRunStatus } from '../../workflow';
+
+/**
+ * Branch the FE outcome strip renders for a TERMINAL run. Mirrors the
+ * branch matrix for terminal runs.
+ *
+ * Every terminal run lands in exactly one branch — the engine sets it on
+ * the {@link RunDetailDto.outcome} field at run-end so the FE never has
+ * to re-derive from `status` + reason text.
+ */
+export enum RunOutcomeBranch {
+  SUCCEEDED = 'succeeded',
+  FAILED = 'failed',
+  CANCELLED = 'cancelled',
+  ESCALATION_EXHAUSTED = 'escalation_exhausted',
+}
+
+/**
+ * What the user sees in the outcome card. Each branch's `actions` list
+ * is computed server-side (only valid CTAs leak into the wire) so the
+ * FE renders without policy logic.
+ *
+ * `summary` is one human sentence — never JSON. The FE displays it
+ * verbatim under the status header.
+ */
+export interface RunOutcomeDto {
+  readonly branch: RunOutcomeBranch;
+  readonly summary: string;
+  readonly actions: readonly RunOutcomeActionDto[];
+}
+
+/**
+ * A button rendered under the outcome card. Closed CTA enum — the FE
+ * fails-fast on unknown values rather than rendering a placeholder.
+ */
+export interface RunOutcomeActionDto {
+  readonly kind: RunOutcomeActionKind;
+  readonly label: string;
+  /** Optional href; if absent the action is dispatched to the engine via SDK. */
+  readonly href?: string;
+  /** Optional opaque payload the engine echoes on dispatch. */
+  readonly payload?: Readonly<Record<string, unknown>>;
+}
+
+export enum RunOutcomeActionKind {
+  RUN_AGAIN = 'run_again',
+  OPEN_IN_KB = 'open_in_kb',
+  REDO_FROM_PHASE = 'redo_from_phase',
+  OPEN_LAST_SUCCESSFUL_ARTIFACT = 'open_last_successful_artifact',
+  RESTART_WITH_SAME_INPUTS = 'restart_with_same_inputs',
+  ADJUST_ESCALATION_CHAIN = 'adjust_escalation_chain',
+}
+
+/**
+ * True iff a {@link WorkflowRunStatus} represents a terminal state that
+ * carries an outcome. Mirrors {@link TERMINAL_WORKFLOW_RUN_STATUSES} but
+ * rejects `ABORTED_FOR_MIGRATION` because that branch has no user-facing
+ * outcome card (it's an internal lifecycle event).
+ */
+export function isOutcomeBearingStatus(status: WorkflowRunStatus): boolean {
+  return (
+    status === WorkflowRunStatus.SUCCEEDED ||
+    status === WorkflowRunStatus.FAILED ||
+    status === WorkflowRunStatus.CANCELLED
+  );
+}

package/src/run-detail/lib/run-phase-rail.ts

@@ -0,0 +1,43 @@
+/**
+ * The phase rail shown at the top of every run-detail mode. Click any
+ * dot to filter the activity panel to that phase. The rail is a stable,
+ * compile-time-known sequence per workflow definition — the engine
+ * computes it once at run dispatch and freezes it on the run row so the
+ * FE doesn't have to re-derive from runtime activity.
+ */
+export interface RunPhaseRailDto {
+  readonly phases: readonly RunPhaseRailEntryDto[];
+  /**
+   * Index into `phases` of the currently-active phase. `null` when the
+   * run is terminal AND the last phase already completed (the rail
+   * renders fully filled).
+   */
+  readonly currentIndex: number | null;
+}
+
+export interface RunPhaseRailEntryDto {
+  readonly stageKey: string;
+  /** Display label — e.g. "Implementation", "Architecture review". */
+  readonly label: string;
+  readonly status: RunPhaseRailStatus;
+  /** ISO-8601 when the phase entered RUNNING. `null` if not yet started. */
+  readonly startedAt: string | null;
+  /** ISO-8601 when the phase reached a terminal state. `null` if still in flight. */
+  readonly endedAt: string | null;
+}
+
+/**
+ * Closed phase-rail status set. Distinct from {@link JobRunStatus} — a
+ * single phase rolls up many jobs and adds the WAITING / SKIPPED rail
+ * affordances the user sees. Maps from job status server-side; FE
+ * renders the icon+color directly off this enum.
+ */
+export enum RunPhaseRailStatus {
+  PENDING = 'pending',
+  RUNNING = 'running',
+  WAITING = 'waiting',
+  SUCCEEDED = 'succeeded',
+  FAILED = 'failed',
+  CANCELLED = 'cancelled',
+  SKIPPED = 'skipped',
+}

package/src/run-detail/lib/run-revision-state.ts

@@ -0,0 +1,83 @@
+/**
+ * Three deliberately distinct revision UIs.
+ * The engine emits exactly one of these on the run detail payload; the
+ * FE renders the matching component (or nothing for `NONE`).
+ *
+ * - `REVISE` — purple checkpoint card embedded in the doc flow.
+ *   CTAs: "Approve & continue" | "Revise with feedback".
+ * - `MANUAL_OVERRIDE` — warning banner shown after auto-retries are
+ *   exhausted. CTAs: "Extend retries" | "Force approve" | "Reject run".
+ * - `REDO_FROM_PHASE` — terminal-only dropdown that re-dispatches from
+ *   a chosen earlier phase.
+ * - `NONE` — no revision UI; the run is progressing normally.
+ *
+ * Auto-retry status surfaces as a status pill in the run header, NOT
+ * its own revision-state value. Don't extend this enum to cover
+ * non-revision states.
+ */
+export enum RunRevisionState {
+  NONE = 'none',
+  REVISE = 'revise',
+  MANUAL_OVERRIDE = 'manual_override',
+  REDO_FROM_PHASE = 'redo_from_phase',
+}
+
+/**
+ * Per-state payload the FE needs to render the matching component. The
+ * engine includes whichever variant matches `state` and omits the rest.
+ *
+ * `NONE` carries no payload — the discriminator alone suffices.
+ */
+export type RunRevisionPayload =
+  | { readonly state: RunRevisionState.NONE }
+  | { readonly state: RunRevisionState.REVISE; readonly checkpoint: RunReviseCheckpointDto }
+  | {
+      readonly state: RunRevisionState.MANUAL_OVERRIDE;
+      readonly override: RunManualOverrideDto;
+    }
+  | {
+      readonly state: RunRevisionState.REDO_FROM_PHASE;
+      readonly redo: RunRedoFromPhaseDto;
+    };
+
+/** Payload for the purple checkpoint card. */
+export interface RunReviseCheckpointDto {
+  readonly checkpointId: string;
+  readonly stageKey: string;
+  readonly title: string;
+  /** Human-readable summary of what's being reviewed. */
+  readonly summary: string;
+  /** Reviewer findings to render inline alongside the canvas. */
+  readonly findings: readonly RunReviseFindingDto[];
+}
+
+export interface RunReviseFindingDto {
+  readonly id: string;
+  readonly severity: 'info' | 'minor' | 'major' | 'critical';
+  /** Optional file:line anchor — `null` if the finding is run-level. */
+  readonly anchor: string | null;
+  readonly message: string;
+}
+
+/** Payload for the manual-override banner (auto-retries exhausted). */
+export interface RunManualOverrideDto {
+  readonly retryCount: number;
+  readonly retryLimit: number;
+  readonly lastFailureReason: string;
+  /** When the engine is willing to attempt one more retry on demand. */
+  readonly canExtendRetries: boolean;
+}
+
+/** Payload for the redo-from-phase dropdown (terminal runs only). */
+export interface RunRedoFromPhaseDto {
+  readonly availablePhases: readonly RunRedoPhaseChoiceDto[];
+}
+
+export interface RunRedoPhaseChoiceDto {
+  readonly stageKey: string;
+  readonly label: string;
+  /** Whether the engine has the inputs needed to re-dispatch from here. */
+  readonly available: boolean;
+  /** Human-readable reason when `available === false`. */
+  readonly unavailableReason?: string;
+}

package/src/run-detail/lib/wait-windows.ts

@@ -0,0 +1,70 @@
+/**
+ * Single source of truth for "the run is waiting on X" math used by the
+ * RunHeaderTimebar, the run-list "what's blocking" inline text, and the
+ * Overview blocking callout.
+ *
+ * Three different surfaces used to compute these windows independently
+ * and could disagree by the
+ * second. They now share this util.
+ *
+ * All times are ISO-8601 strings on the wire; the helpers parse + return
+ * primitive ms numbers so callers stay framework-agnostic.
+ */
+
+export interface WaitWindow {
+  /** Inclusive start ISO-8601. */
+  readonly startedAt: string;
+  /** Exclusive end ISO-8601, or `null` if the wait is still open. */
+  readonly endedAt: string | null;
+  readonly reason: WaitReason;
+}
+
+/**
+ * Closed reason set. The user-visible label is rendered by the FE from
+ * this discriminator — never accept a free-form `reason` string from
+ * the wire.
+ */
+export enum WaitReason {
+  WAITING_ON_HUMAN = 'waiting_on_human',
+  WAITING_ON_AGENT = 'waiting_on_agent',
+  WAITING_ON_EXTERNAL = 'waiting_on_external',
+  WAITING_ON_DEPENDENCY = 'waiting_on_dependency',
+  WAITING_ON_QUOTA = 'waiting_on_quota',
+}
+
+/**
+ * Total wait duration (ms) summed across windows. Open windows count
+ * up to `nowMs`. Caller passes `nowMs` (test-injectable) — the lib
+ * never reads `Date.now()` on its own.
+ */
+export function totalWaitMs(windows: readonly WaitWindow[], nowMs: number): number {
+  let total = 0;
+  for (const w of windows) {
+    const start = Date.parse(w.startedAt);
+    const end = w.endedAt !== null ? Date.parse(w.endedAt) : nowMs;
+    if (Number.isFinite(start) && Number.isFinite(end) && end > start) {
+      total += end - start;
+    }
+  }
+  return total;
+}
+
+/**
+ * The currently-open wait window, if any. Returns the most recent open
+ * window (there should never be more than one open at a time, but if
+ * the engine emits overlapping waits we surface the most recent so the
+ * FE doesn't pick a stale reason).
+ */
+export function currentOpenWait(windows: readonly WaitWindow[]): WaitWindow | null {
+  let bestStart = -Infinity;
+  let bestWindow: WaitWindow | null = null;
+  for (const w of windows) {
+    if (w.endedAt !== null) continue;
+    const start = Date.parse(w.startedAt);
+    if (Number.isFinite(start) && start > bestStart) {
+      bestStart = start;
+      bestWindow = w;
+    }
+  }
+  return bestWindow;
+}