@beyondwork/docx-react-component 1.0.66 → 1.0.69

package/src/runtime/workflow/overlay-store.ts

@@ -0,0 +1,690 @@
+/**
+ * Layer 06 — Workflow overlay store.
+ *
+ * Owns the per-runtime workflow state that used to live as top-level
+ * closure variables inside `document-runtime.ts`:
+ *   - workflow overlay (scopes + candidates + work items + active-work-item)
+ *   - workflow metadata (definitions + entries)
+ *   - marker-backed scope-id set (derived from canonical document)
+ *   - shared workflow state (collab round-locked mode)
+ *   - scope-chrome visibility (local UI state; never collab-replicated)
+ *
+ * Plus the pure-ish derivations the store alone can safely compute:
+ *   - `normalizeOverlayForDocument` — converts overlay anchors into
+ *     normalized range / node / detached shapes given the current
+ *     canonical document. Cached per (document, overlay) pair.
+ *   - `buildDetachedScopeWarnings` + `createInvalidatedScopeWarning` —
+ *     synthesize the `workflow_scope_invalidated` warning when a
+ *     previously marker-backed scope has been detached.
+ *   - `mergeDetachedScopeWarnings` — diff desired-vs-existing detached
+ *     warnings so the runtime can emit precise `warning_added` /
+ *     `warning_cleared` deltas.
+ *
+ * What it does NOT own (by design — those belong to the coordinator):
+ *   - interaction-guard / workflow-scope / workflow-markup snapshot
+ *     caches (require runtime-scope deps like revisionToken, render
+ *     snapshot, selection).
+ *   - blocked-reason composition + scope-matching heuristics (require
+ *     protection snapshot + viewState.documentMode).
+ *   - rail / card composition (requires page graph + render frame).
+ *
+ * This file must satisfy Layer-06 purity contract W9: no imports from
+ * `document-runtime.ts`, `render`, `ui*`, `api/v*`, or `io`.
+ * Enforced by `scripts/ci-check-workflow-layer-purity.mjs`.
+ */
+
+import type {
+  EditorAnchorProjection,
+  ScopeChromeVisibilityState,
+  WorkflowMetadataDefinition,
+  WorkflowMetadataEntry,
+  WorkflowMetadataSnapshot,
+  WorkflowOverlay,
+  WorkflowScope,
+} from "../../api/public-types.ts";
+import {
+  type CanonicalDocumentEnvelope,
+  type EditorWarning as InternalEditorWarning,
+} from "../../core/state/editor-state.ts";
+import type { SharedWorkflowState } from "../collab/workflow-shared.ts";
+import type { TelemetryBus } from "../debug/telemetry-bus.ts";
+import { toInternalAnchorProjection } from "../../core/selection/anchor-conversion.ts";
+import { buildDiagnosticFromLegacyWarningCode } from "../diagnostics/build-diagnostic.ts";
+import { collectScopeLocations } from "./scope-resolver.ts";
+import {
+  overlayVisibilityPoliciesEqual,
+  type OverlayKind,
+  type OverlayVisibilityPolicy,
+} from "./visibility-policy.ts";
+import {
+  workflowMarkupModePoliciesEqual,
+  type WorkflowMarkupModePolicy,
+} from "./markup-mode-policy.ts";
+
+export interface OverlayStoreConfig {
+  readonly initialOverlay: WorkflowOverlay | null;
+  readonly initialMetadataDefinitions: readonly WorkflowMetadataDefinition[];
+  readonly initialMetadataEntries: readonly WorkflowMetadataEntry[];
+  readonly initialVisibilityPolicies?: readonly OverlayVisibilityPolicy[];
+  /** X5 — class-A markup-mode policy. Single record; null = document
+   * predates the schema (consumer falls back to class-C default). */
+  readonly initialMarkupModePolicy?: WorkflowMarkupModePolicy | null;
+  readonly telemetryBus: TelemetryBus;
+}
+
+/** Result of `mergeDetachedScopeWarnings` — the existing `warnings`
+ * array replaced with the next-consistent state plus a per-warning
+ * delta suitable for emitting `warning_added` / `warning_cleared`
+ * events at the dispatch site. */
+export interface MergeDetachedWarningsResult {
+  readonly nextWarnings: InternalEditorWarning[];
+  readonly added: InternalEditorWarning[];
+  readonly cleared: Array<{
+    readonly warningId: string;
+    readonly code: InternalEditorWarning["code"];
+  }>;
+}
+
+export interface OverlayStore {
+  // ---- state getters ----
+  getOverlay(): WorkflowOverlay | null;
+  getMetadataDefinitions(): readonly WorkflowMetadataDefinition[];
+  getMetadataEntries(): readonly WorkflowMetadataEntry[];
+  getMarkerBackedScopeIds(): ReadonlySet<string>;
+  getSharedWorkflowState(): SharedWorkflowState | null;
+  getScopeChromeVisibility(): ScopeChromeVisibilityState;
+  /** W10 — class-A visibility policy for a single overlay kind. Returns
+   * `null` when no policy has been authored for that kind. */
+  getVisibilityPolicy(kind: OverlayKind): OverlayVisibilityPolicy | null;
+  /** W10 — full policy set (zero or more entries; never more than one
+   * per OverlayKind). Order is deterministic per `OVERLAY_KINDS`. */
+  getVisibilityPolicies(): readonly OverlayVisibilityPolicy[];
+
+  // ---- state mutations (invoked by coordinator dispatch branches) ----
+  /** Replace the overlay and sync marker-backed scope set. Invalidates
+   * the normalization cache. Returns nothing — the caller is
+   * responsible for cache invalidation downstream (guard / scope /
+   * markup) and for emitting the matching workflow_* events. */
+  replaceOverlay(
+    next: WorkflowOverlay | null,
+    document: CanonicalDocumentEnvelope,
+  ): void;
+  replaceMetadataDefinitions(defs: readonly WorkflowMetadataDefinition[]): void;
+  replaceMetadataEntries(entries: readonly WorkflowMetadataEntry[]): void;
+  replaceSharedWorkflowState(state: SharedWorkflowState | null): void;
+  replaceScopeChromeVisibility(visibility: ScopeChromeVisibilityState): void;
+  /** W10 — set (or clear) a single overlay kind's visibility policy.
+   * Returns `true` when the policy set actually changed, `false` on
+   * no-op. Callers emit the matching workflow_* event + persist via
+   * customXml export only when this returns `true`. */
+  replaceVisibilityPolicy(
+    kind: OverlayKind,
+    policy: OverlayVisibilityPolicy | null,
+  ): boolean;
+  /** W10 — bulk replace the policy set (e.g., on reload or collab
+   * state sync). Same semantics as per-kind but atomic. */
+  replaceVisibilityPolicies(
+    policies: readonly OverlayVisibilityPolicy[],
+  ): boolean;
+  /** W10 — subscribe to any policy-set change (any kind). Listener
+   * fires after the store mutation lands, once per settled change.
+   * Returns an unsubscribe function. */
+  subscribeVisibilityPolicy(listener: () => void): () => void;
+  /** W10 — internal signal emitter. Coordinator/runtime invoke this
+   * AFTER a successful `replaceVisibilityPolicy` / `replaceVisibilityPolicies`
+   * call to notify subscribers. Kept on the store so the policy-notify
+   * pipeline stays self-contained (no external bus coupling). */
+  notifyVisibilityPolicyChanged(): void;
+
+  /** X5 — class-A markup-mode policy (single record; null = none). */
+  getMarkupModePolicy(): WorkflowMarkupModePolicy | null;
+  /** X5 — replace the policy record. Returns `true` on actual change. */
+  replaceMarkupModePolicy(policy: WorkflowMarkupModePolicy | null): boolean;
+  /** X5 — subscribe to markup-mode policy changes. */
+  subscribeMarkupModePolicy(listener: () => void): () => void;
+  /** X5 — internal signal emitter for markup-mode changes. */
+  notifyMarkupModePolicyChanged(): void;
+
+  // ---- derivations ----
+  /** Normalized overlay for a given document. Returns null when no
+   * overlay is set. Uses (document, overlay) reference equality to
+   * short-circuit. */
+  getNormalizedOverlay(document: CanonicalDocumentEnvelope): WorkflowOverlay | null;
+
+  /** Structured-clone metadata definitions + entries for API callers
+   * so downstream mutations don't leak back into the store. */
+  getMetadataSnapshot(): WorkflowMetadataSnapshot;
+
+  // ---- warning synthesis ----
+  /** Pure factory — builds a `workflow_scope_invalidated` warning for
+   * a detached scope, including diagnostic + llmMetadata for recovery. */
+  createInvalidatedScopeWarning(scope: WorkflowScope): InternalEditorWarning;
+
+  /** Diff the detached-scope warnings we *want* (one per detached
+   * scope in the overlay) against the warnings already in `existing`.
+   * Returns the next warning list plus a precise add/clear delta. */
+  mergeDetachedScopeWarnings(
+    overlay: WorkflowOverlay | null,
+    existing: readonly InternalEditorWarning[],
+  ): MergeDetachedWarningsResult;
+}
+
+/* ---------------------------------------------------------------- *\
+ * Private pure helpers (not exported — internal to the store)
+\* ---------------------------------------------------------------- */
+
+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 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 emitMarkerBackedDelta(
+  bus: TelemetryBus,
+  prior: ReadonlySet<string>,
+  next: ReadonlySet<string>,
+): void {
+  if (!bus.isEnabled("scope")) return;
+  const added: string[] = [];
+  const removed: string[] = [];
+  for (const id of next) if (!prior.has(id)) added.push(id);
+  for (const id of prior) if (!next.has(id)) removed.push(id);
+  if (added.length === 0 && removed.length === 0) return;
+  bus.emit({
+    channel: "scope",
+    type: "scope.marker_backed_delta",
+    t: 0,
+    payload: { added, removed, total: next.size },
+  });
+}
+
+/* ---------------------------------------------------------------- *\
+ * Factory
+\* ---------------------------------------------------------------- */
+
+export function createOverlayStore(config: OverlayStoreConfig): OverlayStore {
+  let overlay: WorkflowOverlay | null = config.initialOverlay
+    ? structuredClone(config.initialOverlay)
+    : null;
+  let metadataDefinitions: WorkflowMetadataDefinition[] = structuredClone(
+    [...config.initialMetadataDefinitions],
+  );
+  let metadataEntries: WorkflowMetadataEntry[] = structuredClone(
+    [...config.initialMetadataEntries],
+  );
+  let markerBackedScopeIds: ReadonlySet<string> = new Set<string>();
+  let sharedWorkflowState: SharedWorkflowState | null = null;
+  let scopeChromeVisibility: ScopeChromeVisibilityState = { mode: "all" };
+  // W10 — class-A visibility policies keyed by OverlayKind. Cloned on
+  // read so callers cannot mutate stored records.
+  let visibilityPolicies: Map<OverlayKind, OverlayVisibilityPolicy> = new Map(
+    (config.initialVisibilityPolicies ?? []).map((policy) => [
+      policy.kind,
+      structuredClone(policy),
+    ]),
+  );
+  const visibilityPolicyListeners = new Set<() => void>();
+  // X5 · markup-mode policy — single record, not per-kind.
+  let markupModePolicy: WorkflowMarkupModePolicy | null =
+    config.initialMarkupModePolicy
+      ? structuredClone(config.initialMarkupModePolicy)
+      : null;
+  const markupModePolicyListeners = new Set<() => void>();
+
+  let normalizedOverlayCache:
+    | {
+        document: CanonicalDocumentEnvelope;
+        overlay: WorkflowOverlay;
+        normalized: WorkflowOverlay;
+      }
+    | undefined;
+
+  function syncMarkerBackedScopeIds(
+    document: CanonicalDocumentEnvelope,
+    currentOverlay: WorkflowOverlay | null,
+  ): void {
+    const prior = markerBackedScopeIds;
+    const presentScopeIds = new Set(collectScopeLocations(document).keys());
+    if (!currentOverlay) {
+      markerBackedScopeIds = presentScopeIds;
+      emitMarkerBackedDelta(config.telemetryBus, prior, markerBackedScopeIds);
+      return;
+    }
+    const overlayScopeIds = new Set(
+      currentOverlay.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;
+    emitMarkerBackedDelta(config.telemetryBus, prior, next);
+  }
+
+  function normalizeOverlayForDocument(
+    document: CanonicalDocumentEnvelope,
+    source: WorkflowOverlay,
+  ): WorkflowOverlay {
+    if (
+      normalizedOverlayCache &&
+      normalizedOverlayCache.document === document &&
+      normalizedOverlayCache.overlay === source
+    ) {
+      return normalizedOverlayCache.normalized;
+    }
+
+    const scopeIdCounts = new Map<string, number>();
+    for (const scope of source.scopes) {
+      scopeIdCounts.set(scope.scopeId, (scopeIdCounts.get(scope.scopeId) ?? 0) + 1);
+    }
+    const locations = collectScopeLocations(document);
+    let changed = false;
+    const normalizedScopes = source.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
+      ) {
+        // Coord-06 §13d — preserve the scope's original `assoc` when
+        // normalizing marker positions. Pre-§13d this hardcoded
+        // `{ start: -1, end: 1 }` (fixed), dropping the caller's
+        // `{ start: 1, end: -1 }` (greedy — default) or any other
+        // variant authored via `CreateScopeFromBlockIdInput.assoc`.
+        // Agents pin signature-block / template-slot scopes with
+        // `{ -1, 1 }` via the v3 primitive; that pin is meaningless
+        // if normalization erases it every render.
+        const preservedAssoc: { start: -1 | 1; end: -1 | 1 } =
+          scope.anchor.kind === "range"
+            ? scope.anchor.assoc
+            : { start: -1, end: 1 };
+        nextAnchor = {
+          kind: "range",
+          from: Math.min(location.startPos, location.endPos),
+          to: Math.max(location.startPos, location.endPos),
+          assoc: preservedAssoc,
+        };
+      } 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
+      ? { ...source, scopes: normalizedScopes }
+      : source;
+    normalizedOverlayCache = {
+      document,
+      overlay: source,
+      normalized,
+    };
+    return normalized;
+  }
+
+  function createInvalidatedScopeWarning(
+    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",
+      // Internal* collapsed to public flat 2026-04-22 (see
+      // `docs/plans/cross-layer-coord-02.md §8`). `scope.anchor` is
+      // already public flat; no `toInternalAnchorProjection` wrap.
+      affectedAnchor: 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.",
+      },
+    };
+  }
+
+  function mergeDetachedScopeWarnings(
+    normalizedOverlay: WorkflowOverlay | null,
+    existing: readonly InternalEditorWarning[],
+  ): MergeDetachedWarningsResult {
+    const detachedScopesById = new Map<string, WorkflowScope>();
+    for (const scope of normalizedOverlay?.scopes ?? []) {
+      if (scope.anchor.kind === "detached") {
+        detachedScopesById.set(scope.scopeId, scope);
+      }
+    }
+
+    const retainedWarnings = existing.filter(
+      (warning) => warning.code !== "workflow_scope_invalidated",
+    );
+    const existingDetachedWarnings = existing.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 = createInvalidatedScopeWarning(scope);
+        return [warning.warningId, warning] as const;
+      }),
+    );
+
+    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,
+    };
+  }
+
+  /* -------------------- public store surface -------------------- */
+
+  // Pre-populate the marker-backed set — deferred until after the
+  // coordinator first calls `replaceOverlay` with the runtime's
+  // initial document; until then the set is empty. The coordinator
+  // also invokes `syncInitialMarkerBackedScopeIds` directly from the
+  // runtime's constructor so the first getSnapshot() sees a populated
+  // set even before any overlay commands dispatch.
+
+  return {
+    getOverlay: () => overlay,
+    getMetadataDefinitions: () => metadataDefinitions,
+    getMetadataEntries: () => metadataEntries,
+    getMarkerBackedScopeIds: () => markerBackedScopeIds,
+    getSharedWorkflowState: () => sharedWorkflowState,
+    getScopeChromeVisibility: () => scopeChromeVisibility,
+    getVisibilityPolicy(kind) {
+      const entry = visibilityPolicies.get(kind);
+      return entry ? structuredClone(entry) : null;
+    },
+    getVisibilityPolicies() {
+      // Deterministic order by OverlayKind — needed for byte-identical
+      // re-export when unchanged. Stored keys are the canonical set.
+      return [...visibilityPolicies.values()].map((policy) => structuredClone(policy));
+    },
+
+    replaceOverlay(next, document) {
+      overlay = next ? structuredClone(next) : null;
+      normalizedOverlayCache = undefined;
+      syncMarkerBackedScopeIds(document, overlay);
+    },
+    replaceMetadataDefinitions(defs) {
+      metadataDefinitions = structuredClone([...defs]);
+    },
+    replaceMetadataEntries(entries) {
+      metadataEntries = structuredClone([...entries]);
+    },
+    replaceSharedWorkflowState(state) {
+      sharedWorkflowState = state;
+    },
+    replaceScopeChromeVisibility(visibility) {
+      scopeChromeVisibility = visibility;
+    },
+    replaceVisibilityPolicy(kind, policy) {
+      const existing = visibilityPolicies.get(kind) ?? null;
+      if (overlayVisibilityPoliciesEqual(existing, policy)) {
+        return false;
+      }
+      if (!policy) {
+        visibilityPolicies.delete(kind);
+      } else {
+        visibilityPolicies.set(kind, structuredClone(policy));
+      }
+      return true;
+    },
+    replaceVisibilityPolicies(next) {
+      // Fast equality via canonical-ordered serialization of the
+      // (kind, enforcement, defaultOn, authoredBy) tuple. Small set
+      // (≤ 6 kinds), so the allocation cost is negligible.
+      const currentKey = canonicalizePolicyMap(visibilityPolicies);
+      const nextMap = new Map<OverlayKind, OverlayVisibilityPolicy>();
+      for (const policy of next) {
+        nextMap.set(policy.kind, structuredClone(policy));
+      }
+      const nextKey = canonicalizePolicyMap(nextMap);
+      if (currentKey === nextKey) {
+        return false;
+      }
+      visibilityPolicies = nextMap;
+      return true;
+    },
+    subscribeVisibilityPolicy(listener) {
+      visibilityPolicyListeners.add(listener);
+      return () => {
+        visibilityPolicyListeners.delete(listener);
+      };
+    },
+    notifyVisibilityPolicyChanged() {
+      // Snapshot-and-iterate so an unsubscribe inside a listener
+      // doesn't mutate the set we're walking.
+      for (const listener of [...visibilityPolicyListeners]) {
+        try {
+          listener();
+        } catch {
+          // Isolate listener errors — one broken subscriber must not
+          // block the rest of the notification chain.
+        }
+      }
+    },
+    getMarkupModePolicy() {
+      return markupModePolicy ? structuredClone(markupModePolicy) : null;
+    },
+    replaceMarkupModePolicy(next) {
+      if (workflowMarkupModePoliciesEqual(markupModePolicy, next)) {
+        return false;
+      }
+      markupModePolicy = next ? structuredClone(next) : null;
+      return true;
+    },
+    subscribeMarkupModePolicy(listener) {
+      markupModePolicyListeners.add(listener);
+      return () => {
+        markupModePolicyListeners.delete(listener);
+      };
+    },
+    notifyMarkupModePolicyChanged() {
+      for (const listener of [...markupModePolicyListeners]) {
+        try {
+          listener();
+        } catch {
+          // Listener-throw isolation — same pattern as visibility policy.
+        }
+      }
+    },
+
+    getNormalizedOverlay(document) {
+      if (!overlay) return null;
+      return normalizeOverlayForDocument(document, overlay);
+    },
+    getMetadataSnapshot() {
+      return {
+        definitions: structuredClone(metadataDefinitions),
+        entries: structuredClone(metadataEntries),
+      };
+    },
+
+    createInvalidatedScopeWarning,
+    mergeDetachedScopeWarnings,
+  };
+}
+
+function canonicalizePolicyMap(
+  map: ReadonlyMap<OverlayKind, OverlayVisibilityPolicy>,
+): string {
+  const sorted = [...map.values()].sort((a, b) => a.kind.localeCompare(b.kind));
+  return sorted
+    .map(
+      (policy) =>
+        `${policy.kind}|${policy.enforcement}|${policy.defaultOn}|${
+          policy.authoredBy ? `${policy.authoredBy.actorId}@${policy.authoredBy.at}` : ""
+        }`,
+    )
+    .join(";");
+}
+
+/**
+ * Called once during `createDocumentRuntime` construction to seed the
+ * marker-backed scope-id set from the initial document. The store's
+ * factory intentionally leaves this empty so the first
+ * `replaceOverlay` from the coordinator is the sole writer of the set
+ * (simpler invariant). When no overlay is set initially, we still
+ * want the set populated so marker-only scopes are discoverable via
+ * `getMarkerBackedScopeIds()`. This helper performs that initial sync
+ * without firing a telemetry delta (prior set is definitionally empty).
+ */
+export function seedMarkerBackedScopeIds(
+  store: OverlayStore,
+  document: CanonicalDocumentEnvelope,
+): void {
+  // The public surface only exposes `replaceOverlay` as the
+  // marker-backed mutator. Seeding without overlay replacement is
+  // achieved by calling replaceOverlay(currentOverlay, document) —
+  // idempotent on state but triggers the marker-backed sync.
+  const current = store.getOverlay();
+  store.replaceOverlay(current, document);
+}