@qontinui/shared-types 0.2.4 → 0.2.5

package/src/ui-bridge-ir/adapter.ts

@@ -1,220 +1,220 @@
-/**
- * IR -> WorkflowConfig adapter.
- *
- * Single point of translation between authoring-time IR (with provenance,
- * metadata, effect, crossRefs, visualRefs) and the runtime/storage shape
- * that ui-bridge-auto consumes. See ADR-001 (decision #6 / #7) for the
- * boundary rationale.
- *
- * The output is intentionally typed structurally — this module has no
- * runtime dependency on ui-bridge-auto. ui-bridge-auto's own tests verify
- * end-to-end compatibility with `engine.defineStates(...)` /
- * `engine.defineTransitions(...)` (see
- * `ui-bridge-auto/src/__tests__/spike-ir-contract.test.ts`).
- */
-
-import type { IRElementCriteria } from "./element-criteria";
-import type { IRDocument } from "./document";
-import type { IRState, IRStateCondition } from "./state";
-import type { IRTransition, IRTransitionAction, IRWaitSpec } from "./transition";
-
-// ---------------------------------------------------------------------------
-// Output shapes — structural mirrors of ui-bridge-auto's WorkflowConfig.
-// Kept in sync via ui-bridge-auto's regression test, NOT compile-time
-// imports (qontinui-schemas has no runtime deps by design).
-// ---------------------------------------------------------------------------
-
-/** Mirrors `StateConfig` from ui-bridge-auto/src/config/workflow.ts:47. */
-export interface AdaptedState {
-  id: string;
-  name: string;
-  description?: string;
-  requiredElements: IRElementCriteria[];
-  excludedElements?: IRElementCriteria[];
-  conditions?: IRStateCondition[];
-  isInitial?: boolean;
-  isTerminal?: boolean;
-  blocking?: boolean;
-  group?: string;
-  pathCost?: number;
-}
-
-/**
- * Mirrors the runtime `TransitionDefinition` shape from
- * ui-bridge-auto/src/state/state-machine.ts:40.
- *
- * Note: ui-bridge-auto has two related Transition shapes — the storage shape
- * (`TransitionConfig` in config/workflow.ts:54, with action field named
- * `type`) and the runtime engine shape (`TransitionDefinition` in
- * state-machine.ts:40, with action field named `action`). The runtime engine
- * is what consumers actually pass adapter output into via
- * `engine.defineTransitions(...)`, so the adapter targets the runtime shape.
- */
-export interface AdaptedTransition {
-  id: string;
-  name: string;
-  description?: string;
-  fromStates: string[];
-  activateStates: string[];
-  /** Adapter normalizes IR's optional `exitStates` to a required array. */
-  exitStates: string[];
-  actions: AdaptedTransitionAction[];
-  pathCost?: number;
-  bidirectional?: boolean;
-}
-
-/**
- * Mirrors the runtime `TransitionAction` from
- * ui-bridge-auto/src/state/state-machine.ts:55.
- *
- * The IR uses `type` for the action verb (matching the storage-shape
- * convention); the adapter renames it to `action` for the runtime engine.
- *
- * `waitAfter` is narrower than `IRWaitSpec` — the runtime engine accepts
- * only a subset of wait types and a subset of fields. The adapter drops
- * IR-only wait variants (e.g., `state`, `condition`) and IR-only fields
- * (e.g., `property`, `quietPeriodMs`). Authors can still express richer
- * waits in the IR; they just don't survive the runtime contract.
- */
-export interface AdaptedWaitAfter {
-  type: "idle" | "element" | "time" | "vanish" | "change" | "stable";
-  query?: IRElementCriteria;
-  ms?: number;
-  timeout?: number;
-}
-
-export interface AdaptedTransitionAction {
-  /** Action verb — renamed from IR's `type` to match the runtime contract. */
-  action: string;
-  target: IRElementCriteria;
-  params?: Record<string, unknown>;
-  waitAfter?: AdaptedWaitAfter;
-}
-
-/** Mirrors `WorkflowConfig` from ui-bridge-auto/src/config/workflow.ts:67. */
-export interface AdaptedWorkflowConfig {
-  id: string;
-  name: string;
-  description?: string;
-  version?: string;
-  states: AdaptedState[];
-  transitions: AdaptedTransition[];
-  initialState?: string;
-}
-
-// ---------------------------------------------------------------------------
-// Adapter implementation
-// ---------------------------------------------------------------------------
-
-const SUPPORTED_IR_VERSIONS = new Set<string>(["1.0"]);
-
-/**
- * Convert an IR state declaration into the runtime/storage state shape.
- * Strips IR-only fields (metadata, provenance, elementIds,
- * incomingTransitions, crossRefs, visualRefs).
- */
-export function adaptIRState(state: IRState): AdaptedState {
-  const out: AdaptedState = {
-    id: state.id,
-    name: state.name,
-    requiredElements: state.requiredElements,
-  };
-  if (state.description !== undefined) out.description = state.description;
-  if (state.excludedElements !== undefined) out.excludedElements = state.excludedElements;
-  if (state.conditions !== undefined) out.conditions = state.conditions;
-  if (state.isInitial !== undefined) out.isInitial = state.isInitial;
-  if (state.isTerminal !== undefined) out.isTerminal = state.isTerminal;
-  if (state.blocking !== undefined) out.blocking = state.blocking;
-  if (state.group !== undefined) out.group = state.group;
-  if (state.pathCost !== undefined) out.pathCost = state.pathCost;
-  return out;
-}
-
-/**
- * Wait types the runtime engine accepts. IR-authored waits with other types
- * (e.g., `state`, `condition`) are dropped from the adapter output.
- */
-const RUNTIME_WAIT_TYPES = new Set<AdaptedWaitAfter["type"]>([
-  "idle",
-  "element",
-  "time",
-  "vanish",
-  "change",
-  "stable",
-]);
-
-function adaptIRWaitAfter(wait: IRWaitSpec): AdaptedWaitAfter | undefined {
-  if (!RUNTIME_WAIT_TYPES.has(wait.type as AdaptedWaitAfter["type"])) {
-    // IR-authored wait is richer than runtime supports — drop it.
-    // Runtime defaults (default idle behaviour) take over.
-    return undefined;
-  }
-  const out: AdaptedWaitAfter = { type: wait.type as AdaptedWaitAfter["type"] };
-  if (wait.query !== undefined) out.query = wait.query;
-  if (wait.ms !== undefined) out.ms = wait.ms;
-  if (wait.timeout !== undefined) out.timeout = wait.timeout;
-  return out;
-}
-
-/**
- * Convert an IR transition action into the runtime action shape.
- * Renames IR's `type` to runtime's `action`; narrows `waitAfter` to the
- * runtime-accepted subset.
- */
-export function adaptIRTransitionAction(action: IRTransitionAction): AdaptedTransitionAction {
-  const out: AdaptedTransitionAction = {
-    action: action.type,
-    target: action.target,
-  };
-  if (action.params !== undefined) out.params = action.params;
-  if (action.waitAfter !== undefined) {
-    const adaptedWait = adaptIRWaitAfter(action.waitAfter);
-    if (adaptedWait !== undefined) out.waitAfter = adaptedWait;
-  }
-  return out;
-}
-
-/**
- * Convert an IR transition declaration into the runtime/storage transition
- * shape. Strips IR-only fields (effect, metadata, provenance, crossRefs)
- * and defaults `exitStates` to `[]` when omitted.
- */
-export function adaptIRTransition(transition: IRTransition): AdaptedTransition {
-  const out: AdaptedTransition = {
-    id: transition.id,
-    name: transition.name,
-    fromStates: transition.fromStates,
-    activateStates: transition.activateStates,
-    exitStates: transition.exitStates ?? [],
-    actions: transition.actions.map(adaptIRTransitionAction),
-  };
-  if (transition.description !== undefined) out.description = transition.description;
-  if (transition.pathCost !== undefined) out.pathCost = transition.pathCost;
-  if (transition.bidirectional !== undefined) out.bidirectional = transition.bidirectional;
-  return out;
-}
-
-/**
- * Convert a top-level IR document into the runtime `WorkflowConfig` shape.
- *
- * Throws on unknown IR versions to fail loudly rather than silently emit
- * stale shapes.
- */
-export function adaptIRDocumentToWorkflowConfig(doc: IRDocument): AdaptedWorkflowConfig {
-  if (!SUPPORTED_IR_VERSIONS.has(doc.version)) {
-    throw new Error(
-      `adaptIRDocumentToWorkflowConfig: unsupported IR version "${doc.version}". ` +
-        `Supported: ${Array.from(SUPPORTED_IR_VERSIONS).join(", ")}`,
-    );
-  }
-
-  const out: AdaptedWorkflowConfig = {
-    id: doc.id,
-    name: doc.name,
-    states: doc.states.map(adaptIRState),
-    transitions: doc.transitions.map(adaptIRTransition),
-  };
-  if (doc.description !== undefined) out.description = doc.description;
-  if (doc.initialState !== undefined) out.initialState = doc.initialState;
-  return out;
-}
+/**
+ * IR -> WorkflowConfig adapter.
+ *
+ * Single point of translation between authoring-time IR (with provenance,
+ * metadata, effect, crossRefs, visualRefs) and the runtime/storage shape
+ * that ui-bridge-auto consumes. See ADR-001 (decision #6 / #7) for the
+ * boundary rationale.
+ *
+ * The output is intentionally typed structurally — this module has no
+ * runtime dependency on ui-bridge-auto. ui-bridge-auto's own tests verify
+ * end-to-end compatibility with `engine.defineStates(...)` /
+ * `engine.defineTransitions(...)` (see
+ * `ui-bridge-auto/src/__tests__/spike-ir-contract.test.ts`).
+ */
+
+import type { IRElementCriteria } from "./element-criteria";
+import type { IRDocument } from "./document";
+import type { IRState, IRStateCondition } from "./state";
+import type { IRTransition, IRTransitionAction, IRWaitSpec } from "./transition";
+
+// ---------------------------------------------------------------------------
+// Output shapes — structural mirrors of ui-bridge-auto's WorkflowConfig.
+// Kept in sync via ui-bridge-auto's regression test, NOT compile-time
+// imports (qontinui-schemas has no runtime deps by design).
+// ---------------------------------------------------------------------------
+
+/** Mirrors `StateConfig` from ui-bridge-auto/src/config/workflow.ts:47. */
+export interface AdaptedState {
+  id: string;
+  name: string;
+  description?: string;
+  requiredElements: IRElementCriteria[];
+  excludedElements?: IRElementCriteria[];
+  conditions?: IRStateCondition[];
+  isInitial?: boolean;
+  isTerminal?: boolean;
+  blocking?: boolean;
+  group?: string;
+  pathCost?: number;
+}
+
+/**
+ * Mirrors the runtime `TransitionDefinition` shape from
+ * ui-bridge-auto/src/state/state-machine.ts:40.
+ *
+ * Note: ui-bridge-auto has two related Transition shapes — the storage shape
+ * (`TransitionConfig` in config/workflow.ts:54, with action field named
+ * `type`) and the runtime engine shape (`TransitionDefinition` in
+ * state-machine.ts:40, with action field named `action`). The runtime engine
+ * is what consumers actually pass adapter output into via
+ * `engine.defineTransitions(...)`, so the adapter targets the runtime shape.
+ */
+export interface AdaptedTransition {
+  id: string;
+  name: string;
+  description?: string;
+  fromStates: string[];
+  activateStates: string[];
+  /** Adapter normalizes IR's optional `exitStates` to a required array. */
+  exitStates: string[];
+  actions: AdaptedTransitionAction[];
+  pathCost?: number;
+  bidirectional?: boolean;
+}
+
+/**
+ * Mirrors the runtime `TransitionAction` from
+ * ui-bridge-auto/src/state/state-machine.ts:55.
+ *
+ * The IR uses `type` for the action verb (matching the storage-shape
+ * convention); the adapter renames it to `action` for the runtime engine.
+ *
+ * `waitAfter` is narrower than `IRWaitSpec` — the runtime engine accepts
+ * only a subset of wait types and a subset of fields. The adapter drops
+ * IR-only wait variants (e.g., `state`, `condition`) and IR-only fields
+ * (e.g., `property`, `quietPeriodMs`). Authors can still express richer
+ * waits in the IR; they just don't survive the runtime contract.
+ */
+export interface AdaptedWaitAfter {
+  type: "idle" | "element" | "time" | "vanish" | "change" | "stable";
+  query?: IRElementCriteria;
+  ms?: number;
+  timeout?: number;
+}
+
+export interface AdaptedTransitionAction {
+  /** Action verb — renamed from IR's `type` to match the runtime contract. */
+  action: string;
+  target: IRElementCriteria;
+  params?: Record<string, unknown>;
+  waitAfter?: AdaptedWaitAfter;
+}
+
+/** Mirrors `WorkflowConfig` from ui-bridge-auto/src/config/workflow.ts:67. */
+export interface AdaptedWorkflowConfig {
+  id: string;
+  name: string;
+  description?: string;
+  version?: string;
+  states: AdaptedState[];
+  transitions: AdaptedTransition[];
+  initialState?: string;
+}
+
+// ---------------------------------------------------------------------------
+// Adapter implementation
+// ---------------------------------------------------------------------------
+
+const SUPPORTED_IR_VERSIONS = new Set<string>(["1.0"]);
+
+/**
+ * Convert an IR state declaration into the runtime/storage state shape.
+ * Strips IR-only fields (metadata, provenance, elementIds,
+ * incomingTransitions, crossRefs, visualRefs).
+ */
+export function adaptIRState(state: IRState): AdaptedState {
+  const out: AdaptedState = {
+    id: state.id,
+    name: state.name,
+    requiredElements: state.requiredElements,
+  };
+  if (state.description !== undefined) out.description = state.description;
+  if (state.excludedElements !== undefined) out.excludedElements = state.excludedElements;
+  if (state.conditions !== undefined) out.conditions = state.conditions;
+  if (state.isInitial !== undefined) out.isInitial = state.isInitial;
+  if (state.isTerminal !== undefined) out.isTerminal = state.isTerminal;
+  if (state.blocking !== undefined) out.blocking = state.blocking;
+  if (state.group !== undefined) out.group = state.group;
+  if (state.pathCost !== undefined) out.pathCost = state.pathCost;
+  return out;
+}
+
+/**
+ * Wait types the runtime engine accepts. IR-authored waits with other types
+ * (e.g., `state`, `condition`) are dropped from the adapter output.
+ */
+const RUNTIME_WAIT_TYPES = new Set<AdaptedWaitAfter["type"]>([
+  "idle",
+  "element",
+  "time",
+  "vanish",
+  "change",
+  "stable",
+]);
+
+function adaptIRWaitAfter(wait: IRWaitSpec): AdaptedWaitAfter | undefined {
+  if (!RUNTIME_WAIT_TYPES.has(wait.type as AdaptedWaitAfter["type"])) {
+    // IR-authored wait is richer than runtime supports — drop it.
+    // Runtime defaults (default idle behaviour) take over.
+    return undefined;
+  }
+  const out: AdaptedWaitAfter = { type: wait.type as AdaptedWaitAfter["type"] };
+  if (wait.query !== undefined) out.query = wait.query;
+  if (wait.ms !== undefined) out.ms = wait.ms;
+  if (wait.timeout !== undefined) out.timeout = wait.timeout;
+  return out;
+}
+
+/**
+ * Convert an IR transition action into the runtime action shape.
+ * Renames IR's `type` to runtime's `action`; narrows `waitAfter` to the
+ * runtime-accepted subset.
+ */
+export function adaptIRTransitionAction(action: IRTransitionAction): AdaptedTransitionAction {
+  const out: AdaptedTransitionAction = {
+    action: action.type,
+    target: action.target,
+  };
+  if (action.params !== undefined) out.params = action.params;
+  if (action.waitAfter !== undefined) {
+    const adaptedWait = adaptIRWaitAfter(action.waitAfter);
+    if (adaptedWait !== undefined) out.waitAfter = adaptedWait;
+  }
+  return out;
+}
+
+/**
+ * Convert an IR transition declaration into the runtime/storage transition
+ * shape. Strips IR-only fields (effect, metadata, provenance, crossRefs)
+ * and defaults `exitStates` to `[]` when omitted.
+ */
+export function adaptIRTransition(transition: IRTransition): AdaptedTransition {
+  const out: AdaptedTransition = {
+    id: transition.id,
+    name: transition.name,
+    fromStates: transition.fromStates,
+    activateStates: transition.activateStates,
+    exitStates: transition.exitStates ?? [],
+    actions: transition.actions.map(adaptIRTransitionAction),
+  };
+  if (transition.description !== undefined) out.description = transition.description;
+  if (transition.pathCost !== undefined) out.pathCost = transition.pathCost;
+  if (transition.bidirectional !== undefined) out.bidirectional = transition.bidirectional;
+  return out;
+}
+
+/**
+ * Convert a top-level IR document into the runtime `WorkflowConfig` shape.
+ *
+ * Throws on unknown IR versions to fail loudly rather than silently emit
+ * stale shapes.
+ */
+export function adaptIRDocumentToWorkflowConfig(doc: IRDocument): AdaptedWorkflowConfig {
+  if (!SUPPORTED_IR_VERSIONS.has(doc.version)) {
+    throw new Error(
+      `adaptIRDocumentToWorkflowConfig: unsupported IR version "${doc.version}". ` +
+        `Supported: ${Array.from(SUPPORTED_IR_VERSIONS).join(", ")}`,
+    );
+  }
+
+  const out: AdaptedWorkflowConfig = {
+    id: doc.id,
+    name: doc.name,
+    states: doc.states.map(adaptIRState),
+    transitions: doc.transitions.map(adaptIRTransition),
+  };
+  if (doc.description !== undefined) out.description = doc.description;
+  if (doc.initialState !== undefined) out.initialState = doc.initialState;
+  return out;
+}

package/src/ui-bridge-ir/document.ts

@@ -1,114 +1,114 @@
-/**
- * Top-level IR document.
- *
- * Versioned (`'1.0'`) container for the states + transitions that describe
- * a page or scope of an application. Build plugins emit this shape; the
- * adapter folds it into ui-bridge-auto's `WorkflowConfig`.
- */
-
-import type { IRGroup } from "./group";
-import type { IRMetadata, IRProvenance } from "./primitives";
-import type { IRState } from "./state";
-import type { IRTransition } from "./transition";
-
-/**
- * IR schema version. Bump when the shape changes in a backwards-incompatible
- * way. The adapter rejects documents whose version it does not understand.
- */
-export type IRVersion = "1.0";
-
-/**
- * Axes that the spec <-> IR pairing gate compares. A document's
- * `pairingPolicy.acceptDrift.axes` lists which of these are
- * intentionally allowed to diverge between the legacy spec and the
- * IR's forward projection.
- */
-export type IRPairingAxis = "groupCount" | "groupIds" | "assertionCount";
-
-/**
- * Per-document opt-out for specific spec<->IR pairing axes.
- *
- * The canonical use case is a hand-authored IR that uses a different
- * grouping convention than the legacy spec. Without an explicit policy
- * the pairing gate flags it as a mismatch on every PR, which trains
- * reviewers to ignore the gate. The policy makes the divergence
- * explicit and audit-friendly:
- *
- *   - `axes`     — which fingerprint comparisons to skip
- *   - `reason`   — human-readable justification (required, surfaced in
- *                  `check-spec-pairing` summary output)
- *   - `since`    — ISO date (YYYY-MM-DD) the exemption was added
- *   - `expiresAt` — optional ISO date (YYYY-MM-DD) after which the
- *                   exemption stops applying. Forces periodic
- *                   re-justification: the pairing gate downgrades
- *                   expired exemptions back to ordinary mismatches.
- *
- * Mismatches NOT covered by the listed `axes` still fail the gate as
- * usual — you can accept drift on `groupCount` while still requiring
- * the assertion total to match.
- */
-export interface IRAcceptDriftPolicy {
-  /** Fingerprint axes whose mismatches are tolerated. */
-  axes: IRPairingAxis[];
-  /** Human-readable justification for the exemption. */
-  reason: string;
-  /** ISO date (YYYY-MM-DD) the exemption was added. */
-  since: string;
-  /**
-   * Optional ISO date (YYYY-MM-DD) after which the exemption stops
-   * applying. The pairing gate then surfaces the document as an
-   * ordinary mismatch.
-   */
-  expiresAt?: string;
-}
-
-/**
- * Per-document pairing policy block. Currently only carries
- * `acceptDrift`; future policies (e.g. assertion-shape exemptions)
- * can extend this without breaking the IR schema.
- */
-export interface IRPairingPolicy {
-  /** Opt-out from specific spec<->IR pairing mismatch axes. */
-  acceptDrift?: IRAcceptDriftPolicy;
-}
-
-/**
- * Top-level IR document.
- */
-export interface IRDocument {
-  /** Schema version. */
-  version: IRVersion;
-  /** Stable document identifier (typically the page or scope name). */
-  id: string;
-  /** Human-readable document name. */
-  name: string;
-  /** Optional description of what this document covers. */
-  description?: string;
-  /** Document-level semantic metadata. */
-  metadata?: IRMetadata;
-  /** Where this document came from. */
-  provenance?: IRProvenance;
-
-  /**
-   * Per-document policy block — opt-out from specific spec<->IR
-   * pairing mismatches. Used by hand-authored IRs that intentionally
-   * diverge from the legacy spec shape.
-   */
-  pairingPolicy?: IRPairingPolicy;
-
-  /** State declarations within this document. */
-  states: IRState[];
-  /** Transition declarations within this document. */
-  transitions: IRTransition[];
-
-  /**
-   * Groups produced by workflow-criteria synthesis (not by IR state authoring).
-   * Synthesis appends to this list; the projection emits them after state-derived
-   * groups in legacy `groups[]` output. Authoring tools should treat this field
-   * as read-only.
-   */
-  synthesizedGroups?: IRGroup[];
-
-  /** ID of the initial/starting state, if applicable. */
-  initialState?: string;
-}
+/**
+ * Top-level IR document.
+ *
+ * Versioned (`'1.0'`) container for the states + transitions that describe
+ * a page or scope of an application. Build plugins emit this shape; the
+ * adapter folds it into ui-bridge-auto's `WorkflowConfig`.
+ */
+
+import type { IRGroup } from "./group";
+import type { IRMetadata, IRProvenance } from "./primitives";
+import type { IRState } from "./state";
+import type { IRTransition } from "./transition";
+
+/**
+ * IR schema version. Bump when the shape changes in a backwards-incompatible
+ * way. The adapter rejects documents whose version it does not understand.
+ */
+export type IRVersion = "1.0";
+
+/**
+ * Axes that the spec <-> IR pairing gate compares. A document's
+ * `pairingPolicy.acceptDrift.axes` lists which of these are
+ * intentionally allowed to diverge between the legacy spec and the
+ * IR's forward projection.
+ */
+export type IRPairingAxis = "groupCount" | "groupIds" | "assertionCount";
+
+/**
+ * Per-document opt-out for specific spec<->IR pairing axes.
+ *
+ * The canonical use case is a hand-authored IR that uses a different
+ * grouping convention than the legacy spec. Without an explicit policy
+ * the pairing gate flags it as a mismatch on every PR, which trains
+ * reviewers to ignore the gate. The policy makes the divergence
+ * explicit and audit-friendly:
+ *
+ *   - `axes`     — which fingerprint comparisons to skip
+ *   - `reason`   — human-readable justification (required, surfaced in
+ *                  `check-spec-pairing` summary output)
+ *   - `since`    — ISO date (YYYY-MM-DD) the exemption was added
+ *   - `expiresAt` — optional ISO date (YYYY-MM-DD) after which the
+ *                   exemption stops applying. Forces periodic
+ *                   re-justification: the pairing gate downgrades
+ *                   expired exemptions back to ordinary mismatches.
+ *
+ * Mismatches NOT covered by the listed `axes` still fail the gate as
+ * usual — you can accept drift on `groupCount` while still requiring
+ * the assertion total to match.
+ */
+export interface IRAcceptDriftPolicy {
+  /** Fingerprint axes whose mismatches are tolerated. */
+  axes: IRPairingAxis[];
+  /** Human-readable justification for the exemption. */
+  reason: string;
+  /** ISO date (YYYY-MM-DD) the exemption was added. */
+  since: string;
+  /**
+   * Optional ISO date (YYYY-MM-DD) after which the exemption stops
+   * applying. The pairing gate then surfaces the document as an
+   * ordinary mismatch.
+   */
+  expiresAt?: string;
+}
+
+/**
+ * Per-document pairing policy block. Currently only carries
+ * `acceptDrift`; future policies (e.g. assertion-shape exemptions)
+ * can extend this without breaking the IR schema.
+ */
+export interface IRPairingPolicy {
+  /** Opt-out from specific spec<->IR pairing mismatch axes. */
+  acceptDrift?: IRAcceptDriftPolicy;
+}
+
+/**
+ * Top-level IR document.
+ */
+export interface IRDocument {
+  /** Schema version. */
+  version: IRVersion;
+  /** Stable document identifier (typically the page or scope name). */
+  id: string;
+  /** Human-readable document name. */
+  name: string;
+  /** Optional description of what this document covers. */
+  description?: string;
+  /** Document-level semantic metadata. */
+  metadata?: IRMetadata;
+  /** Where this document came from. */
+  provenance?: IRProvenance;
+
+  /**
+   * Per-document policy block — opt-out from specific spec<->IR
+   * pairing mismatches. Used by hand-authored IRs that intentionally
+   * diverge from the legacy spec shape.
+   */
+  pairingPolicy?: IRPairingPolicy;
+
+  /** State declarations within this document. */
+  states: IRState[];
+  /** Transition declarations within this document. */
+  transitions: IRTransition[];
+
+  /**
+   * Groups produced by workflow-criteria synthesis (not by IR state authoring).
+   * Synthesis appends to this list; the projection emits them after state-derived
+   * groups in legacy `groups[]` output. Authoring tools should treat this field
+   * as read-only.
+   */
+  synthesizedGroups?: IRGroup[];
+
+  /** ID of the initial/starting state, if applicable. */
+  initialState?: string;
+}