@beyondwork/docx-react-component 1.0.28 → 1.0.30

package/src/runtime/context-analytics.ts

@@ -0,0 +1,824 @@
+import type {
+  CompatibilityReport,
+  EditorAnchorProjection,
+  EditorStoryTarget,
+  EditorWarning,
+  InteractionGuardSnapshot,
+  ReviewWorkSnapshot,
+  RuntimeContextAnalyticsActionHint,
+  RuntimeContextAnalyticsBadge,
+  RuntimeContextAnalyticsProvenance,
+  RuntimeContextAnalyticsQuery,
+  RuntimeContextAnalyticsSnapshot,
+  RuntimeRenderSnapshot,
+  SuggestionsSnapshot,
+  WorkflowBlockedCommandReason,
+  WorkflowMarkupItem,
+  WorkflowMarkupSnapshot,
+  WorkflowOverlay,
+  WorkflowScope,
+  WorkflowScopeSnapshot,
+  WorkflowWorkItem,
+} from "../api/public-types";
+import { MAIN_STORY_TARGET, storyTargetsEqual } from "../core/selection/mapping.ts";
+
+const DERIVED_FROM: RuntimeContextAnalyticsProvenance["derivedFrom"] = [
+  "render",
+  "workflowScope",
+  "interactionGuard",
+  "workflowMarkup",
+  "reviewWork",
+  "warnings",
+  "compatibility",
+];
+
+const UNAVAILABLE_FIELDS: RuntimeContextAnalyticsProvenance["unavailable"] = [
+  "tasksRemaining",
+  "approvalsRemaining",
+  "overdueItems",
+  "tags",
+  "assignee",
+  "dueDate",
+  "lastTouchedAt",
+];
+
+type AnalyticsInput = {
+  query?: RuntimeContextAnalyticsQuery;
+  renderSnapshot: RuntimeRenderSnapshot;
+  workflowOverlay: WorkflowOverlay | null;
+  workflowScopeSnapshot: WorkflowScopeSnapshot | null;
+  interactionGuardSnapshot: InteractionGuardSnapshot;
+  workflowMarkupSnapshot: WorkflowMarkupSnapshot;
+  suggestionsSnapshot: SuggestionsSnapshot;
+  reviewWorkSnapshot: ReviewWorkSnapshot;
+  warnings: EditorWarning[];
+  compatibility: CompatibilityReport;
+};
+
+export function createRuntimeContextAnalyticsSnapshot(
+  input: AnalyticsInput,
+): RuntimeContextAnalyticsSnapshot | null {
+  const scopeKind = input.query?.scopeKind ?? "selection";
+  switch (scopeKind) {
+    case "document":
+      return buildDocumentAnalytics(input);
+    case "workflow_scope":
+      return buildWorkflowScopeAnalytics(
+        input,
+        input.query?.scopeId ?? input.interactionGuardSnapshot.matchedScopeId,
+      );
+    case "work_item":
+      return buildWorkItemAnalytics(
+        input,
+        input.query?.workItemId ??
+          input.workflowOverlay?.activeWorkItemId ??
+          input.workflowScopeSnapshot?.activeWorkItemId ??
+          undefined,
+      );
+    case "selection":
+    default:
+      return buildSelectionAnalytics(input);
+  }
+}
+
+export function resolveCurrentContextAnalyticsQuery(input: {
+  workflowScopeSnapshot: WorkflowScopeSnapshot | null;
+  interactionGuardSnapshot: InteractionGuardSnapshot;
+}): RuntimeContextAnalyticsQuery | undefined {
+  const activeWorkItemId = input.workflowScopeSnapshot?.activeWorkItemId ?? null;
+  if (activeWorkItemId) {
+    return {
+      scopeKind: "work_item",
+      workItemId: activeWorkItemId,
+    };
+  }
+  if (input.interactionGuardSnapshot.matchedScopeId) {
+    return {
+      scopeKind: "workflow_scope",
+      scopeId: input.interactionGuardSnapshot.matchedScopeId,
+    };
+  }
+  return undefined;
+}
+
+export function runtimeContextAnalyticsSnapshotsEqual(
+  left: RuntimeContextAnalyticsSnapshot | null,
+  right: RuntimeContextAnalyticsSnapshot | null,
+): boolean {
+  if (left === right) {
+    return true;
+  }
+  if (!left || !right) {
+    return false;
+  }
+  return (
+    left.scopeKind === right.scopeKind &&
+    left.scopeId === right.scopeId &&
+    left.workItemId === right.workItemId &&
+    analyticsBadgesEqual(left.badges, right.badges) &&
+    analyticsActionHintsEqual(left.nextActions, right.nextActions) &&
+    analyticsCountsEqual(left.counts, right.counts) &&
+    analyticsStateEqual(left.state, right.state) &&
+    analyticsProvenanceEqual(left.provenance, right.provenance)
+  );
+}
+
+function buildDocumentAnalytics(input: AnalyticsInput): RuntimeContextAnalyticsSnapshot {
+  const warningCount = getDocumentWarningCount(input.compatibility, input.warnings);
+  const errorCount = getDocumentErrorCount(input.compatibility);
+  const exportReadiness = getExportReadiness({
+    compatibility: input.compatibility,
+    warnings: warningCount,
+    errors: errorCount,
+    workflowMarkup: input.workflowMarkupSnapshot,
+  });
+  const openWorkItems = countOpenWorkItems(input.workflowOverlay, input.workflowScopeSnapshot);
+  const unresolvedComments = input.reviewWorkSnapshot.openCommentCount;
+  const pendingRevisions = input.reviewWorkSnapshot.actionableRevisionCount;
+  const pendingSuggestions = countActiveSuggestions(input.suggestionsSnapshot);
+  const badges = [
+    openWorkItems > 0 ? createCountBadge("open-work-items", openWorkItems, "open work item") : null,
+    unresolvedComments > 0
+      ? createCountBadge("document-comments", unresolvedComments, "unresolved comment")
+      : null,
+    pendingSuggestions > 0
+      ? createCountBadge("document-suggestions", pendingSuggestions, "pending suggestion")
+      : pendingRevisions > 0
+        ? createCountBadge("document-revisions", pendingRevisions, "pending change")
+      : null,
+    createExportBadge(exportReadiness),
+  ].filter((badge): badge is RuntimeContextAnalyticsBadge => Boolean(badge));
+  const nextActions = [
+    openWorkItems > 0
+      ? createActionHint(
+          "open-work-items",
+          `Continue ${openWorkItems} open ${pluralize(openWorkItems, "work item")}`,
+          "next_step",
+        )
+      : null,
+    unresolvedComments > 0
+      ? createActionHint(
+          "resolve-comments",
+          `Resolve ${unresolvedComments} ${pluralize(unresolvedComments, "comment")}`,
+          "next_step",
+        )
+      : null,
+    pendingSuggestions > 0
+      ? createActionHint(
+          "review-suggestions",
+          `Review ${pendingSuggestions} pending ${pluralize(pendingSuggestions, "suggestion")}`,
+          "next_step",
+        )
+      : pendingRevisions > 0
+      ? createActionHint(
+          "review-revisions",
+          `Review ${pendingRevisions} pending ${pluralize(pendingRevisions, "change")}`,
+          "next_step",
+        )
+      : null,
+    exportReadiness === "blocked"
+      ? createActionHint("export-blocked", "Export is currently blocked", "blocker")
+      : exportReadiness === "warning"
+        ? createActionHint("export-warning", "Export has compatibility warnings", "warning")
+        : null,
+  ].filter((action): action is RuntimeContextAnalyticsActionHint => Boolean(action));
+
+  return {
+    scopeKind: "document",
+    badges,
+    nextActions,
+    counts: {
+      unresolvedComments,
+      pendingRevisions,
+      pendingSuggestions,
+      warnings: warningCount,
+      errors: errorCount,
+      openWorkItems,
+      exportBlockers: input.compatibility.blockExport ? 1 : 0,
+    },
+    state: {
+      isBlocked: exportReadiness === "blocked",
+      completionState:
+        openWorkItems === 0 && unresolvedComments === 0 && pendingRevisions === 0 && exportReadiness === "ready"
+          ? "ready"
+          : "in_progress",
+      exportReadiness,
+    },
+    provenance: createProvenance(),
+  };
+}
+
+function buildSelectionAnalytics(input: AnalyticsInput): RuntimeContextAnalyticsSnapshot {
+  const selectionAnchor = getSelectionAnchor(input.renderSnapshot);
+  const activeStory = input.renderSnapshot.activeStory;
+  const matchingScope = findMatchingScopeForSelection(
+    input.workflowOverlay,
+    input.workflowScopeSnapshot,
+    input.interactionGuardSnapshot,
+    selectionAnchor,
+    activeStory,
+  );
+  const matchingItems = input.workflowMarkupSnapshot.items.filter((item) =>
+    markupMatchesAnchor(item, selectionAnchor, activeStory),
+  );
+  const unresolvedComments = countUnresolvedComments(matchingItems);
+  const pendingRevisions = countPendingRevisions(matchingItems);
+  const pendingSuggestions = countPendingSuggestionsForMarkupItems(
+    matchingItems,
+    input.suggestionsSnapshot,
+  );
+  const blockedCommands = input.interactionGuardSnapshot.blockedReasons.length;
+  const badges = [
+    createModeBadge(input.interactionGuardSnapshot.effectiveMode),
+    unresolvedComments > 0
+      ? createCountBadge("selection-comments", unresolvedComments, "comment")
+      : null,
+    pendingSuggestions > 0
+      ? createCountBadge("selection-suggestions", pendingSuggestions, "pending suggestion")
+      : pendingRevisions > 0
+        ? createCountBadge("selection-revisions", pendingRevisions, "pending change")
+      : null,
+  ].filter((badge): badge is RuntimeContextAnalyticsBadge => Boolean(badge));
+
+  return {
+    scopeKind: "selection",
+    ...(matchingScope?.scopeId ? { scopeId: matchingScope.scopeId } : {}),
+    ...(matchingScope?.workItemId ? { workItemId: matchingScope.workItemId } : {}),
+    badges,
+    nextActions: createAttentionHints({
+      unresolvedComments,
+      pendingRevisions,
+      pendingSuggestions,
+      blockedReasons: input.interactionGuardSnapshot.blockedReasons,
+    }),
+    counts: {
+      unresolvedComments,
+      pendingRevisions,
+      pendingSuggestions,
+      blockedCommands,
+    },
+    state: {
+      effectiveMode: input.interactionGuardSnapshot.effectiveMode,
+      isBlocked: input.interactionGuardSnapshot.effectiveMode === "blocked",
+      ...(input.interactionGuardSnapshot.disabledReason
+        ? { disabledReason: input.interactionGuardSnapshot.disabledReason }
+        : {}),
+      completionState:
+        unresolvedComments === 0 &&
+        pendingRevisions === 0 &&
+        input.interactionGuardSnapshot.blockedReasons.length === 0
+          ? "ready"
+          : "in_progress",
+    },
+    provenance: createProvenance(),
+  };
+}
+
+function buildWorkflowScopeAnalytics(
+  input: AnalyticsInput,
+  scopeId: string | undefined,
+): RuntimeContextAnalyticsSnapshot | null {
+  if (!scopeId) {
+    return null;
+  }
+  const scope = getAllScopes(input.workflowOverlay, input.workflowScopeSnapshot).find(
+    (entry) => entry.scopeId === scopeId,
+  );
+  if (!scope) {
+    return null;
+  }
+  const matchingItems = input.workflowMarkupSnapshot.items.filter((item) =>
+    markupMatchesScope(item, scope),
+  );
+  const blockedReasons = (input.workflowScopeSnapshot?.blockedReasons ?? []).filter(
+    (reason) => reason.scopeId === scope.scopeId,
+  );
+  const unresolvedComments = countUnresolvedComments(matchingItems);
+  const pendingRevisions = countPendingRevisions(matchingItems);
+  const effectiveMode = deriveBlockedAwareMode(scope.mode, blockedReasons);
+
+  return {
+    scopeKind: "workflow_scope",
+    scopeId: scope.scopeId,
+    ...(scope.workItemId ? { workItemId: scope.workItemId } : {}),
+    badges: [
+      scope.label ? { key: "scope-label", label: scope.label, tone: "accent" } : null,
+      createModeBadge(effectiveMode),
+      unresolvedComments > 0 ? createCountBadge("scope-comments", unresolvedComments, "comment") : null,
+      pendingRevisions > 0 ? createCountBadge("scope-revisions", pendingRevisions, "pending change") : null,
+    ].filter((badge): badge is RuntimeContextAnalyticsBadge => Boolean(badge)),
+    nextActions: createAttentionHints({
+      unresolvedComments,
+      pendingRevisions,
+      blockedReasons,
+    }),
+    counts: {
+      unresolvedComments,
+      pendingRevisions,
+      blockedCommands: blockedReasons.length,
+    },
+    state: {
+      effectiveMode,
+      isBlocked: effectiveMode === "blocked",
+      ...(blockedReasons[0]?.message ? { disabledReason: blockedReasons[0].message } : {}),
+      completionState:
+        unresolvedComments === 0 && pendingRevisions === 0 && blockedReasons.length === 0
+          ? "ready"
+          : "in_progress",
+    },
+    provenance: createProvenance(),
+  };
+}
+
+function buildWorkItemAnalytics(
+  input: AnalyticsInput,
+  workItemId: string | undefined,
+): RuntimeContextAnalyticsSnapshot | null {
+  if (!workItemId) {
+    return null;
+  }
+  const workItem = getWorkflowWorkItem(input.workflowOverlay, input.workflowScopeSnapshot, workItemId);
+  const scopes = getAllScopes(input.workflowOverlay, input.workflowScopeSnapshot).filter(
+    (scope) => scope.workItemId === workItemId,
+  );
+  if (!workItem && scopes.length === 0) {
+    return null;
+  }
+  const matchingItems = input.workflowMarkupSnapshot.items.filter((item) =>
+    scopes.some((scope) => markupMatchesScope(item, scope)),
+  );
+  const blockedReasons = (input.workflowScopeSnapshot?.blockedReasons ?? []).filter(
+    (reason) => reason.workItemId === workItemId,
+  );
+  const unresolvedComments = countUnresolvedComments(matchingItems);
+  const pendingRevisions = countPendingRevisions(matchingItems);
+  const effectiveMode =
+    scopes.length === 1
+      ? deriveBlockedAwareMode(scopes[0]!.mode, blockedReasons)
+      : undefined;
+
+  return {
+    scopeKind: "work_item",
+    workItemId,
+    ...(scopes.length === 1 ? { scopeId: scopes[0]!.scopeId } : {}),
+    badges: [
+      workItem?.title ? { key: "work-item-title", label: workItem.title, tone: "accent" } : null,
+      effectiveMode ? createModeBadge(effectiveMode) : null,
+      unresolvedComments > 0
+        ? createCountBadge("work-item-comments", unresolvedComments, "comment")
+        : null,
+      pendingRevisions > 0
+        ? createCountBadge("work-item-revisions", pendingRevisions, "pending change")
+        : null,
+    ].filter((badge): badge is RuntimeContextAnalyticsBadge => Boolean(badge)),
+    nextActions: createAttentionHints({
+      unresolvedComments,
+      pendingRevisions,
+      blockedReasons,
+    }),
+    counts: {
+      unresolvedComments,
+      pendingRevisions,
+      blockedCommands: blockedReasons.length,
+    },
+    state: {
+      ...(effectiveMode ? { effectiveMode } : {}),
+      isBlocked: blockedReasons.length > 0,
+      ...(blockedReasons[0]?.message ? { disabledReason: blockedReasons[0].message } : {}),
+      completionState: resolveCompletionState(workItem, unresolvedComments, pendingRevisions, blockedReasons.length > 0),
+    },
+    provenance: createProvenance(),
+  };
+}
+
+function getSelectionAnchor(snapshot: RuntimeRenderSnapshot): EditorAnchorProjection {
+  if (!snapshot.selection.isCollapsed) {
+    return snapshot.selection.activeRange;
+  }
+  return {
+    kind: "node",
+    at: snapshot.selection.head,
+    assoc: 1,
+  };
+}
+
+function findMatchingScopeForSelection(
+  workflowOverlay: WorkflowOverlay | null,
+  workflowScopeSnapshot: WorkflowScopeSnapshot | null,
+  interactionGuardSnapshot: InteractionGuardSnapshot,
+  selectionAnchor: EditorAnchorProjection,
+  activeStory: EditorStoryTarget,
+): WorkflowScope | null {
+  if (interactionGuardSnapshot.matchedScopeId) {
+    return (
+      getAllScopes(workflowOverlay, workflowScopeSnapshot).find(
+        (scope) => scope.scopeId === interactionGuardSnapshot.matchedScopeId,
+      ) ?? null
+    );
+  }
+  return (
+    getAllScopes(workflowOverlay, workflowScopeSnapshot).find((scope) =>
+      anchorsOverlap(scope.anchor, scope.storyTarget, selectionAnchor, activeStory),
+    ) ?? null
+  );
+}
+
+function getAllScopes(
+  workflowOverlay: WorkflowOverlay | null,
+  workflowScopeSnapshot: WorkflowScopeSnapshot | null,
+): WorkflowScope[] {
+  return workflowOverlay?.scopes ?? workflowScopeSnapshot?.scopes ?? [];
+}
+
+function getWorkflowWorkItem(
+  workflowOverlay: WorkflowOverlay | null,
+  workflowScopeSnapshot: WorkflowScopeSnapshot | null,
+  workItemId: string,
+): WorkflowWorkItem | null {
+  if (workflowOverlay?.workItems) {
+    return workflowOverlay.workItems.find((item) => item.workItemId === workItemId) ?? null;
+  }
+  if (workflowScopeSnapshot?.activeWorkItem?.workItemId === workItemId) {
+    return workflowScopeSnapshot.activeWorkItem;
+  }
+  return null;
+}
+
+function countOpenWorkItems(
+  workflowOverlay: WorkflowOverlay | null,
+  workflowScopeSnapshot: WorkflowScopeSnapshot | null,
+): number {
+  if (workflowOverlay?.workItems?.length) {
+    return workflowOverlay.workItems.filter((item) => item.status !== "done").length;
+  }
+  const uniqueWorkItemIds = new Set(
+    (workflowScopeSnapshot?.scopes ?? [])
+      .map((scope) => scope.workItemId)
+      .filter((workItemId): workItemId is string => Boolean(workItemId)),
+  );
+  return uniqueWorkItemIds.size;
+}
+
+function markupMatchesScope(item: WorkflowMarkupItem, scope: WorkflowScope): boolean {
+  return anchorsOverlap(item.anchor, item.storyTarget, scope.anchor, scope.storyTarget);
+}
+
+function markupMatchesAnchor(
+  item: WorkflowMarkupItem,
+  anchor: EditorAnchorProjection,
+  storyTarget: EditorStoryTarget,
+): boolean {
+  return anchorsOverlap(item.anchor, item.storyTarget, anchor, storyTarget);
+}
+
+function anchorsOverlap(
+  left: EditorAnchorProjection,
+  leftStoryTarget: EditorStoryTarget | undefined,
+  right: EditorAnchorProjection,
+  rightStoryTarget: EditorStoryTarget | undefined,
+): boolean {
+  if (
+    !storyTargetsEqual(leftStoryTarget ?? MAIN_STORY_TARGET, rightStoryTarget ?? MAIN_STORY_TARGET)
+  ) {
+    return false;
+  }
+  const leftRange = toComparableRange(left);
+  const rightRange = toComparableRange(right);
+  if (!leftRange || !rightRange) {
+    return false;
+  }
+  return leftRange.from <= rightRange.to && rightRange.from <= leftRange.to;
+}
+
+function toComparableRange(
+  anchor: EditorAnchorProjection,
+): { from: number; to: number } | null {
+  if (anchor.kind === "detached") {
+    return null;
+  }
+  if (anchor.kind === "range") {
+    return {
+      from: Math.min(anchor.from, anchor.to),
+      to: Math.max(anchor.from, anchor.to),
+    };
+  }
+  return {
+    from: anchor.at,
+    to: anchor.at,
+  };
+}
+
+function countUnresolvedComments(items: readonly WorkflowMarkupItem[]): number {
+  return items.filter((item) => item.kind === "comment" && item.status === "open").length;
+}
+
+function countPendingRevisions(items: readonly WorkflowMarkupItem[]): number {
+  return items.filter(
+    (item) =>
+      item.kind === "revision" &&
+      item.status === "active" &&
+      item.actionability === "actionable",
+  ).length;
+}
+
+function getDocumentWarningCount(
+  compatibility: CompatibilityReport,
+  warnings: readonly EditorWarning[],
+): number {
+  return (
+    warnings.length +
+    compatibility.featureEntries.filter((entry) => entry.featureClass !== "supported-roundtrip").length
+  );
+}
+
+function getDocumentErrorCount(compatibility: CompatibilityReport): number {
+  return compatibility.errors.length;
+}
+
+function getExportReadiness(input: {
+  compatibility: CompatibilityReport;
+  workflowMarkup: WorkflowMarkupSnapshot;
+  warnings: number;
+  errors: number;
+}): "ready" | "warning" | "blocked" {
+  if (input.compatibility.blockExport || input.errors > 0) {
+    return "blocked";
+  }
+  if (
+    input.warnings > 0 ||
+    input.workflowMarkup.opaqueFragments.length > 0 ||
+    input.workflowMarkup.protectedRanges.some((item) => item.enforced)
+  ) {
+    return "warning";
+  }
+  return "ready";
+}
+
+function createAttentionHints(input: {
+  unresolvedComments: number;
+  pendingRevisions: number;
+  pendingSuggestions?: number;
+  blockedReasons: readonly WorkflowBlockedCommandReason[];
+}): RuntimeContextAnalyticsActionHint[] {
+  return [
+    input.blockedReasons[0]
+      ? createActionHint("blocked", input.blockedReasons[0].message, "blocker")
+      : null,
+    input.pendingSuggestions && input.pendingSuggestions > 0
+      ? createActionHint(
+          "review-suggestions",
+          `Review ${input.pendingSuggestions} pending ${pluralize(input.pendingSuggestions, "suggestion")}`,
+          "next_step",
+        )
+      : input.pendingRevisions > 0
+      ? createActionHint(
+          "review-revisions",
+          `Review ${input.pendingRevisions} pending ${pluralize(input.pendingRevisions, "change")}`,
+          "next_step",
+        )
+      : null,
+    input.unresolvedComments > 0
+      ? createActionHint(
+          "resolve-comments",
+          `Resolve ${input.unresolvedComments} ${pluralize(input.unresolvedComments, "comment")}`,
+          "next_step",
+        )
+      : null,
+  ].filter((action): action is RuntimeContextAnalyticsActionHint => Boolean(action));
+}
+
+function createModeBadge(
+  mode: "edit" | "suggest" | "comment" | "view" | "blocked",
+): RuntimeContextAnalyticsBadge | null {
+  switch (mode) {
+    case "suggest":
+      return { key: "mode", label: "Suggest", tone: "accent" };
+    case "comment":
+      return { key: "mode", label: "Comment only", tone: "accent" };
+    case "view":
+      return { key: "mode", label: "View only" };
+    case "blocked":
+      return { key: "mode", label: "Blocked", tone: "danger" };
+    case "edit":
+    default:
+      return null;
+  }
+}
+
+function createCountBadge(
+  key: string,
+  count: number,
+  singularLabel: string,
+): RuntimeContextAnalyticsBadge {
+  return {
+    key,
+    label: `${count} ${pluralize(count, singularLabel)}`,
+  };
+}
+
+function createExportBadge(
+  exportReadiness: "ready" | "warning" | "blocked",
+): RuntimeContextAnalyticsBadge {
+  return {
+    key: "export",
+    label:
+      exportReadiness === "blocked"
+        ? "Export blocked"
+        : exportReadiness === "warning"
+          ? "Export warnings"
+          : "Export ready",
+    tone:
+      exportReadiness === "blocked"
+        ? "danger"
+        : exportReadiness === "warning"
+          ? "warning"
+          : "success",
+  };
+}
+
+function createActionHint(
+  key: string,
+  label: string,
+  kind: RuntimeContextAnalyticsActionHint["kind"],
+): RuntimeContextAnalyticsActionHint {
+  return { key, label, kind };
+}
+
+function countActiveSuggestions(snapshot: SuggestionsSnapshot): number {
+  return snapshot.suggestions.filter(
+    (suggestion) =>
+      suggestion.status === "active" &&
+      suggestion.actionability === "actionable",
+  ).length;
+}
+
+function countPendingSuggestionsForMarkupItems(
+  items: readonly WorkflowMarkupItem[],
+  suggestionsSnapshot: SuggestionsSnapshot,
+): number {
+  if (items.length === 0) {
+    return 0;
+  }
+  const revisionIds = new Set(
+    items
+      .filter((item): item is Extract<WorkflowMarkupItem, { kind: "revision" }> => item.kind === "revision")
+      .filter((item) => item.status === "active" && item.actionability === "actionable")
+      .map((item) => item.revisionId),
+  );
+  if (revisionIds.size === 0) {
+    return 0;
+  }
+  return suggestionsSnapshot.suggestions.filter(
+    (suggestion) =>
+      suggestion.status === "active" &&
+      suggestion.actionability === "actionable" &&
+      suggestion.changeIds.some((changeId) => revisionIds.has(changeId)),
+  ).length;
+}
+
+function createProvenance(): RuntimeContextAnalyticsProvenance {
+  return {
+    kind: "runtime-derived",
+    derivedFrom: [...DERIVED_FROM],
+    unavailable: [...UNAVAILABLE_FIELDS],
+  };
+}
+
+function deriveBlockedAwareMode(
+  mode: WorkflowScope["mode"],
+  blockedReasons: readonly WorkflowBlockedCommandReason[],
+): "edit" | "suggest" | "comment" | "view" | "blocked" {
+  const primaryBlockedReason = blockedReasons[0];
+  if (!primaryBlockedReason) {
+    return mode;
+  }
+  if (primaryBlockedReason.code === "workflow_comment_only") {
+    return "comment";
+  }
+  if (primaryBlockedReason.code === "workflow_view_only") {
+    return "view";
+  }
+  return "blocked";
+}
+
+function resolveCompletionState(
+  workItem: WorkflowWorkItem | null,
+  unresolvedComments: number,
+  pendingRevisions: number,
+  isBlocked: boolean,
+): "not_started" | "in_progress" | "ready" | "done" {
+  if (workItem?.status === "done") {
+    return "done";
+  }
+  if (isBlocked || unresolvedComments > 0 || pendingRevisions > 0 || workItem?.status === "active") {
+    return "in_progress";
+  }
+  if (workItem?.status === "pending") {
+    return "not_started";
+  }
+  return "ready";
+}
+
+function pluralize(count: number, singular: string): string {
+  return count === 1 ? singular : `${singular}s`;
+}
+
+function analyticsBadgesEqual(
+  left: readonly RuntimeContextAnalyticsBadge[],
+  right: readonly RuntimeContextAnalyticsBadge[],
+): boolean {
+  if (left.length !== right.length) {
+    return false;
+  }
+  for (let index = 0; index < left.length; index += 1) {
+    const leftBadge = left[index]!;
+    const rightBadge = right[index]!;
+    if (
+      leftBadge.key !== rightBadge.key ||
+      leftBadge.label !== rightBadge.label ||
+      leftBadge.value !== rightBadge.value ||
+      leftBadge.tone !== rightBadge.tone ||
+      leftBadge.priority !== rightBadge.priority
+    ) {
+      return false;
+    }
+  }
+  return true;
+}
+
+function analyticsActionHintsEqual(
+  left: readonly RuntimeContextAnalyticsActionHint[],
+  right: readonly RuntimeContextAnalyticsActionHint[],
+): boolean {
+  if (left.length !== right.length) {
+    return false;
+  }
+  for (let index = 0; index < left.length; index += 1) {
+    const leftAction = left[index]!;
+    const rightAction = right[index]!;
+    if (
+      leftAction.key !== rightAction.key ||
+      leftAction.label !== rightAction.label ||
+      leftAction.kind !== rightAction.kind
+    ) {
+      return false;
+    }
+  }
+  return true;
+}
+
+function analyticsCountsEqual(
+  left: RuntimeContextAnalyticsSnapshot["counts"],
+  right: RuntimeContextAnalyticsSnapshot["counts"],
+): boolean {
+  return (
+    left.tasksRemaining === right.tasksRemaining &&
+    left.unresolvedComments === right.unresolvedComments &&
+    left.pendingRevisions === right.pendingRevisions &&
+    left.pendingSuggestions === right.pendingSuggestions &&
+    left.blockedCommands === right.blockedCommands &&
+    left.approvalsRemaining === right.approvalsRemaining &&
+    left.overdueItems === right.overdueItems &&
+    left.warnings === right.warnings &&
+    left.errors === right.errors &&
+    left.openWorkItems === right.openWorkItems &&
+    left.exportBlockers === right.exportBlockers
+  );
+}
+
+function analyticsStateEqual(
+  left: RuntimeContextAnalyticsSnapshot["state"],
+  right: RuntimeContextAnalyticsSnapshot["state"],
+): boolean {
+  return (
+    left.effectiveMode === right.effectiveMode &&
+    left.isBlocked === right.isBlocked &&
+    left.disabledReason === right.disabledReason &&
+    left.completionState === right.completionState &&
+    left.exportReadiness === right.exportReadiness &&
+    left.lastTouchedAt === right.lastTouchedAt
+  );
+}
+
+function analyticsProvenanceEqual(
+  left: RuntimeContextAnalyticsProvenance,
+  right: RuntimeContextAnalyticsProvenance,
+): boolean {
+  return (
+    left.kind === right.kind &&
+    stringArraysEqual(left.derivedFrom, right.derivedFrom) &&
+    stringArraysEqual(left.unavailable, right.unavailable)
+  );
+}
+
+function stringArraysEqual(left: readonly string[], right: readonly string[]): boolean {
+  if (left.length !== right.length) {
+    return false;
+  }
+  for (let index = 0; index < left.length; index += 1) {
+    if (left[index] !== right[index]) {
+      return false;
+    }
+  }
+  return true;
+}