@beyondwork/docx-react-component 1.0.67 → 1.0.70

package/src/runtime/workflow/coordinator.ts

@@ -0,0 +1,1348 @@
+/**
+ * Layer 06 — Workflow coordinator.
+ *
+ * Owns the workflow/review orchestration that used to live inline in
+ * `document-runtime.ts`. The overlay store (`overlay-store.ts`) holds
+ * state + pure helpers; the coordinator plumbs that state through
+ * runtime-scoped dependencies (selection, revision token, render
+ * snapshot, page graph, dispatch, event emission) and exposes the
+ * full workflow public API plus the dispatch-branch handler.
+ *
+ * ## Contracts
+ *
+ * - W1 (marker-backed scopes) — scope marker pairs remain canonical
+ *   truth for scope location. This coordinator does not own markers;
+ *   it reads them through `collectScopeLocations` (via overlay-store
+ *   + query-scopes) and resolves anchors through `resolveScope`.
+ *
+ * - W3 (single interaction-guard verdict) — `getInteractionGuardSnapshot`
+ *   is the sole authority for effective mode + blocked reasons. The
+ *   snapshot caches against (revisionToken, activeStory, selection,
+ *   readOnly, documentMode, protectionSnapshot, overlay reference,
+ *   sharedWorkflowState).
+ *
+ * - W4 (AI action policy orthogonal to guard) — this coordinator does
+ *   not re-implement AI policy (see `ai-action-policy.ts`); guard
+ *   evaluation is input to AI policy, not vice versa.
+ *
+ * - W7 (rail is page-anchored) — `getRailSegments` / `getAllRailSegments`
+ *   / `getAllScopeCardModels` delegate to `collectScopeRailSegments`
+ *   over the coordinator's page-graph accessor. Layout is a
+ *   page-graph input source, not the owner.
+ *
+ * - W8 (tamper gate blocks on failure) — the coordinator reads
+ *   `sharedWorkflowState.lockedMode` through the overlay store and
+ *   short-circuits blocked-reasons evaluation when the round is
+ *   locked (matches the pre-extraction behavior).
+ *
+ * - W9 (no upward imports) — this file must not import from
+ *   `../document-runtime.ts`, `../render`, `../../ui*`, `../../api/v*`,
+ *   or `../../io`. Enforced by
+ *   `scripts/ci-check-workflow-layer-purity.mjs`.
+ */
+
+import type {
+  AddScopeParams,
+  AddScopeResult,
+  DocumentMode,
+  EditorAnchorProjection,
+  EditorStoryTarget,
+  FieldSnapshot,
+  InteractionGuardSnapshot,
+  ProtectionSnapshot,
+  RuntimeRenderSnapshot,
+  ScopeCardModel,
+  ScopeChromeVisibilityState,
+  ScopeQueryFilter,
+  ScopeQueryResult,
+  ScopeVisibility,
+  WorkflowBlockedCommandReason,
+  WorkflowCandidateRange,
+  WorkflowMarkupSnapshot,
+  WorkflowMetadataDefinition,
+  WorkflowMetadataEntry,
+  WorkflowMetadataSnapshot,
+  WorkflowOverlay,
+  WorkflowScope,
+  WorkflowScopeMode,
+  WorkflowScopeSnapshot,
+} from "../../api/public-types.ts";
+import {
+  type CanonicalDocumentEnvelope,
+  type EditorState,
+  type EditorWarning as InternalEditorWarning,
+} from "../../core/state/editor-state.ts";
+import type { SharedWorkflowState } from "../collab/workflow-shared.ts";
+import type { TelemetryBus } from "../debug/telemetry-bus.ts";
+import {
+  MAIN_STORY_TARGET,
+  storyTargetsEqual,
+} from "../../core/selection/mapping.ts";
+import { storyTargetKey } from "../story-targeting.ts";
+import { collectWorkflowMarkupSnapshot } from "./markup.ts";
+import {
+  collectScopeRailSegments,
+  attachScopeCardModel,
+  type CollectScopeRailSegmentsInput,
+} from "./rail/compose.ts";
+import type { ScopeRailSegment } from "./rail/types.ts";
+import {
+  queryScopes as runQueryScopes,
+  type ScopeQueryInputs,
+} from "./query-scopes.ts";
+import { resolveScope } from "./scope-resolver.ts";
+import { insertScopeMarkers, removeScopeMarkers } from "../../core/commands/add-scope.ts";
+import type { OverlayStore, MergeDetachedWarningsResult } from "./overlay-store.ts";
+import {
+  type OverlayKind,
+  type OverlayVisibilityPolicy,
+} from "./visibility-policy.ts";
+import { type WorkflowMarkupModePolicy } from "./markup-mode-policy.ts";
+
+/** Shape of origin metadata attached to commands. The runtime has a
+ * richer `CommandOrigin` type; we only pass it through, so we keep an
+ * open shape here to avoid coupling. */
+type CoordinatorCommandOrigin = { readonly source: string; readonly at?: string };
+
+/** Document-mutation commands the coordinator emits through `deps.dispatch`. */
+type CoordinatorDispatchedCommand =
+  | {
+      type: "workflow.set-overlay";
+      overlay: WorkflowOverlay;
+      origin: CoordinatorCommandOrigin;
+    }
+  | {
+      type: "workflow.clear-overlay";
+      origin: CoordinatorCommandOrigin;
+    }
+  | {
+      type: "workflow.set-metadata-definitions";
+      definitions: readonly WorkflowMetadataDefinition[];
+      origin: CoordinatorCommandOrigin;
+    }
+  | {
+      type: "workflow.clear-metadata-definitions";
+      origin: CoordinatorCommandOrigin;
+    }
+  | {
+      type: "workflow.set-metadata-entries";
+      entries: readonly WorkflowMetadataEntry[];
+      origin: CoordinatorCommandOrigin;
+    }
+  | {
+      type: "workflow.clear-metadata-entries";
+      origin: CoordinatorCommandOrigin;
+    }
+  | {
+      type: "document.replace";
+      document: CanonicalDocumentEnvelope;
+      origin: CoordinatorCommandOrigin;
+    };
+
+/** Editor-state channel — the coordinator records overlay + metadata
+ * mutations through this for collab broadcast. Matches the runtime's
+ * `editorStateChannel.recordMutation` signature. */
+export interface EditorStateChannel {
+  recordMutation(
+    namespace: string,
+    payload: { namespace: string; schemaVersion: string; data: unknown },
+  ): void;
+}
+
+/** Event-emission callback — the coordinator fires
+ * `workflow_overlay_changed`, `workflow_metadata_changed`, etc. via
+ * this. The runtime owns the event bus; the coordinator does not. */
+export interface WorkflowEmittableEvent {
+  readonly type:
+    | "workflow_overlay_changed"
+    | "workflow_active_work_item_changed"
+    | "workflow_metadata_changed";
+  readonly documentId: string;
+  readonly snapshot?: WorkflowScopeSnapshot | WorkflowMetadataSnapshot | null;
+  readonly activeWorkItemId?: string | null;
+}
+
+export interface PerfCounters {
+  increment(key: string, n?: number): void;
+}
+
+/** Runtime-scoped dependencies the coordinator needs. These are
+ * read-only accessors (pure functions of the runtime's current state)
+ * plus callbacks to dispatch commands, emit events, and record
+ * mutations — everything required to preserve current behavior. */
+export interface CoordinatorDeps {
+  readonly overlayStore: OverlayStore;
+  readonly telemetryBus: TelemetryBus;
+  readonly clock: () => string;
+  /** Current canonical document envelope. */
+  readonly getDocument: () => CanonicalDocumentEnvelope;
+  /** Current editor state (selection + revisionToken + readOnly + warnings). */
+  readonly getState: () => EditorState;
+  /** Active story target (main / header / footer / footnote / endnote). */
+  readonly getActiveStory: () => EditorStoryTarget;
+  /** View state accessor (documentMode used for guard composition). */
+  readonly getDocumentMode: () => DocumentMode;
+  /** Current protection snapshot (document protection + preserved ranges). */
+  readonly getProtectionSnapshot: () => ProtectionSnapshot;
+  /** Current render snapshot — used by markup + rail derivations. */
+  readonly getRenderSnapshot: () => RuntimeRenderSnapshot;
+  /** Field snapshot (used by markup). Runtime owns the cache; we just read. */
+  readonly getFieldSnapshot: () => FieldSnapshot;
+  /** Suggestions snapshot — used by scope-card composition. */
+  readonly getSuggestionsSnapshot: () => unknown;
+  /** Render-frame anchor index — used by scope-card composition. */
+  readonly getRenderFrameAnchorIndex: () => unknown;
+  /** Page graph — used by rail composition. */
+  readonly getPageGraph: () => CollectScopeRailSegmentsInput["pageGraph"];
+  /** Runtime's opaque-workflow-blocked-reason probe (preservation +
+   * blocked-import gating). Owned by the runtime because it reads
+   * preservation store and content-range overlap. */
+  readonly deriveOpaqueWorkflowBlockedReason: (
+    range: { from: number; to: number },
+  ) => WorkflowBlockedCommandReason | null;
+  /** Protection-blocked selection probe. Owned by the runtime. */
+  readonly isBlockedByProtection: (
+    protection: ProtectionSnapshot,
+    selection: EditorState["selection"],
+  ) => boolean;
+  /** Dispatch a runtime command. Used by addScope / removeScope /
+   * setWorkflowOverlay / etc. which route through the standard
+   * dispatch gate. */
+  readonly dispatch: (command: CoordinatorDispatchedCommand) => void;
+  /** Emit a workflow_* event to the runtime's event bus. */
+  readonly emitEvent: (event: WorkflowEmittableEvent) => void;
+  /** Runtime's editor-state channel (collab mutation log). */
+  readonly editorStateChannel: EditorStateChannel;
+  /** Set of command types that are unsupported in suggesting mode. */
+  readonly suggestingUnsupportedCommands: ReadonlySet<string>;
+}
+
+/** The coordinator's public API surface. The runtime forwards its
+ * public methods to these 1:1; cache invalidation flows through
+ * `invalidateCachesForDocumentMutation` + `invalidateGuardAndScopeCaches`. */
+export interface WorkflowCoordinator {
+  /* --- scope lifecycle (mutating, dispatch-backed) --- */
+  addScope(params: AddScopeParams): AddScopeResult;
+  removeScope(scopeId: string): void;
+  addInvisibleScope(params: AddScopeParams): AddScopeResult;
+  setScopeVisibility(scopeId: string, visibility: ScopeVisibility): void;
+  getScopeVisibility(scopeId: string): ScopeVisibility;
+  getScope(scopeId: string): WorkflowScope | null;
+  getMarkerBackedScopeIds(): ReadonlySet<string>;
+  /* --- scope chrome visibility (local view state) --- */
+  setScopeChromeVisibility(state: ScopeChromeVisibilityState): void;
+  getScopeChromeVisibility(): ScopeChromeVisibilityState;
+  /* --- overlay / metadata (mutating, dispatch-backed) --- */
+  setWorkflowOverlay(overlay: WorkflowOverlay): void;
+  clearWorkflowOverlay(): void;
+  getWorkflowOverlay(): WorkflowOverlay | null;
+  setWorkflowMetadataDefinitions(
+    definitions: readonly WorkflowMetadataDefinition[],
+  ): void;
+  clearWorkflowMetadataDefinitions(): void;
+  setWorkflowMetadataEntries(entries: readonly WorkflowMetadataEntry[]): void;
+  clearWorkflowMetadataEntries(): void;
+  getWorkflowMetadataSnapshot(): WorkflowMetadataSnapshot;
+  /* --- W10 overlay-visibility policy (class-A state) --- */
+  getVisibilityPolicy(kind: OverlayKind): OverlayVisibilityPolicy | null;
+  getVisibilityPolicies(): readonly OverlayVisibilityPolicy[];
+  setVisibilityPolicy(policy: OverlayVisibilityPolicy): boolean;
+  clearVisibilityPolicy(kind: OverlayKind): boolean;
+  /** Bulk replace — used by reload + collab state sync. */
+  replaceVisibilityPolicies(
+    policies: readonly OverlayVisibilityPolicy[],
+  ): boolean;
+  /** W10 — subscribe to any policy-set change. Consumed by L10 X3's
+   * `ui.overlays.subscribeVisibility` so authoring-tool mutations
+   * re-fire UI subscribers without a document reload. Returns an
+   * unsubscribe function. */
+  subscribeVisibilityPolicy(listener: () => void): () => void;
+  /* --- X5 · class-A markup-mode policy --- */
+  /** X5 — class-A markup-mode policy. `null` means the document carried
+   * no authored mode (consumer falls back to class-C local preference). */
+  getMarkupModePolicy(): WorkflowMarkupModePolicy | null;
+  /** X5 — author (or clear with `null`) the class-A markup-mode policy.
+   * Returns `true` when the record actually changed. Persists via
+   * customXml on next export + fires subscribers. */
+  setMarkupModePolicy(policy: WorkflowMarkupModePolicy | null): boolean;
+  /** X5 — subscribe to markup-mode policy changes. Consumed by L10's
+   * X5 consumer (`ui.viewport.getEffectiveMarkupMode` + its subscribe
+   * seam) so UI surfaces re-fire when policy changes mid-session. */
+  subscribeMarkupModePolicy(listener: () => void): () => void;
+  /* --- collab shared state --- */
+  setSharedWorkflowState(state: SharedWorkflowState | null): void;
+  /* --- snapshots (cached) --- */
+  getInteractionGuardSnapshot(): InteractionGuardSnapshot;
+  getWorkflowScopeSnapshot(): WorkflowScopeSnapshot | null;
+  getWorkflowMarkupSnapshot(): WorkflowMarkupSnapshot;
+  /* --- scope matching / blocked reasons --- */
+  evaluateBlockedReasons(
+    selection: EditorState["selection"],
+    commandType?: string,
+  ): WorkflowBlockedCommandReason[];
+  getMatchingScope(selection: EditorState["selection"]): WorkflowScope | null;
+  getMatchingScopeStack(
+    selection: EditorState["selection"],
+  ): readonly WorkflowScope[];
+  getEffectiveDocumentMode(selection: EditorState["selection"]): DocumentMode;
+  /* --- queries --- */
+  queryScopes(filter?: ScopeQueryFilter): ScopeQueryResult[];
+  /* --- rail / card (runtime.workflow facet backing) --- */
+  getRailSegments(pageIndex: number): readonly ScopeRailSegment[];
+  getAllRailSegments(): readonly ScopeRailSegment[];
+  getAllScopeCardModels(): readonly ScopeCardModel[];
+  /* --- dispatch branch handler (called from runtime's dispatch loop) --- */
+  applyOverlayCommand(
+    command: CoordinatorDispatchedCommand,
+    onRefreshRender: () => void,
+  ): MergeDetachedWarningsResult | null;
+  /* --- warning synthesis (called after document.replace) --- */
+  syncDetachedScopeWarnings(
+    existing: readonly InternalEditorWarning[],
+  ): MergeDetachedWarningsResult;
+  /* --- cache invalidation (called from runtime's cache-bust routines) --- */
+  invalidateCachesForDocumentMutation(): void;
+  invalidateGuardAndScopeCaches(): void;
+}
+
+/* ---------------------------------------------------------------- *\
+ * Factory
+\* ---------------------------------------------------------------- */
+
+const MODE_RESTRICTIVENESS: Record<WorkflowScopeMode, number> = {
+  edit: 0,
+  suggest: 1,
+  comment: 2,
+  view: 3,
+};
+
+export function createWorkflowCoordinator(deps: CoordinatorDeps): WorkflowCoordinator {
+  const { overlayStore, clock } = deps;
+
+  /* -------- snapshot caches (runtime-scope) -------- */
+
+  let cachedInteractionGuardSnapshot:
+    | {
+        revisionToken: string;
+        activeStoryKey: string;
+        selection: EditorState["selection"];
+        readOnly: boolean;
+        documentMode: DocumentMode;
+        protectionSnapshot: ProtectionSnapshot;
+        overlay: WorkflowOverlay | null;
+        sharedWorkflowState: SharedWorkflowState | null;
+        snapshot: InteractionGuardSnapshot;
+      }
+    | undefined;
+
+  let cachedWorkflowScopeSnapshot:
+    | {
+        overlay: WorkflowOverlay;
+        interactionGuardSnapshot: InteractionGuardSnapshot;
+        snapshot: WorkflowScopeSnapshot;
+      }
+    | undefined;
+
+  let cachedWorkflowMarkupSnapshot:
+    | {
+        revisionToken: string;
+        activeStoryKey: string;
+        protectionSnapshot: ProtectionSnapshot;
+        preservation: CanonicalDocumentEnvelope["preservation"];
+        overlay: WorkflowOverlay | null;
+        metadataDefinitions: readonly WorkflowMetadataDefinition[];
+        metadataEntries: readonly WorkflowMetadataEntry[];
+        snapshot: WorkflowMarkupSnapshot;
+      }
+    | undefined;
+
+  /* -------- normalized-overlay accessor (thin shim over store) -------- */
+
+  function getNormalizedOverlay(): WorkflowOverlay | null {
+    return overlayStore.getNormalizedOverlay(deps.getDocument());
+  }
+
+  /* -------- scope-matching (selection-scoped) -------- */
+
+  function getEffectiveWorkflowScopes(
+    overlay: WorkflowOverlay,
+  ): readonly WorkflowScope[] {
+    const activeStory = deps.getActiveStory();
+    const normalized = overlayStore.getNormalizedOverlay(deps.getDocument());
+    const source = normalized ?? overlay;
+    const activeWorkItemId = source.activeWorkItemId ?? null;
+    const activeWorkItemScopeIds =
+      activeWorkItemId === null
+        ? null
+        : new Set(
+            source.workItems?.find((item) => item.workItemId === activeWorkItemId)
+              ?.scopeIds ?? [],
+          );
+
+    return source.scopes.filter((scope) => {
+      const scopeStoryTarget = scope.storyTarget ?? MAIN_STORY_TARGET;
+      if (!storyTargetsEqual(scopeStoryTarget, activeStory)) {
+        return false;
+      }
+      if (activeWorkItemId === null) return true;
+      return (
+        scope.workItemId === activeWorkItemId ||
+        activeWorkItemScopeIds?.has(scope.scopeId) === true
+      );
+    });
+  }
+
+  function expandSelectionRange(range: {
+    from: number;
+    to: number;
+  }): { from: number; to: number } {
+    return {
+      from: range.from,
+      to: range.to > range.from ? range.to : range.from + 1,
+    };
+  }
+
+  function buildMatchingScopeStack(
+    selection: EditorState["selection"],
+  ): WorkflowScope[] {
+    const overlay = overlayStore.getOverlay();
+    if (!overlay) return [];
+    const selectionBounds = {
+      from: Math.min(selection.anchor, selection.head),
+      to: Math.max(selection.anchor, selection.head),
+    };
+    const activeScopes = getEffectiveWorkflowScopes(overlay);
+    const matching = activeScopes.filter((scope) => {
+      // §C8: invisible non-view scopes are transparent to the guard.
+      if (scope.visibility === "invisible" && scope.mode !== "view") return false;
+      if (scope.anchor.kind === "detached") return false;
+      const scopeFrom =
+        scope.anchor.kind === "range" ? scope.anchor.from : scope.anchor.at;
+      const scopeTo =
+        scope.anchor.kind === "range" ? scope.anchor.to : scope.anchor.at;
+      return selectionBounds.from >= scopeFrom && selectionBounds.to <= scopeTo;
+    });
+    // §C6 — outermost first: startPos ASC, endPos DESC, scopeId ASC tiebreak.
+    matching.sort((a, b) => {
+      const aFrom =
+        a.anchor.kind === "range"
+          ? a.anchor.from
+          : (a.anchor as { at: number }).at;
+      const bFrom =
+        b.anchor.kind === "range"
+          ? b.anchor.from
+          : (b.anchor as { at: number }).at;
+      if (aFrom !== bFrom) return aFrom - bFrom;
+      const aTo =
+        a.anchor.kind === "range" ? a.anchor.to : (a.anchor as { at: number }).at;
+      const bTo =
+        b.anchor.kind === "range" ? b.anchor.to : (b.anchor as { at: number }).at;
+      if (aTo !== bTo) return bTo - aTo;
+      return a.scopeId < b.scopeId ? -1 : a.scopeId > b.scopeId ? 1 : 0;
+    });
+    return matching;
+  }
+
+  function getMatchingWorkflowScope(
+    selection: EditorState["selection"],
+  ): WorkflowScope | null {
+    const stack = buildMatchingScopeStack(selection);
+    if (stack.length === 0) return null;
+    // §C6 — most-restrictive-wins across overlapping scopes.
+    return stack.reduce((best, scope) =>
+      (MODE_RESTRICTIVENESS[scope.mode] ?? 0) >
+      (MODE_RESTRICTIVENESS[best.mode] ?? 0)
+        ? scope
+        : best,
+    );
+  }
+
+  function getEffectiveDocumentMode(
+    selection: EditorState["selection"],
+  ): DocumentMode {
+    const mode = deps.getDocumentMode();
+    if (mode === "viewing" || mode === "commenting") return mode;
+    const matchingScope = getMatchingWorkflowScope(selection);
+    if (matchingScope?.mode === "suggest") return "suggesting";
+    return mode;
+  }
+
+  function evaluateBlockedReasons(
+    selection: EditorState["selection"],
+    commandType?: string,
+  ): WorkflowBlockedCommandReason[] {
+    const reasons: WorkflowBlockedCommandReason[] = [];
+    const sharedWorkflowState = overlayStore.getSharedWorkflowState();
+    if (
+      sharedWorkflowState?.lockedMode &&
+      sharedWorkflowState.lockedMode !== "editing"
+    ) {
+      const lockedMode = sharedWorkflowState.lockedMode;
+      const code: WorkflowBlockedCommandReason["code"] =
+        lockedMode === "commenting"
+          ? "workflow_comment_only"
+          : lockedMode === "viewing"
+            ? "workflow_view_only"
+            : "workflow_round_locked";
+      reasons.push({
+        code,
+        message: `Round is locked to ${lockedMode} mode.`,
+      });
+      return reasons;
+    }
+
+    const selectionBounds = {
+      from: Math.min(selection.anchor, selection.head),
+      to: Math.max(selection.anchor, selection.head),
+    };
+    const selectionRange = expandSelectionRange(selectionBounds);
+    const opaqueReason = deps.deriveOpaqueWorkflowBlockedReason(selectionRange);
+    if (opaqueReason) reasons.push(opaqueReason);
+
+    const state = deps.getState();
+    if (state.readOnly) {
+      reasons.push({
+        code: "document_read_only",
+        message: "Document is in read-only mode.",
+      });
+    }
+
+    const documentMode = deps.getDocumentMode();
+    if (documentMode === "viewing" || documentMode === "commenting") {
+      reasons.push({
+        code: "document_viewing_mode",
+        message: "Document is in viewing mode.",
+      });
+    }
+
+    if (deps.isBlockedByProtection(deps.getProtectionSnapshot(), selection)) {
+      reasons.push({
+        code: "protected_range",
+        message: "Selection falls within a protected range.",
+      });
+    }
+
+    const effectiveDocumentMode = getEffectiveDocumentMode(selection);
+    if (effectiveDocumentMode === "suggesting" && commandType) {
+      if (deps.suggestingUnsupportedCommands.has(commandType)) {
+        reasons.push({
+          code: "suggesting_unsupported",
+          message: `"${commandType}" is not supported in suggesting mode.`,
+        });
+      }
+    }
+
+    const normalized = getNormalizedOverlay();
+    if (normalized) {
+      const matchingScope = getMatchingWorkflowScope(selection);
+      const activeScopes = getEffectiveWorkflowScopes(normalized);
+      const guardingScopes = activeScopes.filter(
+        (s) => !(s.visibility === "invisible" && s.mode !== "view"),
+      );
+
+      if (!matchingScope && guardingScopes.length > 0) {
+        reasons.push({
+          code: "outside_workflow_scope",
+          message: "Selection is outside any active workflow scope.",
+        });
+      } else if (matchingScope) {
+        if (matchingScope.mode === "comment") {
+          const isCommentCommand = commandType?.startsWith("comment.") ?? false;
+          if (!isCommentCommand) {
+            reasons.push({
+              code: "workflow_comment_only",
+              message: `Scope "${matchingScope.label ?? matchingScope.scopeId}" allows comments only.`,
+              scopeId: matchingScope.scopeId,
+              workItemId: matchingScope.workItemId,
+            });
+          }
+        } else if (matchingScope.mode === "view") {
+          reasons.push({
+            code: "workflow_view_only",
+            message: `Scope "${matchingScope.label ?? matchingScope.scopeId}" is view-only.`,
+            scopeId: matchingScope.scopeId,
+            workItemId: matchingScope.workItemId,
+          });
+        }
+      }
+    }
+
+    return reasons;
+  }
+
+  /* -------- snapshot derivations (cached) -------- */
+
+  function deriveWorkflowScopeSnapshot(): WorkflowScopeSnapshot | null {
+    const normalized = getNormalizedOverlay();
+    if (!normalized) return null;
+    const guardSnapshot = getCachedInteractionGuardSnapshot();
+    const activeItem = normalized.activeWorkItemId
+      ? normalized.workItems?.find(
+          (item) => item.workItemId === normalized.activeWorkItemId,
+        )
+      : undefined;
+    return {
+      overlayPresent: true,
+      activeWorkItemId: normalized.activeWorkItemId ?? null,
+      activeWorkItem: activeItem,
+      scopes: normalized.scopes,
+      candidates: normalized.candidates ?? [],
+      blockedReasons: guardSnapshot.blockedReasons,
+    };
+  }
+
+  function getCachedInteractionGuardSnapshot(): InteractionGuardSnapshot {
+    const state = deps.getState();
+    const activeStory = deps.getActiveStory();
+    const activeStoryKey = storyTargetKey(activeStory);
+    const protectionSnapshot = deps.getProtectionSnapshot();
+    const documentMode = deps.getDocumentMode();
+    const overlay = overlayStore.getOverlay();
+    const sharedWorkflowState = overlayStore.getSharedWorkflowState();
+
+    if (
+      cachedInteractionGuardSnapshot &&
+      cachedInteractionGuardSnapshot.revisionToken === state.revisionToken &&
+      cachedInteractionGuardSnapshot.activeStoryKey === activeStoryKey &&
+      cachedInteractionGuardSnapshot.selection === state.selection &&
+      cachedInteractionGuardSnapshot.readOnly === state.readOnly &&
+      cachedInteractionGuardSnapshot.documentMode === documentMode &&
+      cachedInteractionGuardSnapshot.protectionSnapshot === protectionSnapshot &&
+      cachedInteractionGuardSnapshot.overlay === overlay &&
+      cachedInteractionGuardSnapshot.sharedWorkflowState === sharedWorkflowState
+    ) {
+      return cachedInteractionGuardSnapshot.snapshot;
+    }
+
+    const blockedReasons = evaluateBlockedReasons(state.selection);
+    const matchingScope = getMatchingWorkflowScope(state.selection);
+    const scopeStack = buildMatchingScopeStack(state.selection);
+    const primaryBlockedReason = blockedReasons[0];
+    const effectiveMode = primaryBlockedReason
+      ? primaryBlockedReason.code === "workflow_comment_only"
+        ? "comment"
+        : primaryBlockedReason.code === "workflow_view_only"
+          ? "view"
+          : "blocked"
+      : getEffectiveDocumentMode(state.selection) === "suggesting"
+        ? "suggest"
+        : matchingScope?.mode ?? "edit";
+    const matchedScopeStack: InteractionGuardSnapshot["matchedScopeStack"] =
+      scopeStack.length > 0
+        ? scopeStack.map((s) => ({
+            scopeId: s.scopeId,
+            mode: s.mode,
+            visibility: s.visibility ?? "visible",
+          }))
+        : undefined;
+    const snapshot: InteractionGuardSnapshot = {
+      effectiveMode,
+      ...(matchingScope?.scopeId ? { matchedScopeId: matchingScope.scopeId } : {}),
+      ...(matchingScope?.mode ? { matchedScopeMode: matchingScope.mode } : {}),
+      ...(matchedScopeStack ? { matchedScopeStack } : {}),
+      targetAccess:
+        effectiveMode === "edit"
+          ? "direct-edit"
+          : effectiveMode === "suggest"
+            ? "suggest"
+            : effectiveMode === "comment"
+              ? "comment-only"
+              : effectiveMode === "view"
+                ? "view-only"
+                : "blocked",
+      commandCapabilities: [
+        {
+          family: "text",
+          supported:
+            evaluateBlockedReasons(state.selection, "text.insert").length === 0,
+          blockedReasons: evaluateBlockedReasons(state.selection, "text.insert"),
+        },
+        {
+          family: "formatting",
+          supported:
+            evaluateBlockedReasons(state.selection, "toggleBold").length === 0,
+          blockedReasons: evaluateBlockedReasons(state.selection, "toggleBold"),
+        },
+        {
+          family: "structure",
+          supported:
+            evaluateBlockedReasons(state.selection, "insertTable").length === 0,
+          blockedReasons: evaluateBlockedReasons(state.selection, "insertTable"),
+        },
+      ],
+      ...(primaryBlockedReason ? { disabledReason: primaryBlockedReason.message } : {}),
+      blockedReasons,
+    };
+    cachedInteractionGuardSnapshot = {
+      revisionToken: state.revisionToken,
+      activeStoryKey,
+      selection: state.selection,
+      readOnly: state.readOnly,
+      documentMode,
+      protectionSnapshot,
+      overlay,
+      sharedWorkflowState,
+      snapshot,
+    };
+    return snapshot;
+  }
+
+  function getCachedWorkflowScopeSnapshot(): WorkflowScopeSnapshot | null {
+    const overlay = overlayStore.getOverlay();
+    if (!overlay) return null;
+    const interactionGuardSnapshot = getCachedInteractionGuardSnapshot();
+    if (
+      cachedWorkflowScopeSnapshot &&
+      cachedWorkflowScopeSnapshot.overlay === overlay &&
+      cachedWorkflowScopeSnapshot.interactionGuardSnapshot === interactionGuardSnapshot
+    ) {
+      return cachedWorkflowScopeSnapshot.snapshot;
+    }
+    const snapshot = deriveWorkflowScopeSnapshot()!;
+    cachedWorkflowScopeSnapshot = {
+      overlay,
+      interactionGuardSnapshot,
+      snapshot,
+    };
+    return snapshot;
+  }
+
+  function getCachedWorkflowMarkupSnapshot(): WorkflowMarkupSnapshot {
+    const state = deps.getState();
+    const activeStory = deps.getActiveStory();
+    const activeStoryKey = storyTargetKey(activeStory);
+    const protectionSnapshot = deps.getProtectionSnapshot();
+    const preservation = deps.getDocument().preservation;
+    const overlay = overlayStore.getOverlay();
+    const metadataDefinitions = overlayStore.getMetadataDefinitions();
+    const metadataEntries = overlayStore.getMetadataEntries();
+
+    if (
+      cachedWorkflowMarkupSnapshot &&
+      cachedWorkflowMarkupSnapshot.revisionToken === state.revisionToken &&
+      cachedWorkflowMarkupSnapshot.activeStoryKey === activeStoryKey &&
+      cachedWorkflowMarkupSnapshot.protectionSnapshot === protectionSnapshot &&
+      cachedWorkflowMarkupSnapshot.preservation === preservation &&
+      cachedWorkflowMarkupSnapshot.overlay === overlay &&
+      cachedWorkflowMarkupSnapshot.metadataDefinitions === metadataDefinitions &&
+      cachedWorkflowMarkupSnapshot.metadataEntries === metadataEntries
+    ) {
+      return cachedWorkflowMarkupSnapshot.snapshot;
+    }
+
+    const snapshot = collectWorkflowMarkupSnapshot({
+      renderSnapshot: deps.getRenderSnapshot(),
+      fieldSnapshot: deps.getFieldSnapshot(),
+      protectionSnapshot,
+      preservation,
+      workflowMetadataSnapshot: overlayStore.getMetadataSnapshot(),
+    });
+    cachedWorkflowMarkupSnapshot = {
+      revisionToken: state.revisionToken,
+      activeStoryKey,
+      protectionSnapshot,
+      preservation,
+      overlay,
+      metadataDefinitions,
+      metadataEntries,
+      snapshot,
+    };
+    return snapshot;
+  }
+
+  /* -------- rail composition -------- */
+
+  function buildRailInput(): {
+    scopes: readonly WorkflowScope[];
+    candidates?: readonly WorkflowCandidateRange[];
+    activeWorkItemScopeIds: readonly string[];
+    activeStory: EditorStoryTarget;
+  } | null {
+    const normalized = getNormalizedOverlay();
+    if (!normalized) return null;
+    const activeWorkItemId = normalized.activeWorkItemId ?? null;
+    const activeWorkItem =
+      activeWorkItemId !== null
+        ? normalized.workItems?.find(
+            (item) => item.workItemId === activeWorkItemId,
+          )
+        : undefined;
+    return {
+      scopes: normalized.scopes,
+      candidates: normalized.candidates,
+      activeWorkItemScopeIds: activeWorkItem?.scopeIds ?? [],
+      activeStory: deps.getActiveStory(),
+    };
+  }
+
+  /* -------- scope lifecycle (mutating) -------- */
+
+  function addScope(params: AddScopeParams): AddScopeResult {
+    const state = deps.getState();
+    const scopeId =
+      params.scopeId ??
+      `scope-${clock().replace(/[^0-9]/gu, "")}-${Math.floor(Math.random() * 1e6)}`;
+    const anchor =
+      params.anchor.kind === "range"
+        ? { from: params.anchor.from, to: params.anchor.to }
+        : null;
+
+    if (!anchor) {
+      return { scopeId, anchor: params.anchor };
+    }
+
+    const { document: nextDocument } = insertScopeMarkers(
+      deps.getDocument(),
+      { scopeId, from: anchor.from, to: anchor.to },
+    );
+
+    if (nextDocument !== deps.getDocument()) {
+      deps.dispatch({
+        type: "document.replace",
+        document: nextDocument,
+        origin: { source: "api", at: clock() },
+      });
+    }
+
+    // Coord-06 §13d — preserve the caller's assoc on the public anchor.
+    // resolveScope re-derives the range from the inserted markers but emits
+    // a hardcoded { start: -1, end: 1 }; without this override the caller's
+    // per-scope edge-stickiness choice is silently dropped before the scope
+    // ever lands on the overlay.
+    const callerAssoc: { readonly start: -1 | 1; readonly end: -1 | 1 } =
+      params.anchor.kind === "range"
+        ? params.anchor.assoc
+        : { start: -1, end: 1 };
+    const resolved = resolveScope(nextDocument, scopeId);
+    const publicAnchor: EditorAnchorProjection =
+      resolved && resolved.kind === "range"
+        ? { ...resolved, assoc: callerAssoc }
+        : {
+            kind: "range",
+            from: anchor.from,
+            to: anchor.to,
+            assoc: callerAssoc,
+          };
+
+    const currentOverlay: WorkflowOverlay =
+      overlayStore.getOverlay() ?? {
+        overlayVersion: "workflow-overlay/1",
+        scopes: [],
+      };
+    const existingScopes = currentOverlay.scopes.filter(
+      (existing) => existing.scopeId !== scopeId,
+    );
+    const scope: WorkflowScope = {
+      scopeId,
+      mode: params.mode ?? "comment",
+      anchor: publicAnchor,
+      ...(params.storyTarget ? { storyTarget: params.storyTarget } : {}),
+      ...(params.label ? { label: params.label } : {}),
+    };
+
+    deps.dispatch({
+      type: "workflow.set-overlay",
+      overlay: { ...currentOverlay, scopes: [...existingScopes, scope] },
+      origin: { source: "api", at: clock() },
+    });
+
+    if (params.persistence && params.persistence !== "runtime-only") {
+      const requestedMetadata = params.metadata ?? {};
+      const entryPersistence =
+        requestedMetadata.metadataPersistence ??
+        (params.persistence === "session" ? "external" : "internal");
+      const entry: WorkflowMetadataEntry = {
+        entryId: requestedMetadata.entryId ?? `scope-metadata-${scopeId}`,
+        metadataId: requestedMetadata.metadataId ?? "workflow.scope",
+        anchor: publicAnchor,
+        ...(params.storyTarget ? { storyTarget: params.storyTarget } : {}),
+        scopeId,
+        ...(requestedMetadata.workItemId
+          ? { workItemId: requestedMetadata.workItemId }
+          : {}),
+        ...(requestedMetadata.value !== undefined
+          ? { value: requestedMetadata.value }
+          : params.persistence === "document-metadata" && params.label
+            ? { value: { label: params.label } }
+            : {}),
+        metadataPersistence: entryPersistence,
+        ...(requestedMetadata.storageRef !== undefined
+          ? { storageRef: requestedMetadata.storageRef }
+          : {}),
+        ...(requestedMetadata.metadataVersion !== undefined
+          ? { metadataVersion: requestedMetadata.metadataVersion }
+          : {}),
+      };
+      const priorEntries = overlayStore.getMetadataEntries();
+      deps.dispatch({
+        type: "workflow.set-metadata-entries",
+        entries: [...priorEntries, entry],
+        origin: { source: "api", at: clock() },
+      });
+    }
+
+    return { scopeId, anchor: publicAnchor };
+  }
+
+  function removeScope(scopeId: string): void {
+    // Step 1: drop from overlay first (the workflow-blocked-reasons
+    // gate in dispatch would otherwise refuse the subsequent
+    // document.replace on comment/view scopes).
+    const overlay = overlayStore.getOverlay();
+    if (overlay) {
+      const nextScopes = overlay.scopes.filter((s) => s.scopeId !== scopeId);
+      if (nextScopes.length !== overlay.scopes.length) {
+        deps.dispatch({
+          type: "workflow.set-overlay",
+          overlay: { ...overlay, scopes: nextScopes },
+          origin: { source: "api", at: clock() },
+        });
+      }
+    }
+    // Step 2: strip markers from doc.
+    const nextDocument = removeScopeMarkers(deps.getDocument(), scopeId);
+    if (nextDocument !== deps.getDocument()) {
+      deps.dispatch({
+        type: "document.replace",
+        document: nextDocument,
+        origin: { source: "api", at: clock() },
+      });
+    }
+    // Step 3: clear customXml-persisted metadata entries.
+    const entries = overlayStore.getMetadataEntries();
+    const nextEntries = entries.filter((e) => e.scopeId !== scopeId);
+    if (nextEntries.length !== entries.length) {
+      deps.dispatch({
+        type: "workflow.set-metadata-entries",
+        entries: nextEntries,
+        origin: { source: "api", at: clock() },
+      });
+    }
+  }
+
+  function addInvisibleScope(params: AddScopeParams): AddScopeResult {
+    const result = addScope({ ...params, mode: params.mode ?? "comment" });
+    setScopeVisibility(result.scopeId, "invisible");
+    return result;
+  }
+
+  function setScopeVisibility(
+    scopeId: string,
+    visibility: ScopeVisibility,
+  ): void {
+    const overlay = overlayStore.getOverlay();
+    if (!overlay) return;
+    const idx = overlay.scopes.findIndex((s) => s.scopeId === scopeId);
+    if (idx === -1) return;
+    const nextScopes = overlay.scopes.map((s) =>
+      s.scopeId === scopeId ? { ...s, visibility } : s,
+    );
+    deps.dispatch({
+      type: "workflow.set-overlay",
+      overlay: { ...overlay, scopes: nextScopes },
+      origin: { source: "api", at: clock() },
+    });
+  }
+
+  function getScopeVisibility(scopeId: string): ScopeVisibility {
+    const overlay = overlayStore.getOverlay();
+    if (!overlay) return "visible";
+    const scope = overlay.scopes.find((s) => s.scopeId === scopeId);
+    return scope?.visibility ?? "visible";
+  }
+
+  function getScope(scopeId: string): WorkflowScope | null {
+    const normalized = getNormalizedOverlay();
+    const fromOverlay = normalized?.scopes.find((s) => s.scopeId === scopeId);
+    if (fromOverlay) return fromOverlay;
+    const resolved = resolveScope(deps.getDocument(), scopeId);
+    if (!resolved) return null;
+    return { scopeId, mode: "comment", anchor: resolved };
+  }
+
+  /* -------- overlay / metadata setters (dispatch-backed) -------- */
+
+  function setWorkflowOverlay(overlay: WorkflowOverlay): void {
+    deps.dispatch({
+      type: "workflow.set-overlay",
+      overlay,
+      origin: { source: "api", at: clock() },
+    });
+    const normalized = getNormalizedOverlay();
+    deps.editorStateChannel.recordMutation("workflowOverlay", {
+      namespace: "workflowOverlay",
+      schemaVersion: "workflow-overlay/1",
+      data: normalized ?? overlay,
+    });
+  }
+
+  function clearWorkflowOverlay(): void {
+    deps.dispatch({
+      type: "workflow.clear-overlay",
+      origin: { source: "api", at: clock() },
+    });
+  }
+
+  function getWorkflowOverlay(): WorkflowOverlay | null {
+    return getNormalizedOverlay();
+  }
+
+  function setWorkflowMetadataDefinitions(
+    definitions: readonly WorkflowMetadataDefinition[],
+  ): void {
+    deps.dispatch({
+      type: "workflow.set-metadata-definitions",
+      definitions,
+      origin: { source: "api", at: clock() },
+    });
+  }
+
+  function clearWorkflowMetadataDefinitions(): void {
+    deps.dispatch({
+      type: "workflow.clear-metadata-definitions",
+      origin: { source: "api", at: clock() },
+    });
+  }
+
+  function setWorkflowMetadataEntries(
+    entries: readonly WorkflowMetadataEntry[],
+  ): void {
+    deps.dispatch({
+      type: "workflow.set-metadata-entries",
+      entries,
+      origin: { source: "api", at: clock() },
+    });
+    deps.editorStateChannel.recordMutation("workflowMetadata", {
+      namespace: "workflowMetadata",
+      schemaVersion: "workflow-metadata/1",
+      data: entries,
+    });
+  }
+
+  function clearWorkflowMetadataEntries(): void {
+    deps.dispatch({
+      type: "workflow.clear-metadata-entries",
+      origin: { source: "api", at: clock() },
+    });
+  }
+
+  function getWorkflowMetadataSnapshot(): WorkflowMetadataSnapshot {
+    return overlayStore.getMetadataSnapshot();
+  }
+
+  function setSharedWorkflowState(state: SharedWorkflowState | null): void {
+    const prior = overlayStore.getSharedWorkflowState();
+    if (state === prior) return;
+    overlayStore.replaceSharedWorkflowState(state);
+    cachedInteractionGuardSnapshot = undefined;
+    cachedWorkflowScopeSnapshot = undefined;
+  }
+
+  function setScopeChromeVisibility(state: ScopeChromeVisibilityState): void {
+    overlayStore.replaceScopeChromeVisibility(state);
+  }
+
+  function getScopeChromeVisibility(): ScopeChromeVisibilityState {
+    return overlayStore.getScopeChromeVisibility();
+  }
+
+  /* -------- W10 overlay-visibility policy (class-A) -------- */
+
+  function getVisibilityPolicy(kind: OverlayKind): OverlayVisibilityPolicy | null {
+    return overlayStore.getVisibilityPolicy(kind);
+  }
+
+  function getVisibilityPolicies(): readonly OverlayVisibilityPolicy[] {
+    return overlayStore.getVisibilityPolicies();
+  }
+
+  function setVisibilityPolicy(policy: OverlayVisibilityPolicy): boolean {
+    const changed = overlayStore.replaceVisibilityPolicy(policy.kind, policy);
+    if (changed) emitVisibilityPolicyChanged();
+    return changed;
+  }
+
+  function clearVisibilityPolicy(kind: OverlayKind): boolean {
+    const changed = overlayStore.replaceVisibilityPolicy(kind, null);
+    if (changed) emitVisibilityPolicyChanged();
+    return changed;
+  }
+
+  function replaceVisibilityPoliciesBulk(
+    policies: readonly OverlayVisibilityPolicy[],
+  ): boolean {
+    const changed = overlayStore.replaceVisibilityPolicies(policies);
+    if (changed) emitVisibilityPolicyChanged();
+    return changed;
+  }
+
+  function subscribeVisibilityPolicy(listener: () => void): () => void {
+    return overlayStore.subscribeVisibilityPolicy(listener);
+  }
+
+  /* -------- X5 class-A markup-mode policy -------- */
+
+  function getMarkupModePolicy(): WorkflowMarkupModePolicy | null {
+    return overlayStore.getMarkupModePolicy();
+  }
+
+  function setMarkupModePolicy(
+    policy: WorkflowMarkupModePolicy | null,
+  ): boolean {
+    const changed = overlayStore.replaceMarkupModePolicy(policy);
+    if (changed) {
+      overlayStore.notifyMarkupModePolicyChanged();
+      if (deps.telemetryBus.isEnabled("scope")) {
+        deps.telemetryBus.emit({
+          channel: "scope",
+          type: "scope.markup_mode_policy_changed",
+          t: 0,
+          payload: { hasPolicy: policy !== null },
+        });
+      }
+    }
+    return changed;
+  }
+
+  function subscribeMarkupModePolicy(listener: () => void): () => void {
+    return overlayStore.subscribeMarkupModePolicy(listener);
+  }
+
+  function emitVisibilityPolicyChanged(): void {
+    // Notify direct subscribers first — L10 X3's ui.overlays.subscribeVisibility
+    // chains onto this signal so UI surfaces re-fire when an authoring tool
+    // mutates policy mid-session.
+    overlayStore.notifyVisibilityPolicyChanged();
+    if (!deps.telemetryBus.isEnabled("scope")) return;
+    deps.telemetryBus.emit({
+      channel: "scope",
+      type: "scope.visibility_policy_changed",
+      t: 0,
+      payload: {
+        total: overlayStore.getVisibilityPolicies().length,
+      },
+    });
+  }
+
+  /* -------- queries + rail -------- */
+
+  function queryScopes(filter?: ScopeQueryFilter): ScopeQueryResult[] {
+    const inputs: ScopeQueryInputs = {
+      overlay: overlayStore.getOverlay(),
+      entries: overlayStore.getMetadataEntries(),
+      document: deps.getDocument(),
+      markerBackedScopeIds: overlayStore.getMarkerBackedScopeIds(),
+    };
+    return runQueryScopes(inputs, filter);
+  }
+
+  function getRailSegments(pageIndex: number): readonly ScopeRailSegment[] {
+    const input = buildRailInput();
+    if (!input) return [];
+    return collectScopeRailSegments({
+      ...input,
+      pageGraph: deps.getPageGraph(),
+    }).filter((segment) => segment.pageIndex === pageIndex);
+  }
+
+  function getAllRailSegments(): readonly ScopeRailSegment[] {
+    const input = buildRailInput();
+    if (!input) return [];
+    return collectScopeRailSegments({
+      ...input,
+      pageGraph: deps.getPageGraph(),
+    });
+  }
+
+  function getAllScopeCardModels(): readonly ScopeCardModel[] {
+    const railInput = buildRailInput();
+    if (!railInput) return [];
+    const segments = collectScopeRailSegments({
+      ...railInput,
+      pageGraph: deps.getPageGraph(),
+    });
+    if (segments.length === 0) return [];
+    const metadata = getCachedWorkflowMarkupSnapshot().metadata;
+    // deps returns `unknown` for suggestions / anchor-index — cast at
+    // the composition boundary because attachScopeCardModel's types
+    // accept the runtime-shaped values verbatim.
+    return attachScopeCardModel({
+      segments,
+      scopes: railInput.scopes ?? [],
+      metadata,
+      anchorIndex: deps.getRenderFrameAnchorIndex() as never,
+      suggestions: deps.getSuggestionsSnapshot() as never,
+      reviewActionMetadata: metadata,
+      candidates: railInput.candidates,
+    });
+  }
+
+  /* -------- dispatch branch handler -------- */
+
+  function applyOverlayCommand(
+    command: CoordinatorDispatchedCommand,
+    onRefreshRender: () => void,
+  ): MergeDetachedWarningsResult | null {
+    const documentId = deps.getState().documentId;
+    switch (command.type) {
+      case "workflow.set-overlay": {
+        overlayStore.replaceOverlay(command.overlay, deps.getDocument());
+        const state = deps.getState();
+        const warningDelta = overlayStore.mergeDetachedScopeWarnings(
+          getNormalizedOverlay(),
+          state.warnings,
+        );
+        onRefreshRender();
+        const snapshot = deriveWorkflowScopeSnapshot()!;
+        deps.emitEvent({
+          type: "workflow_overlay_changed",
+          documentId,
+          snapshot,
+        });
+        if (command.overlay.activeWorkItemId !== undefined) {
+          deps.emitEvent({
+            type: "workflow_active_work_item_changed",
+            documentId,
+            activeWorkItemId: command.overlay.activeWorkItemId ?? null,
+          });
+        }
+        return warningDelta;
+      }
+      case "workflow.clear-overlay": {
+        overlayStore.replaceOverlay(null, deps.getDocument());
+        const state = deps.getState();
+        const warningDelta = overlayStore.mergeDetachedScopeWarnings(
+          null,
+          state.warnings,
+        );
+        onRefreshRender();
+        deps.emitEvent({
+          type: "workflow_active_work_item_changed",
+          documentId,
+          activeWorkItemId: null,
+        });
+        deps.emitEvent({
+          type: "workflow_overlay_changed",
+          documentId,
+          snapshot: {
+            overlayPresent: false,
+            activeWorkItemId: null,
+            scopes: [],
+            candidates: [],
+            blockedReasons: [],
+          },
+        });
+        return warningDelta;
+      }
+      case "workflow.set-metadata-definitions": {
+        overlayStore.replaceMetadataDefinitions(command.definitions);
+        deps.emitEvent({
+          type: "workflow_metadata_changed",
+          documentId,
+          snapshot: overlayStore.getMetadataSnapshot(),
+        });
+        return null;
+      }
+      case "workflow.clear-metadata-definitions": {
+        overlayStore.replaceMetadataDefinitions([]);
+        deps.emitEvent({
+          type: "workflow_metadata_changed",
+          documentId,
+          snapshot: overlayStore.getMetadataSnapshot(),
+        });
+        return null;
+      }
+      case "workflow.set-metadata-entries": {
+        overlayStore.replaceMetadataEntries(command.entries);
+        deps.emitEvent({
+          type: "workflow_metadata_changed",
+          documentId,
+          snapshot: overlayStore.getMetadataSnapshot(),
+        });
+        return null;
+      }
+      case "workflow.clear-metadata-entries": {
+        overlayStore.replaceMetadataEntries([]);
+        deps.emitEvent({
+          type: "workflow_metadata_changed",
+          documentId,
+          snapshot: overlayStore.getMetadataSnapshot(),
+        });
+        return null;
+      }
+      default:
+        return null;
+    }
+  }
+
+  /* -------- warning synthesis (called after document mutations) -------- */
+
+  function syncDetachedScopeWarnings(
+    existing: readonly InternalEditorWarning[],
+  ): MergeDetachedWarningsResult {
+    return overlayStore.mergeDetachedScopeWarnings(
+      getNormalizedOverlay(),
+      existing,
+    );
+  }
+
+  /* -------- cache invalidation -------- */
+
+  function invalidateCachesForDocumentMutation(): void {
+    cachedInteractionGuardSnapshot = undefined;
+    cachedWorkflowScopeSnapshot = undefined;
+    cachedWorkflowMarkupSnapshot = undefined;
+  }
+
+  function invalidateGuardAndScopeCaches(): void {
+    cachedInteractionGuardSnapshot = undefined;
+    cachedWorkflowScopeSnapshot = undefined;
+  }
+
+  /* -------- public API surface -------- */
+
+  return {
+    addScope,
+    removeScope,
+    addInvisibleScope,
+    setScopeVisibility,
+    getScopeVisibility,
+    getScope,
+    getMarkerBackedScopeIds: () => overlayStore.getMarkerBackedScopeIds(),
+    setScopeChromeVisibility,
+    getScopeChromeVisibility,
+    getVisibilityPolicy,
+    getVisibilityPolicies,
+    setVisibilityPolicy,
+    clearVisibilityPolicy,
+    replaceVisibilityPolicies: replaceVisibilityPoliciesBulk,
+    subscribeVisibilityPolicy,
+    getMarkupModePolicy,
+    setMarkupModePolicy,
+    subscribeMarkupModePolicy,
+    setWorkflowOverlay,
+    clearWorkflowOverlay,
+    getWorkflowOverlay,
+    setWorkflowMetadataDefinitions,
+    clearWorkflowMetadataDefinitions,
+    setWorkflowMetadataEntries,
+    clearWorkflowMetadataEntries,
+    getWorkflowMetadataSnapshot,
+    setSharedWorkflowState,
+    getInteractionGuardSnapshot: getCachedInteractionGuardSnapshot,
+    getWorkflowScopeSnapshot: getCachedWorkflowScopeSnapshot,
+    getWorkflowMarkupSnapshot: getCachedWorkflowMarkupSnapshot,
+    evaluateBlockedReasons,
+    getMatchingScope: getMatchingWorkflowScope,
+    getMatchingScopeStack: buildMatchingScopeStack,
+    getEffectiveDocumentMode,
+    queryScopes,
+    getRailSegments,
+    getAllRailSegments,
+    getAllScopeCardModels,
+    applyOverlayCommand,
+    syncDetachedScopeWarnings,
+    invalidateCachesForDocumentMutation,
+    invalidateGuardAndScopeCaches,
+  };
+}