@beyondwork/docx-react-component 1.0.106 → 1.0.108

package/src/runtime/telemetry/perf-probe.ts

@@ -0,0 +1,216 @@
+export type PerfProbeKind =
+  | "typing"
+  | "typing.predicted"
+  | "typing.reconcile"
+  | "typing.divergence"
+  | "selection"
+  | "runtime.create"
+  | "loadSession.laycacheProbe"
+  | "loadSession.compatReportCached"
+  | "snapshot.surface"
+  | "snapshot.compatibility"
+  | "snapshot.navigation"
+  | "pm.rebuild"
+  | "pm.decorations"
+  | "pm.decorations.apply"
+  | "pm.decorations.comments"
+  | "pm.decorations.revisions"
+  | "pm.decorations.workflow"
+  | "pm.mount"
+  | "shell.render"
+  | "workspace.chrome"
+  | "selection.sync"
+  | "layout.incremental"
+  | "layout.full"
+  | "render.frame_build"
+  | "render.frame_diff"
+  | "render.decoration_resolve"
+  | "chrome.overlay_reposition"
+  | "chrome.hit_test"
+  | "rail.segment_project";
+
+/**
+ * Counter names the FastTextEditLane emits via `incrementInvalidationCounter`.
+ * Expose them as a const so integrators can read the shape without duplicating
+ * strings.
+ */
+export const PREDICTED_LANE_COUNTERS = {
+  applied: "predictions.applied",
+  equivalent: "predictions.equivalent",
+  adjusted: "predictions.adjusted",
+  rejected: "predictions.rejected",
+  rollback: "predictions.rollback",
+  structuralDivergence: "predictions.structuralDivergence",
+  bailBeforePredict: "predictions.bailBeforePredict",
+  refreshSelectionOnly: "predictions.refresh.selectionOnly",
+  refreshLocalTextEquivalent: "predictions.refresh.localTextEquivalent",
+  refreshSurfaceOnly: "predictions.refresh.surfaceOnly",
+  refreshFullProjection: "predictions.refresh.fullProjection",
+  refreshBlocked: "predictions.refresh.blocked",
+} as const;
+
+export interface PerfProbeSample {
+  token: string;
+  kind: PerfProbeKind;
+  durationMs: number;
+  recordedAt: number;
+}
+
+interface PendingProbe {
+  kind: PerfProbeKind;
+  startedAt: number;
+}
+
+interface PerfProbeState {
+  enabled?: boolean;
+  nextToken?: number;
+  pending?: Record<string, PendingProbe>;
+  samples?: PerfProbeSample[];
+  maxSamples?: number;
+  invalidationCounts?: Record<string, number>;
+}
+
+export interface PerfProbeSummary {
+  samples: PerfProbeSample[];
+  latest: Partial<Record<PerfProbeKind, PerfProbeSample | null>>;
+  invalidationCounts: Record<string, number>;
+}
+
+declare global {
+  interface Window {
+    __DOCX_REACT_PERF_PROBE__?: PerfProbeState;
+  }
+}
+
+export function startPerfProbe(kind: PerfProbeKind): string | null {
+  const state = getEnabledState();
+  if (!state) {
+    return null;
+  }
+
+  const token = `${kind}-${state.nextToken ?? 0}`;
+  state.nextToken = (state.nextToken ?? 0) + 1;
+  state.pending ??= {};
+  state.pending[token] = {
+    kind,
+    startedAt: performance.now(),
+  };
+  return token;
+}
+
+export function finishPerfProbe(token: string | null | undefined): PerfProbeSample | null {
+  if (!token) {
+    return null;
+  }
+  const state = getEnabledState();
+  if (!state?.pending?.[token]) {
+    return null;
+  }
+
+  const pending = state.pending[token];
+  delete state.pending[token];
+
+  const sample: PerfProbeSample = {
+    token,
+    kind: pending.kind,
+    durationMs: performance.now() - pending.startedAt,
+    recordedAt: Date.now(),
+  };
+
+  pushSample(state, sample);
+
+  return sample;
+}
+
+export function recordPerfSample(
+  kind: PerfProbeKind,
+  durationMs = 0,
+): PerfProbeSample | null {
+  const state = getEnabledState();
+  if (!state) {
+    return null;
+  }
+
+  const token = `${kind}-${state.nextToken ?? 0}`;
+  state.nextToken = (state.nextToken ?? 0) + 1;
+  const sample: PerfProbeSample = {
+    token,
+    kind,
+    durationMs,
+    recordedAt: Date.now(),
+  };
+  pushSample(state, sample);
+  return sample;
+}
+
+export function incrementInvalidationCounter(
+  counter: string,
+  amount = 1,
+): number {
+  const state = getEnabledState();
+  if (!state) {
+    return 0;
+  }
+
+  state.invalidationCounts ??= {};
+  state.invalidationCounts[counter] =
+    (state.invalidationCounts[counter] ?? 0) + amount;
+  return state.invalidationCounts[counter]!;
+}
+
+export function getLatestPerfSummary(): PerfProbeSummary | null {
+  const state = getEnabledState();
+  const samples = state?.samples ?? [];
+  if (!state || samples.length === 0) {
+    return null;
+  }
+
+  return {
+    samples: [...samples],
+    latest: buildLatestSampleMap(samples),
+    invalidationCounts: { ...(state.invalidationCounts ?? {}) },
+  };
+}
+
+export function resetPerfProbeState(): void {
+  const state = getEnabledState();
+  if (!state) {
+    return;
+  }
+  state.nextToken = 0;
+  state.pending = {};
+  state.samples = [];
+  state.invalidationCounts = {};
+}
+
+function getEnabledState(): PerfProbeState | null {
+  if (typeof window === "undefined") {
+    return null;
+  }
+  const state = window.__DOCX_REACT_PERF_PROBE__;
+  if (!state?.enabled) {
+    return null;
+  }
+  return state;
+}
+
+function pushSample(state: PerfProbeState, sample: PerfProbeSample): void {
+  state.samples ??= [];
+  state.samples.push(sample);
+  const maxSamples = state.maxSamples ?? 20;
+  if (state.samples.length > maxSamples) {
+    state.samples.splice(0, state.samples.length - maxSamples);
+  }
+}
+
+function buildLatestSampleMap(
+  samples: PerfProbeSample[],
+): Partial<Record<PerfProbeKind, PerfProbeSample | null>> {
+  const latest: Partial<Record<PerfProbeKind, PerfProbeSample | null>> = {};
+  for (const sample of [...samples].reverse()) {
+    if (latest[sample.kind] === undefined) {
+      latest[sample.kind] = sample;
+    }
+  }
+  return latest;
+}

package/src/runtime/virtualized-rendering.ts

@@ -35,6 +35,21 @@ export interface VirtualizedViewport {
   overscanHeight?: number;
 }
 
+export interface VirtualizedBlockGeometryProvider {
+  getBlock(blockId: string): { rects: readonly { topPx: number }[] } | null;
+}
+
+export interface ComputeVirtualizedWindowOptions {
+  /**
+   * Optional L05 geometry source. When present, `offsetTop` is derived from
+   * `GeometryFacet.getBlock(firstVisibleBlockId).rects[0].topPx` instead of
+   * the synthetic virtualization estimate. This keeps DOM-free consumers on
+   * geometry truth while preserving the legacy estimate for unwired tests and
+   * pre-paint sessions.
+   */
+  geometryFacet?: VirtualizedBlockGeometryProvider;
+}
+
 export interface VirtualizedWindow {
   startIndex: number;
   endIndex: number;
@@ -121,6 +136,7 @@ export function createVirtualizedRenderingSession(
 export function computeVirtualizedWindow(
   session: VirtualizedRenderingSession,
   viewport: VirtualizedViewport,
+  options: ComputeVirtualizedWindowOptions = {},
 ): VirtualizedWindow {
   if (session.metrics.length === 0) {
     return {
@@ -145,19 +161,38 @@ export function computeVirtualizedWindow(
   const safeEndIndex = Math.max(startIndex + 1, endIndexExclusive);
   const visibleMetrics = session.metrics.slice(startIndex, safeEndIndex);
   const visibleBlocks = session.blocks.slice(startIndex, safeEndIndex);
+  const firstMetric = visibleMetrics[0];
+  const firstBlock = visibleBlocks[0];
   const lastMetric = visibleMetrics[visibleMetrics.length - 1]!;
 
   return {
     startIndex,
     endIndex: safeEndIndex,
     totalHeight: session.totalHeight,
-    offsetTop: visibleMetrics[0]?.top ?? 0,
+    offsetTop: resolveWindowOffsetTop(
+      firstBlock?.blockId ?? firstMetric?.blockId,
+      firstMetric,
+      options,
+    ),
     offsetBottom: Math.max(0, session.totalHeight - lastMetric.bottom),
     visibleBlocks,
     visibleMetrics,
   };
 }
 
+function resolveWindowOffsetTop(
+  blockId: string | undefined,
+  fallbackMetric: VirtualizedRenderingMetrics | undefined,
+  options: ComputeVirtualizedWindowOptions,
+): number {
+  const geometryTop = blockId
+    ? options.geometryFacet?.getBlock(blockId)?.rects[0]?.topPx
+    : undefined;
+  return typeof geometryTop === "number" && Number.isFinite(geometryTop)
+    ? geometryTop
+    : (fallbackMetric?.top ?? 0);
+}
+
 function findFirstVisibleIndex(
   metrics: VirtualizedRenderingMetrics[],
   top: number,

package/src/runtime/workflow/ai-issue-lifecycle.ts

@@ -0,0 +1,253 @@
+import type {
+  WorkflowEventOrigin,
+  WorkflowMetadataEntry,
+  WorkflowMetadataSnapshot,
+} from "../../api/public-types.ts";
+
+export const AI_ISSUE_METADATA_ID = "ai.issue" as const;
+
+export type AIIssueStatus = "open" | "resolved";
+export type AIIssueLifecycleAction = "resolve" | "reopen";
+
+export interface AIIssueLifecycleAuditEntry {
+  readonly action: AIIssueLifecycleAction;
+  readonly actorId: string;
+  readonly at: string;
+  readonly origin: string;
+  readonly fromStatus: AIIssueStatus;
+  readonly toStatus: AIIssueStatus;
+}
+
+export interface AIIssueLifecycleValue {
+  readonly issueId: string;
+  readonly summary: string;
+  readonly severity?: string;
+  readonly status: AIIssueStatus;
+  readonly createdAtUtc?: string;
+  readonly statusUpdatedAtUtc?: string;
+  readonly resolvedAtUtc?: string;
+  readonly resolvedBy?: string;
+  readonly reopenedAtUtc?: string;
+  readonly reopenedBy?: string;
+  readonly lifecycle?: readonly AIIssueLifecycleAuditEntry[];
+}
+
+export interface AIIssueLifecycleReadback {
+  readonly issueId: string;
+  readonly entryId: string;
+  readonly scopeId?: string;
+  readonly summary: string;
+  readonly severity?: string;
+  readonly status: AIIssueStatus;
+  readonly canResolve: boolean;
+  readonly canReopen: boolean;
+  readonly createdAtUtc?: string;
+  readonly statusUpdatedAtUtc?: string;
+  readonly lastTransition?: AIIssueLifecycleAuditEntry;
+}
+
+export interface AIIssueLifecycleRuntime {
+  getWorkflowMetadataSnapshot(): WorkflowMetadataSnapshot;
+  setWorkflowMetadataEntries(
+    entries: readonly WorkflowMetadataEntry[],
+    origin?: WorkflowEventOrigin,
+  ): void;
+}
+
+export interface TransitionAIIssueLifecycleInput {
+  readonly issueId: string;
+  readonly action: AIIssueLifecycleAction;
+  readonly actorId: string;
+  readonly at: string;
+  readonly origin?: WorkflowEventOrigin;
+}
+
+export type TransitionAIIssueLifecycleResult =
+  | {
+      readonly transitioned: true;
+      readonly issueId: string;
+      readonly entryId: string;
+      readonly fromStatus: AIIssueStatus;
+      readonly toStatus: AIIssueStatus;
+      readonly audit: AIIssueLifecycleAuditEntry;
+    }
+  | {
+      readonly transitioned: false;
+      readonly issueId: string;
+      readonly reason:
+        | "issue-not-found"
+        | "issue-value-malformed"
+        | "already-resolved"
+        | "already-open";
+    };
+
+export function projectAIIssueLifecycleReadback(
+  entries: readonly WorkflowMetadataEntry[],
+): AIIssueLifecycleReadback[] {
+  return entries
+    .filter((entry) => entry.metadataId === AI_ISSUE_METADATA_ID)
+    .map(projectEntry)
+    .filter((entry): entry is AIIssueLifecycleReadback => entry !== null)
+    .sort((a, b) => a.issueId.localeCompare(b.issueId));
+}
+
+export function transitionAIIssueLifecycle(
+  runtime: AIIssueLifecycleRuntime,
+  input: TransitionAIIssueLifecycleInput,
+): TransitionAIIssueLifecycleResult {
+  const snapshot = runtime.getWorkflowMetadataSnapshot();
+  const target = snapshot.entries.find((entry) => {
+    if (entry.metadataId !== AI_ISSUE_METADATA_ID) return false;
+    const value = coerceIssueValue(entry.value);
+    return value?.issueId === input.issueId || entry.entryId === input.issueId;
+  });
+
+  if (!target) {
+    return {
+      transitioned: false,
+      issueId: input.issueId,
+      reason: "issue-not-found",
+    };
+  }
+
+  const currentValue = coerceIssueValue(target.value);
+  if (!currentValue) {
+    return {
+      transitioned: false,
+      issueId: input.issueId,
+      reason: "issue-value-malformed",
+    };
+  }
+
+  const fromStatus = currentValue.status;
+  const toStatus = input.action === "resolve" ? "resolved" : "open";
+  if (fromStatus === toStatus) {
+    return {
+      transitioned: false,
+      issueId: currentValue.issueId,
+      reason: toStatus === "resolved" ? "already-resolved" : "already-open",
+    };
+  }
+
+  const audit: AIIssueLifecycleAuditEntry = {
+    action: input.action,
+    actorId: input.actorId,
+    at: input.at,
+    origin: input.origin?.source ?? "agent",
+    fromStatus,
+    toStatus,
+  };
+  const nextValue = nextIssueValue(currentValue, audit);
+  const nextEntry: WorkflowMetadataEntry = {
+    ...target,
+    value: nextValue as unknown as Record<string, unknown>,
+  };
+  const nextEntries = snapshot.entries.map((entry) =>
+    entry.entryId === target.entryId ? nextEntry : entry,
+  );
+  runtime.setWorkflowMetadataEntries(nextEntries, input.origin ?? {
+    source: audit.origin,
+    at: input.at,
+  });
+
+  return {
+    transitioned: true,
+    issueId: currentValue.issueId,
+    entryId: target.entryId,
+    fromStatus,
+    toStatus,
+    audit,
+  };
+}
+
+function projectEntry(entry: WorkflowMetadataEntry): AIIssueLifecycleReadback | null {
+  const value = coerceIssueValue(entry.value);
+  if (!value) return null;
+  const lastTransition = value.lifecycle?.[value.lifecycle.length - 1];
+  return {
+    issueId: value.issueId,
+    entryId: entry.entryId,
+    ...(entry.scopeId ? { scopeId: entry.scopeId } : {}),
+    summary: value.summary,
+    ...(value.severity ? { severity: value.severity } : {}),
+    status: value.status,
+    canResolve: value.status === "open",
+    canReopen: value.status === "resolved",
+    ...(value.createdAtUtc ? { createdAtUtc: value.createdAtUtc } : {}),
+    ...(value.statusUpdatedAtUtc ? { statusUpdatedAtUtc: value.statusUpdatedAtUtc } : {}),
+    ...(lastTransition ? { lastTransition } : {}),
+  };
+}
+
+function nextIssueValue(
+  value: AIIssueLifecycleValue,
+  audit: AIIssueLifecycleAuditEntry,
+): AIIssueLifecycleValue {
+  const lifecycle = [...(value.lifecycle ?? []), audit];
+  const base =
+    audit.action === "resolve"
+      ? omitReopenFields(value)
+      : omitResolveFields(value);
+  return {
+    ...base,
+    status: audit.toStatus,
+    statusUpdatedAtUtc: audit.at,
+    ...(audit.action === "resolve"
+      ? { resolvedAtUtc: audit.at, resolvedBy: audit.actorId }
+      : { reopenedAtUtc: audit.at, reopenedBy: audit.actorId }),
+    lifecycle,
+  };
+}
+
+function omitReopenFields(value: AIIssueLifecycleValue): AIIssueLifecycleValue {
+  const { reopenedAtUtc: _reopenedAtUtc, reopenedBy: _reopenedBy, ...base } = value;
+  return base;
+}
+
+function omitResolveFields(value: AIIssueLifecycleValue): AIIssueLifecycleValue {
+  const { resolvedAtUtc: _resolvedAtUtc, resolvedBy: _resolvedBy, ...base } = value;
+  return base;
+}
+
+function coerceIssueValue(value: unknown): AIIssueLifecycleValue | null {
+  if (!isRecord(value)) return null;
+  if (typeof value.issueId !== "string" || value.issueId.length === 0) return null;
+  if (typeof value.summary !== "string" || value.summary.length === 0) return null;
+  const status = value.status === "resolved" ? "resolved" : value.status === "open" ? "open" : null;
+  if (!status) return null;
+  const lifecycle = Array.isArray(value.lifecycle)
+    ? value.lifecycle.filter(isLifecycleAuditEntry)
+    : undefined;
+  return {
+    ...value,
+    issueId: value.issueId,
+    summary: value.summary,
+    ...(typeof value.severity === "string" ? { severity: value.severity } : {}),
+    status,
+    ...(typeof value.createdAtUtc === "string" ? { createdAtUtc: value.createdAtUtc } : {}),
+    ...(typeof value.statusUpdatedAtUtc === "string"
+      ? { statusUpdatedAtUtc: value.statusUpdatedAtUtc }
+      : {}),
+    ...(typeof value.resolvedAtUtc === "string" ? { resolvedAtUtc: value.resolvedAtUtc } : {}),
+    ...(typeof value.resolvedBy === "string" ? { resolvedBy: value.resolvedBy } : {}),
+    ...(typeof value.reopenedAtUtc === "string" ? { reopenedAtUtc: value.reopenedAtUtc } : {}),
+    ...(typeof value.reopenedBy === "string" ? { reopenedBy: value.reopenedBy } : {}),
+    ...(lifecycle ? { lifecycle } : {}),
+  };
+}
+
+function isLifecycleAuditEntry(value: unknown): value is AIIssueLifecycleAuditEntry {
+  return (
+    isRecord(value) &&
+    (value.action === "resolve" || value.action === "reopen") &&
+    typeof value.actorId === "string" &&
+    typeof value.at === "string" &&
+    typeof value.origin === "string" &&
+    (value.fromStatus === "open" || value.fromStatus === "resolved") &&
+    (value.toStatus === "open" || value.toStatus === "resolved")
+  );
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}

package/src/runtime/workflow/coordinator.ts

@@ -17,9 +17,9 @@
  *
  * - W3 (single interaction-guard verdict) — `getInteractionGuardSnapshot`
  *   is the sole authority for effective mode + blocked reasons. The
- *   snapshot caches against (revisionToken, activeStory, selection,
- *   readOnly, documentMode, protectionSnapshot, overlay reference,
- *   sharedWorkflowState).
+ *   snapshot caches against structural workflow inputs (activeStory,
+ *   selection, readOnly, documentMode, protectionSnapshot, overlay
+ *   reference, sharedWorkflowState).
  *
  * - W4 (AI action policy orthogonal to guard) — this coordinator does
  *   not re-implement AI policy (see `ai-action-policy.ts`); guard
@@ -95,6 +95,11 @@ import {
 import { resolveScope } from "./scope-resolver.ts";
 import { insertScopeMarkers, removeScopeMarkers } from "../../core/commands/add-scope.ts";
 import type { OverlayStore, MergeDetachedWarningsResult } from "./overlay-store.ts";
+import {
+  projectWorkflowReviewOverlayLane,
+  type WorkflowReviewOverlayLaneKind,
+  type WorkflowReviewOverlayLaneSnapshot,
+} from "./overlay-lanes.ts";
 import {
   type OverlayKind,
   type OverlayVisibilityPolicy,
@@ -252,7 +257,10 @@ export interface WorkflowCoordinator {
     definitions: readonly WorkflowMetadataDefinition[],
   ): void;
   clearWorkflowMetadataDefinitions(): void;
-  setWorkflowMetadataEntries(entries: readonly WorkflowMetadataEntry[]): void;
+  setWorkflowMetadataEntries(
+    entries: readonly WorkflowMetadataEntry[],
+    origin?: CoordinatorCommandOrigin,
+  ): void;
   clearWorkflowMetadataEntries(): void;
   getWorkflowMetadataSnapshot(): WorkflowMetadataSnapshot;
   /* --- W10 overlay-visibility policy (class-A state) --- */
@@ -290,6 +298,7 @@ export interface WorkflowCoordinator {
   getInteractionGuardSnapshot(): InteractionGuardSnapshot;
   getWorkflowScopeSnapshot(): WorkflowScopeSnapshot | null;
   getWorkflowMarkupSnapshot(): WorkflowMarkupSnapshot;
+  getReviewOverlayLane(kind: WorkflowReviewOverlayLaneKind): WorkflowReviewOverlayLaneSnapshot;
   /* --- scope matching / blocked reasons --- */
   evaluateBlockedReasons(
     selection: EditorState["selection"],
@@ -350,7 +359,6 @@ export function createWorkflowCoordinator(deps: CoordinatorDeps): WorkflowCoordi
 
   let cachedInteractionGuardSnapshot:
     | {
-        revisionToken: string;
         activeStoryKey: string;
         selection: EditorState["selection"];
         readOnly: boolean;
@@ -372,7 +380,6 @@ export function createWorkflowCoordinator(deps: CoordinatorDeps): WorkflowCoordi
 
   let cachedWorkflowMarkupSnapshot:
     | {
-        revisionToken: string;
         activeStoryKey: string;
         protectionSnapshot: ProtectionSnapshot;
         preservation: CanonicalDocumentEnvelope["preservation"];
@@ -631,7 +638,6 @@ export function createWorkflowCoordinator(deps: CoordinatorDeps): WorkflowCoordi
 
     if (
       cachedInteractionGuardSnapshot &&
-      cachedInteractionGuardSnapshot.revisionToken === state.revisionToken &&
       cachedInteractionGuardSnapshot.activeStoryKey === activeStoryKey &&
       cachedInteractionGuardSnapshot.selection === state.selection &&
       cachedInteractionGuardSnapshot.readOnly === state.readOnly &&
@@ -706,7 +712,6 @@ export function createWorkflowCoordinator(deps: CoordinatorDeps): WorkflowCoordi
       blockedReasons,
     };
     cachedInteractionGuardSnapshot = {
-      revisionToken: state.revisionToken,
       activeStoryKey,
       selection: state.selection,
       readOnly: state.readOnly,
@@ -751,7 +756,6 @@ export function createWorkflowCoordinator(deps: CoordinatorDeps): WorkflowCoordi
 
     if (
       cachedWorkflowMarkupSnapshot &&
-      cachedWorkflowMarkupSnapshot.revisionToken === state.revisionToken &&
       cachedWorkflowMarkupSnapshot.activeStoryKey === activeStoryKey &&
       cachedWorkflowMarkupSnapshot.protectionSnapshot === protectionSnapshot &&
       cachedWorkflowMarkupSnapshot.preservation === preservation &&
@@ -770,7 +774,6 @@ export function createWorkflowCoordinator(deps: CoordinatorDeps): WorkflowCoordi
       workflowMetadataSnapshot: overlayStore.getMetadataSnapshot(),
     });
     cachedWorkflowMarkupSnapshot = {
-      revisionToken: state.revisionToken,
       activeStoryKey,
       protectionSnapshot,
       preservation,
@@ -1118,11 +1121,12 @@ export function createWorkflowCoordinator(deps: CoordinatorDeps): WorkflowCoordi
 
   function setWorkflowMetadataEntries(
     entries: readonly WorkflowMetadataEntry[],
+    origin: CoordinatorCommandOrigin = { source: "api", at: clock() },
   ): void {
     deps.dispatch({
       type: "workflow.set-metadata-entries",
       entries,
-      origin: { source: "api", at: clock() },
+      origin,
     });
     deps.editorStateChannel.recordMutation("workflowMetadata", {
       namespace: "workflowMetadata",
@@ -1146,6 +1150,11 @@ export function createWorkflowCoordinator(deps: CoordinatorDeps): WorkflowCoordi
     state: SharedWorkflowState | null,
     origin: CoordinatorCommandOrigin = { source: "api", at: clock() },
   ): void {
+    if (isAwarenessWorkflowOrigin(origin)) {
+      throw new Error(
+        "runtime.workflow.setSharedWorkflowState: awareness is transient presence state and cannot enforce durable workflow policy",
+      );
+    }
     const prior = overlayStore.getSharedWorkflowState();
     if (state === prior) return;
     overlayStore.replaceSharedWorkflowState(state);
@@ -1265,6 +1274,10 @@ export function createWorkflowCoordinator(deps: CoordinatorDeps): WorkflowCoordi
     });
   }
 
+  function isAwarenessWorkflowOrigin(origin: CoordinatorCommandOrigin): boolean {
+    return origin.source === "awareness";
+  }
+
   /* -------- queries + rail -------- */
 
   function queryScopes(filter?: ScopeQueryFilter): ScopeQueryResult[] {
@@ -1318,6 +1331,20 @@ export function createWorkflowCoordinator(deps: CoordinatorDeps): WorkflowCoordi
     });
   }
 
+  function getReviewOverlayLane(
+    kind: WorkflowReviewOverlayLaneKind,
+  ): WorkflowReviewOverlayLaneSnapshot {
+    const renderSnapshot = deps.getRenderSnapshot();
+    return projectWorkflowReviewOverlayLane(kind, {
+      comments: renderSnapshot.comments,
+      trackedChanges: renderSnapshot.trackedChanges,
+      suggestions: deps.getSuggestionsSnapshot() as never,
+      workflowScope: getCachedWorkflowScopeSnapshot() ?? undefined,
+      workflowMarkup: getCachedWorkflowMarkupSnapshot(),
+      revision: deps.getState().revision,
+    });
+  }
+
   /* -------- dispatch branch handler -------- */
 
   function applyOverlayCommand(
@@ -1483,6 +1510,7 @@ export function createWorkflowCoordinator(deps: CoordinatorDeps): WorkflowCoordi
     getInteractionGuardSnapshot: getCachedInteractionGuardSnapshot,
     getWorkflowScopeSnapshot: getCachedWorkflowScopeSnapshot,
     getWorkflowMarkupSnapshot: getCachedWorkflowMarkupSnapshot,
+    getReviewOverlayLane,
     evaluateBlockedReasons,
     getMatchingScope: getMatchingWorkflowScope,
     getMatchingScopeStack: buildMatchingScopeStack,