@beyondwork/docx-react-component 1.0.67 → 1.0.70

package/src/runtime/document-runtime.ts

@@ -81,6 +81,9 @@ import type {
   WorkflowCandidateRangeOptions,
   WorkflowBlockedCommandReason,
   WorkflowMetadataDefinition,
+  OverlayKind,
+  OverlayVisibilityPolicy,
+  WorkflowMarkupModePolicy,
   WorkflowMetadataEntry,
   WorkflowMetadataSnapshot,
   WorkflowMarkupSnapshot,
@@ -129,7 +132,7 @@ import {
   snapCommentAnchorAwayFromTable,
 } from "../core/selection/review-anchors.ts";
 import { buildBookmarkNameMap } from "../legal/bookmarks.ts";
-import { createFieldResolver, type FieldResolver } from "./field-resolver.ts";
+import { createFieldResolver, type FieldResolver } from "./formatting/field/resolver.ts";
 import { createFootnoteResolver, type FootnoteResolver } from "./footnote-resolver.ts";
 import {
   describeOpaqueFragment,
@@ -150,12 +153,30 @@ import {
   findAllScopesAt,
   findScopesIntersecting,
   resolveScope,
-} from "./scope-resolver.ts";
+} from "./workflow/scope-resolver.ts";
 import { buildDiagnosticFromLegacyWarningCode } from "./diagnostics/build-diagnostic.ts";
+import { TelemetryBus } from "./debug/telemetry-bus.ts";
+import { emitStageToken } from "./debug/stage-tokens.ts";
+import {
+  createRuntimeDebugFacet,
+  type RuntimeDebugFacet,
+} from "./debug/runtime-debug-facet.ts";
+import { setActiveSerializeTelemetryBus } from "../io/export/serialize-main-document.ts";
 import {
   projectScopeQueryResults,
   queryScopes as runQueryScopes,
-} from "./query-scopes.ts";
+} from "./workflow/query-scopes.ts";
+import {
+  createOverlayStore,
+  seedMarkerBackedScopeIds,
+  type OverlayStore,
+} from "./workflow/overlay-store.ts";
+import type { RuntimeOperationPlan, ScopeBundle } from "./scopes/semantic-scope-types.ts";
+import { createScopeCompilerService } from "./scopes/compiler-service.ts";
+import {
+  createWorkflowCoordinator,
+  type WorkflowCoordinator,
+} from "./workflow/coordinator.ts";
 import {
   insertScopeMarkers,
   removeScopeMarkers,
@@ -171,7 +192,12 @@ import {
 import {
   collectWorkflowMarkupSnapshot,
   deriveWorkflowCandidateRangesFromMarkup,
-} from "./workflow-markup.ts";
+} from "./workflow/markup.ts";
+import {
+  attachScopeCardModel,
+  collectScopeRailSegments,
+  type ScopeRailSegment,
+} from "./workflow/rail/compose.ts";
 import {
   createDocumentNavigationSnapshot,
   findPageForOffset,
@@ -181,12 +207,18 @@ import {
   createLayoutEngine,
   createLayoutFacet,
   createMeasurementProvider,
+  setActiveLayoutWarningEmitter,
   type DocxFontLoader,
   type LayoutEngineInstance,
+  type LayoutFacet,
   type LayoutMeasurementProvider,
   type WordReviewEditorLayoutFacet,
 } from "./layout/index.ts";
 import { createRenderKernel, type RenderKernel } from "./render/index.ts";
+import {
+  createGeometryFacet,
+  type GeometryFacet,
+} from "./geometry/index.ts";
 import {
   createDocumentOutlineSnapshot,
   createDocumentSectionSnapshots,
@@ -237,24 +269,25 @@ import {
   createEditorViewStateSnapshot,
   type ViewState,
 } from "./view-state.ts";
-import { ThemeColorResolver } from "./theme-color-resolver.ts";
+import { ThemeColorResolver } from "./formatting/theme-color.ts";
 import type {
   BlockNode,
   CanonicalDocument,
   FieldNode,
   FieldRefreshStatus,
   InlineNode,
+  MutableCanonicalDocument,
   PageMargins,
   ParagraphNode,
   SectionProperties,
   SubPartsCatalog,
 } from "../model/canonical-document.ts";
 import {
-  buildFieldRegistry,
   isSupportedFieldFamily,
   parseTocLevelRange,
   resolveRefFieldText,
 } from "../io/ooxml/parse-fields.ts";
+import { rebuildFieldRegistry } from "./formatting/field/registry.ts";
 import {
   incrementInvalidationCounter,
   recordPerfSample,
@@ -286,7 +319,7 @@ import {
 import type { EditorStatePayload } from "../io/ooxml/workflow-payload.ts";
 import type { SharedWorkflowState } from "./collab/workflow-shared.ts";
 import { mapLocalSelectionOnRemoteReplay } from "./collab/map-local-selection-on-remote-replay.ts";
-import { formatPageNumber } from "./page-number-format.ts";
+import { formatPageNumber } from "./formatting/field/page-number-format.ts";
 
 /** Internal extension of ExportDocxOptions that threads the collected
  *  editorState payload from the runtime to the docx serializer. */
@@ -393,6 +426,16 @@ export interface DocumentRuntime {
   /** R.5.a — `true` when the runtime is inside one or more action brackets. */
   isInAction(): boolean;
   applyActiveStoryTextCommand(command: ActiveStoryTextCommand): TextCommandAck;
+  /**
+   * Layer-08 Slice-5 — apply a compiled `RuntimeOperationPlan` from the
+   * scope compiler. Each plan step lowers to one or more existing
+   * runtime commands (text.insert, tracked-change ops). Callers route
+   * through `src/runtime/scopes/replacement/apply.ts` which validates
+   * the plan and emits a single `ScopeActionAudit` on the `scope`
+   * telemetry channel — do not call this method directly from agent or
+   * UI paths.
+   */
+  applyScopeReplacement(plan: RuntimeOperationPlan): void;
   dispatch(command: EditorCommand): void;
   /**
    * Apply a command received from a remote collaborator. The command
@@ -469,6 +512,33 @@ export interface DocumentRuntime {
   editCommentBody(commentId: string, body: string): void;
   addScope(params: AddScopeParams): AddScopeResult;
   getScope(scopeId: string): WorkflowScope | null;
+  /**
+   * Layer-08 scope-bundle lookup keyed by scopeId — read-side join over
+   * canonical document + enumerated scopes + workflow metadata entries.
+   * `nowUtc` stays caller-supplied (S3 determinism — no `new Date()`
+   * fallback). Returns `null` when the id does not enumerate.
+   *
+   * Exposed on the runtime so v3's `ui.scope.*` family (L10) can reach
+   * `ScopeBundle` without importing `src/runtime/scopes/**` (blocked by
+   * `ci-check-ui-api-layer-purity`). Parallels `ai.getScopeBundle`
+   * (scope-handle keyed) minus the handle-unpack step and the structured
+   * not-found discriminator — the L10 seam takes raw scopeIds from UI
+   * state so null/nothing semantics match lookup-by-id elsewhere on the
+   * handle (e.g. `getScope`).
+   */
+  compileScopeBundleById(scopeId: string, nowUtc: string): ScopeBundle | null;
+  /**
+   * Debug projector support — readonly view of scope ids the runtime
+   * considers marker-backed (present in both `collectScopeLocations(doc)`
+   * and `workflowOverlay.scopes`). Internal-only.
+   */
+  getMarkerBackedScopeIds(): ReadonlySet<string>;
+  /**
+   * Debug + telemetry facet. Internal-only. Not forwarded onto the public
+   * ref. Phase 2 `services/debug/` accesses it via direct runtime reference
+   * (in-process) or via the hidden harness page's `window.__debug` RPC.
+   */
+  readonly debug: import("./debug/runtime-debug-facet.ts").RuntimeDebugFacet;
   removeScope(scopeId: string): void;
   /** §C8 — Add a scope with visibility: "invisible" atomically. */
   addInvisibleScope(params: Omit<AddScopeParams, "mode"> & { mode?: WorkflowScopeMode }): AddScopeResult;
@@ -517,8 +587,59 @@ export interface DocumentRuntime {
    * Runtime-owned layout facet.  Provides graph-aware queries, fragment
    * resolution, formatting inspection, and layout events.  Prefer this over
    * the opaque snapshot methods for new integration code.
+   *
+   * The public-API type name is `WordReviewEditorLayoutFacet`; the
+   * refactor-era structural alias is `LayoutFacet` (see
+   * `src/runtime/layout/layout-facet-types.ts`). Both resolve to the same
+   * interface.
    */
   readonly layout: WordReviewEditorLayoutFacet;
+  /**
+   * Layer-06 (workflow) API surface. Canonical site for scope-rail
+   * composition and scope-card projection. Post refactor/06 Slice 4C
+   * rail-seam inversion, `runtime.layout` no longer exposes rail/card
+   * methods at all — this is the sole seam. See
+   * `docs/architecture/06-workflow-review.md` contract W7 + W9.
+   */
+  readonly workflow: {
+    /** Scope rail segments for the given page index. */
+    getRailSegments(pageIndex: number): readonly ScopeRailSegment[];
+    /** All scope rail segments across every page in the current page graph. */
+    getAllRailSegments(): readonly ScopeRailSegment[];
+    /**
+     * Project current rail segments into per-scope `ScopeCardModel` values,
+     * joining issue/review-action metadata, suggestions, and (when a render
+     * kernel is available) primary anchor rects.
+     */
+    getAllScopeCardModels(): readonly import("../api/public-types.ts").ScopeCardModel[];
+  };
+  /**
+   * Runtime-owned geometry facet (Layer 05 · Geometry Projection).
+   *
+   * Owns concrete visual geometry: rects, hit-tests, caret geometry, anchor
+   * rects, selection rects, replacement envelopes, object handles, and the
+   * runtime viewport. Projected from the render-kernel frame + layout
+   * semantics — never from the DOM (contract G2;
+   * `docs/architecture/05-geometry-projection.md`).
+   *
+   * Construction is wired to the same `renderKernelRef` as the layout facet,
+   * so hit-test and anchor queries read from the current render frame
+   * directly rather than via the layout-facet compat wrappers that remain on
+   * the layout surface for backwards-compat.
+   *
+   * v3 `runtime.geometry.*` family (`src/api/v3/runtime/geometry.ts`) reads
+   * through this facet; the v3 layer does NOT reach geometry through
+   * `runtime.layout` any more.
+   */
+  readonly geometry: GeometryFacet;
+  /**
+   * Refactor/04 Slice 2 — expose the layout facet via the structural alias
+   * `LayoutFacet` for consumers that want to depend on the
+   * refactor-era name rather than the public-API name. Returns the same
+   * underlying facet as `runtime.layout`; the type narrows to `LayoutFacet`
+   * at the return site.
+   */
+  getLayoutFacet(): LayoutFacet;
   getCurrentLocation(): DocumentLocationSnapshot | null;
   getLocationForSelection(selection: SelectionSnapshot): DocumentLocationSnapshot | null;
   getLocationForAnchor(
@@ -576,6 +697,68 @@ export interface DocumentRuntime {
   setWorkflowMetadataEntries(entries: WorkflowMetadataEntry[]): void;
   clearWorkflowMetadataEntries(): void;
   getWorkflowMetadataSnapshot(): WorkflowMetadataSnapshot;
+  /** W10 — class-A overlay-visibility policy (per-kind read). */
+  getVisibilityPolicy(kind: OverlayKind): OverlayVisibilityPolicy | null;
+  /** W10 — class-A policy set. */
+  getVisibilityPolicies(): readonly OverlayVisibilityPolicy[];
+  /** W10 — author a class-A policy. Returns true when state changed. */
+  setVisibilityPolicy(policy: OverlayVisibilityPolicy): boolean;
+  /** W10 — clear a class-A policy. Returns true when state changed. */
+  clearVisibilityPolicy(kind: OverlayKind): boolean;
+  /**
+   * W10 — subscribe to any policy-set change. Listener fires after a
+   * successful `setVisibilityPolicy` / `clearVisibilityPolicy` call or
+   * any internal bulk-replace (reload / collab sync). Returns an
+   * unsubscribe function. Consumed by L10 X3's
+   * `ui.overlays.subscribeVisibility` so UI subscribers re-fire when
+   * authoring-tool hosts mutate policy mid-session.
+   */
+  subscribeVisibilityPolicy(listener: () => void): Unsubscribe;
+  /** X5 — read the class-A markup-mode policy. `null` means the doc
+   * carried no authored mode. */
+  getMarkupModePolicy(): WorkflowMarkupModePolicy | null;
+  /** X5 — author (or clear with `null`) the class-A markup-mode policy.
+   * Returns true when state changed. */
+  setMarkupModePolicy(policy: WorkflowMarkupModePolicy | null): boolean;
+  /** X5 — subscribe to markup-mode policy changes. Consumed by L10's
+   * `ui.viewport` composition (state-classes X5). */
+  subscribeMarkupModePolicy(listener: () => void): Unsubscribe;
+  /**
+   * X5 end-to-end activation — the composition site
+   * (`api.ui.viewport.getEffectiveMarkupMode`) hands the runtime a
+   * callback that returns the CURRENTLY composed effective markup
+   * mode (L06 policy × L10 local preference). When set, the runtime
+   * threads it into every `createEditorSurfaceSnapshot` call via
+   * `SurfaceProjectionOptions.getEffectiveMarkupMode` so the next
+   * projection applies posture without re-parsing the document.
+   *
+   * Typical wire site: `WordReviewEditor.tsx`, called once right
+   * after `createApiV3(runtime, { ui })` so the callback closes over
+   * the UI family's closure state (local preference + subscriber
+   * chain).
+   *
+   * Pass `undefined` to clear (teardown). When cleared, surface-
+   * projection falls back to the static `revisionMarkupMode` option
+   * (if any caller threads one) or to posture-off behavior.
+   */
+  setEffectiveMarkupModeProvider(
+    provider:
+      | (() => "clean" | "simple" | "all" | undefined)
+      | undefined,
+  ): void;
+  /**
+   * X5 end-to-end activation — the composition site (typically
+   * `WordReviewEditor.tsx` subscribing to
+   * `api.ui.viewport.subscribeEffectiveMarkupMode`) calls this when
+   * the composed mode changes due to a class-C local preference
+   * flip. Busts the derived-runtime surface cache + fires a host
+   * refresh so the new mode propagates on the next frame.
+   *
+   * Class-A policy changes already reach the runtime via
+   * `setMarkupModePolicy` (which triggers its own invalidation
+   * chain), so this entry is for the local-preference-only path.
+   */
+  invalidateForMarkupModeChange(): void;
   /**
    * Phase C §C1 — snapshot-based filter + join projection. See
    * `WordReviewEditorRef.queryScopes` for contract.
@@ -690,6 +873,14 @@ export interface CreateDocumentRuntimeOptions {
   defaultAuthorId?: string;
   fatalError?: EditorError;
   clock?: () => string;
+  /**
+   * Optional pre-constructed telemetry bus. When provided, the runtime
+   * uses this instance instead of creating a fresh one — lets callers
+   * (e.g. `services/debug/lib/session-manager.ts`) share a single bus
+   * across the load path (so the parse channel emits via
+   * `setActiveParseTelemetryBus`) and the runtime lifetime.
+   */
+  telemetryBus?: TelemetryBus;
   exportDocx?: (
     sessionState: EditorSessionState,
     options?: ExportDocxOptions,
@@ -734,7 +925,7 @@ export interface CreateDocumentRuntimeOptions {
    * `LAYOUT_ENGINE_VERSION` (callers rely on the cache-key scheme in
    * `src/runtime/prerender/cache-key.ts` to guarantee this).
    *
-   * See docs/plans/lane-2-render-performance.md §Phase 2.5 §3.7.
+   * See CLAUDE.md (lane status table) §Phase 2.5 §3.7.
    */
   seedLayoutCache?: import("./layout/page-graph.ts").RuntimePageGraph;
 }
@@ -747,7 +938,7 @@ interface HistoryState {
 /**
  * L7 Phase 1.7.4 — structural-counts hash for the reviewWork cache key.
  *
- * `getCachedWorkflowMarkupSnapshot()` returns a NEW object on every
+ * `workflowCoordinator.getWorkflowMarkupSnapshot()` returns a NEW object on every
  * `revisionToken` bump, so the previous reference-equality check
  * (`cachedReviewWork.workflowMarkup === wfMarkup`) always failed on pure
  * text edits — forcing `createReviewWorkSnapshot` to re-walk every comment,
@@ -839,6 +1030,17 @@ export function createDocumentRuntime(
   const loadScheduler: LoadScheduler =
     options.loadScheduler ?? createLoadScheduler({ backendOverride: "sync" });
 
+  // X5 end-to-end activation (coord-03 §5b). Set by the UI API
+  // composition site (`api.ui.viewport.getEffectiveMarkupMode`) via
+  // `setEffectiveMarkupModeProvider` after `createApiV3` constructs
+  // the ui family. When set, every `createEditorSurfaceSnapshot` call
+  // below threads it into `SurfaceProjectionOptions.getEffectiveMarkupMode`
+  // so revision-display posture reflects the composed L06 × L10 mode
+  // without re-parsing the document.
+  let effectiveMarkupModeProvider:
+    | (() => "clean" | "simple" | "all" | undefined)
+    | undefined;
+
   // L7 Phase 0 — perf counters. Each `refreshRenderSnapshot` call increments
   // `refresh.all`. Phase 1 will add per-facet `facet.<name>.build` counters
   // wired to the per-facet cached builders. Cost is one Map.set per call.
@@ -878,27 +1080,46 @@ export function createDocumentRuntime(
     enforcedRangeCount: 0,
     preservedRangeCount: 0,
   };
-  let workflowOverlay: WorkflowOverlay | null =
-    structuredClone(
+  // Phase 1 — session-scoped telemetry. Hoisted early because the
+  // workflow overlay store uses it for the `scope.marker_backed_delta`
+  // event. All channels default off; cost is one bitmask AND per
+  // hook-point when disabled.
+  //
+  // Accepts an injected bus so the load path (docx-session.parseMainDocumentXml
+  // via setActiveParseTelemetryBus) can share one bus with the runtime it
+  // will eventually back — see CreateDocumentRuntimeOptions.telemetryBus.
+  const telemetryBus = options.telemetryBus ?? new TelemetryBus();
+  let hostAnnotationOverlay: HostAnnotationOverlay | null = null;
+  // Layer-06 workflow state + caches live in the overlay store and
+  // coordinator (see src/runtime/workflow/overlay-store.ts +
+  // coordinator.ts). The `overlayStore` is created here before
+  // `state` so the coordinator can seed marker-backed scope IDs as
+  // soon as the initial document lands. `workflowCoordinator` is
+  // wired after `state` + `viewState` + event emitter are in place
+  // (assignment below the initial render-snapshot setup).
+  const overlayStore: OverlayStore = createOverlayStore({
+    initialOverlay:
       options.initialSessionState?.workflowOverlay ??
       options.initialSnapshot?.workflowOverlay ??
       null,
-    );
-  let workflowMetadataDefinitions: WorkflowMetadataDefinition[] =
-    options.initialSessionState?.workflowMetadata?.definitions
-    ?? options.initialSnapshot?.workflowMetadata?.definitions
-    ?? [];
-  let workflowMetadataEntries: WorkflowMetadataEntry[] =
-    options.initialSessionState?.workflowMetadata?.entries
-    ?? options.initialSnapshot?.workflowMetadata?.entries
-    ?? [];
-  let markerBackedScopeIds = new Set<string>();
-  let hostAnnotationOverlay: HostAnnotationOverlay | null = null;
-  // §C7 — local view-state for scope chrome visibility; never collab-replicated.
-  let scopeChromeVisibilityState: ScopeChromeVisibilityState = { mode: "all" };
-  // P13 Slice B: shared workflow state from the collab Y.Map "workflow".
-  // Set via setSharedWorkflowState(); observed by evaluateWorkflowBlockedReasons.
-  let sharedWorkflowState: SharedWorkflowState | null = null;
+    initialMetadataDefinitions:
+      options.initialSessionState?.workflowMetadata?.definitions ??
+      options.initialSnapshot?.workflowMetadata?.definitions ??
+      [],
+    initialMetadataEntries:
+      options.initialSessionState?.workflowMetadata?.entries ??
+      options.initialSnapshot?.workflowMetadata?.entries ??
+      [],
+    initialVisibilityPolicies:
+      options.initialSessionState?.visibilityPolicies ??
+      options.initialSnapshot?.visibilityPolicies ??
+      [],
+    initialMarkupModePolicy:
+      options.initialSessionState?.markupModePolicy ??
+      options.initialSnapshot?.markupModePolicy ??
+      null,
+    telemetryBus,
+  });
   const initialPersistedSnapshot = options.initialSessionState
     ? persistedSnapshotFromEditorSessionState(options.initialSessionState, {
         savedAt: options.initialSessionState.updatedAt,
@@ -930,31 +1151,11 @@ export function createDocumentRuntime(
   storySelections.set(storyTargetKey(MAIN_STORY_TARGET), state.selection);
   lastHeadingFingerprint = computeHeadingFingerprint(state.document);
 
-  function syncMarkerBackedScopeIds(
-    document: CanonicalDocumentEnvelope,
-    overlay: WorkflowOverlay | null,
-  ): void {
-    const presentScopeIds = new Set(collectScopeLocations(document).keys());
-    if (!overlay) {
-      markerBackedScopeIds = presentScopeIds;
-      return;
-    }
-    const overlayScopeIds = new Set(overlay.scopes.map((scope) => scope.scopeId));
-    const next = new Set<string>();
-    for (const scopeId of markerBackedScopeIds) {
-      if (overlayScopeIds.has(scopeId)) {
-        next.add(scopeId);
-      }
-    }
-    for (const scopeId of presentScopeIds) {
-      if (overlayScopeIds.has(scopeId)) {
-        next.add(scopeId);
-      }
-    }
-    markerBackedScopeIds = next;
-  }
-
-  syncMarkerBackedScopeIds(state.document, workflowOverlay);
+  // Seed marker-backed scope IDs from the initial document. The
+  // overlay store's `replaceOverlay` is the sole writer of that set;
+  // `seedMarkerBackedScopeIds` is an idempotent no-telemetry wrapper
+  // that populates the set from the initial document + overlay.
+  seedMarkerBackedScopeIds(overlayStore, state.document);
 
   // Runtime-owned paginated layout engine (Phase 1+ of the layout facet work).
   // The engine caches graph + resolved-formatting + fragment mapper keyed on
@@ -966,7 +1167,9 @@ export function createDocumentRuntime(
   // `createMeasurementProvider({ preference: "auto", fontLoader })` which
   // upgrades to the canvas backend once fonts resolve.  `swapMeasurementProvider`
   // emits `measurement_backend_ready` so chrome consumers can re-read metrics.
-  const layoutEngine: LayoutEngineInstance = createLayoutEngine();
+  const layoutEngine: LayoutEngineInstance = createLayoutEngine({
+    telemetryBus,
+  });
   if (options.seedLayoutCache) {
     // L7 Phase 2.5 — seed the cached graph from the prerender envelope so
     // the first getPageGraph call skips fullRebuild. Seed is keyed on the
@@ -996,30 +1199,10 @@ export function createDocumentRuntime(
     }),
     canonicalDocument: () => state.document,
     renderKernel: () => renderKernelRef,
-    getWorkflowRailInput: () => {
-      const normalizedWorkflowOverlay = getNormalizedWorkflowOverlay();
-      if (!normalizedWorkflowOverlay) return null;
-      const activeWorkItemId = normalizedWorkflowOverlay.activeWorkItemId ?? null;
-      const activeWorkItem =
-        activeWorkItemId !== null
-          ? normalizedWorkflowOverlay.workItems?.find(
-              (item) => item.workItemId === activeWorkItemId,
-            )
-          : undefined;
-      return {
-        scopes: normalizedWorkflowOverlay.scopes,
-        candidates: normalizedWorkflowOverlay.candidates,
-        activeWorkItemScopeIds: activeWorkItem?.scopeIds ?? [],
-        activeStory,
-      };
-    },
-    // R2 / scope-card-overlay P1 — surface metadata markup so
-    // `facet.getAllScopeCardModels()` can attach `IssueMetadataValue`
-    // to its scope without the chrome overlay having to re-fetch a
-    // separate snapshot.  Reads through the same cached snapshot the
-    // runtime already builds for comment/revision/search consumers.
-    getWorkflowMarkupMetadata: () =>
-      getCachedWorkflowMarkupSnapshot().metadata,
+    // Workflow rail / scope-card composition migrated to
+    // `runtime.workflow` in Layer-06 Slice 4. The layout facet no
+    // longer consumes workflow state — it only provides page-graph
+    // input via the getQueryInput + engine accessors above.
     // L7 Phase 2 — delegate viewport culling through the facet so the
     // workspace (which only holds a `layoutFacet` ref) can drive culling
     // without a separate `DocumentRuntime` prop.  The lambdas forward to
@@ -1047,10 +1230,31 @@ export function createDocumentRuntime(
       refreshSurfaceOnly();
     },
   });
+  // D1 — wire the layout-guard warning emitter so `return []` guard sites
+  // in public-facet.ts emit on the `warning` channel when it is enabled.
+  setActiveLayoutWarningEmitter((type, guard, inputs) => {
+    if (!telemetryBus.isEnabled("warning")) return;
+    const t = typeof performance !== "undefined" && typeof performance.now === "function"
+      ? performance.now()
+      : Date.now();
+    telemetryBus.emit({ channel: "warning", type, t, payload: { guard, inputs } });
+  });
   renderKernelRef = createRenderKernel({
     facet: layoutFacet,
     getActiveStory: () => activeStory,
   });
+  // Layer 05 · Geometry Projection — construct the geometry facet once
+  // the render kernel exists. The facet's `hitTest` / `getAnchorRects` /
+  // `getBlockRects` / `getPage` / `getBlock` / `getCaret` /
+  // `getSelectionRects` / `getReplacementEnvelope` / `getObjectHandles`
+  // all resolve via the kernel's current frame through the pure helpers
+  // in `src/runtime/geometry/**`. Architecture target:
+  // `docs/architecture/05-geometry-projection.md`.
+  const geometryFacet: GeometryFacet = createGeometryFacet({
+    layoutFacet,
+    renderKernel: () => renderKernelRef,
+    getCanonicalDocument: () => state.document,
+  });
   // L7 Phase 2 — viewport block range for surface culling.
   let viewportBlockRange: { start: number; end: number } | null = null;
 
@@ -1105,7 +1309,7 @@ export function createDocumentRuntime(
   //   - `workflowMarkupHash` — structural-counts hash over wfMarkup.
   //     Replaces the old `workflowMarkup === wfMarkup` reference check,
   //     which always failed on pure text edits because
-  //     `getCachedWorkflowMarkupSnapshot()` is keyed on revisionToken.
+  //     `workflowCoordinator.getWorkflowMarkupSnapshot()` is keyed on revisionToken.
   //     Pure text edits keep all per-category item counts stable → hash
   //     equal. A comment ADDITION, revision AUTHORED, protected-range added,
   //     opaque-fragment added → at least one count changes → hash diverges.
@@ -1179,45 +1383,9 @@ export function createDocumentRuntime(
         snapshot: EditorViewStateSnapshot;
       }
     | undefined;
-  let cachedInteractionGuardSnapshot:
-    | {
-        revisionToken: string;
-        activeStoryKey: string;
-        selection: EditorState["selection"];
-        readOnly: boolean;
-        documentMode: DocumentMode;
-        protectionSnapshot: ProtectionSnapshot;
-        workflowOverlay: WorkflowOverlay | null;
-        sharedWorkflowState: SharedWorkflowState | null;
-        snapshot: InteractionGuardSnapshot;
-      }
-    | undefined;
-  let cachedWorkflowScopeSnapshot:
-    | {
-        workflowOverlay: WorkflowOverlay;
-        interactionGuardSnapshot: InteractionGuardSnapshot;
-        snapshot: WorkflowScopeSnapshot;
-      }
-    | undefined;
-  let cachedNormalizedWorkflowOverlay:
-    | {
-        document: CanonicalDocumentEnvelope;
-        workflowOverlay: WorkflowOverlay;
-        normalized: WorkflowOverlay;
-      }
-    | undefined;
-  let cachedWorkflowMarkupSnapshot:
-    | {
-        revisionToken: string;
-        activeStoryKey: string;
-        protectionSnapshot: ProtectionSnapshot;
-        preservation: CanonicalDocumentEnvelope["preservation"];
-        workflowOverlay: WorkflowOverlay | null;
-        workflowMetadataDefinitions: WorkflowMetadataDefinition[];
-        workflowMetadataEntries: WorkflowMetadataEntry[];
-        snapshot: WorkflowMarkupSnapshot;
-      }
-    | undefined;
+  // Layer-06 workflow/review caches (interaction guard, scope
+  // snapshot, normalized overlay, markup snapshot) live on the
+  // workflow coordinator. See `src/runtime/workflow/coordinator.ts`.
   // Keyed on block count + subParts identity (not revisionToken) — fields only
   // change when blocks are inserted/deleted or subParts (headers/footers) change,
   // NOT on text-only edits. Cleared explicitly by updateFields() for field-refresh.
@@ -1260,7 +1428,12 @@ export function createDocumentRuntime(
       return cachedSurface.snapshot;
     }
 
-    const snapshot = createEditorSurfaceSnapshot(document, state.selection, nextActiveStory, { viewportBlockRange });
+    const snapshot = createEditorSurfaceSnapshot(document, state.selection, nextActiveStory, {
+      viewportBlockRange,
+      ...(effectiveMarkupModeProvider
+        ? { getEffectiveMarkupMode: effectiveMarkupModeProvider }
+        : {}),
+    });
     recordPerfSample("snapshot.surface");
     incrementInvalidationCounter("runtime.snapshot.surfaceMisses");
     cachedSurface = {
@@ -1505,197 +1678,13 @@ export function createDocumentRuntime(
     return snapshot;
   }
 
-  function evaluateWorkflowBlockedReasons(
-    selection: EditorState["selection"],
-    commandType?: string,
-  ): WorkflowBlockedCommandReason[] {
-    const reasons: WorkflowBlockedCommandReason[] = [];
-    // P13 Slice B: shared lockedMode overrides all other scope checks when
-    // non-editing. Short-circuit: no other scope reason applies when the round
-    // is locked (the round state supersedes scope/overlay-level gating).
-    // Emit a reason code whose effectiveMode mapping matches the mode intent:
-    //   "commenting" → workflow_comment_only (maps to effectiveMode: "comment")
-    //   "viewing"    → workflow_view_only    (maps to effectiveMode: "view")
-    //   "suggesting" → workflow_round_locked (no existing mapping; stays "blocked"
-    //                   for this slice — full suggesting-mode semantics will be a
-    //                   future slice that hooks getEffectiveDocumentMode instead).
-    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 = deriveOpaqueWorkflowBlockedReason(selectionRange);
-
-    if (opaqueReason) {
-      reasons.push(opaqueReason);
-    }
-
-    if (state.readOnly) {
-      reasons.push({
-        code: "document_read_only",
-        message: "Document is in read-only mode.",
-      });
-    }
-
-    if (viewState.documentMode === "viewing" || viewState.documentMode === "commenting") {
-      reasons.push({
-        code: "document_viewing_mode",
-        message: "Document is in viewing mode.",
-      });
-    }
-
-    if (
-      isBlockedByProtection(protectionSnapshot, selection)
-    ) {
-      reasons.push({
-        code: "protected_range",
-        message: "Selection falls within a protected range.",
-      });
-    }
-
-    const effectiveDocumentMode = getEffectiveDocumentMode(selection);
-
-    if (effectiveDocumentMode === "suggesting" && commandType) {
-      if (SUGGESTING_UNSUPPORTED_COMMANDS.has(commandType)) {
-        reasons.push({
-          code: "suggesting_unsupported",
-          message: `"${commandType}" is not supported in suggesting mode.`,
-        });
-      }
-    }
-
-    const normalizedWorkflowOverlay = getNormalizedWorkflowOverlay();
-    if (normalizedWorkflowOverlay) {
-      const matchingScope = getMatchingWorkflowScope(selection);
-      const activeScopes = getEffectiveWorkflowScopes(normalizedWorkflowOverlay);
-      // §C8: invisible non-view scopes are transparent to the interaction guard.
-      // Don't count them toward the "outside_workflow_scope" threshold.
-      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;
-  }
-
-  // §C6 — most-restrictive-wins ordering for overlap layering.
-  const MODE_RESTRICTIVENESS: Record<WorkflowScopeMode, number> = {
-    edit: 0,
-    suggest: 1,
-    comment: 2,
-    view: 3,
-  };
-
-  /**
-   * §C6 — Collect all guard-eligible scopes that contain `selection`,
-   * sorted outermost→innermost (startPos ASC, endPos DESC, scopeId ASC).
-   * Excludes invisible non-view scopes per §C8.
-   */
-  function buildMatchingScopeStack(
-    selection: EditorState["selection"],
-  ): WorkflowOverlay["scopes"] {
-    if (!workflowOverlay) return [];
-    const selectionBounds = {
-      from: Math.min(selection.anchor, selection.head),
-      to: Math.max(selection.anchor, selection.head),
-    };
-    const activeScopes = getEffectiveWorkflowScopes(workflowOverlay);
-    const matching = activeScopes.filter((scope) => {
-      // §C8
-      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;
-    });
-    // Outermost first: startPos ASC, endPos DESC (wider span = outer), 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; // wider first
-      return a.scopeId < b.scopeId ? -1 : a.scopeId > b.scopeId ? 1 : 0;
-    });
-    return matching;
-  }
-
-  function getMatchingWorkflowScope(
-    selection: EditorState["selection"],
-  ): WorkflowOverlay["scopes"][number] | null {
-    const stack = buildMatchingScopeStack(selection);
-    if (stack.length === 0) return null;
-    // §C6 — most-restrictive scope wins across all 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 {
-    if (viewState.documentMode === "viewing" || viewState.documentMode === "commenting") {
-      return viewState.documentMode;
-    }
-    const matchingScope = getMatchingWorkflowScope(selection);
-    if (matchingScope?.mode === "suggest") {
-      return "suggesting";
-    }
-    return viewState.documentMode;
-  }
-
-  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,
-    };
-  }
+  // Layer-06 blocked-reason composition + scope-matching heuristics
+  // live on the workflow coordinator (see
+  // `src/runtime/workflow/coordinator.ts` — §C6 + §C8 rules, most-
+  // restrictive-wins, invisible-scope carve-out). Runtime call sites
+  // delegate via `workflowCoordinator.evaluateBlockedReasons`,
+  // `workflowCoordinator.getMatchingScope`, and
+  // `workflowCoordinator.getEffectiveDocumentMode`.
 
   function deriveOpaqueWorkflowBlockedReason(
     range: { from: number; to: number },
@@ -1920,265 +1909,71 @@ export function createDocumentRuntime(
     return left.from < right.to && right.from < left.to;
   }
 
-  function workflowAnchorsEqual(
-    left: EditorAnchorProjection,
-    right: EditorAnchorProjection,
-  ): boolean {
-    if (left.kind !== right.kind) return false;
-    switch (left.kind) {
-      case "range":
-        return (
-          right.kind === "range" &&
-          left.from === right.from &&
-          left.to === right.to &&
-          left.assoc.start === right.assoc.start &&
-          left.assoc.end === right.assoc.end
-        );
-      case "node":
-        return right.kind === "node" && left.at === right.at;
-      case "detached":
-        return (
-          right.kind === "detached" &&
-          left.reason === right.reason &&
-          left.lastKnownRange.from === right.lastKnownRange.from &&
-          left.lastKnownRange.to === right.lastKnownRange.to
-        );
-      default:
-        return false;
-    }
-  }
-
-  function normalizeWorkflowOverlayForDocument(
-    document: CanonicalDocumentEnvelope,
-    overlay: WorkflowOverlay,
-  ): WorkflowOverlay {
-    if (
-      cachedNormalizedWorkflowOverlay &&
-      cachedNormalizedWorkflowOverlay.document === document &&
-      cachedNormalizedWorkflowOverlay.workflowOverlay === overlay
-    ) {
-      return cachedNormalizedWorkflowOverlay.normalized;
-    }
+  // Layer-06 overlay normalization, rail input composition, and
+  // anchor-equality helpers live on the workflow coordinator +
+  // overlay store. See `src/runtime/workflow/overlay-store.ts` and
+  // `coordinator.ts`.
 
-    const scopeIdCounts = new Map<string, number>();
-    for (const scope of overlay.scopes) {
-      scopeIdCounts.set(scope.scopeId, (scopeIdCounts.get(scope.scopeId) ?? 0) + 1);
-    }
-    const locations = collectScopeLocations(document);
-    let changed = false;
-    const normalizedScopes = overlay.scopes.map((scope) => {
-      if ((scopeIdCounts.get(scope.scopeId) ?? 0) !== 1) {
-        return scope;
-      }
-      const location = locations.get(scope.scopeId);
-      const isMarkerBacked = markerBackedScopeIds.has(scope.scopeId);
-      let nextAnchor: EditorAnchorProjection | null = null;
-      if (
-        location &&
-        location.startPos !== undefined &&
-        location.endPos !== undefined
-      ) {
-        nextAnchor = {
-          kind: "range",
-          from: Math.min(location.startPos, location.endPos),
-          to: Math.max(location.startPos, location.endPos),
-          assoc: { start: -1, end: 1 },
-        };
-      } else if (isMarkerBacked) {
-        const lastKnownRange =
-          scope.anchor.kind === "range"
-            ? { from: scope.anchor.from, to: scope.anchor.to }
-            : scope.anchor.kind === "node"
-              ? { from: scope.anchor.at, to: scope.anchor.at }
-              : scope.anchor.lastKnownRange;
-        nextAnchor = {
-          kind: "detached",
-          reason:
-            location && (location.startPos !== undefined || location.endPos !== undefined)
-              ? "deleted"
-              : "invalidatedByStructureChange",
-          lastKnownRange,
-        };
-      } else {
-        return scope;
-      }
-      if (workflowAnchorsEqual(scope.anchor, nextAnchor)) {
-        return scope;
-      }
-      changed = true;
-      return {
-        ...scope,
-        anchor: nextAnchor,
-      };
-    });
-
-    const normalized = changed
-      ? {
-          ...overlay,
-          scopes: normalizedScopes,
-        }
-      : overlay;
-    cachedNormalizedWorkflowOverlay = {
-      document,
-      workflowOverlay: overlay,
-      normalized,
-    };
-    return normalized;
-  }
-
-  function getNormalizedWorkflowOverlay(): WorkflowOverlay | null {
-    if (!workflowOverlay) return null;
-    return normalizeWorkflowOverlayForDocument(state.document, workflowOverlay);
-  }
-
-  function buildWarningSignature(warning: InternalEditorWarning): string {
-    return JSON.stringify({
-      code: warning.code,
-      severity: warning.severity,
-      message: warning.message,
-      source: warning.source,
-      featureEntryId: warning.featureEntryId ?? null,
-      details: warning.details ?? null,
-      affectedAnchor: warning.affectedAnchor ?? null,
+  function getCurrentPageGraph() {
+    return layoutEngine.getPageGraph({
+      document: state.document,
+      viewState: {
+        activeStory,
+        workspaceMode: viewState.workspaceMode,
+        zoomLevel: viewState.zoomLevel,
+      },
     });
   }
 
-  function mergeDetachedWorkflowScopeWarnings(
-    overlay: WorkflowOverlay | null,
-    existingWarnings: readonly InternalEditorWarning[],
-  ): {
-    nextWarnings: InternalEditorWarning[];
-    added: InternalEditorWarning[];
-    cleared: Array<{ warningId: string; code: InternalEditorWarning["code"] }>;
-  } {
-    const detachedScopesById = new Map<string, WorkflowScope>();
-    for (const scope of overlay?.scopes ?? []) {
-      if (scope.anchor.kind === "detached") {
-        detachedScopesById.set(scope.scopeId, scope);
-      }
-    }
-
-    const retainedWarnings = existingWarnings.filter(
-      (warning) => warning.code !== "workflow_scope_invalidated",
-    );
-    const existingDetachedWarnings = existingWarnings.filter(
-      (warning) => warning.code === "workflow_scope_invalidated",
-    );
-    const existingById = new Map(
-      existingDetachedWarnings.map((warning) => [warning.warningId, warning] as const),
-    );
-    const desiredById = new Map(
-      [...detachedScopesById.values()].map((scope) => {
-        const warning = createInvalidatedWorkflowScopeWarning(scope);
-        return [warning.warningId, warning] as const;
-      }),
+  // Layer-06 workflow coordinator — owns the orchestration layer
+  // that used to live inline here (scope lifecycle, overlay / metadata
+  // setters, interaction-guard + scope + markup snapshot caches,
+  // blocked-reason composition + scope matching, rail composition,
+  // dispatch-branch handler, warning synthesis). Dependencies are
+  // late-bound via accessor functions — `emit`, `refreshRenderSnapshot`
+  // etc. are function declarations (hoisted) so the accessor closures
+  // remain valid even though the declarations live further down the
+  // file. `dispatchToRuntime` is similarly late-bound to avoid a
+  // circular reference between coordinator and the `runtime` object
+  // literal it gets spliced into.
+  //
+  // The runtime's own public methods forward to `workflowCoordinator`
+  // — see the method definitions on the returned `runtime` object.
+  let dispatchToRuntime: (command: unknown) => void = () => {
+    throw new Error(
+      "workflow coordinator: dispatch called before runtime is fully constructed",
     );
+  };
 
-    const added: InternalEditorWarning[] = [];
-    const cleared: Array<{ warningId: string; code: InternalEditorWarning["code"] }> = [];
-
-    for (const [warningId, existingWarning] of existingById) {
-      const desiredWarning = desiredById.get(warningId);
-      if (!desiredWarning) {
-        cleared.push({ warningId, code: existingWarning.code });
-        continue;
-      }
-      if (buildWarningSignature(existingWarning) !== buildWarningSignature(desiredWarning)) {
-        cleared.push({ warningId, code: existingWarning.code });
-        added.push(desiredWarning);
-      }
-    }
-
-    for (const [warningId, desiredWarning] of desiredById) {
-      if (!existingById.has(warningId)) {
-        added.push(desiredWarning);
-      }
-    }
-
-    return {
-      nextWarnings: [...retainedWarnings, ...desiredById.values()],
-      added,
-      cleared,
-    };
-  }
-
-  function createInvalidatedWorkflowScopeWarning(
-    scope: WorkflowScope,
-  ): InternalEditorWarning {
-    const anchor = scope.anchor.kind === "detached" ? scope.anchor : null;
-    const subject = scope.label
-      ? `Workflow scope "${scope.label}" (${scope.scopeId})`
-      : `Workflow scope ${scope.scopeId}`;
-    const reasonPhrase =
-      anchor?.reason === "deleted"
-        ? "its anchored text was deleted"
-        : anchor?.reason === "invalidatedByStructureChange"
-          ? "document structure changed around it"
-          : "its anchor could not be resolved unambiguously";
-    const modePhrase =
-      scope.mode === "view"
-        ? "read-only enforcement"
-        : `${scope.mode} enforcement`;
-
-    return {
-      warningId: `warning:workflow-scope-invalidated:${scope.scopeId}`,
-      code: "workflow_scope_invalidated",
-      severity: "warning",
-      message: `${subject} was invalidated because ${reasonPhrase}. Reapply the scope before relying on ${modePhrase}.`,
-      source: "runtime",
-      affectedAnchor: anchor ? toInternalAnchorProjection(anchor) : undefined,
-      diagnostic: buildDiagnosticFromLegacyWarningCode("workflow_scope_invalidated", {
-        diagnosticId: `warning-diag:workflow-scope-invalidated:${scope.scopeId}`,
-        technical: {
-          message: `${subject} lost its trusted anchor and is now detached.`,
-          source: "runtime",
-        },
-        details: {
-          scopeId: scope.scopeId,
-          label: scope.label,
-          mode: scope.mode,
-          reason: anchor?.reason,
-          lastKnownRange: anchor?.lastKnownRange,
-          storyTarget: scope.storyTarget,
-          reapplySuggested: true,
-        },
-        affectedAnchor: anchor ? scope.anchor : undefined,
-        llmMetadata: {
-          userSummary: `${subject} is no longer attached to trusted document content. Reapply the scope before relying on it.`,
-          remediation: {
-            kind: "fallback",
-            suggestion:
-              "Locate the intended text using warning.details.scopeId and warning.details.lastKnownRange, then call addScope again for the repaired range.",
-          },
-          recoveryClass: "requires-input",
-          echoedInput: {
-            scopeId: scope.scopeId,
-            lastKnownRange: anchor?.lastKnownRange,
-          },
-        },
-      }),
-      details: {
-        scopeId: scope.scopeId,
-        label: scope.label,
-        mode: scope.mode,
-        reason: anchor?.reason,
-        lastKnownRange: anchor?.lastKnownRange,
-        storyTarget: scope.storyTarget,
-        reapplySuggested: true,
-        actionabilityNote:
-          "Resolve the intended text again, then reapply the scope; the previous anchor is no longer trusted.",
-      },
-    };
-  }
+  const workflowCoordinator: WorkflowCoordinator = createWorkflowCoordinator({
+    overlayStore,
+    telemetryBus,
+    clock,
+    getDocument: () => state.document,
+    getState: () => state,
+    getActiveStory: () => activeStory,
+    getDocumentMode: () => viewState.documentMode,
+    getProtectionSnapshot: () => protectionSnapshot,
+    getRenderSnapshot: () => cachedRenderSnapshot,
+    getFieldSnapshot: () => getCachedFieldSnapshot(state.document),
+    getSuggestionsSnapshot: () => getCachedSuggestionsSnapshot(state),
+    getRenderFrameAnchorIndex: () =>
+      renderKernelRef?.getRenderFrame?.()?.anchorIndex ?? null,
+    getPageGraph: () => getCurrentPageGraph(),
+    deriveOpaqueWorkflowBlockedReason,
+    isBlockedByProtection,
+    dispatch: (command) => dispatchToRuntime(command as never),
+    emitEvent: (event) => emit(event as DocumentRuntimeEvent),
+    editorStateChannel,
+    suggestingUnsupportedCommands: SUGGESTING_UNSUPPORTED_COMMANDS,
+  });
 
   function syncDetachedWorkflowScopeWarningsInState(): {
     added: InternalEditorWarning[];
     cleared: Array<{ warningId: string; code: InternalEditorWarning["code"] }>;
   } {
-    const { nextWarnings, added, cleared } = mergeDetachedWorkflowScopeWarnings(
-      getNormalizedWorkflowOverlay(),
-      state.warnings,
-    );
+    const { nextWarnings, added, cleared } =
+      workflowCoordinator.syncDetachedScopeWarnings(state.warnings);
     if (added.length === 0 && cleared.length === 0) {
       return { added, cleared };
     }
@@ -2186,25 +1981,6 @@ export function createDocumentRuntime(
     return { added, cleared };
   }
 
-  function deriveWorkflowScopeSnapshot(): WorkflowScopeSnapshot | null {
-    const normalizedWorkflowOverlay = getNormalizedWorkflowOverlay();
-    if (!normalizedWorkflowOverlay) return null;
-    const blockedReasons = getCachedInteractionGuardSnapshot().blockedReasons;
-    const activeItem = normalizedWorkflowOverlay.activeWorkItemId
-      ? normalizedWorkflowOverlay.workItems?.find(
-          (item) => item.workItemId === normalizedWorkflowOverlay.activeWorkItemId,
-        )
-      : undefined;
-    return {
-      overlayPresent: true,
-      activeWorkItemId: normalizedWorkflowOverlay.activeWorkItemId ?? null,
-      activeWorkItem: activeItem,
-      scopes: normalizedWorkflowOverlay.scopes,
-      candidates: normalizedWorkflowOverlay.candidates ?? [],
-      blockedReasons,
-    };
-  }
-
   function deriveHostAnnotationSnapshot(): HostAnnotationSnapshot {
     return {
       totalCount: hostAnnotationOverlay?.annotations.length ?? 0,
@@ -2212,189 +1988,13 @@ export function createDocumentRuntime(
     };
   }
 
-  function deriveWorkflowMetadataSnapshot(): WorkflowMetadataSnapshot {
-    return {
-      definitions: structuredClone(workflowMetadataDefinitions),
-      entries: structuredClone(workflowMetadataEntries),
-    };
-  }
-
-  function getEffectiveWorkflowScopes(overlay: WorkflowOverlay): WorkflowOverlay["scopes"] {
-    const normalizedOverlay = normalizeWorkflowOverlayForDocument(state.document, overlay);
-    const activeWorkItemId = normalizedOverlay.activeWorkItemId ?? null;
-    const activeWorkItemScopeIds =
-      activeWorkItemId === null
-        ? null
-        : new Set(
-            normalizedOverlay.workItems?.find((item) => item.workItemId === activeWorkItemId)?.scopeIds ?? [],
-          );
-
-    return normalizedOverlay.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 getCachedInteractionGuardSnapshot(): InteractionGuardSnapshot {
-    const activeStoryKey = storyTargetKey(activeStory);
-    if (
-      cachedInteractionGuardSnapshot &&
-      cachedInteractionGuardSnapshot.revisionToken === state.revisionToken &&
-      cachedInteractionGuardSnapshot.activeStoryKey === activeStoryKey &&
-      cachedInteractionGuardSnapshot.selection === state.selection &&
-      cachedInteractionGuardSnapshot.readOnly === state.readOnly &&
-      cachedInteractionGuardSnapshot.documentMode === viewState.documentMode &&
-      cachedInteractionGuardSnapshot.protectionSnapshot === protectionSnapshot &&
-      cachedInteractionGuardSnapshot.workflowOverlay === workflowOverlay &&
-      cachedInteractionGuardSnapshot.sharedWorkflowState === sharedWorkflowState
-    ) {
-      return cachedInteractionGuardSnapshot.snapshot;
-    }
-
-    const blockedReasons = evaluateWorkflowBlockedReasons(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: evaluateWorkflowBlockedReasons(state.selection, "text.insert").length === 0,
-          blockedReasons: evaluateWorkflowBlockedReasons(state.selection, "text.insert"),
-        },
-        {
-          family: "formatting",
-          supported: evaluateWorkflowBlockedReasons(state.selection, "toggleBold").length === 0,
-          blockedReasons: evaluateWorkflowBlockedReasons(state.selection, "toggleBold"),
-        },
-        {
-          family: "structure",
-          supported: evaluateWorkflowBlockedReasons(state.selection, "insertTable").length === 0,
-          blockedReasons: evaluateWorkflowBlockedReasons(state.selection, "insertTable"),
-        },
-      ],
-      ...(primaryBlockedReason ? { disabledReason: primaryBlockedReason.message } : {}),
-      blockedReasons,
-    };
-    cachedInteractionGuardSnapshot = {
-      revisionToken: state.revisionToken,
-      activeStoryKey,
-      selection: state.selection,
-      readOnly: state.readOnly,
-      documentMode: viewState.documentMode,
-      protectionSnapshot,
-      workflowOverlay,
-      sharedWorkflowState,
-      snapshot,
-    };
-    return snapshot;
-  }
-
-  function getCachedWorkflowScopeSnapshot(): WorkflowScopeSnapshot | null {
-    if (!workflowOverlay) {
-      return null;
-    }
-
-    const interactionGuardSnapshot = getCachedInteractionGuardSnapshot();
-    if (
-      cachedWorkflowScopeSnapshot &&
-      cachedWorkflowScopeSnapshot.workflowOverlay === workflowOverlay &&
-      cachedWorkflowScopeSnapshot.interactionGuardSnapshot === interactionGuardSnapshot
-    ) {
-      return cachedWorkflowScopeSnapshot.snapshot;
-    }
-
-    const snapshot = deriveWorkflowScopeSnapshot()!;
-    cachedWorkflowScopeSnapshot = {
-      workflowOverlay,
-      interactionGuardSnapshot,
-      snapshot,
-    };
-    return snapshot;
-  }
-
-  function getCachedWorkflowMarkupSnapshot(): WorkflowMarkupSnapshot {
-    const activeStoryKey = storyTargetKey(activeStory);
-    if (
-      cachedWorkflowMarkupSnapshot &&
-      cachedWorkflowMarkupSnapshot.revisionToken === state.revisionToken &&
-      cachedWorkflowMarkupSnapshot.activeStoryKey === activeStoryKey &&
-      cachedWorkflowMarkupSnapshot.protectionSnapshot === protectionSnapshot &&
-      cachedWorkflowMarkupSnapshot.preservation === state.document.preservation &&
-      cachedWorkflowMarkupSnapshot.workflowOverlay === workflowOverlay &&
-      cachedWorkflowMarkupSnapshot.workflowMetadataDefinitions === workflowMetadataDefinitions &&
-      cachedWorkflowMarkupSnapshot.workflowMetadataEntries === workflowMetadataEntries
-    ) {
-      return cachedWorkflowMarkupSnapshot.snapshot;
-    }
-
-    const snapshot = collectWorkflowMarkupSnapshot({
-      renderSnapshot: cachedRenderSnapshot,
-      fieldSnapshot: getCachedFieldSnapshot(state.document),
-      protectionSnapshot,
-      preservation: state.document.preservation,
-      workflowMetadataSnapshot: deriveWorkflowMetadataSnapshot(),
-      perfStage: (name, durationMs) => {
-        perfCounters.increment(`wfMarkup.${name}.us`, Math.round(durationMs * 1000));
-        perfCounters.increment(`wfMarkup.${name}.calls`);
-      },
-    });
-    cachedWorkflowMarkupSnapshot = {
-      revisionToken: state.revisionToken,
-      activeStoryKey,
-      protectionSnapshot,
-      preservation: state.document.preservation,
-      workflowOverlay,
-      workflowMetadataDefinitions,
-      workflowMetadataEntries,
-      snapshot,
-    };
-    return snapshot;
-  }
+  // Layer-06 metadata snapshot derivation + getEffectiveWorkflowScopes
+  // + cached interaction-guard / scope / markup snapshots live on the
+  // workflow coordinator. Runtime call sites delegate via
+  // `workflowCoordinator.getInteractionGuardSnapshot()`,
+  // `workflowCoordinator.getWorkflowScopeSnapshot()`,
+  // `workflowCoordinator.getWorkflowMarkupSnapshot()`, and
+  // `workflowCoordinator.getWorkflowMetadataSnapshot()`.
 
   function getCachedRuntimeContextAnalytics(
     query?: RuntimeContextAnalyticsQuery,
@@ -2419,7 +2019,7 @@ export function createDocumentRuntime(
       cachedEntry.selection === selectionCacheKey &&
       cachedEntry.readOnly === state.readOnly &&
       cachedEntry.documentMode === viewState.documentMode &&
-      cachedEntry.workflowOverlay === workflowOverlay &&
+      cachedEntry.workflowOverlay === overlayStore.getOverlay() &&
       cachedEntry.protectionSnapshot === protectionSnapshot &&
       cachedEntry.warnings === state.warnings &&
       cachedEntry.fatalError === state.fatalError
@@ -2428,9 +2028,9 @@ export function createDocumentRuntime(
     }
 
     const tWf = performance.now();
-    const wfScope = getCachedWorkflowScopeSnapshot();
-    const wfGuard = getCachedInteractionGuardSnapshot();
-    const wfMarkup = getCachedWorkflowMarkupSnapshot();
+    const wfScope = workflowCoordinator.getWorkflowScopeSnapshot();
+    const wfGuard = workflowCoordinator.getInteractionGuardSnapshot();
+    const wfMarkup = workflowCoordinator.getWorkflowMarkupSnapshot();
     perfCounters.increment("ctxa.workflow.us", Math.round((performance.now() - tWf) * 1000));
 
     const tSugg = performance.now();
@@ -2485,7 +2085,7 @@ export function createDocumentRuntime(
     const tCompat = performance.now();
     const compat = toPublicCompatibilityReport(createDerivedCompatibility(state));
     perfCounters.increment("ctxa.compat.us", Math.round((performance.now() - tCompat) * 1000));
-    const normalizedWorkflowOverlay = getNormalizedWorkflowOverlay();
+    const normalizedWorkflowOverlay = workflowCoordinator.getWorkflowOverlay();
 
     const tBuild = performance.now();
     const snapshot = createRuntimeContextAnalyticsSnapshot({
@@ -2509,7 +2109,7 @@ export function createDocumentRuntime(
       selection: selectionCacheKey,
       readOnly: state.readOnly,
       documentMode: viewState.documentMode,
-      workflowOverlay,
+      workflowOverlay: overlayStore.getOverlay(),
       protectionSnapshot,
       warnings: state.warnings,
       fatalError: state.fatalError,
@@ -2531,7 +2131,7 @@ export function createDocumentRuntime(
       undefined,
       { scopeKind: "document" },
     ];
-    const workflowScopeSnapshot = getCachedWorkflowScopeSnapshot();
+    const workflowScopeSnapshot = workflowCoordinator.getWorkflowScopeSnapshot();
     const seenScopeIds = new Set<string>();
     for (const scope of workflowScopeSnapshot?.scopes ?? []) {
       if (seenScopeIds.has(scope.scopeId)) {
@@ -2544,7 +2144,7 @@ export function createDocumentRuntime(
       });
     }
     const seenWorkItemIds = new Set<string>();
-    for (const workItem of workflowOverlay?.workItems ?? []) {
+    for (const workItem of overlayStore.getOverlay()?.workItems ?? []) {
       if (seenWorkItemIds.has(workItem.workItemId)) {
         continue;
       }
@@ -2602,9 +2202,12 @@ export function createDocumentRuntime(
   }
 
   function refreshRenderSnapshot(): RuntimeRenderSnapshot {
+    emitStageToken(telemetryBus, "layout", "layout.refresh.start", {
+      revisionToken: state.revisionToken,
+    });
     perfCounters.increment("refresh.all");
     const surface = timeFacet("surface", () => getCachedSurface(state.document, activeStory));
-    return {
+    const snapshot = {
       documentId: state.documentId,
       sessionId: state.sessionId,
       sourceLabel: state.sourceLabel,
@@ -2631,6 +2234,10 @@ export function createDocumentRuntime(
       protectionSnapshot,
       grabbedObjectId: grabState.objectId,
     };
+    emitStageToken(telemetryBus, "layout", "layout.refresh.complete", {
+      revisionToken: state.revisionToken,
+    });
+    return snapshot;
   }
 
   /**
@@ -2644,7 +2251,12 @@ export function createDocumentRuntime(
       state.document,
       state.selection,
       activeStory,
-      { viewportBlockRange },
+      {
+        viewportBlockRange,
+        ...(effectiveMarkupModeProvider
+          ? { getEffectiveMarkupMode: effectiveMarkupModeProvider }
+          : {}),
+      },
     );
     // Refresh the cache with the just-built snapshot so a subsequent
     // refreshRenderSnapshot (same revisionToken + activeStoryKey) hits cache.
@@ -2675,10 +2287,7 @@ export function createDocumentRuntime(
     cachedPageLayout = undefined;
     cachedNavigation = undefined;
     cachedViewStateSnapshot = undefined;
-    cachedInteractionGuardSnapshot = undefined;
-    cachedWorkflowScopeSnapshot = undefined;
-    cachedNormalizedWorkflowOverlay = undefined;
-    cachedWorkflowMarkupSnapshot = undefined;
+    workflowCoordinator.invalidateCachesForDocumentMutation();
     cachedFieldSnapshotEntry = null;
     cachedContextAnalyticsSnapshots.clear();
     lastEmittedContextAnalyticsSnapshots = undefined;
@@ -2820,6 +2429,11 @@ export function createDocumentRuntime(
   const r5ScratchReplayState: typeof state = { ...state };
   const r5ScratchReplaySnapshot: typeof cachedRenderSnapshot = { ...cachedRenderSnapshot };
 
+  // `telemetryBus` is declared earlier (near `markerBackedScopeIds`) so
+  // early-hoisted calls to `syncMarkerBackedScopeIds` can emit on it. This
+  // is the facet consumed by `runtime.debug`.
+  const debugFacet = createRuntimeDebugFacet(() => runtime, telemetryBus);
+
   const runtime: DocumentRuntime & {
     hydrateCanonicalDocumentInternally(
       document: CanonicalDocumentEnvelope,
@@ -2838,6 +2452,9 @@ export function createDocumentRuntime(
       };
     },
     getRenderSnapshot() {
+      emitStageToken(telemetryBus, "render", "render.snapshot.read", {
+        revisionToken: cachedRenderSnapshot?.revisionToken ?? null,
+      });
       return cachedRenderSnapshot;
     },
     getCanonicalDocument() {
@@ -2872,7 +2489,7 @@ export function createDocumentRuntime(
     dispatch(command) {
       const commandSelection = getCommandSelection(command, state.selection);
       if (isMutationCommand(command)) {
-        const blockedReasons = evaluateWorkflowBlockedReasons(
+        const blockedReasons = workflowCoordinator.evaluateBlockedReasons(
           commandSelection,
           command.type,
         );
@@ -2903,7 +2520,7 @@ export function createDocumentRuntime(
         applyRuntimeStateOverlayCommand(command);
         const context = {
           timestamp: normalizeCommandTimestamp(command.origin?.timestamp) ?? clock(),
-          documentMode: getEffectiveDocumentMode(commandSelection),
+          documentMode: workflowCoordinator.getEffectiveDocumentMode(commandSelection),
           defaultAuthorId: defaultAuthorId ?? undefined,
         } as const;
         const noopTransaction: EditorTransaction = {
@@ -2924,7 +2541,7 @@ export function createDocumentRuntime(
       try {
         const context = {
           timestamp: normalizeCommandTimestamp(command.origin?.timestamp) ?? clock(),
-          documentMode: getEffectiveDocumentMode(commandSelection),
+          documentMode: workflowCoordinator.getEffectiveDocumentMode(commandSelection),
           defaultAuthorId: defaultAuthorId ?? undefined,
           renderSnapshot: cachedRenderSnapshot,
         } as const;
@@ -3000,7 +2617,7 @@ export function createDocumentRuntime(
           // at the same logical content. Do NOT adopt
           // `transaction.nextState.selection` — that is the remote
           // author's caret position, not B's. Without this, B would see
-          // their own cursor jump whenever A types.
+          // their own cursor jump whenever A types. (PR #243 fix.)
           const mappedLocalSelection = mapLocalSelectionOnRemoteReplay(
             state.selection,
             transaction.mapping,
@@ -3038,7 +2655,7 @@ export function createDocumentRuntime(
         // Running local selection: seeded from CURRENT local state, then
         // mapped forward through each same-story envelope's mapping.
         // Cross-story envelopes do not touch this value — B's caret
-        // should never move from a story B isn't looking at.
+        // should never move from a story B isn't looking at. (PR #243 fix.)
         let runningLocalSelection: typeof state.selection = state.selection;
         const warningsAdded: import("../core/state/editor-state.ts").EditorWarning[] = [];
         const warningsCleared: Array<{ warningId: string; code: import("../core/state/editor-state.ts").EditorWarning["code"] }> = [];
@@ -3204,6 +2821,143 @@ export function createDocumentRuntime(
         emitError(toRuntimeError(error));
       }
     },
+    applyScopeReplacement(plan: RuntimeOperationPlan) {
+      // Layer-08 Slice 5. Each step lowers to an existing command; the
+      // apply pipeline (`src/runtime/scopes/replacement/apply.ts`) owns
+      // the validation + audit emission around this call — keep the
+      // implementation strictly mechanical.
+      for (const step of plan.steps) {
+        if (step.kind === "text-replace" && step.range && typeof step.text === "string") {
+          const anchor: EditorAnchorProjection = {
+            kind: "range",
+            from: step.range.from,
+            to: step.range.to,
+            assoc: { start: -1, end: 1 },
+          };
+          const timestamp = clock();
+          try {
+            applyTextCommandInActiveStory(
+              {
+                type: "text.insert",
+                text: step.text,
+                origin: createOrigin("api", timestamp),
+              },
+              {
+                selection: createSelectionFromPublicAnchor(anchor),
+                blockedCommandName: "applyScopeReplacement",
+              },
+            );
+          } catch (error) {
+            emitError(toRuntimeError(error));
+          }
+        } else if (
+          step.kind === "fragment-replace" &&
+          step.range &&
+          step.fragment &&
+          Array.isArray((step.fragment as { blocks?: unknown }).blocks)
+        ) {
+          // Structured-fragment path (coord item 8 unblocked by L02
+          // shipping CanonicalDocumentFragment, 2026-04-22).
+          // Route through the existing fragment.insert command with
+          // the block range as selection — runtime command handler
+          // (src/core/commands/index.ts → applyFragmentInsert) replaces
+          // the selected content with the fragment's blocks.
+          const anchor: EditorAnchorProjection = {
+            kind: "range",
+            from: step.range.from,
+            to: step.range.to,
+            assoc: { start: -1, end: 1 },
+          };
+          const timestamp = clock();
+          try {
+            applyTextCommandInActiveStory(
+              {
+                type: "fragment.insert",
+                fragment: step.fragment as CanonicalDocumentFragment,
+                origin: createOrigin("api", timestamp),
+              },
+              {
+                selection: createSelectionFromPublicAnchor(anchor),
+                blockedCommandName: "applyScopeReplacement",
+              },
+            );
+          } catch (error) {
+            emitError(toRuntimeError(error));
+          }
+        }
+        else if (
+          step.kind === "text-insert-tracked" &&
+          step.range &&
+          typeof step.text === "string"
+        ) {
+          // L08 coord-08 §2 — suggest-mode tracked-insert dispatch primitive.
+          // The compiler emits `text-insert-tracked` only when apply posture
+          // is `"suggest-mode"`; we force the command context's documentMode
+          // to `"suggesting"` so `executeEditorCommand` routes the text.insert
+          // through `applySuggestingInsert` (which produces the insertion
+          // revision record) regardless of what the scope's auto-derived mode
+          // would be. For replacement ranges (from !== to), the tracked
+          // insert handler's non-collapsed branch emits a tracked deletion
+          // for the existing range and a tracked insertion for the new text
+          // in a single review-store update.
+          const anchor: EditorAnchorProjection = {
+            kind: "range",
+            from: step.range.from,
+            to: step.range.to,
+            assoc: { start: -1, end: 1 },
+          };
+          const timestamp = clock();
+          try {
+            applyTextCommandInActiveStory(
+              {
+                type: "text.insert",
+                text: step.text,
+                origin: createOrigin("api", timestamp),
+              },
+              {
+                selection: createSelectionFromPublicAnchor(anchor),
+                blockedCommandName: "applyScopeReplacement",
+                documentModeOverride: "suggesting",
+              },
+            );
+          } catch (error) {
+            emitError(toRuntimeError(error));
+          }
+        } else if (
+          step.kind === "text-delete-tracked" &&
+          step.range &&
+          step.range.to > step.range.from
+        ) {
+          // L08 coord-08 §2 — tracked deletion. Non-collapsed delete-forward
+          // with documentMode override routes into `applySuggestingDelete`,
+          // which appends a tracked deletion revision over the range without
+          // removing the content (matching the ledger-ish invariant of
+          // suggesting mode: accept → gone, reject → stays).
+          const anchor: EditorAnchorProjection = {
+            kind: "range",
+            from: step.range.from,
+            to: step.range.to,
+            assoc: { start: -1, end: 1 },
+          };
+          const timestamp = clock();
+          try {
+            applyTextCommandInActiveStory(
+              {
+                type: "text.delete-forward",
+                origin: createOrigin("api", timestamp),
+              },
+              {
+                selection: createSelectionFromPublicAnchor(anchor),
+                blockedCommandName: "applyScopeReplacement",
+                documentModeOverride: "suggesting",
+              },
+            );
+          } catch (error) {
+            emitError(toRuntimeError(error));
+          }
+        }
+      }
+    },
     insertFragment(fragment, target) {
       // I2 Tier B Slice 1 — dispatch `fragment.insert` against the active story. The
       // runtime command handler routes into `applyFragmentInsert` (structure-ops).
@@ -3526,196 +3280,36 @@ export function createDocumentRuntime(
         origin: createOrigin("api", clock()),
       });
     },
-    addScope(params): AddScopeResult {
-      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(state.document, {
-        scopeId,
-        from: anchor.from,
-        to: anchor.to,
-      });
-
-      if (nextDocument !== state.document) {
-        this.dispatch({
-          type: "document.replace",
-          document: nextDocument,
-          origin: createOrigin("api", clock()),
-        });
-      }
-
-      const resolved = resolveScope(nextDocument, scopeId);
-      const publicAnchor: EditorAnchorProjection =
-        resolved && resolved.kind === "range"
-          ? resolved
-          : {
-              kind: "range",
-              from: anchor.from,
-              to: anchor.to,
-              assoc: { start: -1, end: 1 },
-            };
-
-      const currentOverlay: WorkflowOverlay = workflowOverlay ?? {
-        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 } : {}),
-      };
-      this.dispatch({
-        type: "workflow.set-overlay",
-        overlay: {
-          ...currentOverlay,
-          scopes: [...existingScopes, scope],
-        },
-        origin: createOrigin("api", 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 }
-            : {}),
-        };
-        this.dispatch({
-          type: "workflow.set-metadata-entries",
-          entries: [...(workflowMetadataEntries ?? []), entry],
-          origin: createOrigin("api", clock()),
-        });
-      }
-
-      return {
-        scopeId,
-        anchor: publicAnchor,
-      };
+    addScope(params) {
+      return workflowCoordinator.addScope(params);
     },
     getScope(scopeId) {
-      const normalizedScope =
-        getNormalizedWorkflowOverlay()?.scopes.find((scope) => scope.scopeId === scopeId) ??
-        null;
-      if (normalizedScope) {
-        return normalizedScope;
-      }
-      const resolved = resolveScope(state.document, scopeId);
-      if (!resolved) {
-        return null;
-      }
-      return {
-        scopeId,
-        mode: "comment",
-        anchor: resolved,
-      };
+      return workflowCoordinator.getScope(scopeId);
+    },
+    compileScopeBundleById(scopeId, nowUtc) {
+      return createScopeCompilerService(runtime).compileBundleById(scopeId, nowUtc);
     },
+    getMarkerBackedScopeIds() {
+      return workflowCoordinator.getMarkerBackedScopeIds();
+    },
+    debug: debugFacet as RuntimeDebugFacet,
     removeScope(scopeId) {
-      // Step 1: drop the scope from the overlay FIRST. If the scope's mode was
-      // "comment" / "view" the workflow-blocked-reasons gate in `dispatch`
-      // would otherwise refuse the subsequent `document.replace` with
-      // `workflow_comment_only` / `workflow_view_only`. Overlay commands are
-      // routed through `applyRuntimeStateOverlayCommand` and bypass that gate.
-      if (workflowOverlay) {
-        const nextScopes = workflowOverlay.scopes.filter(
-          (scope) => scope.scopeId !== scopeId,
-        );
-        if (nextScopes.length !== workflowOverlay.scopes.length) {
-          this.dispatch({
-            type: "workflow.set-overlay",
-            overlay: { ...workflowOverlay, scopes: nextScopes },
-            origin: createOrigin("api", clock()),
-          });
-        }
-      }
-      // Step 2: now that the scope is gone, strip the markers from the doc.
-      const nextDocument = removeScopeMarkers(state.document, scopeId);
-      if (nextDocument !== state.document) {
-        this.dispatch({
-          type: "document.replace",
-          document: nextDocument,
-          origin: createOrigin("api", clock()),
-        });
-      }
-      // Step 3: clear any customXml-persisted metadata entries.
-      if (workflowMetadataEntries) {
-        const nextEntries = workflowMetadataEntries.filter(
-          (entry) => entry.scopeId !== scopeId,
-        );
-        if (nextEntries.length !== workflowMetadataEntries.length) {
-          this.dispatch({
-            type: "workflow.set-metadata-entries",
-            entries: nextEntries,
-            origin: createOrigin("api", clock()),
-          });
-        }
-      }
+      workflowCoordinator.removeScope(scopeId);
     },
     addInvisibleScope(params) {
-      const result = this.addScope({
-        ...params,
-        mode: params.mode ?? "comment",
-      });
-      this.setScopeVisibility(result.scopeId, "invisible");
-      return result;
+      return workflowCoordinator.addInvisibleScope(params);
     },
     setScopeVisibility(scopeId, visibility) {
-      if (!workflowOverlay) return;
-      const idx = workflowOverlay.scopes.findIndex((s) => s.scopeId === scopeId);
-      if (idx === -1) return;
-      const nextScopes = workflowOverlay.scopes.map((s) =>
-        s.scopeId === scopeId ? { ...s, visibility } : s,
-      );
-      this.dispatch({
-        type: "workflow.set-overlay",
-        overlay: { ...workflowOverlay, scopes: nextScopes },
-        origin: createOrigin("api", clock()),
-      });
+      workflowCoordinator.setScopeVisibility(scopeId, visibility);
     },
-    getScopeVisibility(scopeId): ScopeVisibility {
-      if (!workflowOverlay) return "visible";
-      const scope = workflowOverlay.scopes.find((s) => s.scopeId === scopeId);
-      return scope?.visibility ?? "visible";
+    getScopeVisibility(scopeId) {
+      return workflowCoordinator.getScopeVisibility(scopeId);
     },
-    setScopeChromeVisibility(state) {
-      scopeChromeVisibilityState = state;
+    setScopeChromeVisibility(chromeVisibility) {
+      workflowCoordinator.setScopeChromeVisibility(chromeVisibility);
     },
-    getScopeChromeVisibility(): ScopeChromeVisibilityState {
-      return scopeChromeVisibilityState;
+    getScopeChromeVisibility() {
+      return workflowCoordinator.getScopeChromeVisibility();
     },
     acceptChange(changeId) {
       this.dispatch({
@@ -3808,7 +3402,7 @@ export function createDocumentRuntime(
       };
 
       const suggesting =
-        getEffectiveDocumentMode(state.selection) === "suggesting";
+        workflowCoordinator.getEffectiveDocumentMode(state.selection) === "suggesting";
       if (suggesting) {
         if (activeStory.kind !== "main") {
           this.emitBlockedCommand("clearHighlight", [{
@@ -3980,7 +3574,7 @@ export function createDocumentRuntime(
         bookmarkMap,
         paragraphOffsets,
         styles: state.document.styles,
-        contentRoot: state.document.content as unknown as import("./field-resolver.ts").DocumentContainerNode,
+        contentRoot: state.document.content as unknown as import("./formatting/field/resolver.ts").DocumentContainerNode,
       });
     },
     getFootnoteResolver(): FootnoteResolver | undefined {
@@ -3994,6 +3588,21 @@ export function createDocumentRuntime(
       );
     },
     layout: layoutFacet,
+    workflow: {
+      getRailSegments(pageIndex: number) {
+        return workflowCoordinator.getRailSegments(pageIndex);
+      },
+      getAllRailSegments() {
+        return workflowCoordinator.getAllRailSegments();
+      },
+      getAllScopeCardModels() {
+        return workflowCoordinator.getAllScopeCardModels();
+      },
+    },
+    geometry: geometryFacet,
+    getLayoutFacet() {
+      return layoutFacet;
+    },
     getCurrentLocation() {
       const navigation = getCachedDocumentNavigationSnapshot(state, activeStory);
       return createCurrentLocation({
@@ -4179,7 +3788,9 @@ export function createDocumentRuntime(
     },
     getSessionState() {
       const compatibility = createDerivedCompatibility(state);
-      const normalizedWorkflowOverlay = getNormalizedWorkflowOverlay();
+      const normalizedWorkflowOverlay = workflowCoordinator.getWorkflowOverlay();
+      const visibilityPolicies = workflowCoordinator.getVisibilityPolicies();
+      const markupModePolicy = workflowCoordinator.getMarkupModePolicy();
       return editorSessionStateFromPersistedSnapshot(
         {
           ...(createPersistedEditorSnapshot(state, {
@@ -4189,7 +3800,9 @@ export function createDocumentRuntime(
             protectionSnapshot,
           }) as unknown as PersistedEditorSnapshot),
           workflowOverlay: normalizedWorkflowOverlay ?? undefined,
-          workflowMetadata: deriveWorkflowMetadataSnapshot(),
+          workflowMetadata: workflowCoordinator.getWorkflowMetadataSnapshot(),
+          ...(visibilityPolicies.length > 0 ? { visibilityPolicies } : {}),
+          ...(markupModePolicy ? { markupModePolicy } : {}),
         },
       );
     },
@@ -4234,17 +3847,25 @@ export function createDocumentRuntime(
               return { schemaVersion: "host-annotation-overlay/1", data: snap };
             }
             case "workflowOverlay": {
-              const ov = getNormalizedWorkflowOverlay();
+              const ov = workflowCoordinator.getWorkflowOverlay();
               if (!ov) return null;
               return { schemaVersion: "workflow-overlay/1", data: ov };
             }
             case "workflowMetadata": {
-              const meta = deriveWorkflowMetadataSnapshot();
+              const meta = workflowCoordinator.getWorkflowMetadataSnapshot();
               if (!meta || (meta.definitions.length === 0 && meta.entries.length === 0)) return null;
               return { schemaVersion: "workflow-metadata/1", data: meta };
             }
             case "workItems":
               return null;
+            case "embeddings":
+              // P8 Step 7: the session layer owns the `embeddings`
+              // namespace (load-time offload + export-time
+              // reconstitute) via
+              // `src/session/import/embedded-offload.ts` +
+              // `src/session/export/embedded-reconstitute.ts`.
+              // The runtime has no per-doc state to serialize here.
+              return null;
           }
         },
       });
@@ -4253,7 +3874,37 @@ export function createDocumentRuntime(
         _editorState: collectedEditorState,
       };
 
-      const result = await options.exportDocx(this.getSessionState(), internalOptions);
+      // Phase 1 io + serialize channels — bracket the exporter call so the
+      // `serialize.main_document.completed` emit runs with this runtime's bus.
+      setActiveSerializeTelemetryBus(telemetryBus);
+      let exportStart = 0;
+      if (telemetryBus.isEnabled("io")) {
+        exportStart = performance.now();
+        telemetryBus.emit({
+          channel: "io",
+          type: "io.export.start",
+          t: 0,
+          payload: { documentId: state.documentId },
+        });
+      }
+      let result: Awaited<ReturnType<typeof options.exportDocx>>;
+      try {
+        result = await options.exportDocx(this.getSessionState(), internalOptions);
+      } finally {
+        setActiveSerializeTelemetryBus(undefined);
+      }
+      if (telemetryBus.isEnabled("io")) {
+        telemetryBus.emit({
+          channel: "io",
+          type: "io.export.completed",
+          t: 0,
+          payload: {
+            documentId: state.documentId,
+            bytes: result.bytes?.byteLength ?? 0,
+            ms: performance.now() - exportStart,
+          },
+        });
+      }
 
       emit({
         type: "export_completed",
@@ -4264,87 +3915,81 @@ export function createDocumentRuntime(
       return result;
     },
     setWorkflowOverlay(overlay) {
-      this.dispatch({
-        type: "workflow.set-overlay",
-        overlay,
-        origin: createOrigin("api", clock()),
-      });
-      const normalizedWorkflowOverlay = getNormalizedWorkflowOverlay();
-      editorStateChannel.recordMutation("workflowOverlay", {
-        namespace: "workflowOverlay",
-        schemaVersion: "workflow-overlay/1",
-        data: normalizedWorkflowOverlay ?? overlay,
-      });
+      workflowCoordinator.setWorkflowOverlay(overlay);
     },
     clearWorkflowOverlay() {
-      this.dispatch({
-        type: "workflow.clear-overlay",
-        origin: createOrigin("api", clock()),
-      });
+      workflowCoordinator.clearWorkflowOverlay();
     },
     getWorkflowOverlay() {
-      return getNormalizedWorkflowOverlay();
+      return workflowCoordinator.getWorkflowOverlay();
     },
-    setSharedWorkflowState(state) {
-      if (state === sharedWorkflowState) return;
-      sharedWorkflowState = state;
-      // Invalidate guard/scope caches so next derivation reflects the new state.
-      cachedInteractionGuardSnapshot = undefined;
-      cachedWorkflowScopeSnapshot = undefined;
+    setSharedWorkflowState(sharedState) {
+      workflowCoordinator.setSharedWorkflowState(sharedState);
     },
     getWorkflowScopeSnapshot() {
-      return getCachedWorkflowScopeSnapshot();
+      return workflowCoordinator.getWorkflowScopeSnapshot();
     },
     getInteractionGuardSnapshot() {
-      return getCachedInteractionGuardSnapshot();
+      return workflowCoordinator.getInteractionGuardSnapshot();
     },
     getWorkflowMarkupSnapshot() {
-      return getCachedWorkflowMarkupSnapshot();
+      return workflowCoordinator.getWorkflowMarkupSnapshot();
     },
     setWorkflowMetadataDefinitions(definitions) {
-      this.dispatch({
-        type: "workflow.set-metadata-definitions",
-        definitions,
-        origin: createOrigin("api", clock()),
-      });
+      workflowCoordinator.setWorkflowMetadataDefinitions(definitions);
     },
     clearWorkflowMetadataDefinitions() {
-      this.dispatch({
-        type: "workflow.clear-metadata-definitions",
-        origin: createOrigin("api", clock()),
-      });
+      workflowCoordinator.clearWorkflowMetadataDefinitions();
     },
     setWorkflowMetadataEntries(entries) {
-      this.dispatch({
-        type: "workflow.set-metadata-entries",
-        entries,
-        origin: createOrigin("api", clock()),
-      });
-      editorStateChannel.recordMutation("workflowMetadata", {
-        namespace: "workflowMetadata",
-        schemaVersion: "workflow-metadata/1",
-        data: entries,
-      });
+      workflowCoordinator.setWorkflowMetadataEntries(entries);
     },
     clearWorkflowMetadataEntries() {
-      this.dispatch({
-        type: "workflow.clear-metadata-entries",
-        origin: createOrigin("api", clock()),
-      });
+      workflowCoordinator.clearWorkflowMetadataEntries();
     },
     getWorkflowMetadataSnapshot() {
-      return deriveWorkflowMetadataSnapshot();
+      return workflowCoordinator.getWorkflowMetadataSnapshot();
+    },
+    getVisibilityPolicy(kind) {
+      return workflowCoordinator.getVisibilityPolicy(kind);
+    },
+    getVisibilityPolicies() {
+      return workflowCoordinator.getVisibilityPolicies();
+    },
+    setVisibilityPolicy(policy) {
+      return workflowCoordinator.setVisibilityPolicy(policy);
+    },
+    clearVisibilityPolicy(kind) {
+      return workflowCoordinator.clearVisibilityPolicy(kind);
+    },
+    subscribeVisibilityPolicy(listener) {
+      return workflowCoordinator.subscribeVisibilityPolicy(listener);
+    },
+    getMarkupModePolicy() {
+      return workflowCoordinator.getMarkupModePolicy();
+    },
+    setMarkupModePolicy(policy) {
+      return workflowCoordinator.setMarkupModePolicy(policy);
+    },
+    subscribeMarkupModePolicy(listener) {
+      return workflowCoordinator.subscribeMarkupModePolicy(listener);
+    },
+    setEffectiveMarkupModeProvider(provider) {
+      effectiveMarkupModeProvider = provider ?? undefined;
+      // Re-project the surface so `cachedRenderSnapshot` reflects the
+      // new mode on the next `getRenderSnapshot()`. `refreshSurfaceOnly`
+      // also notifies listeners — React trees that have subscribed
+      // re-read synchronously.
+      refreshSurfaceOnly();
+    },
+    invalidateForMarkupModeChange() {
+      // Fast path for class-C local-preference flips. Provider is
+      // stable; cache invalidation is what propagates the new value.
+      // `refreshSurfaceOnly` notifies listeners as part of its work.
+      refreshSurfaceOnly();
     },
     queryScopes(filter) {
-      return runQueryScopes(
-        {
-          overlay: workflowOverlay,
-          entries: workflowMetadataEntries,
-          document: state.document,
-          markerBackedScopeIds,
-        },
-        filter,
-      );
+      return workflowCoordinator.queryScopes(filter);
     },
     subscribeToScopeQuery(filter, callback) {
       const buildAnchorKey = (anchor: EditorAnchorProjection): string => {
@@ -4444,10 +4089,10 @@ export function createDocumentRuntime(
       const hits = findAllScopesAt(state.document, pos);
       return projectScopeQueryResults(
         {
-          overlay: workflowOverlay,
-          entries: workflowMetadataEntries,
+          overlay: overlayStore.getOverlay(),
+          entries: overlayStore.getMetadataEntries(),
           document: state.document,
-          markerBackedScopeIds,
+          markerBackedScopeIds: overlayStore.getMarkerBackedScopeIds(),
         },
         hits.map((h) => h.scopeId),
         options,
@@ -4458,10 +4103,10 @@ export function createDocumentRuntime(
       const hits = findScopesIntersecting(state.document, range.from, range.to, options?.mode);
       return projectScopeQueryResults(
         {
-          overlay: workflowOverlay,
-          entries: workflowMetadataEntries,
+          overlay: overlayStore.getOverlay(),
+          entries: overlayStore.getMetadataEntries(),
           document: state.document,
-          markerBackedScopeIds,
+          markerBackedScopeIds: overlayStore.getMarkerBackedScopeIds(),
         },
         hits.map((h) => h.scopeId),
         options,
@@ -4530,14 +4175,14 @@ export function createDocumentRuntime(
       return createWorkflowChunks({
         document: state.document,
         navigation: getCachedDocumentNavigationSnapshot(state, activeStory),
-        workflowMarkup: getCachedWorkflowMarkupSnapshot(),
+        workflowMarkup: workflowCoordinator.getWorkflowMarkupSnapshot(),
       });
     },
     getReviewWorkSnapshot() {
       return createReviewWorkSnapshot({
         comments: cachedRenderSnapshot.comments,
         trackedChanges: cachedRenderSnapshot.trackedChanges,
-        workflowMarkup: getCachedWorkflowMarkupSnapshot(),
+        workflowMarkup: workflowCoordinator.getWorkflowMarkupSnapshot(),
         document: state.document,
         navigation: getCachedDocumentNavigationSnapshot(state, activeStory),
       });
@@ -4590,6 +4235,17 @@ export function createDocumentRuntime(
     },
   };
 
+  // Late-bind the workflow coordinator's dispatch accessor now that
+  // the runtime object exists. addScope / removeScope / setWorkflowOverlay /
+  // setWorkflowMetadataEntries and other coordinator methods route
+  // through this. Calling any of those before this line is a bug
+  // (guarded by the throw in the placeholder).
+  dispatchToRuntime = (command: unknown) => {
+    runtime.dispatch(
+      command as Parameters<typeof runtime.dispatch>[0],
+    );
+  };
+
   return runtime;
 
   function applyHistory(direction: "undo" | "redo"): void {
@@ -4667,6 +4323,12 @@ export function createDocumentRuntime(
       return;
     }
 
+    emitStageToken(telemetryBus, "commit", "commit.apply.start", {
+      revisionToken: state.revisionToken,
+      markDirty: transaction.markDirty,
+      stepCount: transaction.mapping?.steps?.length ?? 0,
+    });
+
     const previous = state;
 
     const tApply0 = performance.now();
@@ -4675,7 +4337,10 @@ export function createDocumentRuntime(
     state = finalizeState(transaction.nextState, transaction.markDirty, clock());
     perfCounters.increment("commit.finalizeState.us", Math.round((performance.now() - tFinalize0) * 1000));
     storySelections.set(storyTargetKey(activeStory), state.selection);
-    syncMarkerBackedScopeIds(state.document, workflowOverlay);
+    // Re-sync marker-backed scope IDs against the new document; the
+    // store handles set computation + telemetry. `replaceOverlay(current, doc)`
+    // is idempotent on state and re-derives the marker-backed set.
+    overlayStore.replaceOverlay(overlayStore.getOverlay(), state.document);
     const detachedWorkflowScopeWarnings = syncDetachedWorkflowScopeWarningsInState();
 
     const tInvalidate0 = performance.now();
@@ -4763,6 +4428,9 @@ export function createDocumentRuntime(
     });
     perfCounters.increment("commit.notify.us", Math.round((performance.now() - tNotify0) * 1000));
     perfCounters.increment("commit.total.us", Math.round((performance.now() - tApply0) * 1000));
+    emitStageToken(telemetryBus, "commit", "commit.apply.complete", {
+      revisionToken: state.revisionToken,
+    });
   }
 
   function notify(
@@ -4986,13 +4654,42 @@ export function createDocumentRuntime(
     textOptions: {
       selection?: EditorState["selection"];
       blockedCommandName?: string;
+      /**
+       * Force the command-execution `documentMode` for this dispatch
+       * regardless of what the workflow coordinator would infer from
+       * the selection's scope stack. Used by
+       * `applyScopeReplacement` for the `text-insert-tracked` +
+       * `text-delete-tracked` step kinds emitted by the L08 compiler:
+       * the compiler has already decided this step should produce
+       * tracked insertion/deletion revisions, so the runtime must
+       * route through the suggesting-mode branch unconditionally.
+       *
+       * Coord-08 §2 ("Suggest-mode tracked-insert dispatch primitive")
+       * asks for this verb; the implementation is a single-field
+       * override to the context that `executeEditorCommand` reads.
+       */
+      documentModeOverride?: DocumentMode;
     } = {},
   ): TextCommandAck {
+    emitStageToken(telemetryBus, "command", "command.dispatch.start", {
+      commandType: command.type,
+    });
+    // Every exit of this function must emit a matching `.complete` stage
+    // token so the `command` channel carries start/complete pairs just like
+    // the `commit` channel does. D1 lineage reads the pair as proof no
+    // silent short-circuit swallowed the dispatch.
+    const completeDispatch = (ack: TextCommandAck): TextCommandAck => {
+      emitStageToken(telemetryBus, "command", "command.dispatch.complete", {
+        commandType: command.type,
+        outcome: ack.kind,
+      });
+      return ack;
+    };
     const opId = (command.origin as { opId?: string } | undefined)?.opId;
     const selection = textOptions.selection ?? state.selection;
     if (
       activeStory.kind !== "main" &&
-      getEffectiveDocumentMode(selection) === "suggesting" &&
+      workflowCoordinator.getEffectiveDocumentMode(selection) === "suggesting" &&
       command.type === "paragraph.split"
     ) {
       const message = `"${command.type}" is not supported in suggesting mode for this story.`;
@@ -5006,14 +4703,14 @@ export function createDocumentRuntime(
           storyTarget: activeStory,
         }],
       });
-      return {
+      return completeDispatch({
         kind: "rejected",
         opId,
         newRevisionToken: "",
         blockedReasons: [{ code: "suggesting_unsupported", message }],
-      };
+      });
     }
-    const blockedReasons = evaluateWorkflowBlockedReasons(selection, command.type);
+    const blockedReasons = workflowCoordinator.evaluateBlockedReasons(selection, command.type);
     if (blockedReasons.length > 0) {
       emit({
         type: "command_blocked",
@@ -5021,18 +4718,20 @@ export function createDocumentRuntime(
         command: textOptions.blockedCommandName ?? command.type,
         reasons: blockedReasons,
       });
-      return {
+      return completeDispatch({
         kind: "rejected",
         opId,
         newRevisionToken: "",
         blockedReasons: blockedReasons.map((r) => ({ code: r.code, message: r.message })),
-      };
+      });
     }
 
     const timestamp = normalizeCommandTimestamp(command.origin?.timestamp) ?? clock();
     const context = {
       timestamp,
-      documentMode: getEffectiveDocumentMode(selection),
+      documentMode:
+        textOptions.documentModeOverride ??
+        workflowCoordinator.getEffectiveDocumentMode(selection),
       defaultAuthorId: defaultAuthorId ?? undefined,
       renderSnapshot: cachedRenderSnapshot,
     } as const;
@@ -5054,13 +4753,13 @@ export function createDocumentRuntime(
         activeStory: preActiveStory,
         priorDocument,
       });
-      return classifyAck({
+      return completeDispatch(classifyAck({
         command,
         opId,
         priorState: baseState,
         transaction: mainTransaction,
         newRevisionToken: state.revisionToken,
-      });
+      }));
     }
 
     const localState = createEditorState({
@@ -5091,11 +4790,11 @@ export function createDocumentRuntime(
         historyBoundary: "skip",
         markDirty: false,
       });
-      return {
+      return completeDispatch({
         kind: "equivalent",
         opId,
         newRevisionToken: state.revisionToken,
-      };
+      });
     }
 
     const nextDocument = replaceStoryBlocks(
@@ -5136,13 +4835,13 @@ export function createDocumentRuntime(
       activeStory: preActiveStory,
       priorDocument,
     });
-    return classifyAck({
+    return completeDispatch(classifyAck({
       command,
       opId,
       priorState: baseState,
       transaction: mergedTransaction,
       newRevisionToken: state.revisionToken,
-    });
+    }));
   }
 
   function classifyAck(params: {
@@ -5346,7 +5045,7 @@ export function createDocumentRuntime(
       // text is not heading text), so this does not loop.
       const ctx = {
         timestamp: clock(),
-        documentMode: getEffectiveDocumentMode(state.selection),
+        documentMode: workflowCoordinator.getEffectiveDocumentMode(state.selection),
         defaultAuthorId: defaultAuthorId ?? undefined,
         renderSnapshot: cachedRenderSnapshot,
       } as const;
@@ -5381,6 +5080,54 @@ export function createDocumentRuntime(
     const t0 = performance.now();
     emitInternal(event);
     perfCounters.increment(`emit.${event.type}.internal.us`, Math.round((performance.now() - t0) * 1000));
+    // Phase 1 — telemetry fan-out. One central emit covering warning / scope /
+    // commit / selection / collab channels. Each branch early-returns if the
+    // corresponding channel is off (one bitmask AND). Zero alloc when all off.
+    if (telemetryBus.isEnabled("warning") && event.type === "warning_added") {
+      telemetryBus.emit({
+        channel: "warning",
+        type: `warning.${event.warning.code}`,
+        t: 0,
+        payload: {
+          warningId: event.warning.warningId,
+          code: event.warning.code,
+          severity: event.warning.severity,
+          source: event.warning.source,
+          scopeId: (event.warning as { scopeId?: string }).scopeId,
+        },
+      });
+    } else if (telemetryBus.isEnabled("warning") && event.type === "warning_cleared") {
+      telemetryBus.emit({
+        channel: "warning",
+        type: "warning.cleared",
+        t: 0,
+        payload: { warningId: event.warningId, code: event.code },
+      });
+    }
+    if (
+      telemetryBus.isEnabled("scope") &&
+      event.type === "workflow_overlay_changed"
+    ) {
+      telemetryBus.emitLazy("scope", () => {
+        const overlay = overlayStore.getOverlay();
+        return {
+          type: "scope.overlay_changed",
+          payload: {
+            markerBackedCount: overlayStore.getMarkerBackedScopeIds().size,
+            overlayScopeCount: overlay?.scopes.length ?? 0,
+            activeWorkItemId: overlay?.activeWorkItemId ?? null,
+          },
+        };
+      });
+    }
+    if (telemetryBus.isEnabled("selection") && event.type === "selection_changed") {
+      telemetryBus.emit({
+        channel: "selection",
+        type: "selection.changed",
+        t: 0,
+        payload: { isCollapsed: (event as { selection?: { isCollapsed?: boolean } }).selection?.isCollapsed ?? true },
+      });
+    }
     if (shouldEmitContextAnalyticsChanged(event)) {
       scheduleContextAnalyticsEmit();
     }
@@ -5396,85 +5143,43 @@ export function createDocumentRuntime(
         }
       | null = null;
     switch (command.type) {
-      case "workflow.set-overlay": {
-        workflowOverlay = structuredClone(command.overlay);
-        syncMarkerBackedScopeIds(state.document, workflowOverlay);
-        cachedNormalizedWorkflowOverlay = undefined;
-        detachedWorkflowScopeWarnings = syncDetachedWorkflowScopeWarningsInState();
-        cachedRenderSnapshot = refreshRenderSnapshot();
-        const snapshot = deriveWorkflowScopeSnapshot()!;
-        emit({
-          type: "workflow_overlay_changed",
-          documentId: state.documentId,
-          snapshot,
-        });
-        if (workflowOverlay.activeWorkItemId !== undefined) {
-          emit({
-            type: "workflow_active_work_item_changed",
-            documentId: state.documentId,
-            activeWorkItemId: workflowOverlay.activeWorkItemId ?? null,
-          });
-        }
-        break;
-      }
-      case "workflow.clear-overlay": {
-        workflowOverlay = null;
-        syncMarkerBackedScopeIds(state.document, workflowOverlay);
-        cachedNormalizedWorkflowOverlay = undefined;
-        detachedWorkflowScopeWarnings = syncDetachedWorkflowScopeWarningsInState();
-        cachedRenderSnapshot = refreshRenderSnapshot();
-        emit({
-          type: "workflow_active_work_item_changed",
-          documentId: state.documentId,
-          activeWorkItemId: null,
-        });
-        emit({
-          type: "workflow_overlay_changed",
-          documentId: state.documentId,
-          snapshot: {
-            overlayPresent: false,
-            activeWorkItemId: null,
-            scopes: [],
-            candidates: [],
-            blockedReasons: [],
-          },
-        });
-        break;
-      }
-      case "workflow.set-metadata-definitions": {
-        workflowMetadataDefinitions = structuredClone(command.definitions);
-        emit({
-          type: "workflow_metadata_changed",
-          documentId: state.documentId,
-          snapshot: deriveWorkflowMetadataSnapshot(),
-        });
-        break;
-      }
-      case "workflow.clear-metadata-definitions": {
-        workflowMetadataDefinitions = [];
-        emit({
-          type: "workflow_metadata_changed",
-          documentId: state.documentId,
-          snapshot: deriveWorkflowMetadataSnapshot(),
-        });
-        break;
-      }
-      case "workflow.set-metadata-entries": {
-        workflowMetadataEntries = structuredClone(command.entries);
-        emit({
-          type: "workflow_metadata_changed",
-          documentId: state.documentId,
-          snapshot: deriveWorkflowMetadataSnapshot(),
-        });
-        break;
-      }
+      case "workflow.set-overlay":
+      case "workflow.clear-overlay":
+      case "workflow.set-metadata-definitions":
+      case "workflow.clear-metadata-definitions":
+      case "workflow.set-metadata-entries":
       case "workflow.clear-metadata-entries": {
-        workflowMetadataEntries = [];
-        emit({
-          type: "workflow_metadata_changed",
-          documentId: state.documentId,
-          snapshot: deriveWorkflowMetadataSnapshot(),
-        });
+        // Delegate all workflow overlay / metadata commands to the
+        // coordinator. It owns state mutation (via the overlay store),
+        // cache invalidation, and event emission. The returned
+        // warning-delta (if any) is rewritten into the runtime's
+        // state.warnings array by `syncDetachedScopeWarnings` called
+        // from inside the coordinator, then surfaced through the
+        // `warning_added` / `warning_cleared` emit loop below.
+        const warningDelta = workflowCoordinator.applyOverlayCommand(
+          command as Parameters<typeof workflowCoordinator.applyOverlayCommand>[0],
+          () => {
+            cachedRenderSnapshot = refreshRenderSnapshot();
+          },
+        );
+        if (warningDelta) {
+          const priorWarnings = state.warnings;
+          if (
+            warningDelta.nextWarnings !== priorWarnings &&
+            warningDelta.nextWarnings.length + priorWarnings.length > 0
+          ) {
+            state = { ...state, warnings: warningDelta.nextWarnings };
+          }
+          if (warningDelta.added.length > 0 || warningDelta.cleared.length > 0) {
+            detachedWorkflowScopeWarnings = {
+              added: warningDelta.added,
+              cleared: warningDelta.cleared.map((c) => ({
+                warningId: c.warningId,
+                code: c.code,
+              })),
+            };
+          }
+        }
         break;
       }
       case "host-annotation.set-overlay": {
@@ -5591,8 +5296,8 @@ export function createDocumentRuntime(
         trackedSnapshots.get(
           getRuntimeContextAnalyticsQueryKey(
             resolveCurrentContextAnalyticsQuery({
-              workflowScopeSnapshot: getCachedWorkflowScopeSnapshot(),
-              interactionGuardSnapshot: getCachedInteractionGuardSnapshot(),
+              workflowScopeSnapshot: workflowCoordinator.getWorkflowScopeSnapshot(),
+              interactionGuardSnapshot: workflowCoordinator.getInteractionGuardSnapshot(),
             }),
           ),
         ) ?? null,
@@ -5994,15 +5699,17 @@ function toPublicCompatibilityReport(
 function toPublicCompatibilityFeatureEntry(
   entry: InternalCompatibilityFeatureEntry,
 ) {
-  return {
-    ...entry,
-    affectedAnchor: entry.affectedAnchor
-      ? toPublicAnchorProjection(entry.affectedAnchor)
-      : undefined,
-  };
+  // Internal* collapsed to public-type aliases 2026-04-22 — the record
+  // `affectedAnchor` is already the public flat shape end-to-end (see
+  // `docs/plans/cross-layer-coord-02.md §8`).
+  return { ...entry };
 }
 
 function toPublicWarning(warning: InternalEditorWarning): EditorWarning {
+  // Internal* collapsed to public-type aliases 2026-04-22; anchor is
+  // already public flat. The function remains meaningful — it still
+  // synthesises the v2.0.0 `diagnostic` composite from legacy warning
+  // codes when absent. Anchor handling is now identity.
   const diagnostic =
     warning.diagnostic ??
     (() => {
@@ -6025,9 +5732,7 @@ function toPublicWarning(warning: InternalEditorWarning): EditorWarning {
               source: warning.source,
             },
             details: warning.details,
-            affectedAnchor: warning.affectedAnchor
-              ? toPublicAnchorProjection(warning.affectedAnchor)
-              : undefined,
+            affectedAnchor: warning.affectedAnchor,
           });
         default:
           return undefined;
@@ -6035,9 +5740,6 @@ function toPublicWarning(warning: InternalEditorWarning): EditorWarning {
     })();
   return {
     ...warning,
-    affectedAnchor: warning.affectedAnchor
-      ? toPublicAnchorProjection(warning.affectedAnchor)
-      : undefined,
     diagnostic,
   };
 }
@@ -6771,7 +6473,7 @@ function refreshDocumentFields(
     return { document, updatedCount, changed: false };
   }
 
-  const nextDocument: CanonicalDocumentEnvelope = {
+  const nextDocument: MutableCanonicalDocument = {
     ...document,
     content: {
       ...document.content,
@@ -6779,7 +6481,7 @@ function refreshDocumentFields(
     },
     ...(nextSubParts ? { subParts: nextSubParts } : {}),
   };
-  const nextRegistry = buildFieldRegistry({
+  const nextRegistry = rebuildFieldRegistry({
     content: nextDocument.content,
     styles: nextDocument.styles,
     subParts: nextDocument.subParts,
@@ -6883,14 +6585,14 @@ function refreshDocumentTableOfContents(
     };
   }
 
-  const nextDocument: CanonicalDocumentEnvelope = {
+  const nextDocument: MutableCanonicalDocument = {
     ...document,
     content: {
       ...document.content,
       children: nextChildren,
     },
   };
-  const nextRegistry = buildFieldRegistry({
+  const nextRegistry = rebuildFieldRegistry({
     content: nextDocument.content,
     styles: nextDocument.styles,
     subParts: nextDocument.subParts,