@xemahq/kernel-contracts 0.30.0 → 0.31.0

package/dist/run-detail/lib/wait-windows.js

@@ -0,0 +1,39 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.WaitReason = void 0;
+exports.totalWaitMs = totalWaitMs;
+exports.currentOpenWait = currentOpenWait;
+var WaitReason;
+(function (WaitReason) {
+    WaitReason["WAITING_ON_HUMAN"] = "waiting_on_human";
+    WaitReason["WAITING_ON_AGENT"] = "waiting_on_agent";
+    WaitReason["WAITING_ON_EXTERNAL"] = "waiting_on_external";
+    WaitReason["WAITING_ON_DEPENDENCY"] = "waiting_on_dependency";
+    WaitReason["WAITING_ON_QUOTA"] = "waiting_on_quota";
+})(WaitReason || (exports.WaitReason = WaitReason = {}));
+function totalWaitMs(windows, nowMs) {
+    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;
+}
+function currentOpenWait(windows) {
+    let bestStart = -Infinity;
+    let bestWindow = 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;
+}
+//# sourceMappingURL=wait-windows.js.map

package/dist/run-detail/lib/wait-windows.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"wait-windows.js","sourceRoot":"","sources":["../../../src/run-detail/lib/wait-windows.ts"],"names":[],"mappings":";;;AAuCA,kCAUC;AAQD,0CAYC;AA3CD,IAAY,UAMX;AAND,WAAY,UAAU;IACpB,mDAAqC,CAAA;IACrC,mDAAqC,CAAA;IACrC,yDAA2C,CAAA;IAC3C,6DAA+C,CAAA;IAC/C,mDAAqC,CAAA;AACvC,CAAC,EANW,UAAU,0BAAV,UAAU,QAMrB;AAOD,SAAgB,WAAW,CAAC,OAA8B,EAAE,KAAa;IACvE,IAAI,KAAK,GAAG,CAAC,CAAC;IACd,KAAK,MAAM,CAAC,IAAI,OAAO,EAAE,CAAC;QACxB,MAAM,KAAK,GAAG,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC;QACtC,MAAM,GAAG,GAAG,CAAC,CAAC,OAAO,KAAK,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC;QAC/D,IAAI,MAAM,CAAC,QAAQ,CAAC,KAAK,CAAC,IAAI,MAAM,CAAC,QAAQ,CAAC,GAAG,CAAC,IAAI,GAAG,GAAG,KAAK,EAAE,CAAC;YAClE,KAAK,IAAI,GAAG,GAAG,KAAK,CAAC;QACvB,CAAC;IACH,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC;AAQD,SAAgB,eAAe,CAAC,OAA8B;IAC5D,IAAI,SAAS,GAAG,CAAC,QAAQ,CAAC;IAC1B,IAAI,UAAU,GAAsB,IAAI,CAAC;IACzC,KAAK,MAAM,CAAC,IAAI,OAAO,EAAE,CAAC;QACxB,IAAI,CAAC,CAAC,OAAO,KAAK,IAAI;YAAE,SAAS;QACjC,MAAM,KAAK,GAAG,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC;QACtC,IAAI,MAAM,CAAC,QAAQ,CAAC,KAAK,CAAC,IAAI,KAAK,GAAG,SAAS,EAAE,CAAC;YAChD,SAAS,GAAG,KAAK,CAAC;YAClB,UAAU,GAAG,CAAC,CAAC;QACjB,CAAC;IACH,CAAC;IACD,OAAO,UAAU,CAAC;AACpB,CAAC"}

package/package.json

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

package/src/decision-gate/index.ts

@@ -0,0 +1,13 @@
+// ═══════════════════════════════════════════════════════════════════════════
+// @xemahq/decision-gate-contracts — Kernel layer
+//
+// Per-kind schemas for the DECISION_GATE InquiryKind: pin one or more
+// artifact versions, ask deciders for a verdict, aggregate per the
+// inquiry's policy, output the approved-version pinned set for downstream
+// consumers (publish-kb etc.) to use unconditionally.
+//
+// Pure types + Zod. Workflow VM imports `import type` only.
+// ═══════════════════════════════════════════════════════════════════════════
+
+export * from './lib/pinned-subject-artifact';
+export * from './lib/decision-gate';

package/src/decision-gate/lib/decision-gate.ts

@@ -0,0 +1,113 @@
+import { z } from 'zod';
+
+import { PinnedSubjectArtifactSchema } from './pinned-subject-artifact';
+
+/**
+ * Verdict a decider returns on a Decision Gate inquiry.
+ *
+ * `ABSTAIN` is distinct from `REJECT`: a non-vote that the gate's policy
+ * may treat as "skip and wait for the rest" or "implicit reject" depending
+ * on the policy's `abstainTreatment`. Humans cannot ABSTAIN today (UI
+ * exposes only Approve / Reject); agents and endpoints may, e.g. when
+ * their structured output fails validation or the underlying activity
+ * exhausts retries.
+ */
+export enum DecisionVerdict {
+  APPROVE = 'approve',
+  REJECT = 'reject',
+  ABSTAIN = 'abstain',
+}
+
+/**
+ * Terminal outcome of the gate as a whole. Distinct from per-recipient
+ * verdict because it accounts for timeout + policy aggregation.
+ */
+export enum DecisionGateOutcome {
+  APPROVED = 'approved',
+  REJECTED = 'rejected',
+  EXPIRED_APPROVED = 'expired_approved',
+  EXPIRED_REJECTED = 'expired_rejected',
+  CANCELLED = 'cancelled',
+}
+
+/**
+ * Prompt payload for a DECISION_GATE inquiry. The pinned set is what
+ * deciders are deciding on; `description` is human-readable context shown
+ * to humans + included in the agent decider's prompt.
+ *
+ * `passthrough()` keeps unknown keys on the parsed object — used by
+ * orchestrators (e.g. `xema/review@v3`) that inject extra context for
+ * the FE to render (`reviewIteration`, `reviewerFindings`,
+ * `pastIterations`). Decision-gate itself never reads them; the FE
+ * gates rendering on field presence and ignores when absent.
+ */
+export const DecisionGatePromptSchema = z
+  .object({
+    subjectArtifacts: z.array(PinnedSubjectArtifactSchema),
+    description: z.string().optional(),
+  })
+  .passthrough();
+export type DecisionGatePrompt = z.infer<typeof DecisionGatePromptSchema>;
+
+/**
+ * Reply payload submitted by one decider (human / agent / endpoint). The
+ * shape is identical across recipient kinds — what differs is the
+ * `submittedBy` attribution and how the payload was produced (UI form,
+ * agent structured output, endpoint verdict mapper).
+ *
+ * `reason` is REQUIRED when the verdict is REJECT and must be a non-empty
+ * trimmed string. The contract enforces this at every entry point (engine
+ * controller, agent reply, endpoint verdict-mapper) so a reviewer cannot
+ * reject a deliverable without articulating why. APPROVE and ABSTAIN
+ * leave `reason` optional — the happy path stays frictionless and an
+ * ABSTAIN typically means "validation failed / cannot decide" which has
+ * no human-authored justification to capture.
+ */
+export const DecisionGateReplySchema = z
+  .object({
+    verdict: z.nativeEnum(DecisionVerdict),
+    reason: z.string().optional(),
+    attachment: z.record(z.string(), z.unknown()).optional(),
+  })
+  .superRefine((value, ctx) => {
+    if (value.verdict !== DecisionVerdict.REJECT) return;
+    const trimmed = value.reason?.trim() ?? '';
+    if (trimmed.length === 0) {
+      ctx.addIssue({
+        code: 'custom',
+        path: ['reason'],
+        message: 'reason is required and must be non-empty when verdict is reject',
+      });
+    }
+  });
+export type DecisionGateReply = z.infer<typeof DecisionGateReplySchema>;
+
+/**
+ * One row in the decision trail — used for audit and to render "alice
+ * approved 12:34:56, bob rejected 12:35:10, oracle-agent abstained" in
+ * the FE focused-page detail view.
+ */
+export const DecisionRecordSchema = z.object({
+  recipientId: z.string().min(1),
+  verdict: z.nativeEnum(DecisionVerdict),
+  reason: z.string().nullable(),
+  submittedBy: z.string().min(1),
+  submittedAtIso: z.string(),
+});
+export type DecisionRecord = z.infer<typeof DecisionRecordSchema>;
+
+/**
+ * Aggregated verdict the gate workflow returns to its parent. Downstream
+ * consumers (`publish-kb`, KB ingest, audit) read `approvedArtifacts` —
+ * NOT `Math.max(version)` — for the bytes to publish.
+ *
+ * `approvedArtifacts` is non-empty iff `outcome` is APPROVED /
+ * EXPIRED_APPROVED. On REJECTED / EXPIRED_REJECTED / CANCELLED, the array
+ * is empty by construction (consumers must not run).
+ */
+export const DecisionGateVerdictSchema = z.object({
+  outcome: z.nativeEnum(DecisionGateOutcome),
+  approvedArtifacts: z.array(PinnedSubjectArtifactSchema),
+  decisionTrail: z.array(DecisionRecordSchema),
+});
+export type DecisionGateVerdict = z.infer<typeof DecisionGateVerdictSchema>;

package/src/decision-gate/lib/pinned-subject-artifact.ts

@@ -0,0 +1,29 @@
+import { z } from 'zod';
+
+/**
+ * Pinned reference to a single artifact version. Stored on the inquiry's
+ * `prompt.subjectArtifacts` for `kind=DECISION_GATE` and propagated through
+ * the decision-gate verdict so downstream consumers (e.g. `publish-kb`,
+ * KB ingest, audit) resolve "the bytes the deciders approved" — not
+ * "whatever happens to be latest at publish time."
+ *
+ * The four-tuple `(artifactId, versionId, version, hash)` is the result
+ * of `flattenSubjectArtifacts` over upstream `deliverables[]` at the
+ * moment the gate workflow registers the inquiry. Once written, it is
+ * frozen for the lifetime of the inquiry.
+ *
+ * Canonical home for this type. Predecessor refactors (artifact-identity
+ * PR1-PR3) inlined it inside the human-approval workflow file because the
+ * workflow VM cannot run Zod; this package keeps the type importable as
+ * `import type` from the workflow file while the engine validates it via
+ * Zod at the controller boundary.
+ */
+export const PinnedSubjectArtifactSchema = z.object({
+  artifactId: z.string().min(1),
+  versionId: z.string().min(1),
+  version: z.number().int().positive(),
+  hash: z.string().min(1),
+});
+export type PinnedSubjectArtifact = z.infer<
+  typeof PinnedSubjectArtifactSchema
+>;

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