@beyondwork/docx-react-component 1.0.67 → 1.0.70

package/src/io/docx-session.ts

@@ -1,4797 +1,36 @@
-import type {
-  CompatibilityReport as PublicCompatibilityReport,
-  EditorError,
-  EditorHostAdapter,
-  EditorSessionState,
-  EditorSurfaceSnapshot,
-  EditorWarning as PublicEditorWarning,
-  EditorAnchorProjection as PublicEditorAnchorProjection,
-  ExportDocxOptions,
-  ExportResult,
-  PersistedEditorSnapshot,
-  ProtectionRange,
-  ProtectionSnapshot,
-  WorkflowMetadataSnapshot,
-  WorkflowOverlay,
-  WorkflowScope,
-  WorkflowScopeMetadataField,
-  WorkflowWorkItem,
-} from "../api/public-types.ts";
-import { editorSessionStateFromPersistedSnapshot } from "../api/session-state.ts";
-import type {
-  CanonicalDocumentEnvelope,
-  CompatibilityFeatureEntry as InternalCompatibilityFeatureEntry,
-  CompatibilityReport as InternalCompatibilityReport,
-  CommentThreadRecord,
-  EditorError as InternalEditorError,
-  RevisionRecord as RuntimeRevisionRecord,
-  EditorWarning as InternalEditorWarning,
-} from "../core/state/editor-state.ts";
-import {
-  createCanonicalDocumentId,
-  createDefaultCanonicalDocument,
-  createSelectionSnapshot,
-} from "../core/state/editor-state.ts";
-// NOTE: docx-session.ts is intentionally an integration orchestrator, not a
-// pure io module. It coordinates io (OOXML parse/export) with runtime
-// (surface projection, cache envelopes, read-only diagnostics) and
-// presentation. The runtime imports below (surface-projection,
-// prerender/cache-envelope, read-only-diagnostics-runtime) are load-bearing
-// and violate the nominal io→runtime boundary on purpose. The proper
-// long-term fix is to relocate this file to src/session/ (see
-// docs/plans/architecture-lane.md §F2). Do NOT add more runtime imports
-// here without first reading that deferral rationale.
-import { createEditorSurfaceSnapshot } from "../runtime/surface-projection.ts";
-import { MAIN_STORY_TARGET } from "../core/selection/mapping.ts";
-import {
-  createDetachedAnchor,
-  storyTargetsEqual,
-  type EditorAnchorProjection as InternalEditorAnchorProjection,
-} from "../core/selection/mapping.ts";
-import { DOCX_MIME_TYPE } from "./opc/docx-package.ts";
-import { readOpcPackage, type OpcPackage } from "./opc/package-reader.ts";
-import {
-  parseMainDocumentXml,
-  type ParsedBlockNode,
-  type ParsedInlineNode,
-  type ParsedPermStartInlineNode,
-} from "./ooxml/parse-main-document.ts";
-import {
-  normalizeParsedTextDocument,
-  normalizeParsedTextDocumentAsync,
-} from "./normalize/normalize-text.ts";
-import { createChartPartLookup, resolveChartPreviewsForDocument, scheduleChartPreviewResolution } from "./chart-preview-resolver.ts";
-import { type LoadScheduler } from "./load-scheduler.ts";
-import type { CacheEnvelope } from "../runtime/prerender/cache-envelope.ts";
-import {
-  CONTENT_TYPES_PATH,
-  PACKAGE_RELATIONSHIPS_PATH,
-  getRelationshipsPartPath,
-  normalizePartPath,
-  resolveRelationshipTarget,
-  type OpcRelationship,
-} from "./ooxml/part-manifest.ts";
-import {
-  buildWorkflowPayloadParts,
-  getDocumentBackedWorkflowMetadata,
-  parseWorkflowPayloadEnvelopeFromPackage,
-  resolvePayloadPartPath,
-  resolveWorkflowPayloadPartPaths,
-  WORKFLOW_PAYLOAD_CONTENT_TYPE,
-  WORKFLOW_PAYLOAD_CUSTOM_PROPS_CONTENT_TYPE,
-  WORKFLOW_PAYLOAD_CUSTOM_PROPS_PART_PATH,
-  WORKFLOW_PAYLOAD_CUSTOM_PROPS_RELATIONSHIP_TYPE,
-  WORKFLOW_PAYLOAD_ITEM_PROPS_CONTENT_TYPE,
-  WORKFLOW_PAYLOAD_RELATIONSHIP_TYPE,
-} from "./ooxml/workflow-payload.ts";
-import {
-  classifyCorruptPackageError,
-  createBrokenRelationshipIssue,
-  createMissingPartIssue,
-} from "./opc/corrupt-package.ts";
-import { buildAppPropertiesXml } from "./export/build-app-properties-xml.ts";
-import { createExportSession } from "./export/export-session.ts";
-import { serializeMainDocument } from "./export/serialize-main-document.ts";
-import {
-  serializeSettingsXml,
-  WORD_SETTINGS_CONTENT_TYPE,
-} from "./export/serialize-settings.ts";
-import {
-  parseRevisionsFromDocumentXml,
-  parseRevisionsFromStoryXml,
-  type ParsedRevisionsResult,
-} from "./ooxml/parse-revisions.ts";
-import { parseCommentsFromOoxml } from "./ooxml/parse-comments.ts";
-import { parseNumberingXml } from "./ooxml/parse-numbering.ts";
-import {
-  createCommentExportIdMap,
-  mapParagraphBoundaries,
-  serializeCommentAnchorsIntoDocumentXml,
-  serializeMergedCommentsXml,
-} from "./export/serialize-comments.ts";
-import { splitDocumentAtReviewBoundaries } from "./export/split-review-boundaries.ts";
-import { splitStoryBlocksForRuntimeRevisions } from "./export/split-story-blocks-for-runtime-revisions.ts";
-import {
-  serializeRuntimeRevisionsIntoDocumentXml,
-  serializeRuntimeRevisionsIntoStoryXml,
-} from "./export/serialize-runtime-revisions.ts";
-import { createCommentStoreFromRuntimeComments } from "../review/store/runtime-comment-store.ts";
-import type { CommentThread } from "../review/store/comment-store.ts";
-import type { RevisionRecord as ReviewRevisionRecord } from "../review/store/revision-types.ts";
-import { getRevisionActionability } from "../review/store/revision-types.ts";
-import { buildCompatibilityReport } from "../validation/compatibility-engine.ts";
-import {
-  createPackageImportDiagnostics,
-  createValidationImportDiagnostics,
-  type ImportDiagnosticsResult,
-} from "../validation/import-diagnostics.ts";
-import type {
-  BlockNode,
-  FootnoteCollection,
-  HeaderDocument,
-  FooterDocument,
-  InlineNode,
-  MediaCatalog,
-  NumberingCatalog,
-  OpaqueFragmentRecord,
-  PreservedPackagePart,
-  SubPartsCatalog,
-} from "../model/canonical-document.ts";
-import { createCanonicalDocumentSignature } from "../model/canonical-document.ts";
-import type { CanonicalDocument } from "../model/canonical-document.ts";
-import type {
-  CommentImportDiagnostic,
-  ImportedCommentDefinition,
-  ParsedCommentsResult,
-} from "./ooxml/parse-comments.ts";
-import { createReadOnlyDiagnosticsRuntime } from "../runtime/read-only-diagnostics-runtime.ts";
-import {
-  WORD_NUMBERING_CONTENT_TYPE,
-  hasSerializableNumberingEntries,
-  serializeNumberingXml,
-} from "./export/serialize-numbering.ts";
-import {
-  parseHeaderFooterReferences,
-  parseHeaderXml,
-  parseFooterXml,
-} from "./ooxml/parse-headers-footers.ts";
-import { parseFootnotesXml, parseEndnotesXml } from "./ooxml/parse-footnotes.ts";
-import { materializeCanonicalTheme, parseThemeXml, resolveTheme } from "./ooxml/parse-theme.ts";
-import { parseSettingsXml } from "./ooxml/parse-settings.ts";
-import { parseStylesXml, type ParseStylesResult } from "./ooxml/parse-styles.ts";
-import { parseFontTable } from "./ooxml/parse-font-table.ts";
-import {
-  serializeHeaderXml,
-  serializeHeaderXmlWithRevisions,
-  serializeFooterXml,
-  serializeFooterXmlWithRevisions,
-  WORD_HEADER_CONTENT_TYPE,
-  WORD_FOOTER_CONTENT_TYPE,
-} from "./export/serialize-headers-footers.ts";
-import {
-  serializeFootnotesXml,
-  serializeEndnotesXml,
-  WORD_FOOTNOTES_CONTENT_TYPE,
-  WORD_ENDNOTES_CONTENT_TYPE,
-} from "./export/serialize-footnotes.ts";
-import { createPersistedSourcePackage } from "./source-package-provenance.ts";
-import { validatePersistedEditorSnapshot } from "../model/snapshot.ts";
-import {
-  createSyntheticDocxNullNumberingCatalog,
-  DOCX_NULL_NUMBERING_INSTANCE_ID,
-} from "./ooxml/numbering-sentinels.ts";
-
-const MAIN_DOCUMENT_PATH = "/word/document.xml";
-const NUMBERING_PART_PATH = "/word/numbering.xml";
-const COMMENTS_PART_PATH = "/word/comments.xml";
-const COMMENTS_EXTENDED_PART_PATH = "/word/commentsExtended.xml";
-const COMMENTS_IDS_PART_PATH = "/word/commentsIds.xml";
-const PEOPLE_PART_PATH = "/word/people.xml";
-const APP_PROPERTIES_PART_PATH = "/docProps/app.xml";
-const CORE_PROPERTIES_PART_PATH = "/docProps/core.xml";
-const MAIN_DOCUMENT_CONTENT_TYPE =
-  "application/vnd.openxmlformats-officedocument.wordprocessingml.document.main+xml";
-const APP_PROPERTIES_CONTENT_TYPE =
-  "application/vnd.openxmlformats-officedocument.extended-properties+xml";
-const CORE_PROPERTIES_CONTENT_TYPE =
-  "application/vnd.openxmlformats-package.core-properties+xml";
-const NUMBERING_RELATIONSHIP_TYPE =
-  "http://schemas.openxmlformats.org/officeDocument/2006/relationships/numbering";
-const COMMENTS_CONTENT_TYPE =
-  "application/vnd.openxmlformats-officedocument.wordprocessingml.comments+xml";
-const COMMENTS_EXTENDED_CONTENT_TYPE =
-  "application/vnd.openxmlformats-officedocument.wordprocessingml.commentsExtended+xml";
-const COMMENTS_IDS_CONTENT_TYPE =
-  "application/vnd.openxmlformats-officedocument.wordprocessingml.commentsIds+xml";
-const PEOPLE_CONTENT_TYPE =
-  "application/vnd.openxmlformats-officedocument.wordprocessingml.people+xml";
-const COMMENTS_RELATIONSHIP_TYPE =
-  "http://schemas.openxmlformats.org/officeDocument/2006/relationships/comments";
-const COMMENTS_EXTENDED_RELATIONSHIP_TYPE =
-  "http://schemas.microsoft.com/office/2011/relationships/commentsExtended";
-const COMMENTS_IDS_RELATIONSHIP_TYPE =
-  "http://schemas.microsoft.com/office/2016/09/relationships/commentsIds";
-const PEOPLE_RELATIONSHIP_TYPE =
-  "http://schemas.microsoft.com/office/2011/relationships/people";
-const APP_PROPERTIES_RELATIONSHIP_TYPE =
-  "http://schemas.openxmlformats.org/officeDocument/2006/relationships/extended-properties";
-const CORE_PROPERTIES_RELATIONSHIP_TYPE =
-  "http://schemas.openxmlformats.org/package/2006/relationships/metadata/core-properties";
-const OFFICE_DOCUMENT_RELATIONSHIP_TYPE =
-  "http://schemas.openxmlformats.org/officeDocument/2006/relationships/officeDocument";
-const HEADER_RELATIONSHIP_TYPE =
-  "http://schemas.openxmlformats.org/officeDocument/2006/relationships/header";
-const FOOTER_RELATIONSHIP_TYPE =
-  "http://schemas.openxmlformats.org/officeDocument/2006/relationships/footer";
-const FOOTNOTES_RELATIONSHIP_TYPE =
-  "http://schemas.openxmlformats.org/officeDocument/2006/relationships/footnotes";
-const ENDNOTES_RELATIONSHIP_TYPE =
-  "http://schemas.openxmlformats.org/officeDocument/2006/relationships/endnotes";
-const SETTINGS_RELATIONSHIP_TYPE =
-  "http://schemas.openxmlformats.org/officeDocument/2006/relationships/settings";
-const STYLES_RELATIONSHIP_TYPE =
-  "http://schemas.openxmlformats.org/officeDocument/2006/relationships/styles";
-const STYLES_PART_PATH = "/word/styles.xml";
-const FONT_TABLE_RELATIONSHIP_TYPE =
-  "http://schemas.openxmlformats.org/officeDocument/2006/relationships/fontTable";
-const FONT_TABLE_PART_PATH = "/word/fontTable.xml";
-const FOOTNOTES_PART_PATH = "/word/footnotes.xml";
-const ENDNOTES_PART_PATH = "/word/endnotes.xml";
-const SETTINGS_PART_PATH = "/word/settings.xml";
-
-interface LoadDocxEditorSessionOptions {
-  documentId: string;
-  sourceLabel?: string;
-  bytes: Uint8Array | ArrayBuffer;
-  editorBuild?: string;
-  /**
-   * Fastload P2: optional instrumentation callback invoked once per
-   * completed load stage. Stage ordering: opc → body →
-   * styles-numbering-comments → skeleton-ready. `durationMs` is
-   * measured against `performance.now()` boundaries inside the loader.
-   *
-   * Pure instrumentation — has no effect on returned session shape.
-   * Safe to leave undefined; existing callers observe no behavior
-   * change.
-   */
-  onLoadStage?: (stage: import("../api/public-types.ts").LoadStage, durationMs: number) => void;
-  /**
-   * Stage 0B.1: host-adapter surface. The sync loader accepts the option for
-   * API symmetry with {@link LoadDocxEditorSessionAsyncOptions} but does not
-   * invoke `renderChartPreview` — chart-preview synthesis is asynchronous, so
-   * hosts that want preview bitmaps must call {@link loadDocxEditorSessionAsync}.
-   * Other adapter methods (load/saveSession/logEvent) are not consumed by the
-   * loader itself and are carried through unchanged.
-   */
-  hostAdapter?: EditorHostAdapter;
-}
-
-export interface LoadedDocxEditorSession {
-  initialSessionState: EditorSessionState;
-  initialSnapshot: PersistedEditorSnapshot;
-  fatalError?: EditorError;
-  readOnly: boolean;
-  protectionSnapshot: ProtectionSnapshot;
-  exportDocx: (
-    sessionState: EditorSessionState | PersistedEditorSnapshot,
-    options?: ExportDocxOptions,
-  ) => Promise<ExportResult>;
-  /** Schema 1.2 — editorState block parsed from the 1.2 payload, if present. */
-  initialEditorStatePayload?: import("./ooxml/workflow-payload.ts").EditorStatePayload;
-}
-
-interface ImportedDocxState {
-  sourceBytes: Uint8Array;
-  sourcePackage: OpcPackage;
-  sourceDocumentXml: string;
-  sourceDocumentPartPath: string;
-  sourceDocumentRelationships: readonly OpcRelationship[];
-  sourceDocumentAttributes: Record<string, string>;
-  sourceNumberingPartPath?: string;
-  sourceNumberingRelationshipId?: string;
-  /**
-   * Resolved `/word/settings.xml` part path when the source package carried
-   * one. Threaded through to the export path so the settings serializer can
-   * call `replaceOwnedPart` with the right relationship target.
-   */
-  sourceSettingsPartPath?: string;
-  /**
-   * Original settings.xml bytes decoded as UTF-8. Passed to
-   * `serializeSettingsXml(settings, sourceXml)` as the graft source so
-   * unmodelled top-level children (`<w:defaultTabStop>`,
-   * `<w:documentProtection>`, mail-merge state, etc.) survive verbatim
-   * through round-trip. Undefined when the source package lacked a
-   * settings part.
-   */
-  sourceSettingsXml?: string;
-  sourceCommentsPartPath?: string;
-  sourceCommentsRelationshipId?: string;
-  sourceCommentsRootTag?: string;
-  sourceCommentsExtendedPartPath?: string;
-  sourceCommentsExtendedRelationshipId?: string;
-  sourceCommentsExtendedRootTag?: string;
-  sourceCommentsIdsPartPath?: string;
-  sourceCommentsIdsRelationshipId?: string;
-  sourceCommentsIdsRootTag?: string;
-  sourcePeoplePartPath?: string;
-  sourcePeopleRelationshipId?: string;
-  sourcePeopleRootTag?: string;
-  sourcePeopleAuthors: readonly string[];
-  protectionSnapshot: ProtectionSnapshot;
-  preservedCommentDefinitions: readonly ImportedCommentDefinition[];
-  blockingCommentDiagnostics: readonly CommentImportDiagnostic[];
-  initialCanonicalSignature: string;
-  sourceSubPartPaths: {
-    headers: Array<{ partPath: string; relationshipId: string }>;
-    footers: Array<{ partPath: string; relationshipId: string }>;
-    footnotesPartPath?: string;
-    footnotesRelationshipId?: string;
-    endnotesPartPath?: string;
-    endnotesRelationshipId?: string;
-    themePartPath?: string;
-    themeRelationshipId?: string;
-  };
-}
-
-export interface NormalizedImportedCommentsResult extends ParsedCommentsResult {
-  preservedDefinitions: readonly ImportedCommentDefinition[];
-}
-
-const BLOCKING_COMMENT_DIAGNOSTIC_CODES = new Set<CommentImportDiagnostic["code"]>([
-  "missing_comment_definition",
-  "missing_anchor_reference",
-  "multi_paragraph_anchor_preserve_only",
-  "opaque_anchor_preserve_only",
-  "preserve_only_revision_overlap",
-]);
-
-interface StageEmitter {
-  emit(stage: import("../api/public-types.ts").LoadStage): void;
-}
-
-/**
- * Fastload P2 (hoisted in P6): build a stage-event emitter. When no callback
- * is supplied the emitter is a zero-cost no-op. Shared between the sync and
- * async load orchestrators so both paths emit `load-stage` events at the
- * same four boundaries: `opc` → `body` → `styles-numbering-comments` →
- * `skeleton-ready`.
- */
-function createStageEmitter(
-  onStage: LoadDocxEditorSessionOptions["onLoadStage"],
-): StageEmitter {
-  if (!onStage) {
-    return {
-      emit() {
-        /* no-op */
-      },
-    };
-  }
-  let cursor = loadStageNow();
-  return {
-    emit(stage) {
-      const nextMark = loadStageNow();
-      onStage(stage, nextMark - cursor);
-      cursor = nextMark;
-    },
-  };
-}
-
-export function loadDocxEditorSession(
-  options: LoadDocxEditorSessionOptions,
-): LoadedDocxEditorSession {
-  const editorBuild =
-    typeof options.editorBuild === "string" && options.editorBuild.length > 0
-      ? options.editorBuild
-      : "dev";
-  const sourceBytes = toUint8Array(options.bytes);
-
-  const stages = createStageEmitter(options.onLoadStage);
-
-  let sourcePackage: OpcPackage;
-
-  try {
-    sourcePackage = readOpcPackage(sourceBytes);
-  } catch (error) {
-    return createDiagnosticsSession(
-      options,
-      createPackageImportDiagnostics({
-        issue: classifyCorruptPackageError(error),
-      }),
-    );
-  }
-  stages.emit("opc");
-  const embeddedWorkflowPayload = parseWorkflowPayloadEnvelopeFromPackage(sourcePackage);
-  const embeddedWorkflowMetadata = embeddedWorkflowPayload?.workflowMetadata;
-  const embeddedWorkflowOverlay = embeddedWorkflowPayload?.workflowOverlay;
-
-  const mainDocumentPath = resolveMainDocumentPartPath(sourcePackage);
-  const brokenRelationshipIssues = collectBrokenInternalRelationshipIssues(
-    sourcePackage,
-    mainDocumentPath,
-  );
-  if (brokenRelationshipIssues.length > 0) {
-    return createDiagnosticsSession(
-      options,
-      createPackageImportDiagnostics({
-        issue: {
-          ...brokenRelationshipIssues[0],
-          message: summarizeBrokenRelationshipIssues(brokenRelationshipIssues),
-          details: {
-            issueCount: brokenRelationshipIssues.length,
-            targets: brokenRelationshipIssues.map((issue) => issue.targetPartPath).filter(Boolean),
-          },
-        },
-      }),
-    );
-  }
-
-  if (!mainDocumentPath) {
-    return createDiagnosticsSession(
-      options,
-      createPackageImportDiagnostics({
-        issue: createMissingPartIssue(MAIN_DOCUMENT_PATH),
-      }),
-    );
-  }
-
-  const documentPart = sourcePackage.parts.get(mainDocumentPath);
-  if (!documentPart) {
-    return createDiagnosticsSession(
-      options,
-      createPackageImportDiagnostics({
-        issue: createMissingPartIssue(mainDocumentPath),
-      }),
-    );
-  }
-  if (documentPart.contentType !== MAIN_DOCUMENT_CONTENT_TYPE) {
-    return createDiagnosticsSession(
-      options,
-      createValidationImportDiagnostics({
-        message: `DOCX main document part ${mainDocumentPath} must use content type ${MAIN_DOCUMENT_CONTENT_TYPE}.`,
-      }),
-    );
-  }
-
-  try {
-    const sourceDocumentXml = decodeUtf8(documentPart.bytes);
-    const importedRevisions = parseRevisionsFromDocumentXml(sourceDocumentXml);
-    const numberingPartPath = resolveDocumentRelatedPartPath(
-      sourcePackage,
-      mainDocumentPath,
-      documentPart.relationships,
-      NUMBERING_RELATIONSHIP_TYPE,
-      NUMBERING_PART_PATH,
-    );
-    const parsedNumbering = numberingPartPath
-      ? parseNumberingXml(
-          decodeUtf8(sourcePackage.parts.get(numberingPartPath)?.bytes ?? new Uint8Array()),
-          {
-            relationships: sourcePackage.parts.get(numberingPartPath)?.relationships,
-            partPath: numberingPartPath,
-          },
-        )
-      : createEmptyNumberingCatalog();
-    const mediaParts = collectInlineMediaParts(sourcePackage);
-    const chartPartLookup = createChartPartLookup(
-      sourcePackage,
-      mainDocumentPath,
-      documentPart.relationships,
-    );
-    const parsedDocument = parseMainDocumentXml(
-      sourceDocumentXml,
-      documentPart.relationships,
-      mediaParts,
-      mainDocumentPath,
-      chartPartLookup,
-    );
-    const protectionRanges = extractProtectionRanges(parsedDocument.blocks);
-    const normalizedDocument = normalizeParsedTextDocument(
-      parsedDocument,
-      mainDocumentPath,
-    );
-    stages.emit("body");
-    const commentsPartPath = resolveCommentsPartPath(
-      sourcePackage,
-      mainDocumentPath,
-      documentPart.relationships,
-    );
-    const commentsExtendedPartPath = resolveDocumentRelatedPartPath(
-      sourcePackage,
-      mainDocumentPath,
-      documentPart.relationships,
-      COMMENTS_EXTENDED_RELATIONSHIP_TYPE,
-      COMMENTS_EXTENDED_PART_PATH,
-    );
-    const commentsIdsPartPath = resolveDocumentRelatedPartPath(
-      sourcePackage,
-      mainDocumentPath,
-      documentPart.relationships,
-      COMMENTS_IDS_RELATIONSHIP_TYPE,
-      COMMENTS_IDS_PART_PATH,
-    );
-    const peoplePartPath = resolveDocumentRelatedPartPath(
-      sourcePackage,
-      mainDocumentPath,
-      documentPart.relationships,
-      PEOPLE_RELATIONSHIP_TYPE,
-      PEOPLE_PART_PATH,
-    );
-    const parsedComments = commentsPartPath
-      ? parseCommentsFromOoxml(
-          sourceDocumentXml,
-          {
-            commentsXml: decodeUtf8(sourcePackage.parts.get(commentsPartPath)?.bytes ?? new Uint8Array()),
-            commentsExtendedXml: decodeUtf8(
-              sourcePackage.parts.get(commentsExtendedPartPath ?? "")?.bytes ?? new Uint8Array(),
-            ),
-            commentsIdsXml: decodeUtf8(
-              sourcePackage.parts.get(commentsIdsPartPath ?? "")?.bytes ?? new Uint8Array(),
-            ),
-            peopleXml: decodeUtf8(
-              sourcePackage.parts.get(peoplePartPath ?? "")?.bytes ?? new Uint8Array(),
-            ),
-          },
-        )
-      : {
-          threads: [] as CommentThread[],
-          diagnostics: [] as CommentImportDiagnostic[],
-          definitions: [] as ImportedCommentDefinition[],
-          sourceRootTag: undefined,
-          sourceExtendedRootTag: undefined,
-          sourceIdsRootTag: undefined,
-          sourcePeopleRootTag: undefined,
-          peopleAuthors: [] as string[],
-        };
-    const normalizedRevisions = normalizeImportedRevisionRecords(
-      importedRevisions,
-      normalizedDocument.content,
-      normalizedDocument.preservation.opaqueFragments,
-    );
-    const normalizedComments = normalizeImportedCommentThreads(
-      parsedComments,
-      normalizedDocument.preservation.opaqueFragments,
-      normalizedRevisions.revisions,
-    );
-    stages.emit("styles-numbering-comments");
-    const importedStoryRevisions: ReviewRevisionRecord[] = [];
-    const importedStoryRevisionDiagnostics: ParsedRevisionsResult["diagnostics"] = [];
-    const subPartOpaqueState = createSubPartOpaqueImportState(
-      normalizedDocument.preservation.opaqueFragments,
-      normalizedDocument.diagnostics.warnings,
-    );
-    // ---- Parse sub-parts: headers, footers, footnotes, endnotes, theme ----
-    const headerFooterRefs = parseHeaderFooterReferences(sourceDocumentXml);
-    const parsedHeaders: HeaderDocument[] = [];
-    const parsedFooters: FooterDocument[] = [];
-    const sourceHeaderPaths: Array<{ partPath: string; relationshipId: string }> = [];
-    const sourceFooterPaths: Array<{ partPath: string; relationshipId: string }> = [];
-    const seenSubPartKeys = new Set<string>();
-
-    for (const ref of headerFooterRefs) {
-      const dedupeKey = `${ref.kind}:${ref.variant}:${ref.relationshipId}`;
-      if (seenSubPartKeys.has(dedupeKey)) {
-        continue;
-      }
-      seenSubPartKeys.add(dedupeKey);
-
-      const relationship = documentPart.relationships.find(
-        (r) => r.id === ref.relationshipId && r.targetMode === "internal",
-      );
-      if (!relationship) {
-        continue;
-      }
-
-      const partPath = resolveRelationshipTarget(mainDocumentPath, relationship);
-      const part = sourcePackage.parts.get(partPath);
-      const partBytes = part?.bytes;
-      if (!partBytes) {
-        continue;
-      }
-
-      const xml = decodeUtf8(partBytes);
-      const subPartRelationships = part?.relationships ?? [];
-      const subPartChartPartLookup = createChartPartLookup(
-        sourcePackage,
-        partPath,
-        subPartRelationships,
-      );
-      if (ref.kind === "header") {
-        const parsedHeaderRevisions = parseRevisionsFromStoryXml(xml);
-        const parsed = parseHeaderXml(xml, {
-          relationships: subPartRelationships,
-          mediaParts,
-          sourcePartPath: partPath,
-          chartPartLookup: subPartChartPartLookup,
-        });
-        parsedHeaders.push({
-          variant: ref.variant,
-          partPath,
-          relationshipId: ref.relationshipId,
-          ...(ref.sectionIndex !== undefined ? { sectionIndex: ref.sectionIndex } : {}),
-          blocks: normalizeSubPartOpaqueBlocks(
-            parsed.blocks,
-            normalizedDocument.preservation.opaqueFragments,
-            normalizedDocument.diagnostics.warnings,
-            partPath,
-            subPartOpaqueState,
-          ),
-        });
-        importedStoryRevisions.push(
-          ...parsedHeaderRevisions.revisions.map((revision): ReviewRevisionRecord => ({
-            ...revision,
-            metadata: {
-              ...revision.metadata,
-              storyTarget: {
-                kind: "header" as const,
-                relationshipId: ref.relationshipId,
-                variant: ref.variant,
-                ...(ref.sectionIndex !== undefined ? { sectionIndex: ref.sectionIndex } : {}),
-              },
-            },
-          })),
-        );
-        importedStoryRevisionDiagnostics.push(...parsedHeaderRevisions.diagnostics);
-        sourceHeaderPaths.push({ partPath, relationshipId: ref.relationshipId });
-      } else {
-        const parsedFooterRevisions = parseRevisionsFromStoryXml(xml);
-        const parsed = parseFooterXml(xml, {
-          relationships: subPartRelationships,
-          mediaParts,
-          sourcePartPath: partPath,
-          chartPartLookup: subPartChartPartLookup,
-        });
-        parsedFooters.push({
-          variant: ref.variant,
-          partPath,
-          relationshipId: ref.relationshipId,
-          ...(ref.sectionIndex !== undefined ? { sectionIndex: ref.sectionIndex } : {}),
-          blocks: normalizeSubPartOpaqueBlocks(
-            parsed.blocks,
-            normalizedDocument.preservation.opaqueFragments,
-            normalizedDocument.diagnostics.warnings,
-            partPath,
-            subPartOpaqueState,
-          ),
-        });
-        importedStoryRevisions.push(
-          ...parsedFooterRevisions.revisions.map((revision): ReviewRevisionRecord => ({
-            ...revision,
-            metadata: {
-              ...revision.metadata,
-              storyTarget: {
-                kind: "footer" as const,
-                relationshipId: ref.relationshipId,
-                variant: ref.variant,
-                ...(ref.sectionIndex !== undefined ? { sectionIndex: ref.sectionIndex } : {}),
-              },
-            },
-          })),
-        );
-        importedStoryRevisionDiagnostics.push(...parsedFooterRevisions.diagnostics);
-        sourceFooterPaths.push({ partPath, relationshipId: ref.relationshipId });
-      }
-    }
-
-    const footnotesPartPath = resolveDocumentRelatedPartPath(
-      sourcePackage,
-      mainDocumentPath,
-      documentPart.relationships,
-      FOOTNOTES_RELATIONSHIP_TYPE,
-      FOOTNOTES_PART_PATH,
-    );
-    const footnotesRelationshipId = documentPart.relationships.find(
-      (r) => r.type === FOOTNOTES_RELATIONSHIP_TYPE && r.targetMode === "internal",
-    )?.id;
-    const endnotesPartPath = resolveDocumentRelatedPartPath(
-      sourcePackage,
-      mainDocumentPath,
-      documentPart.relationships,
-      ENDNOTES_RELATIONSHIP_TYPE,
-      ENDNOTES_PART_PATH,
-    );
-    const endnotesRelationshipId = documentPart.relationships.find(
-      (r) => r.type === ENDNOTES_RELATIONSHIP_TYPE && r.targetMode === "internal",
-    )?.id;
-
-    let footnoteCollection: FootnoteCollection | undefined;
-    if (footnotesPartPath) {
-      footnoteCollection = parseFootnotesXml(
-        decodeUtf8(sourcePackage.parts.get(footnotesPartPath)?.bytes ?? new Uint8Array()),
-      );
-      normalizeFootnoteCollectionOpaqueBlocks(
-        footnoteCollection,
-        "footnote",
-        normalizedDocument.preservation.opaqueFragments,
-        normalizedDocument.diagnostics.warnings,
-        footnotesPartPath,
-        subPartOpaqueState,
-      );
-    }
-    if (endnotesPartPath) {
-      footnoteCollection = parseEndnotesXml(
-        decodeUtf8(sourcePackage.parts.get(endnotesPartPath)?.bytes ?? new Uint8Array()),
-        footnoteCollection,
-      );
-      normalizeFootnoteCollectionOpaqueBlocks(
-        footnoteCollection,
-        "endnote",
-        normalizedDocument.preservation.opaqueFragments,
-        normalizedDocument.diagnostics.warnings,
-        endnotesPartPath,
-        subPartOpaqueState,
-      );
-    }
-
-    const themeRelationship = documentPart.relationships.find(
-      (r) => r.type === "http://schemas.openxmlformats.org/officeDocument/2006/relationships/theme" &&
-        r.targetMode === "internal",
-    );
-    const themePartPath = themeRelationship
-      ? resolveRelationshipTarget(mainDocumentPath, themeRelationship)
-      : undefined;
-    const parsedTheme =
-      themePartPath && sourcePackage.parts.has(themePartPath)
-        ? parseThemeXml(
-            decodeUtf8(sourcePackage.parts.get(themePartPath)?.bytes ?? new Uint8Array()),
-          )
-        : undefined;
-    const resolvedTheme = parsedTheme ? resolveTheme(parsedTheme) : undefined;
-    const settingsPartPath = resolveDocumentRelatedPartPath(
-      sourcePackage,
-      mainDocumentPath,
-      documentPart.relationships,
-      SETTINGS_RELATIONSHIP_TYPE,
-      SETTINGS_PART_PATH,
-    );
-    const parsedSettings =
-      settingsPartPath && sourcePackage.parts.has(settingsPartPath)
-        ? parseSettingsXml(
-            decodeUtf8(sourcePackage.parts.get(settingsPartPath)?.bytes ?? new Uint8Array()),
-          )
-        : undefined;
-    const canonicalTheme =
-      parsedTheme !== undefined
-        ? materializeCanonicalTheme(
-            parsedTheme,
-            parsedSettings?.clrSchemeMapping ?? {},
-          )
-        : undefined;
-    const settingsXmlForProtection =
-      settingsPartPath && sourcePackage.parts.has(settingsPartPath)
-        ? decodeUtf8(sourcePackage.parts.get(settingsPartPath)?.bytes ?? new Uint8Array())
-        : "";
-    const documentProtection = extractDocumentProtection(settingsXmlForProtection);
-    const importedProtectionSnapshot = buildProtectionSnapshot(documentProtection, protectionRanges);
-
-    // ---- Parse styles.xml for canonical style catalog ----
-    const stylesPartPath = resolveDocumentRelatedPartPath(
-      sourcePackage,
-      mainDocumentPath,
-      documentPart.relationships,
-      STYLES_RELATIONSHIP_TYPE,
-      STYLES_PART_PATH,
-    );
-    const parsedStyles =
-      stylesPartPath && sourcePackage.parts.has(stylesPartPath)
-        ? parseStylesXml(
-            decodeUtf8(sourcePackage.parts.get(stylesPartPath)?.bytes ?? new Uint8Array()),
-          )
-        : parseStylesXml("");
-
-    // ---- Parse fontTable.xml for canonical font catalog ----
-    const fontTablePartPath = resolveDocumentRelatedPartPath(
-      sourcePackage,
-      mainDocumentPath,
-      documentPart.relationships,
-      FONT_TABLE_RELATIONSHIP_TYPE,
-      FONT_TABLE_PART_PATH,
-    );
-    const parsedFontTable =
-      fontTablePartPath && sourcePackage.parts.has(fontTablePartPath)
-        ? parseFontTable(
-            decodeUtf8(sourcePackage.parts.get(fontTablePartPath)?.bytes ?? new Uint8Array()),
-          )
-        : undefined;
-
-    const mergedMedia = mergeSecondaryStoryMediaCatalog(normalizedDocument.media, {
-      headers: parsedHeaders,
-      footers: parsedFooters,
-      footnoteCollection,
-      mediaParts,
-    });
-
-    const subParts: SubPartsCatalog | undefined =
-      parsedHeaders.length > 0 ||
-      parsedFooters.length > 0 ||
-      footnoteCollection !== undefined ||
-      parsedTheme !== undefined ||
-      normalizedDocument.finalSectionProperties !== undefined ||
-      resolvedTheme !== undefined ||
-      canonicalTheme !== undefined ||
-      parsedSettings !== undefined
-        ? {
-            headers: parsedHeaders,
-            footers: parsedFooters,
-            ...(footnoteCollection !== undefined ? { footnoteCollection } : {}),
-            ...(parsedTheme !== undefined ? { theme: parsedTheme } : {}),
-            ...(normalizedDocument.finalSectionProperties !== undefined
-              ? { finalSectionProperties: normalizedDocument.finalSectionProperties }
-              : {}),
-            ...(resolvedTheme !== undefined ? { resolvedTheme } : {}),
-            ...(canonicalTheme !== undefined ? { canonicalTheme } : {}),
-            ...(parsedSettings !== undefined ? { settings: parsedSettings } : {}),
-          }
-        : undefined;
-
-    const timestamp = new Date().toISOString();
-    const translatedWorkflowState = translateClmCommentsToWorkflow({
-      comments: normalizedComments.threads,
-      workflowOverlay: embeddedWorkflowOverlay,
-      workflowMetadata: embeddedWorkflowMetadata,
-      timestamp,
-    });
-    const document = createImportedCanonicalDocument({
-      documentId: options.documentId,
-      timestamp,
-      numbering: parsedNumbering,
-      media: mergedMedia,
-      content: normalizedDocument.content,
-      subParts,
-      parsedStyles,
-      fontTable: parsedFontTable,
-      preservation: {
-        ...normalizedDocument.preservation,
-        packageParts: {
-          ...normalizedDocument.preservation.packageParts,
-          ...collectPreservedPackageParts(sourcePackage, [
-            mainDocumentPath,
-            numberingPartPath,
-            commentsPartPath,
-            commentsExtendedPartPath,
-            commentsIdsPartPath,
-            peoplePartPath,
-          ]),
-        },
-      },
-      diagnostics: {
-        warnings: [
-          ...createBrokenRelationshipWarnings(sourcePackage, mainDocumentPath),
-          ...normalizedDocument.diagnostics.warnings,
-          ...normalizedRevisions.diagnostics.map((diagnostic, index) => ({
-            diagnosticId: `diagnostic:revision-import-${index + 1}`,
-            warningId: `warning:revision-import-${diagnostic.revisionId}`,
-            source: "review" as const,
-            message: diagnostic.message,
-          })),
-          ...importedStoryRevisionDiagnostics.map((diagnostic, index) => ({
-            diagnosticId: `diagnostic:story-revision-import-${index + 1}`,
-            warningId: `warning:story-revision-import-${diagnostic.revisionId}`,
-            source: "review" as const,
-            message: diagnostic.message,
-          })),
-          ...normalizedComments.diagnostics.map((diagnostic, index) => ({
-            diagnosticId: `diagnostic:comment-import-${index + 1}`,
-            warningId: `warning:comment-import-${diagnostic.commentId}`,
-            source: "review" as const,
-            message: diagnostic.message,
-          })),
-        ],
-        errors: [],
-      },
-      review: {
-        comments: toRuntimeCommentRecords(translatedWorkflowState.comments),
-        revisions: toRuntimeRevisionRecords([
-          ...normalizedRevisions.revisions,
-          ...importedStoryRevisions,
-        ]),
-      },
-    });
-    const compatibility = buildCompatibilityReport({
-      document,
-      generatedAt: timestamp,
-    });
-    const snapshot = createImportedSnapshot({
-      documentId: options.documentId,
-      editorBuild,
-      timestamp,
-      document,
-      compatibility: toPublicCompatibilityReport(compatibility),
-      protectionSnapshot: importedProtectionSnapshot,
-      sourcePackage: createPersistedSourcePackage(sourceBytes, options.sourceLabel),
-      workflowOverlay: translatedWorkflowState.workflowOverlay,
-      workflowMetadata: translatedWorkflowState.workflowMetadata,
-    });
-    const snapshotIssues = validatePersistedEditorSnapshot(snapshot);
-    if (snapshotIssues.length > 0) {
-      const firstIssue = snapshotIssues[0];
-      return createDiagnosticsSession(
-        options,
-        createValidationImportDiagnostics({
-          message: `DOCX import produced an invalid editor state during validation${firstIssue ? ` (${firstIssue.path}: ${firstIssue.message})` : "."}`,
-          source: "import",
-          details: {
-            issueCount: snapshotIssues.length,
-            firstIssuePath: firstIssue?.path,
-          },
-        }),
-      );
-    }
-    const initialSessionState = editorSessionStateFromPersistedSnapshot(snapshot);
-    const importedState: ImportedDocxState = {
-      sourceBytes: new Uint8Array(sourceBytes),
-      sourcePackage,
-      sourceDocumentXml,
-      sourceDocumentPartPath: mainDocumentPath,
-      sourceDocumentRelationships: documentPart.relationships,
-      sourceDocumentAttributes: extractDocumentRootAttributes(sourceDocumentXml),
-      sourceNumberingPartPath: numberingPartPath,
-      sourceNumberingRelationshipId: documentPart.relationships.find(
-        (relationship) =>
-          relationship.type === NUMBERING_RELATIONSHIP_TYPE &&
-          relationship.targetMode === "internal",
-      )?.id,
-      sourceSettingsPartPath: settingsPartPath,
-      sourceSettingsXml:
-        settingsXmlForProtection.length > 0 ? settingsXmlForProtection : undefined,
-      sourceCommentsPartPath: commentsPartPath,
-      sourceCommentsRelationshipId: documentPart.relationships.find(
-        (relationship) =>
-          relationship.type === COMMENTS_RELATIONSHIP_TYPE &&
-          relationship.targetMode === "internal",
-      )?.id,
-      sourceCommentsRootTag: normalizedComments.sourceRootTag,
-      sourceCommentsExtendedPartPath: commentsExtendedPartPath,
-      sourceCommentsExtendedRelationshipId: documentPart.relationships.find(
-        (relationship) =>
-          relationship.type === COMMENTS_EXTENDED_RELATIONSHIP_TYPE &&
-          relationship.targetMode === "internal",
-      )?.id,
-      sourceCommentsExtendedRootTag: normalizedComments.sourceExtendedRootTag,
-      sourceCommentsIdsPartPath: commentsIdsPartPath,
-      sourceCommentsIdsRelationshipId: documentPart.relationships.find(
-        (relationship) =>
-          relationship.type === COMMENTS_IDS_RELATIONSHIP_TYPE &&
-          relationship.targetMode === "internal",
-      )?.id,
-      sourceCommentsIdsRootTag: normalizedComments.sourceIdsRootTag,
-      sourcePeoplePartPath: peoplePartPath,
-      sourcePeopleRelationshipId: documentPart.relationships.find(
-        (relationship) =>
-          relationship.type === PEOPLE_RELATIONSHIP_TYPE &&
-          relationship.targetMode === "internal",
-      )?.id,
-      sourcePeopleRootTag: normalizedComments.sourcePeopleRootTag,
-      sourcePeopleAuthors: normalizedComments.peopleAuthors,
-      protectionSnapshot: buildProtectionSnapshot(documentProtection, protectionRanges),
-      preservedCommentDefinitions: normalizedComments.preservedDefinitions,
-      blockingCommentDiagnostics: normalizedComments.diagnostics.filter((diagnostic) =>
-        BLOCKING_COMMENT_DIAGNOSTIC_CODES.has(diagnostic.code),
-      ),
-      initialCanonicalSignature: serializeCanonicalDocumentForExport(document),
-      sourceSubPartPaths: {
-        headers: sourceHeaderPaths,
-        footers: sourceFooterPaths,
-        footnotesPartPath,
-        footnotesRelationshipId,
-        endnotesPartPath,
-        endnotesRelationshipId,
-        themePartPath,
-        themeRelationshipId: themeRelationship?.id,
-      },
-    };
-
-    stages.emit("skeleton-ready");
-    return {
-      initialSessionState,
-      initialSnapshot: snapshot,
-      readOnly: false,
-      protectionSnapshot: importedProtectionSnapshot,
-      exportDocx: async (nextSessionState, exportOptions) =>
-        exportDocxEditorSession(importedState, nextSessionState, exportOptions),
-      ...(embeddedWorkflowPayload?.editorState
-        ? { initialEditorStatePayload: embeddedWorkflowPayload.editorState }
-        : {}),
-    };
-  } catch (error) {
-    return createDiagnosticsSession(
-      options,
-      createImportDiagnosticsFromError(error),
-    );
-  }
-}
-
-export interface LoadDocxEditorSessionAsyncOptions extends LoadDocxEditorSessionOptions {
-  /**
-   * Scheduler that the async loader awaits between parse stages. Callers
-   * in DOM environments should construct this with `createLoadScheduler()`
-   * (auto-detects scheduler.yield → MessageChannel → setTimeout backend).
-   * Callers in Node / SSR should pass
-   * `createLoadScheduler({ backendOverride: "sync" })` — sync backend
-   * yields resolve without task-boundary latency, so the async path
-   * behaves like the sync path from the test harness POV.
-   */
-  scheduler: LoadScheduler;
-  /**
-   * L7 Phase 2.5 Plan B B.6b — optional laycache envelope. When supplied,
-   * `loadDocxEditorSessionAsync` still performs the cheap OPC read +
-   * workflow-payload parse (needed for `initialEditorStatePayload`,
-   * `workflowOverlay`, and `workflowMetadata`), then skips the five
-   * expensive stages — `parseMainDocumentXml`,
-   * `normalizeParsedTextDocumentAsync`, `parseCommentsFromOoxml`,
-   * `parseStylesXml`, and `createImportedCanonicalDocument` — and uses
-   * `envelope.canonicalDocument` directly (reference-equal, no clone).
-   *
-   * Callers obtain a validated envelope by calling
-   * `tryReadLaycacheEnvelope(bytes)` before invoking this function; when
-   * the probe returns `null`, omit this field and the loader runs the
-   * full parse.
-   *
-   * Async-only — the sync `loadDocxEditorSession` does not honor this
-   * option. `buildCompatibilityReport` and
-   * `resolveChartPreviewsForDocument` still run on the short-circuit
-   * path because their outputs are required by downstream consumers.
-   */
-  laycacheEnvelope?: CacheEnvelope;
-  /**
-   * L7 Phase 2 Finale C2 — progressive initial mount. When supplied, the
-   * async loader fires this callback exactly once, after the body stage
-   * completes but before styles / sub-parts / compatibility / snapshot
-   * assembly, with a viewport-windowed `EditorSurfaceSnapshot`. The
-   * callback lets UI consumers show the first page's text before the
-   * rest of the load finishes, measurably shrinking perceived cold-open.
-   *
-   * The progressive surface is synthesized from a provisional
-   * `CanonicalDocumentEnvelope`: `content` is the normalized body; all
-   * other catalogs (styles, numbering, media, review, preservation) are
-   * empty. Viewport blocks render live; blocks beyond the viewport
-   * render as placeholders via the existing `cullBuild` flag. Consumers
-   * must treat the progressive surface as provisional — the final
-   * `LoadedDocxEditorSession` (returned from the same `await`) carries
-   * the real styled envelope.
-   *
-   * The callback receives `blocksRealized` (the viewport window size)
-   * and `blocksTotal` (total block count at body-stage time) so the
-   * consumer can size its viewport-commit telemetry.
-   *
-   * Optional. When absent, the async loader does not perform the
-   * provisional-envelope synthesis — no cold-path regression for
-   * consumers that do not opt in.
-   *
-   * Omitted on the Plan B short-circuit path (laycacheEnvelope !== undefined):
-   * the short-circuit is already fast enough that a progressive pre-commit
-   * adds more overhead than it saves.
-   */
-  onProgressiveSnapshot?: (partial: {
-    surface: EditorSurfaceSnapshot;
-    phase: "viewport";
-    blocksRealized: number;
-    blocksTotal: number;
-  }) => void;
-  /**
-   * C3b — deferred chart preview resolution. When supplied, chart preview
-   * rendering (`renderChartPreview()` calls) is removed from the critical
-   * load path: the session returns without chart previews, and this
-   * callback fires later (via requestIdleCallback / setTimeout) with the
-   * CanonicalDocument that has all chart previews resolved. Expected win:
-   * 30–80 ms on extra-large warm-path docs with ~12 charts.
-   *
-   * Consumers that need chart previews on first render should not supply
-   * this callback — the blocking path remains available by omitting it.
-   */
-  onChartPreviewsReady?: (resolvedDoc: CanonicalDocument) => void;
-}
-
-/**
- * Fastload P6: async sibling of {@link loadDocxEditorSession} that yields to
- * the browser between parse stages. Parse sequence is byte-equivalent to
- * the sync path (asserted on every F*.docx fixture in
- * `test/io/fastload-parity.test.ts`). Yields fire at:
- *   1. after OPC read,
- *   2. after `parseMainDocumentXml`,
- *   3. between every header/footer sub-part parse,
- *   4. after footnotes/endnotes parse,
- *   5. after theme + settings + styles parse,
- *   6. after `buildCompatibilityReport`,
- * plus mid-walk yields every 256 blocks inside
- * `normalizeParsedTextDocumentAsync` (stage 3 — body normalize).
- *
- * Sync `loadDocxEditorSession` remains the only entry point for Node tests
- * and SSR. The DOM boundary in `editor-runtime-boundary.ts` calls this
- * async path so the browser can paint the skeleton mid-parse.
- */
-
-/**
- * L7 Phase 2 Finale C2 — progressive initial mount viewport window size.
- *
- * Sized to cover the first page of a typical paginated document (~20
- * body blocks = ~1 page on CCEP-scale templates at default margins). The
- * window is intentionally small so the provisional-envelope synthesis +
- * surface projection stays under ~30 ms — making `firstViewportCommit`
- * significantly faster than the full load.
- *
- * Blocks beyond this window render as `placeholder-culled` entries via
- * Phase 2.9's cullBuild flag (auto-derived from `!isInViewport`) — they
- * preserve `from`/`to` offsets for selection stability while costing ~0
- * style-cascade work.
- */
-const PROGRESSIVE_VIEWPORT_BLOCKS = 20;
-
-export async function loadDocxEditorSessionAsync(
-  options: LoadDocxEditorSessionAsyncOptions,
-): Promise<LoadedDocxEditorSession> {
-  const { scheduler } = options;
-  const editorBuild =
-    typeof options.editorBuild === "string" && options.editorBuild.length > 0
-      ? options.editorBuild
-      : "dev";
-  const sourceBytes = toUint8Array(options.bytes);
-
-  const stages = createStageEmitter(options.onLoadStage);
-
-  let sourcePackage: OpcPackage;
-
-  try {
-    sourcePackage = readOpcPackage(sourceBytes);
-  } catch (error) {
-    return createDiagnosticsSession(
-      options,
-      createPackageImportDiagnostics({
-        issue: classifyCorruptPackageError(error),
-      }),
-    );
-  }
-  stages.emit("opc");
-  await scheduler.yield();
-  const embeddedWorkflowPayload = parseWorkflowPayloadEnvelopeFromPackage(sourcePackage);
-  const embeddedWorkflowMetadata = embeddedWorkflowPayload?.workflowMetadata;
-  const embeddedWorkflowOverlay = embeddedWorkflowPayload?.workflowOverlay;
-
-  const mainDocumentPath = resolveMainDocumentPartPath(sourcePackage);
-  const brokenRelationshipIssues = collectBrokenInternalRelationshipIssues(
-    sourcePackage,
-    mainDocumentPath,
-  );
-  if (brokenRelationshipIssues.length > 0) {
-    return createDiagnosticsSession(
-      options,
-      createPackageImportDiagnostics({
-        issue: {
-          ...brokenRelationshipIssues[0],
-          message: summarizeBrokenRelationshipIssues(brokenRelationshipIssues),
-          details: {
-            issueCount: brokenRelationshipIssues.length,
-            targets: brokenRelationshipIssues.map((issue) => issue.targetPartPath).filter(Boolean),
-          },
-        },
-      }),
-    );
-  }
-
-  if (!mainDocumentPath) {
-    return createDiagnosticsSession(
-      options,
-      createPackageImportDiagnostics({
-        issue: createMissingPartIssue(MAIN_DOCUMENT_PATH),
-      }),
-    );
-  }
-
-  const documentPart = sourcePackage.parts.get(mainDocumentPath);
-  if (!documentPart) {
-    return createDiagnosticsSession(
-      options,
-      createPackageImportDiagnostics({
-        issue: createMissingPartIssue(mainDocumentPath),
-      }),
-    );
-  }
-  if (documentPart.contentType !== MAIN_DOCUMENT_CONTENT_TYPE) {
-    return createDiagnosticsSession(
-      options,
-      createValidationImportDiagnostics({
-        message: `DOCX main document part ${mainDocumentPath} must use content type ${MAIN_DOCUMENT_CONTENT_TYPE}.`,
-      }),
-    );
-  }
-
-  try {
-    // L7 Phase 2.5 Plan B B.6b — loader short-circuit. Hand
-    // `envelope.canonicalDocument` through reference-equal and skip the
-    // five expensive parse stages. The four `onLoadStage` callbacks still
-    // fire in order — `body` and `styles-numbering-comments` emit with
-    // near-zero duration — so host progress bars are unaffected.
-    if (options.laycacheEnvelope) {
-      stages.emit("body");
-      stages.emit("styles-numbering-comments");
-
-      const canonicalDocument = options.laycacheEnvelope.canonicalDocument;
-
-      // `extractProtectionRanges` needs `parsedDocument.blocks` (which we
-      // are skipping), so the short-circuit uses an empty ranges list;
-      // document-level `editType` / `enforcement` still come from
-      // settings.xml so read-only docs stay read-only.
-      const settingsPartPath = resolveDocumentRelatedPartPath(
-        sourcePackage,
-        mainDocumentPath,
-        documentPart.relationships,
-        SETTINGS_RELATIONSHIP_TYPE,
-        SETTINGS_PART_PATH,
-      );
-      const settingsXml =
-        settingsPartPath && sourcePackage.parts.has(settingsPartPath)
-          ? decodeUtf8(
-              sourcePackage.parts.get(settingsPartPath)?.bytes ?? new Uint8Array(),
-            )
-          : "";
-      const documentProtection = extractDocumentProtection(settingsXml);
-      const protectionSnapshot = buildProtectionSnapshot(documentProtection, []);
-
-      // Chart previews (`previewMediaId` is host-dependent) aren't cached
-      // in the envelope. C3b: when onChartPreviewsReady is provided, defer
-      // resolution out of the critical path. Otherwise block (legacy behavior).
-      let documentWithChartPreviews: CanonicalDocumentEnvelope;
-      if (options.onChartPreviewsReady) {
-        scheduleChartPreviewResolution(
-          canonicalDocument,
-          sourcePackage,
-          options.hostAdapter,
-          options.onChartPreviewsReady,
-        );
-        documentWithChartPreviews = canonicalDocument as CanonicalDocumentEnvelope;
-      } else {
-        documentWithChartPreviews = (await resolveChartPreviewsForDocument(
-          canonicalDocument,
-          sourcePackage,
-          options.hostAdapter,
-        )) as CanonicalDocumentEnvelope;
-      }
-
-      const timestamp = new Date().toISOString();
-      // Phase 2 Finale C3: skip `buildCompatibilityReport` (60–100 ms on
-      // extra-large) when the envelope carries a pre-computed report.
-      // Pure-function determinism of the report is enforced by
-      // `canonicalDocumentHash` (5th input to `deriveCacheKey`): any
-      // change to the canonical doc flips the hash and rejects the
-      // envelope on load.
-      //
-      // The cached report's `generatedAt` is a fixed sentinel
-      // (`CACHE_NORMALIZED_GENERATED_AT`) for envelope byte-identity.
-      // Swap it for the live ISO8601 timestamp here because downstream
-      // `validatePersistedEditorSnapshot` requires
-      // `$.compatibility.generatedAt` to be ISO 8601.
-      const cachedReport = options.laycacheEnvelope?.compatibilityReport;
-      const compatibility = cachedReport
-        ? { ...cachedReport, generatedAt: timestamp }
-        : buildCompatibilityReport({
-            document: documentWithChartPreviews,
-            generatedAt: timestamp,
-          });
-      await scheduler.yield();
-
-      const snapshot = createImportedSnapshot({
-        documentId: options.documentId,
-        editorBuild,
-        timestamp,
-        document: documentWithChartPreviews,
-        compatibility: toPublicCompatibilityReport(compatibility),
-        protectionSnapshot,
-        sourcePackage: createPersistedSourcePackage(sourceBytes, options.sourceLabel),
-        workflowOverlay: embeddedWorkflowOverlay,
-        workflowMetadata: embeddedWorkflowMetadata,
-      });
-      const snapshotIssues = validatePersistedEditorSnapshot(snapshot);
-      if (snapshotIssues.length > 0) {
-        const firstIssue = snapshotIssues[0];
-        return createDiagnosticsSession(
-          options,
-          createValidationImportDiagnostics({
-            message: `DOCX import produced an invalid editor state during validation${firstIssue ? ` (${firstIssue.path}: ${firstIssue.message})` : "."}`,
-            source: "import",
-            details: {
-              issueCount: snapshotIssues.length,
-              firstIssuePath: firstIssue?.path,
-            },
-          }),
-        );
-      }
-
-      // Build `initialSessionState` inline — bypassing
-      // `editorSessionStateFromPersistedSnapshot`'s structuredClone so
-      // `session.initialSessionState.canonicalDocument` is reference-equal
-      // to `envelope.canonicalDocument` (cloning a large canonical document
-      // defeats part of the cache gain).
-      const sessionState: EditorSessionState = {
-        sessionVersion: "editor-session-state/1",
-        schemaVersion: snapshot.schemaVersion,
-        documentId: snapshot.documentId,
-        docId: snapshot.docId,
-        createdAt: snapshot.createdAt,
-        updatedAt: snapshot.updatedAt,
-        editorBuild: snapshot.editorBuild,
-        canonicalDocument: snapshot.canonicalDocument,
-        compatibility: snapshot.compatibility,
-        warningLog: snapshot.warningLog,
-        protectionSnapshot: snapshot.protectionSnapshot,
-        sourcePackage: snapshot.sourcePackage,
-        workflowOverlay: snapshot.workflowOverlay,
-        workflowMetadata: snapshot.workflowMetadata,
-      };
-
-      // The short-circuit path does not carry an `ImportedDocxState`, so
-      // `exportDocx` lazily re-runs the cold path on first invocation and
-      // memoizes. Keeps the warm-load fast while preserving byte-exact
-      // export correctness.
-      let lazyColdExport: LoadedDocxEditorSession["exportDocx"] | undefined;
-      const exportDocx: LoadedDocxEditorSession["exportDocx"] = async (
-        nextSessionStateOrSnapshot,
-        exportOptions,
-      ) => {
-        if (!lazyColdExport) {
-          const { laycacheEnvelope: _unused, ...coldOptions } = options;
-          void _unused;
-          const coldSession = await loadDocxEditorSessionAsync(coldOptions);
-          if (coldSession.fatalError) {
-            throw new Error(
-              `DOCX export via short-circuit fallback failed cold load: ${coldSession.fatalError.message ?? "fatal error"}`,
-            );
-          }
-          lazyColdExport = coldSession.exportDocx;
-        }
-        return lazyColdExport(nextSessionStateOrSnapshot, exportOptions);
-      };
-
-      stages.emit("skeleton-ready");
-      return {
-        initialSessionState: sessionState,
-        initialSnapshot: snapshot,
-        readOnly: false,
-        protectionSnapshot,
-        exportDocx,
-        ...(embeddedWorkflowPayload?.editorState
-          ? { initialEditorStatePayload: embeddedWorkflowPayload.editorState }
-          : {}),
-      };
-    }
-
-    const sourceDocumentXml = decodeUtf8(documentPart.bytes);
-    const importedRevisions = parseRevisionsFromDocumentXml(sourceDocumentXml);
-    const numberingPartPath = resolveDocumentRelatedPartPath(
-      sourcePackage,
-      mainDocumentPath,
-      documentPart.relationships,
-      NUMBERING_RELATIONSHIP_TYPE,
-      NUMBERING_PART_PATH,
-    );
-    const parsedNumbering = numberingPartPath
-      ? parseNumberingXml(
-          decodeUtf8(sourcePackage.parts.get(numberingPartPath)?.bytes ?? new Uint8Array()),
-          {
-            relationships: sourcePackage.parts.get(numberingPartPath)?.relationships,
-            partPath: numberingPartPath,
-          },
-        )
-      : createEmptyNumberingCatalog();
-    const mediaParts = collectInlineMediaParts(sourcePackage);
-    const chartPartLookup = createChartPartLookup(
-      sourcePackage,
-      mainDocumentPath,
-      documentPart.relationships,
-    );
-    const parsedDocument = parseMainDocumentXml(
-      sourceDocumentXml,
-      documentPart.relationships,
-      mediaParts,
-      mainDocumentPath,
-      chartPartLookup,
-    );
-    await scheduler.yield();
-    const protectionRanges = extractProtectionRanges(parsedDocument.blocks);
-    const normalizedDocument = await normalizeParsedTextDocumentAsync(
-      parsedDocument,
-      mainDocumentPath,
-      scheduler,
-    );
-    stages.emit("body");
-    await scheduler.yield();
-
-    // L7 Phase 2 Finale C2 — progressive initial mount.
-    //
-    // Fire `onProgressiveSnapshot` exactly once, after the body stage and
-    // its post-yield. At this point `normalizedDocument.content` carries
-    // the full block tree with per-block runProperties already resolved
-    // during `normalizeParsedTextDocumentAsync`. We synthesize a
-    // throw-away `CanonicalDocumentEnvelope` using the normalized content
-    // + empty style/review/preservation catalogs, then project a
-    // viewport-windowed `EditorSurfaceSnapshot` (first `PROGRESSIVE_VIEWPORT_BLOCKS`
-    // blocks real, rest as culled placeholders via the Phase 2.9 flag).
-    //
-    // The bench's measured signal: time from `loadDocxEditorSessionAsync`
-    // entry to this callback's fire is `firstViewportCommitMs` — the
-    // metric C2 gates on.
-    //
-    // Skipped on the Plan B short-circuit: `laycacheEnvelope !== undefined`
-    // already completes ~376 ms faster than cold — adding a progressive
-    // synthesis on top costs more than it saves. The short-circuit path
-    // returns the real snapshot fast enough.
-    if (
-      options.onProgressiveSnapshot !== undefined &&
-      options.laycacheEnvelope === undefined
-    ) {
-      const provisionalDoc: CanonicalDocumentEnvelope = {
-        ...createDefaultCanonicalDocument(
-          options.documentId,
-          new Date().toISOString(),
-        ),
-        content: normalizedDocument.content,
-      };
-      const blocksTotal = normalizedDocument.content.children.length;
-      const blocksRealized = Math.min(
-        PROGRESSIVE_VIEWPORT_BLOCKS,
-        blocksTotal,
-      );
-      const progressiveSurface = createEditorSurfaceSnapshot(
-        provisionalDoc,
-        createSelectionSnapshot(0, 0),
-        MAIN_STORY_TARGET,
-        blocksRealized < blocksTotal
-          ? { viewportBlockRange: { start: 0, end: blocksRealized } }
-          : undefined,
-      );
-      try {
-        options.onProgressiveSnapshot({
-          surface: progressiveSurface,
-          phase: "viewport",
-          blocksRealized,
-          blocksTotal,
-        });
-      } catch {
-        // A throwing consumer must not abort the load. Progressive is
-        // a best-effort optimization; errors on the callback side
-        // silently fall through to the normal full-commit path.
-      }
-    }
-
-    const commentsPartPath = resolveCommentsPartPath(
-      sourcePackage,
-      mainDocumentPath,
-      documentPart.relationships,
-    );
-    const commentsExtendedPartPath = resolveDocumentRelatedPartPath(
-      sourcePackage,
-      mainDocumentPath,
-      documentPart.relationships,
-      COMMENTS_EXTENDED_RELATIONSHIP_TYPE,
-      COMMENTS_EXTENDED_PART_PATH,
-    );
-    const commentsIdsPartPath = resolveDocumentRelatedPartPath(
-      sourcePackage,
-      mainDocumentPath,
-      documentPart.relationships,
-      COMMENTS_IDS_RELATIONSHIP_TYPE,
-      COMMENTS_IDS_PART_PATH,
-    );
-    const peoplePartPath = resolveDocumentRelatedPartPath(
-      sourcePackage,
-      mainDocumentPath,
-      documentPart.relationships,
-      PEOPLE_RELATIONSHIP_TYPE,
-      PEOPLE_PART_PATH,
-    );
-    const parsedComments = commentsPartPath
-      ? parseCommentsFromOoxml(
-          sourceDocumentXml,
-          {
-            commentsXml: decodeUtf8(sourcePackage.parts.get(commentsPartPath)?.bytes ?? new Uint8Array()),
-            commentsExtendedXml: decodeUtf8(
-              sourcePackage.parts.get(commentsExtendedPartPath ?? "")?.bytes ?? new Uint8Array(),
-            ),
-            commentsIdsXml: decodeUtf8(
-              sourcePackage.parts.get(commentsIdsPartPath ?? "")?.bytes ?? new Uint8Array(),
-            ),
-            peopleXml: decodeUtf8(
-              sourcePackage.parts.get(peoplePartPath ?? "")?.bytes ?? new Uint8Array(),
-            ),
-          },
-        )
-      : {
-          threads: [] as CommentThread[],
-          diagnostics: [] as CommentImportDiagnostic[],
-          definitions: [] as ImportedCommentDefinition[],
-          sourceRootTag: undefined,
-          sourceExtendedRootTag: undefined,
-          sourceIdsRootTag: undefined,
-          sourcePeopleRootTag: undefined,
-          peopleAuthors: [] as string[],
-        };
-    const normalizedRevisions = normalizeImportedRevisionRecords(
-      importedRevisions,
-      normalizedDocument.content,
-      normalizedDocument.preservation.opaqueFragments,
-    );
-    const normalizedComments = normalizeImportedCommentThreads(
-      parsedComments,
-      normalizedDocument.preservation.opaqueFragments,
-      normalizedRevisions.revisions,
-    );
-    stages.emit("styles-numbering-comments");
-    const importedStoryRevisions: ReviewRevisionRecord[] = [];
-    const importedStoryRevisionDiagnostics: ParsedRevisionsResult["diagnostics"] = [];
-    const subPartOpaqueState = createSubPartOpaqueImportState(
-      normalizedDocument.preservation.opaqueFragments,
-      normalizedDocument.diagnostics.warnings,
-    );
-    // ---- Parse sub-parts: headers, footers, footnotes, endnotes, theme ----
-    const headerFooterRefs = parseHeaderFooterReferences(sourceDocumentXml);
-    const parsedHeaders: HeaderDocument[] = [];
-    const parsedFooters: FooterDocument[] = [];
-    const sourceHeaderPaths: Array<{ partPath: string; relationshipId: string }> = [];
-    const sourceFooterPaths: Array<{ partPath: string; relationshipId: string }> = [];
-    const seenSubPartKeys = new Set<string>();
-
-    for (const ref of headerFooterRefs) {
-      const dedupeKey = `${ref.kind}:${ref.variant}:${ref.relationshipId}`;
-      if (seenSubPartKeys.has(dedupeKey)) {
-        continue;
-      }
-      seenSubPartKeys.add(dedupeKey);
-
-      const relationship = documentPart.relationships.find(
-        (r) => r.id === ref.relationshipId && r.targetMode === "internal",
-      );
-      if (!relationship) {
-        continue;
-      }
-
-      const partPath = resolveRelationshipTarget(mainDocumentPath, relationship);
-      const part = sourcePackage.parts.get(partPath);
-      const partBytes = part?.bytes;
-      if (!partBytes) {
-        continue;
-      }
-
-      await scheduler.yield();
-      const xml = decodeUtf8(partBytes);
-      const subPartRelationships = part?.relationships ?? [];
-      const subPartChartPartLookup = createChartPartLookup(
-        sourcePackage,
-        partPath,
-        subPartRelationships,
-      );
-      if (ref.kind === "header") {
-        const parsedHeaderRevisions = parseRevisionsFromStoryXml(xml);
-        const parsed = parseHeaderXml(xml, {
-          relationships: subPartRelationships,
-          mediaParts,
-          sourcePartPath: partPath,
-          chartPartLookup: subPartChartPartLookup,
-        });
-        parsedHeaders.push({
-          variant: ref.variant,
-          partPath,
-          relationshipId: ref.relationshipId,
-          ...(ref.sectionIndex !== undefined ? { sectionIndex: ref.sectionIndex } : {}),
-          blocks: normalizeSubPartOpaqueBlocks(
-            parsed.blocks,
-            normalizedDocument.preservation.opaqueFragments,
-            normalizedDocument.diagnostics.warnings,
-            partPath,
-            subPartOpaqueState,
-          ),
-        });
-        importedStoryRevisions.push(
-          ...parsedHeaderRevisions.revisions.map((revision): ReviewRevisionRecord => ({
-            ...revision,
-            metadata: {
-              ...revision.metadata,
-              storyTarget: {
-                kind: "header" as const,
-                relationshipId: ref.relationshipId,
-                variant: ref.variant,
-                ...(ref.sectionIndex !== undefined ? { sectionIndex: ref.sectionIndex } : {}),
-              },
-            },
-          })),
-        );
-        importedStoryRevisionDiagnostics.push(...parsedHeaderRevisions.diagnostics);
-        sourceHeaderPaths.push({ partPath, relationshipId: ref.relationshipId });
-      } else {
-        const parsedFooterRevisions = parseRevisionsFromStoryXml(xml);
-        const parsed = parseFooterXml(xml, {
-          relationships: subPartRelationships,
-          mediaParts,
-          sourcePartPath: partPath,
-          chartPartLookup: subPartChartPartLookup,
-        });
-        parsedFooters.push({
-          variant: ref.variant,
-          partPath,
-          relationshipId: ref.relationshipId,
-          ...(ref.sectionIndex !== undefined ? { sectionIndex: ref.sectionIndex } : {}),
-          blocks: normalizeSubPartOpaqueBlocks(
-            parsed.blocks,
-            normalizedDocument.preservation.opaqueFragments,
-            normalizedDocument.diagnostics.warnings,
-            partPath,
-            subPartOpaqueState,
-          ),
-        });
-        importedStoryRevisions.push(
-          ...parsedFooterRevisions.revisions.map((revision): ReviewRevisionRecord => ({
-            ...revision,
-            metadata: {
-              ...revision.metadata,
-              storyTarget: {
-                kind: "footer" as const,
-                relationshipId: ref.relationshipId,
-                variant: ref.variant,
-                ...(ref.sectionIndex !== undefined ? { sectionIndex: ref.sectionIndex } : {}),
-              },
-            },
-          })),
-        );
-        importedStoryRevisionDiagnostics.push(...parsedFooterRevisions.diagnostics);
-        sourceFooterPaths.push({ partPath, relationshipId: ref.relationshipId });
-      }
-    }
-
-    const footnotesPartPath = resolveDocumentRelatedPartPath(
-      sourcePackage,
-      mainDocumentPath,
-      documentPart.relationships,
-      FOOTNOTES_RELATIONSHIP_TYPE,
-      FOOTNOTES_PART_PATH,
-    );
-    const footnotesRelationshipId = documentPart.relationships.find(
-      (r) => r.type === FOOTNOTES_RELATIONSHIP_TYPE && r.targetMode === "internal",
-    )?.id;
-    const endnotesPartPath = resolveDocumentRelatedPartPath(
-      sourcePackage,
-      mainDocumentPath,
-      documentPart.relationships,
-      ENDNOTES_RELATIONSHIP_TYPE,
-      ENDNOTES_PART_PATH,
-    );
-    const endnotesRelationshipId = documentPart.relationships.find(
-      (r) => r.type === ENDNOTES_RELATIONSHIP_TYPE && r.targetMode === "internal",
-    )?.id;
-
-    let footnoteCollection: FootnoteCollection | undefined;
-    if (footnotesPartPath) {
-      footnoteCollection = parseFootnotesXml(
-        decodeUtf8(sourcePackage.parts.get(footnotesPartPath)?.bytes ?? new Uint8Array()),
-      );
-      normalizeFootnoteCollectionOpaqueBlocks(
-        footnoteCollection,
-        "footnote",
-        normalizedDocument.preservation.opaqueFragments,
-        normalizedDocument.diagnostics.warnings,
-        footnotesPartPath,
-        subPartOpaqueState,
-      );
-    }
-    if (endnotesPartPath) {
-      footnoteCollection = parseEndnotesXml(
-        decodeUtf8(sourcePackage.parts.get(endnotesPartPath)?.bytes ?? new Uint8Array()),
-        footnoteCollection,
-      );
-      normalizeFootnoteCollectionOpaqueBlocks(
-        footnoteCollection,
-        "endnote",
-        normalizedDocument.preservation.opaqueFragments,
-        normalizedDocument.diagnostics.warnings,
-        endnotesPartPath,
-        subPartOpaqueState,
-      );
-    }
-    await scheduler.yield();
-
-    const themeRelationship = documentPart.relationships.find(
-      (r) => r.type === "http://schemas.openxmlformats.org/officeDocument/2006/relationships/theme" &&
-        r.targetMode === "internal",
-    );
-    const themePartPath = themeRelationship
-      ? resolveRelationshipTarget(mainDocumentPath, themeRelationship)
-      : undefined;
-    const parsedTheme =
-      themePartPath && sourcePackage.parts.has(themePartPath)
-        ? parseThemeXml(
-            decodeUtf8(sourcePackage.parts.get(themePartPath)?.bytes ?? new Uint8Array()),
-          )
-        : undefined;
-    const resolvedTheme = parsedTheme ? resolveTheme(parsedTheme) : undefined;
-    const settingsPartPath = resolveDocumentRelatedPartPath(
-      sourcePackage,
-      mainDocumentPath,
-      documentPart.relationships,
-      SETTINGS_RELATIONSHIP_TYPE,
-      SETTINGS_PART_PATH,
-    );
-    const parsedSettings =
-      settingsPartPath && sourcePackage.parts.has(settingsPartPath)
-        ? parseSettingsXml(
-            decodeUtf8(sourcePackage.parts.get(settingsPartPath)?.bytes ?? new Uint8Array()),
-          )
-        : undefined;
-    const canonicalTheme =
-      parsedTheme !== undefined
-        ? materializeCanonicalTheme(
-            parsedTheme,
-            parsedSettings?.clrSchemeMapping ?? {},
-          )
-        : undefined;
-    const settingsXmlForProtection =
-      settingsPartPath && sourcePackage.parts.has(settingsPartPath)
-        ? decodeUtf8(sourcePackage.parts.get(settingsPartPath)?.bytes ?? new Uint8Array())
-        : "";
-    const documentProtection = extractDocumentProtection(settingsXmlForProtection);
-    const importedProtectionSnapshot = buildProtectionSnapshot(documentProtection, protectionRanges);
-
-    // ---- Parse styles.xml for canonical style catalog ----
-    const stylesPartPath = resolveDocumentRelatedPartPath(
-      sourcePackage,
-      mainDocumentPath,
-      documentPart.relationships,
-      STYLES_RELATIONSHIP_TYPE,
-      STYLES_PART_PATH,
-    );
-    const parsedStyles =
-      stylesPartPath && sourcePackage.parts.has(stylesPartPath)
-        ? parseStylesXml(
-            decodeUtf8(sourcePackage.parts.get(stylesPartPath)?.bytes ?? new Uint8Array()),
-          )
-        : parseStylesXml("");
-    await scheduler.yield();
-
-    // ---- Parse fontTable.xml for canonical font catalog ----
-    const fontTablePartPath = resolveDocumentRelatedPartPath(
-      sourcePackage,
-      mainDocumentPath,
-      documentPart.relationships,
-      FONT_TABLE_RELATIONSHIP_TYPE,
-      FONT_TABLE_PART_PATH,
-    );
-    const parsedFontTable =
-      fontTablePartPath && sourcePackage.parts.has(fontTablePartPath)
-        ? parseFontTable(
-            decodeUtf8(sourcePackage.parts.get(fontTablePartPath)?.bytes ?? new Uint8Array()),
-          )
-        : undefined;
-
-    const mergedMedia = mergeSecondaryStoryMediaCatalog(normalizedDocument.media, {
-      headers: parsedHeaders,
-      footers: parsedFooters,
-      footnoteCollection,
-      mediaParts,
-    });
-
-    const subParts: SubPartsCatalog | undefined =
-      parsedHeaders.length > 0 ||
-      parsedFooters.length > 0 ||
-      footnoteCollection !== undefined ||
-      parsedTheme !== undefined ||
-      normalizedDocument.finalSectionProperties !== undefined ||
-      resolvedTheme !== undefined ||
-      canonicalTheme !== undefined ||
-      parsedSettings !== undefined
-        ? {
-            headers: parsedHeaders,
-            footers: parsedFooters,
-            ...(footnoteCollection !== undefined ? { footnoteCollection } : {}),
-            ...(parsedTheme !== undefined ? { theme: parsedTheme } : {}),
-            ...(normalizedDocument.finalSectionProperties !== undefined
-              ? { finalSectionProperties: normalizedDocument.finalSectionProperties }
-              : {}),
-            ...(resolvedTheme !== undefined ? { resolvedTheme } : {}),
-            ...(canonicalTheme !== undefined ? { canonicalTheme } : {}),
-            ...(parsedSettings !== undefined ? { settings: parsedSettings } : {}),
-          }
-        : undefined;
-
-    const timestamp = new Date().toISOString();
-    const translatedWorkflowState = translateClmCommentsToWorkflow({
-      comments: normalizedComments.threads,
-      workflowOverlay: embeddedWorkflowOverlay,
-      workflowMetadata: embeddedWorkflowMetadata,
-      timestamp,
-    });
-    const importedDocument = createImportedCanonicalDocument({
-      documentId: options.documentId,
-      timestamp,
-      numbering: parsedNumbering,
-      media: mergedMedia,
-      content: normalizedDocument.content,
-      subParts,
-      parsedStyles,
-      fontTable: parsedFontTable,
-      preservation: {
-        ...normalizedDocument.preservation,
-        packageParts: {
-          ...normalizedDocument.preservation.packageParts,
-          ...collectPreservedPackageParts(sourcePackage, [
-            mainDocumentPath,
-            numberingPartPath,
-            commentsPartPath,
-            commentsExtendedPartPath,
-            commentsIdsPartPath,
-            peoplePartPath,
-          ]),
-        },
-      },
-      diagnostics: {
-        warnings: [
-          ...createBrokenRelationshipWarnings(sourcePackage, mainDocumentPath),
-          ...normalizedDocument.diagnostics.warnings,
-          ...normalizedRevisions.diagnostics.map((diagnostic, index) => ({
-            diagnosticId: `diagnostic:revision-import-${index + 1}`,
-            warningId: `warning:revision-import-${diagnostic.revisionId}`,
-            source: "review" as const,
-            message: diagnostic.message,
-          })),
-          ...importedStoryRevisionDiagnostics.map((diagnostic, index) => ({
-            diagnosticId: `diagnostic:story-revision-import-${index + 1}`,
-            warningId: `warning:story-revision-import-${diagnostic.revisionId}`,
-            source: "review" as const,
-            message: diagnostic.message,
-          })),
-          ...normalizedComments.diagnostics.map((diagnostic, index) => ({
-            diagnosticId: `diagnostic:comment-import-${index + 1}`,
-            warningId: `warning:comment-import-${diagnostic.commentId}`,
-            source: "review" as const,
-            message: diagnostic.message,
-          })),
-        ],
-        errors: [],
-      },
-      review: {
-        comments: toRuntimeCommentRecords(translatedWorkflowState.comments),
-        revisions: toRuntimeRevisionRecords([
-          ...normalizedRevisions.revisions,
-          ...importedStoryRevisions,
-        ]),
-      },
-    });
-    // Stage 0B.1: if the host implements `renderChartPreview`, resolve
-    // chart_preview nodes inline so the first snapshot already carries the
-    // synthesized `previewMediaId`. Fallback-safe: returning null or throwing
-    // is per-chart — the typed badge renders as if the adapter weren't set.
-    // C3b: when onChartPreviewsReady is provided, defer resolution out of
-    // the critical path (same pattern as the short-circuit branch above).
-    let document: CanonicalDocumentEnvelope;
-    if (options.onChartPreviewsReady) {
-      scheduleChartPreviewResolution(
-        importedDocument,
-        sourcePackage,
-        options.hostAdapter,
-        options.onChartPreviewsReady,
-      );
-      document = importedDocument as CanonicalDocumentEnvelope;
-    } else {
-      document = (await resolveChartPreviewsForDocument(
-        importedDocument,
-        sourcePackage,
-        options.hostAdapter,
-      )) as CanonicalDocumentEnvelope;
-    }
-    const compatibility = buildCompatibilityReport({
-      document,
-      generatedAt: timestamp,
-    });
-    await scheduler.yield();
-    const snapshot = createImportedSnapshot({
-      documentId: options.documentId,
-      editorBuild,
-      timestamp,
-      document,
-      compatibility: toPublicCompatibilityReport(compatibility),
-      protectionSnapshot: importedProtectionSnapshot,
-      sourcePackage: createPersistedSourcePackage(sourceBytes, options.sourceLabel),
-      workflowOverlay: translatedWorkflowState.workflowOverlay,
-      workflowMetadata: translatedWorkflowState.workflowMetadata,
-    });
-    const snapshotIssues = validatePersistedEditorSnapshot(snapshot);
-    if (snapshotIssues.length > 0) {
-      const firstIssue = snapshotIssues[0];
-      return createDiagnosticsSession(
-        options,
-        createValidationImportDiagnostics({
-          message: `DOCX import produced an invalid editor state during validation${firstIssue ? ` (${firstIssue.path}: ${firstIssue.message})` : "."}`,
-          source: "import",
-          details: {
-            issueCount: snapshotIssues.length,
-            firstIssuePath: firstIssue?.path,
-          },
-        }),
-      );
-    }
-    const initialSessionState = editorSessionStateFromPersistedSnapshot(snapshot);
-    const importedState: ImportedDocxState = {
-      sourceBytes: new Uint8Array(sourceBytes),
-      sourcePackage,
-      sourceDocumentXml,
-      sourceDocumentPartPath: mainDocumentPath,
-      sourceDocumentRelationships: documentPart.relationships,
-      sourceDocumentAttributes: extractDocumentRootAttributes(sourceDocumentXml),
-      sourceNumberingPartPath: numberingPartPath,
-      sourceNumberingRelationshipId: documentPart.relationships.find(
-        (relationship) =>
-          relationship.type === NUMBERING_RELATIONSHIP_TYPE &&
-          relationship.targetMode === "internal",
-      )?.id,
-      sourceSettingsPartPath: settingsPartPath,
-      sourceSettingsXml:
-        settingsXmlForProtection.length > 0 ? settingsXmlForProtection : undefined,
-      sourceCommentsPartPath: commentsPartPath,
-      sourceCommentsRelationshipId: documentPart.relationships.find(
-        (relationship) =>
-          relationship.type === COMMENTS_RELATIONSHIP_TYPE &&
-          relationship.targetMode === "internal",
-      )?.id,
-      sourceCommentsRootTag: normalizedComments.sourceRootTag,
-      sourceCommentsExtendedPartPath: commentsExtendedPartPath,
-      sourceCommentsExtendedRelationshipId: documentPart.relationships.find(
-        (relationship) =>
-          relationship.type === COMMENTS_EXTENDED_RELATIONSHIP_TYPE &&
-          relationship.targetMode === "internal",
-      )?.id,
-      sourceCommentsExtendedRootTag: normalizedComments.sourceExtendedRootTag,
-      sourceCommentsIdsPartPath: commentsIdsPartPath,
-      sourceCommentsIdsRelationshipId: documentPart.relationships.find(
-        (relationship) =>
-          relationship.type === COMMENTS_IDS_RELATIONSHIP_TYPE &&
-          relationship.targetMode === "internal",
-      )?.id,
-      sourceCommentsIdsRootTag: normalizedComments.sourceIdsRootTag,
-      sourcePeoplePartPath: peoplePartPath,
-      sourcePeopleRelationshipId: documentPart.relationships.find(
-        (relationship) =>
-          relationship.type === PEOPLE_RELATIONSHIP_TYPE &&
-          relationship.targetMode === "internal",
-      )?.id,
-      sourcePeopleRootTag: normalizedComments.sourcePeopleRootTag,
-      sourcePeopleAuthors: normalizedComments.peopleAuthors,
-      protectionSnapshot: buildProtectionSnapshot(documentProtection, protectionRanges),
-      preservedCommentDefinitions: normalizedComments.preservedDefinitions,
-      blockingCommentDiagnostics: normalizedComments.diagnostics.filter((diagnostic) =>
-        BLOCKING_COMMENT_DIAGNOSTIC_CODES.has(diagnostic.code),
-      ),
-      initialCanonicalSignature: serializeCanonicalDocumentForExport(document),
-      sourceSubPartPaths: {
-        headers: sourceHeaderPaths,
-        footers: sourceFooterPaths,
-        footnotesPartPath,
-        footnotesRelationshipId,
-        endnotesPartPath,
-        endnotesRelationshipId,
-        themePartPath,
-        themeRelationshipId: themeRelationship?.id,
-      },
-    };
-
-    stages.emit("skeleton-ready");
-    return {
-      initialSessionState,
-      initialSnapshot: snapshot,
-      readOnly: false,
-      protectionSnapshot: importedProtectionSnapshot,
-      exportDocx: async (nextSessionState, exportOptions) =>
-        exportDocxEditorSession(importedState, nextSessionState, exportOptions),
-      ...(embeddedWorkflowPayload?.editorState
-        ? { initialEditorStatePayload: embeddedWorkflowPayload.editorState }
-        : {}),
-    };
-  } catch (error) {
-    return createDiagnosticsSession(
-      options,
-      createImportDiagnosticsFromError(error),
-    );
-  }
-}
-
-function loadStageNow(): number {
-  return typeof performance !== "undefined" && typeof performance.now === "function"
-    ? performance.now()
-    : Date.now();
-}
-
-function exportDocxEditorSession(
-  state: ImportedDocxState,
-  sessionStateOrSnapshot: EditorSessionState | PersistedEditorSnapshot,
-  options?: ExportDocxOptions,
-): ExportResult {
-  const sessionState = toEditorSessionState(sessionStateOrSnapshot);
-
-  if (sessionState.compatibility.blockExport) {
-    throw new Error("DOCX export is blocked by the current compatibility report.");
-  }
-
-  const currentDocument = sessionState.canonicalDocument as CanonicalDocumentEnvelope;
-  const signatureMatch = serializeCanonicalDocumentForExport(currentDocument) ===
-      state.initialCanonicalSignature;
-  const canReuse = canReuseSourceBytesForCurrentDocument(state, currentDocument);
-  const durableWorkflowMetadata = getDocumentBackedWorkflowMetadata(sessionState.workflowMetadata);
-  const hasWorkflowOverlay = Boolean(sessionState.workflowOverlay);
-  const sourceHasWorkflowPayload = resolvePayloadPartPath(state.sourcePackage) !== null;
-  const commentCount = Object.keys(currentDocument.review?.comments ?? {}).length;
-  const currentRevisions = toReviewRevisionRecords(currentDocument.review.revisions);
-  const hasActiveImportedPreserveOnlyRevisions = currentRevisions.some(
-    (revision) =>
-      revision.status === "active" &&
-      revision.metadata.source === "import" &&
-      typeof revision.metadata.preserveOnlyReason === "string" &&
-      revision.metadata.preserveOnlyReason.length > 0,
-  );
-
-  if (
-    signatureMatch &&
-    canReuse &&
-    durableWorkflowMetadata.definitions.length === 0 &&
-    durableWorkflowMetadata.entries.length === 0 &&
-    !hasWorkflowOverlay &&
-    !sourceHasWorkflowPayload
-  ) {
-    return {
-      bytes: new Uint8Array(state.sourceBytes),
-      mimeType: DOCX_MIME_TYPE,
-      fileName: options?.fileName ?? `${sessionState.documentId}.docx`,
-      delivery: {
-        mode: "exported-bytes-only",
-      },
-    };
-  }
-  const preservedCommentIds = new Set(
-    state.preservedCommentDefinitions.map((definition) => definition.commentId),
-  );
-  const blockingCommentCount = Math.max(
-    state.blockingCommentDiagnostics.length,
-    preservedCommentIds.size,
-  );
-  if (blockingCommentCount > 0) {
-    throw new Error(
-      `DOCX export is blocked because ${blockingCommentCount} preserve-only comment anchors cannot be safely remapped after runtime edits.`,
-    );
-  }
-  const actionableRevisions = currentRevisions.filter(
-    (revision) => getRevisionActionability(revision) === "actionable",
-  );
-  const mainStoryActionableRevisions = actionableRevisions.filter((revision) =>
-    !revision.metadata.storyTarget?.kind || revision.metadata.storyTarget.kind === "main"
-  );
-  const commentThreads = Object.values(
-    createCommentStoreFromRuntimeComments(currentDocument.review.comments).threads,
-  );
-  const ownedCommentThreads = commentThreads.filter(
-    (thread) => !preservedCommentIds.has(thread.commentId),
-  );
-  const revisionReadyMainContent = {
-    ...currentDocument.content,
-    children: splitStoryBlocksForRuntimeRevisions(
-      currentDocument.content.children,
-      mainStoryActionableRevisions,
-    ),
-  };
-  const serialized = serializeMainDocument(
-    splitDocumentAtReviewBoundaries(
-      revisionReadyMainContent as never,
-      ownedCommentThreads,
-      mainStoryActionableRevisions,
-    ) as never,
-    currentDocument.preservation as never,
-    state.sourceDocumentRelationships,
-    {
-      documentAttributes: state.sourceDocumentAttributes,
-      media: currentDocument.media as MediaCatalog,
-      finalSectionProperties: currentDocument.subParts?.finalSectionProperties,
-      namespaceFlavor: options?.exportStrictOoxml ? "strict" : "transitional",
-    },
-  );
-  const revisionDocument = serializeRuntimeRevisionsIntoDocumentXml(
-    serialized.documentXml,
-    mainStoryActionableRevisions,
-  );
-  if (revisionDocument.skippedRevisionIds.length > 0) {
-    throw new Error(
-      `DOCX export is blocked because ${revisionDocument.skippedRevisionIds.length} active revisions overlap unsupported serialization boundaries.`,
-    );
-  }
-
-  const strippedDocumentXml = stripCommentMarkup(
-    revisionDocument.documentXml,
-    ownedCommentThreads.map((thread) => thread.commentId),
-  );
-  const exportCommentIds = createCommentExportIdMap(
-    ownedCommentThreads,
-    state.preservedCommentDefinitions,
-  );
-  const serializedComments = serializeMergedCommentsXml(ownedCommentThreads, {
-    exportCommentIds,
-    preservedDefinitions: state.preservedCommentDefinitions,
-    sourceRootTag: state.sourceCommentsRootTag,
-    sourceExtendedRootTag: state.sourceCommentsExtendedRootTag,
-    sourceIdsRootTag: state.sourceCommentsIdsRootTag,
-    sourcePeopleRootTag: state.sourcePeopleRootTag,
-    peopleAuthors: state.sourcePeopleAuthors,
-  });
-  const annotatedDocument = serializeCommentAnchorsIntoDocumentXml(
-    strippedDocumentXml,
-    ownedCommentThreads,
-    undefined,
-    {
-      exportCommentIds,
-    },
-  );
-  const protectedDocumentXml = serializeProtectionRangesIntoDocumentXml(
-    annotatedDocument.documentXml,
-    state.protectionSnapshot,
-  );
-  const blockingSkippedCommentIds = annotatedDocument.skippedCommentIds.filter((commentId) => {
-    const thread = ownedCommentThreads.find((candidate) => candidate.commentId === commentId);
-    return !thread || thread.anchor.kind !== "detached";
-  });
-  if (blockingSkippedCommentIds.length > 0) {
-    throw new Error(
-      `DOCX export is blocked because ${blockingSkippedCommentIds.length} comments no longer map to serializable ranges.`,
-    );
-  }
-  const commentsPartPath =
-    state.sourceCommentsPartPath ?? COMMENTS_PART_PATH;
-  const commentsExtendedPartPath =
-    state.sourceCommentsExtendedPartPath ?? COMMENTS_EXTENDED_PART_PATH;
-  const commentsIdsPartPath =
-    state.sourceCommentsIdsPartPath ?? COMMENTS_IDS_PART_PATH;
-  const peoplePartPath =
-    state.sourcePeoplePartPath ?? PEOPLE_PART_PATH;
-  const numberingPartPath =
-    state.sourceNumberingPartPath ?? NUMBERING_PART_PATH;
-  const serializedNumberingXml = hasSerializableNumberingEntries(
-    currentDocument.numbering as NumberingCatalog,
-  )
-    ? serializeNumberingXml(currentDocument.numbering as NumberingCatalog)
-    : undefined;
-  const nextRelationships = withDocumentRelatedParts(
-    serialized.relationships,
-    [
-      {
-        relationshipType: NUMBERING_RELATIONSHIP_TYPE,
-        partPath: numberingPartPath,
-        existingRelationshipId: state.sourceNumberingRelationshipId,
-        include:
-          Boolean(serializedNumberingXml) ||
-          Boolean(state.sourceNumberingPartPath),
-      },
-      {
-        relationshipType: COMMENTS_RELATIONSHIP_TYPE,
-        partPath: commentsPartPath,
-        existingRelationshipId: state.sourceCommentsRelationshipId,
-        include:
-          serializedComments.serializedCommentIds.length > 0 ||
-          Boolean(state.sourceCommentsPartPath),
-      },
-      {
-        relationshipType: COMMENTS_EXTENDED_RELATIONSHIP_TYPE,
-        partPath: commentsExtendedPartPath,
-        existingRelationshipId: state.sourceCommentsExtendedRelationshipId,
-        include:
-          Boolean(serializedComments.commentsExtendedXml) ||
-          Boolean(state.sourceCommentsExtendedPartPath),
-      },
-      {
-        relationshipType: COMMENTS_IDS_RELATIONSHIP_TYPE,
-        partPath: commentsIdsPartPath,
-        existingRelationshipId: state.sourceCommentsIdsRelationshipId,
-        include:
-          Boolean(serializedComments.commentsIdsXml) ||
-          Boolean(state.sourceCommentsIdsPartPath),
-      },
-      {
-        relationshipType: PEOPLE_RELATIONSHIP_TYPE,
-        partPath: peoplePartPath,
-        existingRelationshipId: state.sourcePeopleRelationshipId,
-        include:
-          Boolean(serializedComments.peopleXml) ||
-          Boolean(state.sourcePeoplePartPath),
-      },
-    ],
-  );
-
-  const exportedSubParts = currentDocument.subParts as SubPartsCatalog | undefined;
-  const subPartOwnedPaths: string[] = [];
-  if (exportedSubParts) {
-    for (const header of exportedSubParts.headers) {
-      subPartOwnedPaths.push(header.partPath);
-    }
-    for (const footer of exportedSubParts.footers) {
-      subPartOwnedPaths.push(footer.partPath);
-    }
-    if (exportedSubParts.footnoteCollection) {
-      if (state.sourceSubPartPaths.footnotesPartPath) {
-        subPartOwnedPaths.push(state.sourceSubPartPaths.footnotesPartPath);
-      }
-      if (state.sourceSubPartPaths.endnotesPartPath) {
-        subPartOwnedPaths.push(state.sourceSubPartPaths.endnotesPartPath);
-      }
-    }
-    if (exportedSubParts.theme && state.sourceSubPartPaths.themePartPath) {
-      subPartOwnedPaths.push(state.sourceSubPartPaths.themePartPath);
-    }
-  }
-
-  // Settings.xml is owned when the source package carried one OR the canonical
-  // model carries settings we need to re-emit. The `canReuse && signatureMatch`
-  // short-circuit above already skips re-export entirely for no-edit sessions,
-  // so every path that reaches here is willing to emit a rebuilt settings.xml.
-  const settingsPartPath =
-    state.sourceSettingsPartPath ?? SETTINGS_PART_PATH;
-  const hasSettingsSurface =
-    Boolean(state.sourceSettingsPartPath) ||
-    exportedSubParts?.settings !== undefined;
-  const workflowPayloadPartPaths = resolveWorkflowPayloadPartPaths(
-    state.sourcePackage,
-    sessionState.documentId,
-  );
-  const internalEditorState = (
-    options as { _editorState?: import("./ooxml/workflow-payload.ts").EditorStatePayload } | undefined
-  )?._editorState;
-
-  const exportSession = createExportSession(state.sourcePackage, [
-    state.sourceDocumentPartPath,
-    APP_PROPERTIES_PART_PATH,
-    CORE_PROPERTIES_PART_PATH,
-    workflowPayloadPartPaths.payloadPartPath,
-    workflowPayloadPartPaths.itemPropsPartPath,
-    WORKFLOW_PAYLOAD_CUSTOM_PROPS_PART_PATH,
-    numberingPartPath,
-    commentsPartPath,
-    commentsExtendedPartPath,
-    commentsIdsPartPath,
-    peoplePartPath,
-    ...(hasSettingsSurface ? [settingsPartPath] : []),
-    ...subPartOwnedPaths,
-  ]);
-
-  const mainDocumentXmlForExport =
-    signatureMatch &&
-    durableWorkflowMetadata.definitions.length === 0 &&
-    durableWorkflowMetadata.entries.length === 0 &&
-    !hasWorkflowOverlay &&
-    commentCount === 0 &&
-    hasActiveImportedPreserveOnlyRevisions
-      ? state.sourceDocumentXml
-      : protectedDocumentXml;
-
-  exportSession.replaceOwnedPart({
-    path: state.sourceDocumentPartPath,
-    bytes: new TextEncoder().encode(mainDocumentXmlForExport),
-    contentType: MAIN_DOCUMENT_CONTENT_TYPE,
-    relationships: nextRelationships,
-  });
-
-  if (serializedNumberingXml || state.sourceNumberingPartPath) {
-    exportSession.replaceOwnedPart({
-      path: numberingPartPath,
-      bytes: new TextEncoder().encode(
-        serializedNumberingXml ??
-          `<?xml version="1.0" encoding="UTF-8" standalone="yes"?>\n<w:numbering xmlns:w="http://schemas.openxmlformats.org/wordprocessingml/2006/main"></w:numbering>`,
-      ),
-      contentType:
-        state.sourcePackage.parts.get(numberingPartPath)?.contentType ??
-        WORD_NUMBERING_CONTENT_TYPE,
-    });
-  }
-
-  if (hasSettingsSurface) {
-    // Canonical settings ∅ + no source settings → omit the owned-part write
-    // (hasSettingsSurface is already false in that case). Otherwise route
-    // through the graft serializer so unmodelled children round-trip via
-    // source bytes while canonical mutations land.
-    const canonicalSettings = exportedSubParts?.settings ?? {};
-    const settingsXml = serializeSettingsXml(canonicalSettings, state.sourceSettingsXml);
-    exportSession.replaceOwnedPart({
-      path: settingsPartPath,
-      bytes: new TextEncoder().encode(settingsXml),
-      contentType:
-        state.sourcePackage.parts.get(settingsPartPath)?.contentType ??
-        WORD_SETTINGS_CONTENT_TYPE,
-    });
-  }
-
-  if (serializedComments.serializedCommentIds.length > 0 || state.sourceCommentsPartPath) {
-    exportSession.replaceOwnedPart({
-      path: commentsPartPath,
-      bytes: new TextEncoder().encode(serializedComments.commentsXml),
-      contentType:
-        state.sourcePackage.parts.get(commentsPartPath)?.contentType ?? COMMENTS_CONTENT_TYPE,
-    });
-  }
-
-  if (serializedComments.commentsExtendedXml || state.sourceCommentsExtendedPartPath) {
-    exportSession.replaceOwnedPart({
-      path: commentsExtendedPartPath,
-      bytes: new TextEncoder().encode(
-        serializedComments.commentsExtendedXml ?? `<?xml version="1.0" encoding="UTF-8" standalone="yes"?>\n<w15:commentsEx xmlns:w15="http://schemas.microsoft.com/office/word/2012/wordml"></w15:commentsEx>`,
-      ),
-      contentType:
-        state.sourcePackage.parts.get(commentsExtendedPartPath)?.contentType ??
-        COMMENTS_EXTENDED_CONTENT_TYPE,
-    });
-  }
-
-  if (serializedComments.commentsIdsXml || state.sourceCommentsIdsPartPath) {
-    exportSession.replaceOwnedPart({
-      path: commentsIdsPartPath,
-      bytes: new TextEncoder().encode(
-        serializedComments.commentsIdsXml ?? `<?xml version="1.0" encoding="UTF-8" standalone="yes"?>\n<w16cid:commentsIds xmlns:w16cid="http://schemas.microsoft.com/office/word/2016/wordml/cid"></w16cid:commentsIds>`,
-      ),
-      contentType:
-        state.sourcePackage.parts.get(commentsIdsPartPath)?.contentType ??
-        COMMENTS_IDS_CONTENT_TYPE,
-    });
-  }
-
-  if (serializedComments.peopleXml || state.sourcePeoplePartPath) {
-    exportSession.replaceOwnedPart({
-      path: peoplePartPath,
-      bytes: new TextEncoder().encode(
-        serializedComments.peopleXml ?? `<?xml version="1.0" encoding="UTF-8" standalone="yes"?>\n<w15:people xmlns:w15="http://schemas.microsoft.com/office/word/2012/wordml"></w15:people>`,
-      ),
-      contentType:
-        state.sourcePackage.parts.get(peoplePartPath)?.contentType ??
-        PEOPLE_CONTENT_TYPE,
-    });
-  }
-
-  if (exportedSubParts) {
-    const headersByPartPath = new Map<
-      string,
-      { header: (typeof exportedSubParts.headers)[number]; revisions: ReviewRevisionRecord[] }
-    >();
-    for (const header of exportedSubParts.headers) {
-      const entry = headersByPartPath.get(header.partPath) ?? { header, revisions: [] };
-      const matchingRevisions = actionableRevisions.filter((revision) =>
-        storyTargetsEqual(revision.metadata.storyTarget ?? { kind: "main" }, {
-          kind: "header",
-          relationshipId: header.relationshipId,
-          variant: header.variant,
-          ...(header.sectionIndex !== undefined ? { sectionIndex: header.sectionIndex } : {}),
-        })
-      );
-      entry.revisions.push(...matchingRevisions);
-      if (matchingRevisions.length > 0) {
-        entry.header = header;
-      }
-      headersByPartPath.set(header.partPath, entry);
-    }
-    for (const { header, revisions } of headersByPartPath.values()) {
-      const serializedHeaderXml = serializeSecondaryStoryWithRuntimeRevisions(
-        serializeHeaderXmlWithRevisions(header, revisions),
-        revisions,
-        `header ${header.partPath}`,
-      );
-      exportSession.replaceOwnedPart({
-        path: header.partPath,
-        bytes: new TextEncoder().encode(serializedHeaderXml),
-        contentType:
-          state.sourcePackage.parts.get(header.partPath)?.contentType ?? WORD_HEADER_CONTENT_TYPE,
-      });
-    }
-    const footersByPartPath = new Map<
-      string,
-      { footer: (typeof exportedSubParts.footers)[number]; revisions: ReviewRevisionRecord[] }
-    >();
-    for (const footer of exportedSubParts.footers) {
-      const entry = footersByPartPath.get(footer.partPath) ?? { footer, revisions: [] };
-      const matchingRevisions = actionableRevisions.filter((revision) =>
-        storyTargetsEqual(revision.metadata.storyTarget ?? { kind: "main" }, {
-          kind: "footer",
-          relationshipId: footer.relationshipId,
-          variant: footer.variant,
-          ...(footer.sectionIndex !== undefined ? { sectionIndex: footer.sectionIndex } : {}),
-        })
-      );
-      entry.revisions.push(...matchingRevisions);
-      if (matchingRevisions.length > 0) {
-        entry.footer = footer;
-      }
-      footersByPartPath.set(footer.partPath, entry);
-    }
-    for (const { footer, revisions } of footersByPartPath.values()) {
-      const serializedFooterXml = serializeSecondaryStoryWithRuntimeRevisions(
-        serializeFooterXmlWithRevisions(footer, revisions),
-        revisions,
-        `footer ${footer.partPath}`,
-      );
-      exportSession.replaceOwnedPart({
-        path: footer.partPath,
-        bytes: new TextEncoder().encode(serializedFooterXml),
-        contentType:
-          state.sourcePackage.parts.get(footer.partPath)?.contentType ?? WORD_FOOTER_CONTENT_TYPE,
-      });
-    }
-    if (exportedSubParts.footnoteCollection) {
-      if (state.sourceSubPartPaths.footnotesPartPath) {
-        const serializedFootnotesXml = serializeFootnotesXml(
-          exportedSubParts.footnoteCollection,
-          Object.fromEntries(
-            actionableRevisions
-              .filter((revision) => revision.metadata.storyTarget?.kind === "footnote")
-              .map((revision) =>
-                revision.metadata.storyTarget?.kind === "footnote"
-                  ? [revision.metadata.storyTarget.noteId, [] as ReviewRevisionRecord[]] as const
-                  : null,
-              )
-              .filter((entry): entry is readonly [string, ReviewRevisionRecord[]] => entry !== null)
-              .map(([noteId]) => [
-                noteId,
-                actionableRevisions.filter(
-                  (revision) =>
-                    revision.metadata.storyTarget?.kind === "footnote" &&
-                    revision.metadata.storyTarget.noteId === noteId,
-                ),
-              ]),
-          ),
-        );
-        exportSession.replaceOwnedPart({
-          path: state.sourceSubPartPaths.footnotesPartPath,
-          bytes: new TextEncoder().encode(serializedFootnotesXml),
-          contentType:
-            state.sourcePackage.parts.get(state.sourceSubPartPaths.footnotesPartPath)?.contentType ??
-            WORD_FOOTNOTES_CONTENT_TYPE,
-        });
-      }
-      if (state.sourceSubPartPaths.endnotesPartPath) {
-        const serializedEndnotesXml = serializeEndnotesXml(
-          exportedSubParts.footnoteCollection,
-          Object.fromEntries(
-            actionableRevisions
-              .filter((revision) => revision.metadata.storyTarget?.kind === "endnote")
-              .map((revision) =>
-                revision.metadata.storyTarget?.kind === "endnote"
-                  ? [revision.metadata.storyTarget.noteId, [] as ReviewRevisionRecord[]] as const
-                  : null,
-              )
-              .filter((entry): entry is readonly [string, ReviewRevisionRecord[]] => entry !== null)
-              .map(([noteId]) => [
-                noteId,
-                actionableRevisions.filter(
-                  (revision) =>
-                    revision.metadata.storyTarget?.kind === "endnote" &&
-                    revision.metadata.storyTarget.noteId === noteId,
-                ),
-              ]),
-          ),
-        );
-        exportSession.replaceOwnedPart({
-          path: state.sourceSubPartPaths.endnotesPartPath,
-          bytes: new TextEncoder().encode(serializedEndnotesXml),
-          contentType:
-            state.sourcePackage.parts.get(state.sourceSubPartPaths.endnotesPartPath)?.contentType ??
-            WORD_ENDNOTES_CONTENT_TYPE,
-          });
-      }
-    }
-    if (exportedSubParts.theme && state.sourceSubPartPaths.themePartPath) {
-      const sourceThemePart = state.sourcePackage.parts.get(state.sourceSubPartPaths.themePartPath);
-      if (sourceThemePart) {
-        exportSession.replaceOwnedPart({
-          path: state.sourceSubPartPaths.themePartPath,
-          bytes: sourceThemePart.bytes,
-          contentType:
-            sourceThemePart.contentType ??
-            "application/vnd.openxmlformats-officedocument.theme+xml",
-          relationships: sourceThemePart.relationships,
-          compression: sourceThemePart.compression,
-        });
-      }
-    }
-  }
-
-  ensureHostMetadataParts(exportSession, state.sourcePackage, currentDocument);
-  // Schema 1.2: pass through editorState payload collected by the runtime channel.
-  ensureWorkflowPayloadParts(
-    exportSession,
-    sessionState,
-    currentDocument,
-    state.sourcePackage,
-    workflowPayloadPartPaths,
-    internalEditorState,
-  );
-
-  return {
-    bytes: exportSession.serialize(),
-    mimeType: DOCX_MIME_TYPE,
-    fileName: options?.fileName ?? `${sessionState.documentId}.docx`,
-    delivery: {
-      mode: "exported-bytes-only",
-    },
-  };
-}
-
-function toEditorSessionState(
-  sessionStateOrSnapshot: EditorSessionState | PersistedEditorSnapshot,
-): EditorSessionState {
-  return "sessionVersion" in sessionStateOrSnapshot
-    ? sessionStateOrSnapshot
-    : editorSessionStateFromPersistedSnapshot(sessionStateOrSnapshot);
-}
-
-function createImportedCanonicalDocument(input: {
-  documentId: string;
-  timestamp: string;
-  numbering: CanonicalDocumentEnvelope["numbering"];
-  media: CanonicalDocumentEnvelope["media"];
-  content: CanonicalDocumentEnvelope["content"];
-  subParts?: SubPartsCatalog;
-  parsedStyles?: ParseStylesResult;
-  fontTable?: CanonicalDocumentEnvelope["fontTable"];
-  preservation: CanonicalDocumentEnvelope["preservation"];
-  diagnostics: CanonicalDocumentEnvelope["diagnostics"];
-  review: CanonicalDocumentEnvelope["review"];
-}): CanonicalDocumentEnvelope {
-  const numbering = ensureImportedNumberingCatalogSupportsContent(
-    input.numbering,
-    input.content,
-  );
-
-  // Use package-backed style catalog when available; fall back to synthetic
-  // styles derived from referenced styleId values when styles.xml is missing
-  // or could not be parsed.
-  const styles = buildStylesCatalog(input.parsedStyles, input.content, input.subParts);
-
-  return {
-    schemaVersion: "cds/1.0.0",
-    docId: createCanonicalDocumentId(input.documentId),
-    createdAt: input.timestamp,
-    updatedAt: input.timestamp,
-    metadata: {
-      customProperties: {},
-    },
-    styles,
-    numbering,
-    media: input.media,
-    content: input.content,
-    review: input.review,
-    preservation: input.preservation,
-    diagnostics: input.diagnostics,
-    ...(input.subParts !== undefined ? { subParts: input.subParts } : {}),
-    ...(input.fontTable !== undefined ? { fontTable: input.fontTable } : {}),
-  };
-}
-
-type SubPartOpaqueImportState = {
-  nextFragmentIndex: number;
-  nextWarningIndex: number;
-  nextDiagnosticIndex: number;
-  cursor: number;
-};
-
-function createSubPartOpaqueImportState(
-  opaqueFragments: Record<string, OpaqueFragmentRecord>,
-  warnings: CanonicalDocumentEnvelope["diagnostics"]["warnings"],
-): SubPartOpaqueImportState {
-  const maxByPrefix = (values: Iterable<string>, prefix: string): number => {
-    let max = 0;
-    for (const value of values) {
-      const match = new RegExp(`^${prefix}(\\d+)$`).exec(value);
-      if (!match) {
-        continue;
-      }
-      const parsed = Number.parseInt(match[1] ?? "0", 10);
-      if (Number.isFinite(parsed) && parsed > max) {
-        max = parsed;
-      }
-    }
-    return max;
-  };
-
-  const maxCursor = Object.values(opaqueFragments).reduce(
-    (currentMax, fragment) => Math.max(currentMax, fragment.lastKnownRange?.to ?? 0),
-    0,
-  );
-
-  return {
-    nextFragmentIndex:
-      maxByPrefix(Object.keys(opaqueFragments), "fragment:import-") + 1,
-    nextWarningIndex:
-      maxByPrefix(
-        [
-          ...Object.values(opaqueFragments).map((fragment) => fragment.warningId),
-          ...warnings.map((warning) => warning.warningId),
-        ],
-        "warning:import-",
-      ) + 1,
-    nextDiagnosticIndex:
-      maxByPrefix(warnings.map((warning) => warning.diagnosticId), "diagnostic:import-") + 1,
-    cursor: maxCursor,
-  };
-}
-
-function normalizeSubPartOpaqueBlocks(
-  blocks: BlockNode[],
-  opaqueFragments: Record<string, OpaqueFragmentRecord>,
-  warnings: CanonicalDocumentEnvelope["diagnostics"]["warnings"],
-  packagePartName: string,
-  state: SubPartOpaqueImportState,
-): BlockNode[] {
-  return blocks.map((block) => {
-    if (block.type !== "opaque_block" || typeof block.rawXml !== "string") {
-      return block;
-    }
-    return recordImportedOpaqueBlock(
-      block.rawXml,
-      opaqueFragments,
-      warnings,
-      packagePartName,
-      state,
-    );
-  });
-}
-
-function normalizeFootnoteCollectionOpaqueBlocks(
-  collection: FootnoteCollection | undefined,
-  kind: "footnote" | "endnote",
-  opaqueFragments: Record<string, OpaqueFragmentRecord>,
-  warnings: CanonicalDocumentEnvelope["diagnostics"]["warnings"],
-  packagePartName: string,
-  state: SubPartOpaqueImportState,
-): void {
-  if (!collection) {
-    return;
-  }
-  const notes = kind === "footnote" ? collection.footnotes : collection.endnotes;
-  for (const definition of Object.values(notes)) {
-    definition.blocks = normalizeSubPartOpaqueBlocks(
-      definition.blocks,
-      opaqueFragments,
-      warnings,
-      packagePartName,
-      state,
-    );
-  }
-}
-
-function recordImportedOpaqueBlock(
-  rawXml: string,
-  opaqueFragments: Record<string, OpaqueFragmentRecord>,
-  warnings: CanonicalDocumentEnvelope["diagnostics"]["warnings"],
-  packagePartName: string,
-  state: SubPartOpaqueImportState,
-): BlockNode {
-  const fragmentId = `fragment:import-${state.nextFragmentIndex}`;
-  state.nextFragmentIndex += 1;
-  const warningId = `warning:import-${state.nextWarningIndex}`;
-  state.nextWarningIndex += 1;
-  const diagnosticId = `diagnostic:import-${state.nextDiagnosticIndex}`;
-  state.nextDiagnosticIndex += 1;
-
-  const rangeStart = state.cursor;
-  const rangeEnd = state.cursor + 1;
-  state.cursor = rangeEnd;
-
-  opaqueFragments[fragmentId] = {
-    fragmentId,
-    payloadKind: "xml-subtree",
-    payloadReference: rawXml,
-    featureClass: "preserve-only",
-    lastKnownRange: {
-      from: rangeStart,
-      to: rangeEnd,
-    },
-    warningId,
-    packagePartName,
-  };
-  warnings.push({
-    diagnosticId,
-    warningId,
-    source: "import",
-    message: "Unsupported sub-part OOXML was preserved as an opaque placeholder.",
-  });
-
-  return {
-    type: "opaque_block",
-    fragmentId,
-    warningId,
-    rawXml,
-  };
-}
-
-function mergeSecondaryStoryMediaCatalog(
-  media: MediaCatalog,
-  input: {
-    headers: readonly HeaderDocument[];
-    footers: readonly FooterDocument[];
-    footnoteCollection?: FootnoteCollection;
-    mediaParts: ReadonlyMap<string, { path: string; contentType: string }>;
-  },
-): MediaCatalog {
-  const items = { ...media.items };
-  let changed = false;
-
-  const registerMediaItem = (
-    mediaId: string,
-    record: Omit<NonNullable<MediaCatalog["items"][string]>, "mediaId">,
-  ) => {
-    const existing = items[mediaId];
-    items[mediaId] = existing
-      ? {
-          ...existing,
-          ...record,
-          mediaId,
-        }
-      : {
-          mediaId,
-          ...record,
-        };
-    changed = true;
-  };
-
-  const visitInline = (node: InlineNode) => {
-    if (node.type === "image") {
-      const packagePartName = `/${node.mediaId.slice("media:".length)}`;
-      registerMediaItem(node.mediaId, {
-        contentType:
-          items[node.mediaId]?.contentType ??
-          input.mediaParts.get(packagePartName)?.contentType ??
-          "application/octet-stream",
-        filename: packagePartName.slice(packagePartName.lastIndexOf("/") + 1) || "image.bin",
-        packagePartName,
-        ...(node.altText ? { altText: node.altText } : {}),
-      });
-      return;
-    }
-    if (node.type === "drawing_frame" && node.content.type === "picture" && node.content.mediaId) {
-      const packagePartName =
-        typeof node.content.packagePartName === "string" && node.content.packagePartName.length > 0
-          ? node.content.packagePartName
-          : `/${node.content.mediaId.slice("media:".length)}`;
-      registerMediaItem(node.content.mediaId, {
-        contentType:
-          items[node.content.mediaId]?.contentType ??
-          input.mediaParts.get(packagePartName)?.contentType ??
-          "application/octet-stream",
-        filename: packagePartName.slice(packagePartName.lastIndexOf("/") + 1) || "image.bin",
-        packagePartName,
-        relationshipId: node.content.blipRef,
-        ...(node.anchor.docPr?.descr ? { altText: node.anchor.docPr.descr } : {}),
-        widthEmu: node.anchor.extent.widthEmu,
-        heightEmu: node.anchor.extent.heightEmu,
-      });
-      return;
-    }
-    if (node.type === "hyperlink" || node.type === "field") {
-      for (const child of node.children) {
-        visitInline(child);
-      }
-    }
-  };
-
-  const visitBlocks = (blocks: ReadonlyArray<BlockNode>) => {
-    for (const block of blocks) {
-      if (block.type === "paragraph") {
-        for (const child of block.children) {
-          visitInline(child);
-        }
-        continue;
-      }
-      if (block.type === "table") {
-        for (const row of block.rows) {
-          for (const cell of row.cells) {
-            visitBlocks(cell.children);
-          }
-        }
-        continue;
-      }
-      if (block.type === "sdt" || block.type === "custom_xml") {
-        visitBlocks(block.children);
-      }
-    }
-  };
-
-  for (const header of input.headers) {
-    visitBlocks(header.blocks);
-  }
-  for (const footer of input.footers) {
-    visitBlocks(footer.blocks);
-  }
-  if (input.footnoteCollection) {
-    for (const note of Object.values(input.footnoteCollection.footnotes)) {
-      visitBlocks(note.blocks);
-    }
-    for (const note of Object.values(input.footnoteCollection.endnotes)) {
-      visitBlocks(note.blocks);
-    }
-  }
-
-  return changed ? { ...media, items } : media;
-}
-
-// Canonical model styleId validation pattern — styleIds that don't match
-// are excluded from the catalog to avoid snapshot validation failures.
-const VALID_STYLE_ID = /^[A-Za-z_][A-Za-z0-9._-]{0,127}$/;
-
-function buildStylesCatalog(
-  parsedStyles: ParseStylesResult | undefined,
-  content: CanonicalDocumentEnvelope["content"],
-  subParts?: SubPartsCatalog,
-): CanonicalDocumentEnvelope["styles"] {
-  if (parsedStyles?.fromPackage) {
-    // Package-backed catalog: filter entries whose styleId does not satisfy
-    // the canonical model pattern (e.g. numeric-only ids from Word).
-    const catalog = filterValidStyleIds(parsedStyles.catalog);
-
-    // Merge in any referenced styleIds that the package styles.xml did not
-    // define (rare but defensive).
-    const referencedIds = collectReferencedParagraphStyleIds(content, subParts);
-    for (const styleId of referencedIds) {
-      if (!catalog.paragraphs[styleId] && VALID_STYLE_ID.test(styleId)) {
-        catalog.paragraphs[styleId] = {
-          styleId,
-          displayName: styleId,
-          kind: "paragraph",
-          isDefault: styleId === "Normal",
-        };
-      }
-    }
-    return {
-      ...catalog,
-      fromPackage: true,
-    };
-  }
-
-  // Synthetic fallback: no styles.xml available
-  const paragraphStyles = Object.fromEntries(
-    [...collectReferencedParagraphStyleIds(content, subParts)]
-      .sort((left, right) => left.localeCompare(right))
-      .filter((styleId) => VALID_STYLE_ID.test(styleId))
-      .map((styleId) => [
-        styleId,
-        {
-          styleId,
-          displayName: styleId,
-          kind: "paragraph" as const,
-          isDefault: styleId === "Normal",
-        },
-      ]),
-  );
-  return {
-    paragraphs: paragraphStyles,
-    characters: {},
-    tables: {},
-    fromPackage: false,
-  };
-}
-
-function filterValidStyleIds(
-  catalog: CanonicalDocumentEnvelope["styles"],
-): CanonicalDocumentEnvelope["styles"] {
-  const filterRecord = <T extends { styleId: string }>(
-    record: Record<string, T>,
-  ): Record<string, T> => {
-    const result: Record<string, T> = {};
-    for (const [key, value] of Object.entries(record)) {
-      if (VALID_STYLE_ID.test(key)) {
-        result[key] = value;
-      }
-    }
-    return result;
-  };
-
-  return {
-    paragraphs: filterRecord(catalog.paragraphs),
-    characters: filterRecord(catalog.characters),
-    tables: filterRecord(catalog.tables),
-    ...(catalog.latentStyles ? { latentStyles: catalog.latentStyles } : {}),
-    ...(catalog.docDefaults ? { docDefaults: catalog.docDefaults } : {}),
-    ...(catalog.fromPackage !== undefined ? { fromPackage: catalog.fromPackage } : {}),
-  };
-}
-
-function ensureImportedNumberingCatalogSupportsContent(
-  catalog: NumberingCatalog,
-  content: CanonicalDocumentEnvelope["content"],
-): NumberingCatalog {
-  if (
-    catalog.instances[DOCX_NULL_NUMBERING_INSTANCE_ID] ||
-    !collectReferencedNumberingInstanceIds(content).has(DOCX_NULL_NUMBERING_INSTANCE_ID)
-  ) {
-    return catalog;
-  }
-
-  const syntheticNullCatalog = createSyntheticDocxNullNumberingCatalog();
-  return {
-    abstractDefinitions: {
-      ...catalog.abstractDefinitions,
-      ...syntheticNullCatalog.abstractDefinitions,
-    },
-    instances: {
-      ...catalog.instances,
-      ...syntheticNullCatalog.instances,
-    },
-    ...(catalog.numPicBullets !== undefined ? { numPicBullets: catalog.numPicBullets } : {}),
-  };
-}
-
-function collectReferencedNumberingInstanceIds(
-  content: CanonicalDocumentEnvelope["content"],
-): Set<string> {
-  const numberingInstanceIds = new Set<string>();
-
-  const visitBlocks = (blocks: ReadonlyArray<BlockNode>) => {
-    for (const block of blocks) {
-      if (block.type === "paragraph" && block.numbering?.numberingInstanceId) {
-        numberingInstanceIds.add(block.numbering.numberingInstanceId);
-      }
-      if (block.type === "table") {
-        for (const row of block.rows) {
-          for (const cell of row.cells) {
-            visitBlocks(cell.children);
-          }
-        }
-      } else if (block.type === "sdt" || block.type === "custom_xml") {
-        visitBlocks(block.children);
-      }
-    }
-  };
-
-  visitBlocks(content.children);
-  return numberingInstanceIds;
-}
-
-function collectReferencedParagraphStyleIds(
-  content: CanonicalDocumentEnvelope["content"],
-  subParts?: SubPartsCatalog,
-): Set<string> {
-  const styleIds = new Set<string>();
-
-  const visitBlocks = (blocks: ReadonlyArray<BlockNode>) => {
-    for (const block of blocks) {
-      if ("styleId" in block && typeof block.styleId === "string" && block.styleId.length > 0) {
-        styleIds.add(block.styleId);
-      }
-      if (block.type === "table") {
-        for (const row of block.rows) {
-          for (const cell of row.cells) {
-            visitBlocks(cell.children);
-          }
-        }
-      } else if (block.type === "sdt" || block.type === "custom_xml") {
-        visitBlocks(block.children);
-      }
-    }
-  };
-
-  visitBlocks(content.children);
-  if (subParts) {
-    for (const header of subParts.headers) {
-      visitBlocks(header.blocks);
-    }
-    for (const footer of subParts.footers) {
-      visitBlocks(footer.blocks);
-    }
-    if (subParts.footnoteCollection) {
-      for (const note of Object.values(subParts.footnoteCollection.footnotes)) {
-        visitBlocks(note.blocks);
-      }
-      for (const note of Object.values(subParts.footnoteCollection.endnotes)) {
-        visitBlocks(note.blocks);
-      }
-    }
-  }
-
-  return styleIds;
-}
-
-function createImportedSnapshot(input: {
-  documentId: string;
-  editorBuild: string;
-  timestamp: string;
-  document: CanonicalDocumentEnvelope;
-  compatibility: PersistedEditorSnapshot["compatibility"];
-  protectionSnapshot: ProtectionSnapshot;
-  sourcePackage?: PersistedEditorSnapshot["sourcePackage"];
-  workflowOverlay?: PersistedEditorSnapshot["workflowOverlay"];
-  workflowMetadata?: PersistedEditorSnapshot["workflowMetadata"];
-}): PersistedEditorSnapshot {
-  return {
-    snapshotVersion: "persisted-editor-snapshot/2",
-    schemaVersion: input.document.schemaVersion,
-    documentId: input.documentId,
-    docId: input.document.docId,
-    createdAt: input.document.createdAt,
-    updatedAt: input.document.updatedAt,
-    savedAt: input.timestamp,
-    editorBuild: input.editorBuild,
-    canonicalDocument: input.document,
-    compatibility: input.compatibility,
-    warningLog: input.compatibility.warnings,
-    protectionSnapshot: input.protectionSnapshot,
-    sourcePackage: input.sourcePackage,
-    workflowOverlay: input.workflowOverlay,
-    workflowMetadata: input.workflowMetadata,
-  };
-}
-
-function toPublicAnchorProjection(
-  anchor: InternalEditorAnchorProjection,
-): PublicEditorAnchorProjection {
-  switch (anchor.kind) {
-    case "range":
-      return {
-        kind: "range",
-        from: anchor.range.from,
-        to: anchor.range.to,
-        assoc: anchor.assoc,
-      };
-    case "node":
-      return {
-        kind: "node",
-        at: anchor.at,
-        assoc: anchor.assoc,
-      };
-    case "detached":
-      return {
-        kind: "detached",
-        lastKnownRange: anchor.lastKnownRange,
-        reason: anchor.reason,
-      };
-  }
-}
-
-function toPublicCompatibilityFeatureEntry(entry: InternalCompatibilityFeatureEntry) {
-  return {
-    ...entry,
-    affectedAnchor: entry.affectedAnchor
-      ? toPublicAnchorProjection(entry.affectedAnchor)
-      : undefined,
-  };
-}
-
-function toPublicWarning(warning: InternalEditorWarning): PublicEditorWarning {
-  return {
-    ...warning,
-    affectedAnchor: warning.affectedAnchor
-      ? toPublicAnchorProjection(warning.affectedAnchor)
-      : undefined,
-  };
-}
-
-function toPublicError(error: InternalEditorError): EditorError {
-  return { ...error };
-}
-
-function toPublicCompatibilityReport(
-  report: InternalCompatibilityReport,
-): PublicCompatibilityReport {
-  return {
-    reportVersion: report.reportVersion,
-    generatedAt: report.generatedAt,
-    blockExport: report.blockExport,
-    featureEntries: report.featureEntries.map((entry) =>
-      toPublicCompatibilityFeatureEntry(entry),
-    ),
-    warnings: report.warnings.map((warning) => toPublicWarning(warning)),
-    errors: report.errors.map((error) => toPublicError(error)),
-  };
-}
-
-function createDiagnosticsSession(
-  options: LoadDocxEditorSessionOptions,
-  diagnostics: ImportDiagnosticsResult,
-): LoadedDocxEditorSession {
-  const timestamp = new Date().toISOString();
-  const editorBuild =
-    typeof options.editorBuild === "string" && options.editorBuild.length > 0
-      ? options.editorBuild
-      : "dev";
-  const runtime = createReadOnlyDiagnosticsRuntime({
-    documentId: options.documentId,
-    sourceLabel: options.sourceLabel,
-    editorBuild,
-    generatedAt: timestamp,
-    diagnostics,
-  });
-  const initialSnapshot = runtime.getPersistedSnapshot();
-  const initialSessionState = editorSessionStateFromPersistedSnapshot(initialSnapshot);
-
-  return {
-    initialSessionState,
-    initialSnapshot,
-    fatalError: diagnostics.fatalError,
-    readOnly: true,
-    protectionSnapshot: EMPTY_PROTECTION_SNAPSHOT,
-    exportDocx: async (_sessionState, exportOptions) => runtime.exportDocx(exportOptions),
-  };
-}
-
-function createImportDiagnosticsFromError(error: unknown): ImportDiagnosticsResult {
-  if (isPackageImportError(error)) {
-    return createPackageImportDiagnostics({
-      issue: classifyCorruptPackageError(error),
-    });
-  }
-
-  return createValidationImportDiagnostics({
-    message:
-      error instanceof Error
-        ? error.message
-        : "DOCX import failed during validation.",
-  });
-}
-
-function normalizeImportedRevisionRecords(
-  parsed: ParsedRevisionsResult,
-  content: CanonicalDocumentEnvelope["content"],
-  opaqueFragments: Record<string, OpaqueFragmentRecord>,
-): ParsedRevisionsResult {
-  const opaqueRanges = Object.values(opaqueFragments).map((fragment) => fragment.lastKnownRange);
-  const paragraphRanges = collectCanonicalParagraphRanges(content);
-  if (opaqueRanges.length === 0) {
-    return {
-      ...parsed,
-      revisions: parsed.revisions.map((revision) => {
-        if (revision.anchor.kind !== "range" || revision.metadata.preserveOnlyReason) {
-          return revision;
-        }
-
-        const preserveOnlyReason = getStructuralPreserveOnlyReason(
-          revision,
-          paragraphRanges,
-        );
-        if (!preserveOnlyReason) {
-          return revision;
-        }
-
-        return {
-          ...revision,
-          metadata: {
-            ...revision.metadata,
-            preserveOnlyReason,
-          },
-        };
-      }),
-    };
-  }
-
-  return {
-    ...parsed,
-    revisions: parsed.revisions.map((revision) => {
-      const { anchor } = revision;
-      if (anchor.kind !== "range" || revision.metadata.preserveOnlyReason) {
-        return revision;
-      }
-
-      const preserveOnlyReason =
-        getStructuralPreserveOnlyReason(revision, paragraphRanges) ??
-        (opaqueRanges.some((range) => rangesIntersect(range, anchor.range))
-          ? "Imported revision overlaps preserve-only OOXML and remains preserve-only."
-          : undefined);
-
-      if (!preserveOnlyReason) {
-        return revision;
-      }
-
-      return {
-        ...revision,
-        metadata: {
-          ...revision.metadata,
-          preserveOnlyReason,
-        },
-      };
-    }),
-  };
-}
-
-export function normalizeImportedCommentThreads(
-  parsed: ParsedCommentsResult,
-  opaqueFragments: Record<string, OpaqueFragmentRecord>,
-  revisions: readonly ReviewRevisionRecord[],
-): NormalizedImportedCommentsResult {
-  const opaqueRanges = Object.values(opaqueFragments).map((fragment) => fragment.lastKnownRange);
-  // Use getRevisionActionability() — not the raw preserveOnlyReason flag — so
-  // Lane 7b-promoted shapes (cellIns/cellDel/cellMerge, linked-pair moves) that
-  // still carry a default preserveOnlyReason aren't treated as preserve-only
-  // for comment-anchor detachment. See revision-types.ts:192-200.
-  const preserveOnlyRevisionRanges = revisions.flatMap((revision) => {
-    if (
-      revision.anchor.kind !== "range" ||
-      getRevisionActionability(revision) !== "preserve-only"
-    ) {
-      return [];
-    }
-    return [revision.anchor.range];
-  });
-  const preserveOnlyCommentIds = new Set(parsed.diagnostics.map((diagnostic) => diagnostic.commentId));
-  const additionalDiagnostics: CommentImportDiagnostic[] = [];
-  const normalizedThreads: CommentThread[] = parsed.threads.map((thread) => {
-    const { anchor } = thread;
-    if (anchor.kind !== "range") {
-      preserveOnlyCommentIds.add(thread.commentId);
-      return thread;
-    }
-
-    const opaqueOverlap = opaqueRanges.some((range) => rangesIntersect(range, anchor.range));
-    if (opaqueOverlap) {
-      preserveOnlyCommentIds.add(thread.commentId);
-      additionalDiagnostics.push({
-        commentId: thread.commentId,
-        code: "opaque_anchor_preserve_only",
-        message:
-          "Comment anchor intersects preserve-only OOXML content. Thread is visible but detached; anchor cannot be safely remapped.",
-        featureClass: "preserve-only",
-        detachedReason: "opaque-region" as const,
-        actionabilityNote: "The comment body is preserved. The anchor overlaps opaque content that the editor cannot safely modify.",
-      });
-      return {
-        ...thread,
-        anchor: createDetachedAnchor(anchor.range, "importAmbiguity"),
-        status: "detached",
-        metadata: {
-          ...thread.metadata,
-          detachedReason: "opaque-region",
-          actionabilityNote:
-            "The comment body is preserved. The anchor overlaps opaque content that the editor cannot safely modify.",
-        },
-      };
-    }
-
-    const preserveOnlyRevisionOverlap = preserveOnlyRevisionRanges.some((range) =>
-      rangesIntersect(range, anchor.range),
-    );
-    if (preserveOnlyRevisionOverlap) {
-      preserveOnlyCommentIds.add(thread.commentId);
-      additionalDiagnostics.push({
-        commentId: thread.commentId,
-        code: "preserve_only_revision_overlap",
-        message:
-          "Comment anchor overlaps preserve-only review markup. Thread is visible but detached; anchor cannot be safely remapped during editing.",
-        featureClass: "preserve-only",
-        detachedReason: "revision-overlap" as const,
-        actionabilityNote: "The comment body is preserved. The anchor overlaps preserve-only revision markup that the editor cannot safely modify.",
-      });
-      return {
-        ...thread,
-        anchor: createDetachedAnchor(anchor.range, "importAmbiguity"),
-        status: "detached",
-        metadata: {
-          ...thread.metadata,
-          detachedReason: "revision-overlap",
-          actionabilityNote:
-            "The comment body is preserved. The anchor overlaps preserve-only revision markup that the editor cannot safely modify.",
-        },
-      };
-    }
-
-    return thread;
-  });
-
-  return {
-    ...parsed,
-    threads: normalizedThreads,
-    diagnostics: [...parsed.diagnostics, ...additionalDiagnostics],
-    definitions: parsed.definitions,
-    preservedDefinitions: parsed.definitions.filter((definition) =>
-      preserveOnlyCommentIds.has(
-        resolveDefinitionRootCommentId(definition, parsed.definitions),
-      ),
-    ),
-  };
-}
-
-function translateClmCommentsToWorkflow(input: {
-  comments: readonly CommentThread[];
-  workflowOverlay?: WorkflowOverlay;
-  workflowMetadata?: WorkflowMetadataSnapshot;
-  timestamp: string;
-}): {
-  comments: CommentThread[];
-  workflowOverlay?: WorkflowOverlay;
-  workflowMetadata?: WorkflowMetadataSnapshot;
-} {
-  const nextComments = input.comments.map((thread) => structuredClone(thread));
-  let nextOverlay = input.workflowOverlay ? structuredClone(input.workflowOverlay) : undefined;
-  let overlayChanged = false;
-
-  for (const [index, thread] of nextComments.entries()) {
-    const directive = parseClmCommentDirective(thread);
-    if (!directive || thread.anchor.kind !== "range") {
-      continue;
-    }
-
-    if (!nextOverlay) {
-      nextOverlay = {
-        overlayVersion: "workflow-overlay/1",
-        scopes: [],
-      };
-    }
-
-    const existingScope = findExistingClmScope(nextOverlay.scopes, directive);
-    if (!existingScope) {
-      const version = getNextClmScopeVersion(nextOverlay.scopes, thread.anchor);
-      const scopeId = `clm-scope-${thread.commentId}-v${version}`;
-      const workItem = directive.tag === "TASK"
-        ? createClmWorkflowWorkItem(thread, directive.description, scopeId)
-        : undefined;
-      const scope = createClmWorkflowScope(thread, directive, version, scopeId, workItem?.workItemId);
-
-      nextOverlay.scopes = [...nextOverlay.scopes, scope];
-      if (workItem) {
-        nextOverlay.workItems = [...(nextOverlay.workItems ?? []), workItem];
-        if (!nextOverlay.activeWorkItemId) {
-          nextOverlay.activeWorkItemId = workItem.workItemId;
-        }
-      }
-      overlayChanged = true;
-    }
-
-    nextComments[index] = resolveImportedCommentThreadOnTranslation(thread, input.timestamp);
-  }
-
-  return {
-    comments: nextComments,
-    workflowOverlay: overlayChanged || input.workflowOverlay ? nextOverlay : undefined,
-    workflowMetadata: input.workflowMetadata,
-  };
-}
-
-function parseClmCommentDirective(
-  thread: CommentThread,
-): { tag: "TASK" | "READ" | "COMMENT" | "EDIT"; description: string; sourceCommentId: string; sourceCommentDurableId?: string; sourceCommentParaId?: string; mode: WorkflowScope["mode"] } | undefined {
-  if (thread.metadata?.rootParaId === undefined && thread.entries[0]?.metadata?.parentParaId) {
-    return undefined;
-  }
-  const firstMeaningfulLine = thread.entries
-    .flatMap((entry) => entry.body.split(/\r?\n/u))
-    .map((line) => line.trim())
-    .find((line) => line.length > 0);
-  if (!firstMeaningfulLine) {
-    return undefined;
-  }
-  const match = /^CLM:([A-Z]+):(.*)$/u.exec(firstMeaningfulLine);
-  if (!match) {
-    return undefined;
-  }
-  const tag = match[1] as "TASK" | "READ" | "COMMENT" | "EDIT";
-  const description = (match[2] ?? "").trim();
-  const mode = getClmWorkflowScopeMode(tag);
-  if (!mode || description.length === 0) {
-    return undefined;
-  }
-  return {
-    tag,
-    description,
-    sourceCommentId: thread.metadata?.rootOoxmlCommentId ?? thread.commentId,
-    sourceCommentDurableId: thread.entries[0]?.metadata?.durableId,
-    sourceCommentParaId: thread.metadata?.rootParaId ?? thread.entries[0]?.metadata?.paraId,
-    mode,
-  };
-}
-
-function getClmWorkflowScopeMode(tag: string): WorkflowScope["mode"] | undefined {
-  switch (tag) {
-    case "TASK":
-      return "suggest";
-    case "READ":
-      return "view";
-    case "COMMENT":
-      return "comment";
-    case "EDIT":
-      return "edit";
-    default:
-      return undefined;
-  }
-}
-
-function createClmWorkflowWorkItem(
-  thread: CommentThread,
-  description: string,
-  scopeId: string,
-): WorkflowWorkItem {
-  return {
-    workItemId: `clm-task-${thread.commentId}`,
-    title: description,
-    description,
-    status: "pending",
-    scopeIds: [scopeId],
-  };
-}
-
-function createClmWorkflowScope(
-  thread: CommentThread,
-  directive: NonNullable<ReturnType<typeof parseClmCommentDirective>>,
-  version: number,
-  scopeId: string,
-  workItemId?: string,
-): WorkflowScope {
-  if (workItemId) {
-    return {
-      scopeId,
-      version,
-      mode: directive.mode,
-      anchor: toPublicAnchorProjection(thread.anchor),
-      storyTarget: { kind: "main" },
-      workItemId,
-      label: directive.description,
-      metadata: createClmScopeMetadata(directive),
-    };
-  }
-  return {
-    scopeId,
-    version,
-    mode: directive.mode,
-    anchor: toPublicAnchorProjection(thread.anchor),
-    storyTarget: { kind: "main" },
-    label: directive.description,
-    metadata: createClmScopeMetadata(directive),
-  };
-}
-
-function createClmScopeMetadata(
-  directive: NonNullable<ReturnType<typeof parseClmCommentDirective>>,
-): WorkflowScopeMetadataField[] {
-  return [
-    {
-      key: "workblock.clm.tag",
-      valueType: "string",
-      value: directive.tag,
-    },
-    {
-      key: "workblock.clm.description",
-      valueType: "string",
-      value: directive.description,
-    },
-    {
-      key: "workblock.sourceCommentId",
-      valueType: "string",
-      value: directive.sourceCommentId,
-    },
-    ...(directive.sourceCommentDurableId
-      ? [{
-          key: "workblock.sourceCommentDurableId",
-          valueType: "string" as const,
-          value: directive.sourceCommentDurableId,
-        }]
-      : []),
-    ...(directive.sourceCommentParaId
-      ? [{
-          key: "workblock.sourceCommentParaId",
-          valueType: "string" as const,
-          value: directive.sourceCommentParaId,
-        }]
-      : []),
-  ];
-}
-
-function findExistingClmScope(
-  scopes: readonly WorkflowScope[],
-  directive: NonNullable<ReturnType<typeof parseClmCommentDirective>>,
-): WorkflowScope | undefined {
-  return scopes.find((scope) => {
-    const sourceCommentId = getWorkflowScopeMetadataValue(scope.metadata, "workblock.sourceCommentId");
-    const sourceCommentDurableId = getWorkflowScopeMetadataValue(
-      scope.metadata,
-      "workblock.sourceCommentDurableId",
-    );
-    return (
-      sourceCommentId === directive.sourceCommentId ||
-      (directive.sourceCommentDurableId !== undefined &&
-        sourceCommentDurableId === directive.sourceCommentDurableId)
-    );
-  });
-}
-
-function getWorkflowScopeMetadataValue(
-  metadata: WorkflowScope["metadata"] | undefined,
-  key: string,
-): string | undefined {
-  const field = metadata?.find((entry) => entry.key === key);
-  return typeof field?.value === "string" ? field.value : undefined;
-}
-
-function getNextClmScopeVersion(
-  scopes: readonly WorkflowScope[],
-  anchor: Extract<CommentThread["anchor"], { kind: "range" }>,
-): number {
-  const anchorRange = {
-    from: anchor.range.from,
-    to: anchor.range.to,
-  };
-  const overlappingVersions = scopes.flatMap((scope) => {
-    if (scope.anchor.kind !== "range") {
-      return [];
-    }
-    return rangesIntersect(scope.anchor, anchorRange) && typeof scope.version === "number"
-      ? [scope.version]
-      : [];
-  });
-  return overlappingVersions.length > 0 ? Math.max(...overlappingVersions) + 1 : 1;
-}
-
-function resolveImportedCommentThreadOnTranslation(
-  thread: CommentThread,
-  timestamp: string,
-): CommentThread {
-  if (thread.status === "resolved") {
-    return thread;
-  }
-  return {
-    ...thread,
-    status: thread.status === "detached" ? "detached" : "resolved",
-    resolution: thread.resolution ?? {
-      resolvedAt: timestamp,
-      resolvedBy: thread.entries[thread.entries.length - 1]?.authorId ?? thread.createdBy,
-    },
-  };
-}
-
-function resolveDefinitionRootCommentId(
-  definition: ImportedCommentDefinition,
-  definitions: readonly ImportedCommentDefinition[],
-): string {
-  if (!definition.parentParaId) {
-    return definition.commentId;
-  }
-
-  const definitionsByParaId = new Map(
-    definitions
-      .filter((candidate) => typeof candidate.paraId === "string")
-      .map((candidate) => [candidate.paraId!, candidate]),
-  );
-  const visited = new Set<string>();
-  let current: ImportedCommentDefinition | undefined = definition;
-
-  while (current?.parentParaId) {
-    if (visited.has(current.parentParaId)) {
-      break;
-    }
-    visited.add(current.parentParaId);
-    const parent = definitionsByParaId.get(current.parentParaId);
-    if (!parent) {
-      break;
-    }
-    current = parent;
-  }
-
-  return current?.commentId ?? definition.commentId;
-}
-
-function getStructuralPreserveOnlyReason(
-  revision: ReviewRevisionRecord,
-  paragraphRanges: ReadonlyArray<{ start: number; end: number }>,
-): string | undefined {
-  const form = revision.metadata.importedRevisionForm;
-  const { anchor } = revision;
-  if (!form || anchor.kind !== "range") {
-    return undefined;
-  }
-
-  if (
-    (form === "run-insertion" || form === "run-deletion") &&
-    anchor.range.from === anchor.range.to
-  ) {
-    return "Imported zero-width run revision remains preserve-only.";
-  }
-
-  if (form === "paragraph-insertion" || form === "paragraph-deletion") {
-    const paragraphBoundary = paragraphRanges.find(
-      (boundary) =>
-        boundary.end === anchor.range.from ||
-        (anchor.range.from >= boundary.start &&
-          anchor.range.from <= boundary.end),
-    );
-    return paragraphBoundary
-      ? undefined
-      : "Imported revision spans paragraph-level structure and remains preserve-only.";
-  }
-
-  const paragraphBoundary = paragraphRanges.find(
-    (boundary) =>
-      anchor.range.from >= boundary.start &&
-      anchor.range.to <= boundary.end,
-  );
-  return paragraphBoundary
-    ? undefined
-    : "Imported revision spans structural boundaries and remains preserve-only.";
-}
-
-function collectCanonicalParagraphRanges(
-  content: CanonicalDocumentEnvelope["content"],
-): Array<{ start: number; end: number }> {
-  const ranges: Array<{ start: number; end: number }> = [];
-  let cursor = 0;
-  let previousWasParagraph = false;
-
-  for (const block of content.children) {
-    if (block.type === "paragraph") {
-      if (previousWasParagraph) {
-        cursor += 1;
-      }
-      const start = cursor;
-      cursor += measureCanonicalParagraph(block);
-      ranges.push({ start, end: cursor });
-      previousWasParagraph = true;
-      continue;
-    }
-
-    cursor += 1;
-    previousWasParagraph = false;
-  }
-
-  return ranges;
-}
-
-function measureCanonicalParagraph(paragraph: CanonicalDocumentEnvelope["content"]["children"][number] & { type: "paragraph" }): number {
-  return paragraph.children.reduce<number>((size, child) => {
-    if (child.type === "text") {
-      return size + Array.from(child.text).length;
-    }
-    if (child.type === "hyperlink") {
-      return (
-        size +
-        child.children.reduce<number>((childSize, entry) => {
-          if (entry.type === "text") {
-            return childSize + Array.from(entry.text).length;
-          }
-          return childSize + 1;
-        }, 0)
-      );
-    }
-    return size + 1;
-  }, 0);
-}
-
-function rangesIntersect(
-  left: { from: number; to: number },
-  right: { from: number; to: number },
-): boolean {
-  return left.from < right.to && right.from < left.to;
-}
-
-function resolveCommentsPartPath(
-  sourcePackage: OpcPackage,
-  sourceDocumentPartPath: string,
-  relationships: readonly OpcRelationship[],
-): string | undefined {
-  return resolveDocumentRelatedPartPath(
-    sourcePackage,
-    sourceDocumentPartPath,
-    relationships,
-    COMMENTS_RELATIONSHIP_TYPE,
-    COMMENTS_PART_PATH,
-  );
-}
-
-function resolveDocumentRelatedPartPath(
-  sourcePackage: OpcPackage,
-  sourceDocumentPartPath: string,
-  relationships: readonly OpcRelationship[],
-  relationshipType: string,
-  fallbackPartPath: string,
-): string | undefined {
-  const relationship = relationships.find(
-    (candidate) =>
-      candidate.type === relationshipType &&
-      candidate.targetMode === "internal",
-  );
-  if (!relationship) {
-    return sourcePackage.parts.has(fallbackPartPath) ? fallbackPartPath : undefined;
-  }
-
-  const targetPath = resolveRelationshipTarget(sourceDocumentPartPath, relationship);
-  return sourcePackage.parts.has(targetPath) ? targetPath : undefined;
-}
-
-function resolveMainDocumentPartPath(sourcePackage: OpcPackage): string | undefined {
-  const relationship = sourcePackage.manifest.packageRelationships.find(
-    (candidate) =>
-      candidate.type === OFFICE_DOCUMENT_RELATIONSHIP_TYPE &&
-      candidate.targetMode === "internal",
-  );
-  if (relationship) {
-    return resolveRelationshipTarget(null, relationship);
-  }
-
-  return sourcePackage.parts.has(MAIN_DOCUMENT_PATH) ? MAIN_DOCUMENT_PATH : undefined;
-}
-
-function toRuntimeCommentRecords(
-  threads: readonly CommentThread[],
-): Record<string, CommentThreadRecord> {
-  return Object.fromEntries(
-    threads.map((thread) => {
-      return [
-        thread.commentId,
-        {
-          commentId: thread.commentId,
-          body: thread.entries.map((entry) => entry.body).join("\n"),
-          anchor: thread.anchor,
-          createdBy: thread.createdBy,
-          authorId: thread.createdBy,
-          createdAt: thread.createdAt,
-          entries: thread.entries.map((entry) => ({
-            entryId: entry.entryId,
-            authorId: entry.authorId,
-            body: entry.body,
-            createdAt: entry.createdAt,
-            metadata: entry.metadata
-              ? {
-                  ooxmlCommentId: entry.metadata.ooxmlCommentId,
-                  paraId: entry.metadata.paraId,
-                  parentParaId: entry.metadata.parentParaId,
-                  durableId: entry.metadata.durableId,
-                  initials: entry.metadata.initials,
-                }
-              : undefined,
-          })),
-          status: thread.status,
-          resolution: thread.resolution
-            ? {
-                resolvedAt: thread.resolution.resolvedAt,
-                resolvedBy: thread.resolution.resolvedBy,
-              }
-            : undefined,
-          resolvedAt: thread.resolution?.resolvedAt,
-          warningIds: [...thread.warningIds],
-          isResolved: thread.status === "resolved",
-          metadata: thread.metadata
-            ? {
-                source: thread.metadata.source,
-                rootOoxmlCommentId: thread.metadata.rootOoxmlCommentId,
-                rootParaId: thread.metadata.rootParaId,
-              }
-            : undefined,
-        } satisfies CommentThreadRecord,
-      ];
-    }),
-  );
-}
-
-function toRuntimeRevisionRecords(
-  revisions: readonly ReviewRevisionRecord[],
-): Record<string, RuntimeRevisionRecord> {
-  return Object.fromEntries(
-    revisions.map((revision) => [
-      revision.revisionId,
-      {
-        changeId: revision.revisionId,
-        kind: revision.kind,
-        anchor: revision.anchor,
-        authorId: revision.authorId,
-        createdAt: revision.createdAt,
-        warningIds: [...revision.warningIds],
-        metadata: {
-          source: revision.metadata.source,
-          storyTarget: revision.metadata.storyTarget,
-          preserveOnlyReason: revision.metadata.preserveOnlyReason,
-          suggestionId: revision.metadata.suggestionId,
-          semanticKind: revision.metadata.semanticKind,
-          linkedRevisionIds: revision.metadata.linkedRevisionIds,
-          predecessorSuggestionId: revision.metadata.predecessorSuggestionId,
-          importedRevisionForm: revision.metadata.importedRevisionForm,
-          originalRevisionType: revision.metadata.originalRevisionType,
-          ooxmlRevisionId: revision.metadata.ooxmlRevisionId,
-          propertyChangeData: revision.metadata.propertyChangeData,
-          moveData: revision.metadata.moveData,
-        },
-        status: revision.status === "active" ? "open" : revision.status,
-      } satisfies RuntimeRevisionRecord,
-    ]),
-  );
-}
-
-function toReviewRevisionRecords(
-  revisions: CanonicalDocumentEnvelope["review"]["revisions"],
-): ReviewRevisionRecord[] {
-  return Object.values(revisions).map((revision) => ({
-    revisionId: revision.changeId,
-    kind: revision.kind,
-    anchor: revision.anchor,
-    authorId: revision.authorId ?? "unknown",
-    createdAt: revision.createdAt,
-    warningIds: [...(revision.warningIds ?? [])],
-    metadata: {
-      source: revision.metadata?.source ?? "runtime",
-      storyTarget: revision.metadata?.storyTarget,
-      preserveOnlyReason: revision.metadata?.preserveOnlyReason,
-      suggestionId: revision.metadata?.suggestionId,
-      semanticKind: revision.metadata?.semanticKind,
-      linkedRevisionIds: revision.metadata?.linkedRevisionIds,
-      predecessorSuggestionId: revision.metadata?.predecessorSuggestionId,
-      importedRevisionForm: revision.metadata?.importedRevisionForm,
-      originalRevisionType: revision.metadata?.originalRevisionType,
-      ooxmlRevisionId: revision.metadata?.ooxmlRevisionId,
-      propertyChangeData: revision.metadata?.propertyChangeData,
-      moveData: revision.metadata?.moveData,
-    },
-    status: revision.status === "open" ? "active" : revision.status,
-  }));
-}
-
-function serializeSecondaryStoryWithRuntimeRevisions(
-  xml: string,
-  revisions: readonly ReviewRevisionRecord[],
-  label: string,
-): string {
-  if (revisions.length === 0) {
-    return xml;
-  }
-
-  const serialized = serializeRuntimeRevisionsIntoStoryXml(xml, revisions);
-  if (serialized.skippedRevisionIds.length > 0) {
-    throw new Error(
-      `DOCX export is blocked because ${serialized.skippedRevisionIds.length} active revisions overlap unsupported serialization boundaries in ${label}.`,
-    );
-  }
-  return serialized.documentXml;
-}
-
-export function stripCommentMarkup(
-  documentXml: string,
-  ownedCommentIds: readonly string[],
-): string {
-  if (ownedCommentIds.length === 0) {
-    return documentXml;
-  }
-
-  let output = documentXml;
-  for (const commentId of ownedCommentIds) {
-    const escapedCommentId = escapeRegExp(commentId);
-    const attributePattern = `(?:w:id|id)=["']${escapedCommentId}["']`;
-    output = output
-      .replace(
-        new RegExp(`<w:commentRangeStart\\b[^>]*${attributePattern}[^>]*/>`, "gu"),
-        "",
-      )
-      .replace(
-        new RegExp(`<w:commentRangeEnd\\b[^>]*${attributePattern}[^>]*/>`, "gu"),
-        "",
-      )
-      .replace(
-        new RegExp(
-          `<w:r\\b[^>]*>(?:(?!<w:t\\b|</w:r>)[\\s\\S])*?<w:commentReference\\b[^>]*${attributePattern}[^>]*/>(?:(?!<w:t\\b|</w:r>)[\\s\\S])*?</w:r>`,
-          "gu",
-        ),
-        "",
-      );
-  }
-
-  return output;
-}
-
-function escapeRegExp(value: string): string {
-  return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
-}
-
-function withDocumentRelatedParts(
-  relationships: readonly OpcRelationship[],
-  relatedParts: ReadonlyArray<{
-    relationshipType: string;
-    partPath: string;
-    existingRelationshipId?: string;
-    include: boolean;
-  }>,
-): OpcRelationship[] {
-  const filteredTypes = new Set(relatedParts.map((part) => part.relationshipType));
-  const nextRelationships = relationships
-    .filter((relationship) => !filteredTypes.has(relationship.type))
-    .map(cloneRelationship);
-
-  for (const part of relatedParts) {
-    if (!part.include) {
-      continue;
-    }
-
-    nextRelationships.push({
-      id: part.existingRelationshipId ?? createCommentsRelationshipId(nextRelationships),
-      type: part.relationshipType,
-      target: toDocumentRelativeTarget(part.partPath),
-      targetMode: "internal",
-    });
-  }
-
-  return nextRelationships;
-}
-
-function collectPreservedPackageParts(
-  sourcePackage: OpcPackage,
-  ownedPartPaths: ReadonlyArray<string | undefined>,
-): Record<string, PreservedPackagePart> {
-  const normalizedOwnedPaths = new Set(
-    ownedPartPaths
-      .filter((value): value is string => typeof value === "string")
-      .map((path) => normalizePartPath(path)),
-  );
-  return Object.fromEntries(
-    [...sourcePackage.parts.values()]
-      .filter((part) =>
-        shouldPreservePackagePart(part.path, part.surfaceKind, normalizedOwnedPaths),
-      )
-      .map((part) => [
-        part.path,
-        {
-          packagePartName: part.path,
-          contentType: part.contentType ?? "application/octet-stream",
-          relationshipIds: findRelationshipIdsTargetingPart(sourcePackage, part.path),
-        } satisfies PreservedPackagePart,
-      ]),
-  );
-}
-
-function collectInlineMediaParts(
-  sourcePackage: OpcPackage,
-): ReadonlyMap<string, { path: string; contentType: string }> {
-  return new Map(
-    [...sourcePackage.parts.values()]
-      .filter(
-        (part) =>
-          part.path.startsWith("/word/media/") && typeof part.contentType === "string",
-      )
-      .map((part) => [
-        part.path,
-        {
-          path: part.path,
-          contentType: part.contentType ?? "application/octet-stream",
-        },
-      ]),
-  );
-}
-
-function createEmptyNumberingCatalog(): NumberingCatalog {
-  return {
-    abstractDefinitions: {},
-    instances: {},
-  };
-}
-
-function collectBrokenInternalRelationshipIssues(
-  sourcePackage: OpcPackage,
-  mainDocumentPath?: string,
-): ReturnType<typeof createBrokenRelationshipIssue>[] {
-  const brokenTargets = new Map<string, ReturnType<typeof createBrokenRelationshipIssue>>();
-
-  for (const relationship of sourcePackage.manifest.packageRelationships) {
-    if (relationship.targetMode !== "internal") {
-      continue;
-    }
-
-    const target = resolveRelationshipTarget(null, relationship);
-    if (
-      !sourcePackage.parts.has(target) &&
-      isFatalBrokenRelationship({
-        relationshipSourcePath: null,
-        relationship,
-        targetPartPath: target,
-        mainDocumentPath,
-      })
-    ) {
-      brokenTargets.set(
-        `package:${relationship.id}:${target}`,
-        createBrokenRelationshipIssue({
-          relationshipSourcePath: null,
-          relationshipId: relationship.id,
-          targetPartPath: target,
-        }),
-      );
-    }
-  }
-
-  for (const part of sourcePackage.parts.values()) {
-    for (const relationship of part.relationships) {
-      if (relationship.targetMode !== "internal") {
-        continue;
-      }
-
-      const target = resolveRelationshipTarget(part.path, relationship);
-      if (
-        !sourcePackage.parts.has(target) &&
-        isFatalBrokenRelationship({
-          relationshipSourcePath: part.path,
-          relationship,
-          targetPartPath: target,
-          mainDocumentPath,
-        })
-      ) {
-        brokenTargets.set(
-          `${part.path}:${relationship.id}:${target}`,
-          createBrokenRelationshipIssue({
-            relationshipSourcePath: part.path,
-            relationshipId: relationship.id,
-            targetPartPath: target,
-          }),
-        );
-      }
-    }
-  }
-
-  return [...brokenTargets.values()].sort((left, right) =>
-    `${left.relationshipSourcePath ?? ""}:${left.relationshipId}:${left.targetPartPath}`.localeCompare(
-      `${right.relationshipSourcePath ?? ""}:${right.relationshipId}:${right.targetPartPath}`,
-    ),
-  );
-}
-
-function summarizeBrokenRelationshipIssues(
-  issues: readonly ReturnType<typeof createBrokenRelationshipIssue>[],
-): string {
-  return `DOCX package has unresolved internal relationships: ${issues
-    .map((issue) => issue.targetPartPath ?? issue.message)
-    .slice(0, 3)
-    .join(", ")}${issues.length > 3 ? ", ..." : ""}.`;
-}
-
-function createBrokenRelationshipWarnings(
-  sourcePackage: OpcPackage,
-  mainDocumentPath?: string,
-): CanonicalDocumentEnvelope["diagnostics"]["warnings"] {
-  const warnings = new Map<string, CanonicalDocumentEnvelope["diagnostics"]["warnings"][number]>();
-
-  for (const relationship of sourcePackage.manifest.packageRelationships) {
-    if (relationship.targetMode !== "internal") {
-      continue;
-    }
-
-    const target = resolveRelationshipTarget(null, relationship);
-    if (
-      sourcePackage.parts.has(target) ||
-      isFatalBrokenRelationship({
-        relationshipSourcePath: null,
-        relationship,
-        targetPartPath: target,
-        mainDocumentPath,
-      })
-    ) {
-      continue;
-    }
-
-    warnings.set(`package:${relationship.id}:${target}`, {
-      diagnosticId: `diagnostic:broken-relationship-package-${relationship.id}`,
-      warningId: `warning:broken-relationship:${relationship.id}`,
-      source: "preservation",
-      message: `DOCX package has unresolved internal relationships outside the editor-owned graph: ${target}.`,
-    });
-  }
-
-  for (const part of sourcePackage.parts.values()) {
-    for (const relationship of part.relationships) {
-      if (relationship.targetMode !== "internal") {
-        continue;
-      }
-
-      const target = resolveRelationshipTarget(part.path, relationship);
-      if (
-        sourcePackage.parts.has(target) ||
-        isFatalBrokenRelationship({
-          relationshipSourcePath: part.path,
-          relationship,
-          targetPartPath: target,
-          mainDocumentPath,
-        })
-      ) {
-        continue;
-      }
-
-      warnings.set(`${part.path}:${relationship.id}:${target}`, {
-        diagnosticId: `diagnostic:broken-relationship-${relationship.id}`,
-        warningId: `warning:broken-relationship:${relationship.id}`,
-        source: "preservation",
-        message: `DOCX package has unresolved internal relationships outside the editor-owned graph: ${target}.`,
-      });
-    }
-  }
-
-  return [...warnings.values()];
-}
-
-function isFatalBrokenRelationship(input: {
-  relationshipSourcePath: string | null;
-  relationship: OpcRelationship;
-  targetPartPath: string;
-  mainDocumentPath?: string;
-}): boolean {
-  return (
-    input.relationshipSourcePath === null &&
-    input.relationship.type === OFFICE_DOCUMENT_RELATIONSHIP_TYPE &&
-    input.targetPartPath === input.mainDocumentPath
-  );
-}
-
-function shouldPreservePackagePart(
-  partPath: string,
-  surfaceKind: OpcPackage["parts"] extends Map<string, infer T>
-    ? T extends { surfaceKind: infer U }
-      ? U
-      : never
-    : never,
-  ownedPartPaths: ReadonlySet<string>,
-): boolean {
-  if (surfaceKind !== "content") {
-    return false;
-  }
-
-  if (
-    ownedPartPaths.has(partPath) ||
-    partPath.startsWith("/word/media/") ||
-    CORE_NON_PRESERVED_PART_PATHS.has(partPath)
-  ) {
-    return false;
-  }
-
-  return true;
-}
-
-function findRelationshipIdsTargetingPart(
-  sourcePackage: OpcPackage,
-  targetPartPath: string,
-): string[] {
-  const ids = new Set<string>();
-
-  for (const relationship of sourcePackage.manifest.packageRelationships) {
-    if (
-      relationship.targetMode === "internal" &&
-      resolveRelationshipTarget(null, relationship) === targetPartPath
-    ) {
-      ids.add(relationship.id);
-    }
-  }
-
-  for (const part of sourcePackage.parts.values()) {
-    for (const relationship of part.relationships) {
-      if (
-        relationship.targetMode === "internal" &&
-        resolveRelationshipTarget(part.path, relationship) === targetPartPath
-      ) {
-        ids.add(relationship.id);
-      }
-    }
-  }
-
-  return [...ids].sort();
-}
-
-function extractDocumentRootAttributes(documentXml: string): Record<string, string> {
-  const match = documentXml.match(
-    /<(?:[A-Za-z_][A-Za-z0-9:._-]*:)?document\b([^>]*)>/u,
-  );
-  if (!match) {
-    return {};
-  }
-
-  const attributes: Record<string, string> = {};
-  const pattern = /([A-Za-z_][A-Za-z0-9:._-]*)\s*=\s*("([^"]*)"|'([^']*)')/gu;
-  for (const attributeMatch of (match[1] ?? "").matchAll(pattern)) {
-    const name = attributeMatch[1];
-    const value = attributeMatch[3] ?? attributeMatch[4] ?? "";
-    if (!name) {
-      continue;
-    }
-    attributes[name] = value;
-  }
-
-  return attributes;
-}
-
-function isPackageImportError(error: unknown): boolean {
-  if (!(error instanceof Error)) {
-    return false;
-  }
-
-  const normalized = error.message.toLowerCase();
-  return (
-    normalized.includes("zip") ||
-    normalized.includes("opc package") ||
-    normalized.includes("compression") ||
-    normalized.includes("relationship") ||
-    normalized.includes("/[content_types].xml") ||
-    normalized.includes("/word/document.xml") ||
-    normalized.includes("xml")
-  );
-}
-
-const CORE_NON_PRESERVED_PART_PATHS = new Set([
-  "/docProps/app.xml",
-  "/docProps/core.xml",
-  "/word/numbering.xml",
-]);
-
-function createCommentsRelationshipId(
-  relationships: readonly OpcRelationship[],
-): string {
-  let nextIndex = 1;
-  while (relationships.some((relationship) => relationship.id === `rIdComments${nextIndex}`)) {
-    nextIndex += 1;
-  }
-
-  return `rIdComments${nextIndex}`;
-}
-
-function toDocumentRelativeTarget(partPath: string): string {
-  const normalized = normalizePartPath(partPath);
-  return normalized.startsWith("/word/") ? normalized.slice("/word/".length) : normalized.slice(1);
-}
-
-function cloneRelationship(relationship: OpcRelationship): OpcRelationship {
-  return { ...relationship };
-}
-
-const UTF8_DECODER = new TextDecoder("utf-8");
-
-function decodeUtf8(bytes: Uint8Array | undefined): string {
-  if (!bytes) {
-    return "";
-  }
-
-  return UTF8_DECODER.decode(bytes);
-}
-
-function toUint8Array(bytes: Uint8Array | ArrayBuffer): Uint8Array {
-  return bytes instanceof Uint8Array ? bytes : new Uint8Array(bytes);
-}
-
-function serializeCanonicalDocumentForExport(document: CanonicalDocumentEnvelope): string {
-  return createCanonicalDocumentSignature({
-    ...document,
-    docId: "__export__",
-    createdAt: "__export__",
-    updatedAt: "__export__",
-  });
-}
-
-/**
- * Read a Node-style environment variable without referencing the Node-only
- * `process` global in the production build (which excludes @types/node).
- * Returns `undefined` in browser environments or when the var is unset.
- */
-function readNodeEnvVar(name: string): string | undefined {
-  const proc = (globalThis as unknown as {
-    process?: { env?: Record<string, string | undefined> };
-  }).process;
-  return proc?.env?.[name];
-}
-
-function canReuseSourceBytesForCurrentDocument(
-  state: ImportedDocxState,
-  document: CanonicalDocumentEnvelope,
-): boolean {
-  // The validator-loop CI harness (§1 / §7) needs to exercise the full
-  // serializer pipeline — including A.1 / A.2 / A.3 / A.6 / A.7 / A.8 /
-  // A.9 fixes — so it sets DOCX_VALIDATOR_FORCE_REGEN=1 to disable the
-  // fast-path byte-reuse. Never set this flag in production; it forces a
-  // full XML regeneration on every export and is only used by the CCEP
-  // validator harness to prove our serializer's correctness.
-  if (readNodeEnvVar("DOCX_VALIDATOR_FORCE_REGEN") === "1") {
-    return false;
-  }
-  if (requiresHostMetadataNormalization(state.sourcePackage, state.sourceDocumentPartPath)) {
-    return false;
-  }
-
-  const commentThreads = Object.values(document.review.comments);
-  const hasLiveComments = commentThreads.some((thread) => thread.anchor.kind !== "detached");
-  const hasRuntimeAuthoredActiveRevisions = Object.values(document.review.revisions).some((revision) =>
-    revision.status === "open" && revision.metadata?.source === "runtime"
-  );
-  if (hasRuntimeAuthoredActiveRevisions) {
-    return false;
-  }
-  if (!hasLiveComments) {
-    return true;
-  }
-
-  return Boolean(
-    state.sourceCommentsPartPath &&
-      state.sourceCommentsExtendedPartPath &&
-      state.sourceCommentsIdsPartPath &&
-      state.sourcePeoplePartPath,
-  );
-}
-
-function requiresHostMetadataNormalization(
-  sourcePackage: OpcPackage,
-  sourceDocumentPartPath: string,
-): boolean {
-  return (
-    isSuspiciouslySkeletalWordPackage(sourcePackage, sourceDocumentPartPath) &&
-    !hasHostSafeMetadataPackageStructure(sourcePackage)
-  );
-}
-
-function ensureHostMetadataParts(
-  exportSession: ReturnType<typeof createExportSession>,
-  sourcePackage: OpcPackage,
-  document: CanonicalDocumentEnvelope,
-): void {
-  const corePropertiesPart = sourcePackage.parts.get(CORE_PROPERTIES_PART_PATH);
-  if (!corePropertiesPart || corePropertiesPart.contentType !== CORE_PROPERTIES_CONTENT_TYPE) {
-    exportSession.replaceOwnedPart({
-      path: CORE_PROPERTIES_PART_PATH,
-      bytes: corePropertiesPart?.bytes ?? new TextEncoder().encode(buildCorePropertiesXml(document)),
-      contentType: CORE_PROPERTIES_CONTENT_TYPE,
-      compression: corePropertiesPart?.compression,
-    });
-  }
-
-  const appPropertiesPart = sourcePackage.parts.get(APP_PROPERTIES_PART_PATH);
-  if (!appPropertiesPart || appPropertiesPart.contentType !== APP_PROPERTIES_CONTENT_TYPE) {
-    exportSession.replaceOwnedPart({
-      path: APP_PROPERTIES_PART_PATH,
-      bytes: appPropertiesPart?.bytes ?? new TextEncoder().encode(buildAppPropertiesXml()),
-      contentType: APP_PROPERTIES_CONTENT_TYPE,
-      compression: appPropertiesPart?.compression,
-    });
-  }
-
-  exportSession.ensurePackageRelationship({
-    type: CORE_PROPERTIES_RELATIONSHIP_TYPE,
-    target: CORE_PROPERTIES_PART_PATH,
-    preferredId: "rIdDocPropsCore",
-  });
-  exportSession.ensurePackageRelationship({
-    type: APP_PROPERTIES_RELATIONSHIP_TYPE,
-    target: APP_PROPERTIES_PART_PATH,
-    preferredId: "rIdDocPropsApp",
-  });
-}
-
-function ensureWorkflowPayloadParts(
-  exportSession: ReturnType<typeof createExportSession>,
-  sessionState: EditorSessionState,
-  document: CanonicalDocumentEnvelope,
-  sourcePackage: OpcPackage,
-  resolvedPartPaths: {
-    payloadPartPath: string;
-    itemPropsPartPath: string;
-  },
-  editorState?: import("./ooxml/workflow-payload.ts").EditorStatePayload,
-): void {
-  const payloadParts = buildWorkflowPayloadParts({
-    sourcePackage,
-    workflowMetadata: sessionState.workflowMetadata,
-    workflowOverlay: sessionState.workflowOverlay,
-    editorState,
-    documentId: sessionState.documentId,
-    createdAt: document.createdAt,
-    updatedAt: document.updatedAt,
-    producerVersion: sessionState.editorBuild,
-  });
-  if (!payloadParts) {
-    return;
-  }
-  if (
-    payloadParts.payloadPartPath !== resolvedPartPaths.payloadPartPath ||
-    payloadParts.itemPropsPartPath !== resolvedPartPaths.itemPropsPartPath
-  ) {
-    throw new Error(
-      "Workflow payload export resolved inconsistent customXml paths; export session ownership no longer matches payload serialization.",
-    );
-  }
-
-  const payloadPart = sourcePackage.parts.get(payloadParts.payloadPartPath);
-  const itemPropsPart = sourcePackage.parts.get(payloadParts.itemPropsPartPath);
-  const customPropsPart = sourcePackage.parts.get(WORKFLOW_PAYLOAD_CUSTOM_PROPS_PART_PATH);
-
-  exportSession.replaceOwnedPart({
-    path: payloadParts.payloadPartPath,
-    bytes: new TextEncoder().encode(payloadParts.payloadPartXml),
-    contentType: payloadPart?.contentType ?? WORKFLOW_PAYLOAD_CONTENT_TYPE,
-    relationships: payloadParts.payloadRelationships,
-    compression: payloadPart?.compression,
-  });
-  exportSession.replaceOwnedPart({
-    path: payloadParts.itemPropsPartPath,
-    bytes: new TextEncoder().encode(payloadParts.itemPropsXml),
-    contentType: itemPropsPart?.contentType ?? WORKFLOW_PAYLOAD_ITEM_PROPS_CONTENT_TYPE,
-    compression: itemPropsPart?.compression,
-  });
-  exportSession.replaceOwnedPart({
-    path: WORKFLOW_PAYLOAD_CUSTOM_PROPS_PART_PATH,
-    bytes: new TextEncoder().encode(payloadParts.customPropertiesXml),
-    contentType: customPropsPart?.contentType ?? WORKFLOW_PAYLOAD_CUSTOM_PROPS_CONTENT_TYPE,
-    compression: customPropsPart?.compression,
-  });
-
-  exportSession.ensurePackageRelationship({
-    type: WORKFLOW_PAYLOAD_CUSTOM_PROPS_RELATIONSHIP_TYPE,
-    target: WORKFLOW_PAYLOAD_CUSTOM_PROPS_PART_PATH,
-    preferredId: "rIdBwWorkflowCustomProps",
-  });
-}
-
-function hasHostSafeMetadataPackageStructure(sourcePackage: OpcPackage): boolean {
-  const corePropertiesPart = sourcePackage.parts.get(CORE_PROPERTIES_PART_PATH);
-  const appPropertiesPart = sourcePackage.parts.get(APP_PROPERTIES_PART_PATH);
-  return (
-    corePropertiesPart?.contentType === CORE_PROPERTIES_CONTENT_TYPE &&
-    appPropertiesPart?.contentType === APP_PROPERTIES_CONTENT_TYPE &&
-    hasPackageRelationshipTarget(
-      sourcePackage,
-      CORE_PROPERTIES_RELATIONSHIP_TYPE,
-      CORE_PROPERTIES_PART_PATH,
-    ) &&
-    hasPackageRelationshipTarget(
-      sourcePackage,
-      APP_PROPERTIES_RELATIONSHIP_TYPE,
-      APP_PROPERTIES_PART_PATH,
-    )
-  );
-}
-
-function hasPackageRelationshipTarget(
-  sourcePackage: OpcPackage,
-  relationshipType: string,
-  targetPartPath: string,
-): boolean {
-  return sourcePackage.manifest.packageRelationships.some(
-    (relationship) =>
-      relationship.type === relationshipType &&
-      relationship.targetMode === "internal" &&
-      resolveRelationshipTarget(null, relationship) === targetPartPath,
-  );
-}
-
-function isSuspiciouslySkeletalWordPackage(
-  sourcePackage: OpcPackage,
-  sourceDocumentPartPath: string,
-): boolean {
-  const allowedPaths = new Set<string>([
-    CONTENT_TYPES_PATH,
-    PACKAGE_RELATIONSHIPS_PATH,
-    sourceDocumentPartPath,
-  ]);
-  const relationshipsPartPath = getRelationshipsPartPath(sourceDocumentPartPath);
-  if (relationshipsPartPath) {
-    allowedPaths.add(relationshipsPartPath);
-  }
-
-  return [...sourcePackage.parts.keys()].every((partPath) => allowedPaths.has(partPath));
-}
-
-function buildCorePropertiesXml(document: CanonicalDocumentEnvelope): string {
-  const { metadata } = document;
-  const keywords =
-    Array.isArray(metadata.keywords) && metadata.keywords.length > 0
-      ? metadata.keywords.join(", ")
-      : undefined;
-  const propertyLines = [
-    xmlNode("dc:title", metadata.title),
-    xmlNode("dc:subject", metadata.subject),
-    xmlNode("dc:description", metadata.description),
-    xmlNode("dc:language", metadata.language),
-    xmlNode("cp:keywords", keywords),
-    xmlNode("cp:category", metadata.category),
-    xmlNode('dcterms:created xsi:type="dcterms:W3CDTF"', document.createdAt),
-    xmlNode('dcterms:modified xsi:type="dcterms:W3CDTF"', document.updatedAt),
-  ].filter((line): line is string => Boolean(line));
-
-  return [
-    `<?xml version="1.0" encoding="UTF-8" standalone="yes"?>`,
-    `<cp:coreProperties xmlns:cp="http://schemas.openxmlformats.org/package/2006/metadata/core-properties" xmlns:dc="http://purl.org/dc/elements/1.1/" xmlns:dcterms="http://purl.org/dc/terms/" xmlns:dcmitype="http://purl.org/dc/dcmitype/" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">`,
-    ...propertyLines.map((line) => `  ${line}`),
-    `</cp:coreProperties>`,
-  ].join("\n");
-}
-
-// buildAppPropertiesXml moved to src/io/export/build-app-properties-xml.ts
-// per close-render-fidelity §2 A.5. Re-import as `buildAppPropertiesXmlFn`.
-
-function xmlNode(tagName: string, value: string | undefined): string | undefined {
-  if (typeof value !== "string" || value.length === 0) {
-    return undefined;
-  }
-
-  return `<${tagName}>${escapeXml(value)}</${tagName.split(" ", 1)[0]}>`;
-}
-
-function serializeProtectionRangesIntoDocumentXml(
-  documentXml: string,
-  protection: ProtectionSnapshot,
-  paragraphs = mapParagraphBoundaries(documentXml),
-): string {
-  if (protection.ranges.length === 0) {
-    return documentXml;
-  }
-
-  const insertions = new Map<number, string[]>();
-
-  for (const range of protection.ranges) {
-    if (typeof range.start !== "number" || typeof range.end !== "number") {
-      continue;
-    }
-    const rangeStart = range.start;
-    const rangeEnd = range.end;
-
-    const startParagraph = paragraphs.find(
-      (candidate) => rangeStart >= candidate.start && rangeStart <= candidate.end,
-    );
-    const endParagraph = paragraphs.find(
-      (candidate) => rangeEnd >= candidate.start && rangeEnd <= candidate.end,
-    );
-    if (!startParagraph || !endParagraph) {
-      continue;
-    }
-
-    const startIndex =
-      startParagraph.boundaries.get(rangeStart) ??
-      findNearestBoundaryIndex(startParagraph.boundaries, rangeStart, "backward");
-    const endIndex =
-      endParagraph.boundaries.get(rangeEnd) ??
-      findNearestBoundaryIndex(endParagraph.boundaries, rangeEnd, "forward");
-    if (startIndex === undefined || endIndex === undefined) {
-      continue;
-    }
-
-    const permStartXml = [
-      `<w:permStart`,
-      ` w:id="${escapeXmlAttribute(range.rangeId)}"`,
-      range.editorGroup ? ` w:edGrp="${escapeXmlAttribute(range.editorGroup)}"` : "",
-      range.editor ? ` w:ed="${escapeXmlAttribute(range.editor)}"` : "",
-      `/>`,
-    ].join("");
-    const permEndXml = `<w:permEnd w:id="${escapeXmlAttribute(range.rangeId)}"/>`;
-
-    pushProtectionInsertion(insertions, startIndex, permStartXml);
-    pushProtectionInsertion(insertions, endIndex, permEndXml);
-  }
-
-  if (insertions.size === 0) {
-    return documentXml;
-  }
-
-  const parts: string[] = [];
-  let cursor = 0;
-  for (const [index, snippets] of [...insertions.entries()].sort(([left], [right]) => left - right)) {
-    parts.push(documentXml.slice(cursor, index));
-    parts.push(...snippets);
-    cursor = index;
-  }
-  parts.push(documentXml.slice(cursor));
-  return parts.join("");
-}
-
-function pushProtectionInsertion(
-  insertions: Map<number, string[]>,
-  index: number,
-  xml: string,
-): void {
-  const existing = insertions.get(index);
-  if (existing) {
-    existing.push(xml);
-    return;
-  }
-  insertions.set(index, [xml]);
-}
-
-function findNearestBoundaryIndex(
-  boundaries: Map<number, number>,
-  position: number,
-  direction: "backward" | "forward",
-): number | undefined {
-  const ordered = [...boundaries.entries()].sort(([left], [right]) => left - right);
-  if (direction === "backward") {
-    for (let index = ordered.length - 1; index >= 0; index -= 1) {
-      const [boundaryPos, boundaryIndex] = ordered[index]!;
-      if (boundaryPos <= position) {
-        return boundaryIndex;
-      }
-    }
-    return undefined;
-  }
-  for (const [boundaryPos, boundaryIndex] of ordered) {
-    if (boundaryPos >= position) {
-      return boundaryIndex;
-    }
-  }
-  return undefined;
-}
-
-function escapeXml(value: string): string {
-  return value
-    .replace(/&/g, "&amp;")
-    .replace(/</g, "&lt;")
-    .replace(/>/g, "&gt;")
-    .replace(/\"/g, "&quot;")
-    .replace(/'/g, "&apos;");
-}
-
-function escapeXmlAttribute(value: string): string {
-  return value
-    .replace(/&/g, "&amp;")
-    .replace(/</g, "&lt;")
-    .replace(/>/g, "&gt;")
-    .replace(/"/g, "&quot;");
-}
-
-// ---------------------------------------------------------------------------
-// Protection range extraction
-// ---------------------------------------------------------------------------
-
-const EMPTY_PROTECTION_SNAPSHOT: ProtectionSnapshot = {
-  hasDocumentProtection: false,
-  enforcementActive: false,
-  ranges: [],
-  enforcedRangeCount: 0,
-  preservedRangeCount: 0,
-};
-
-interface DocumentProtectionMeta {
-  editType?: string;
-  enforcement: boolean;
-}
-
-function extractDocumentProtection(settingsXml: string): DocumentProtectionMeta {
-  if (!settingsXml) return { enforcement: false };
-  const match = settingsXml.match(/<w:documentProtection\b([^/>]*)\/?>/);
-  if (!match) return { enforcement: false };
-  const attrs = match[1];
-  const editTypeMatch = attrs.match(/w:edit="([^"]*)"/);
-  const enforcementMatch = attrs.match(/w:enforcement="([^"]*)"/);
-  const editType = editTypeMatch?.[1];
-  const enforcement = enforcementMatch?.[1] === "1" || enforcementMatch?.[1] === "true";
-  return { editType, enforcement };
-}
-
-function extractProtectionRanges(blocks: readonly ParsedBlockNode[]): ProtectionRange[] {
-  const ranges: ProtectionRange[] = [];
-  const openRanges = new Map<string, Omit<ProtectionRange, "end">>();
-  collectProtectionRangesFromBlocks(blocks, ranges, openRanges, 0);
-  return ranges;
-}
-
-function collectProtectionRangesFromBlocks(
-  blocks: readonly ParsedBlockNode[],
-  ranges: ProtectionRange[],
-  openRanges: Map<string, Omit<ProtectionRange, "end">>,
-  cursor: number,
-): number {
-  let nextCursor = cursor;
-  let previousParagraph = false;
-
-  for (const block of blocks) {
-    if (block.type === "paragraph") {
-      if (previousParagraph) {
-        nextCursor += 1;
-      }
-      nextCursor = collectProtectionRangesFromInlines(
-        block.children,
-        ranges,
-        openRanges,
-        nextCursor,
-      );
-      previousParagraph = true;
-      continue;
-    }
-
-    if (block.type === "table") {
-      nextCursor += 1;
-      previousParagraph = false;
-      for (const row of block.rows) {
-        for (const cell of row.cells) {
-          nextCursor = collectProtectionRangesFromBlocks(
-            cell.children,
-            ranges,
-            openRanges,
-            nextCursor,
-          );
-        }
-      }
-      continue;
-    }
-
-    if (block.type === "sdt" || block.type === "custom_xml") {
-      nextCursor = collectProtectionRangesFromBlocks(
-        block.children,
-        ranges,
-        openRanges,
-        nextCursor,
-      );
-      previousParagraph = false;
-      continue;
-    }
-
-    nextCursor += 1;
-    previousParagraph = false;
-  }
-
-  return nextCursor;
-}
-
-function collectProtectionRangesFromInlines(
-  nodes: readonly ParsedInlineNode[],
-  ranges: ProtectionRange[],
-  openRanges: Map<string, Omit<ProtectionRange, "end">>,
-  cursor: number,
-): number {
-  let nextCursor = cursor;
-
-  for (const node of nodes) {
-    if (node.type === "perm_start") {
-      openRanges.set(node.rangeId, {
-        rangeId: node.rangeId,
-        start: nextCursor,
-        ...(node.editorGroup ? { editorGroup: node.editorGroup } : {}),
-        ...(node.editor ? { editor: node.editor } : {}),
-        enforced: false,
-        enforcementReason:
-          "preserve-only: runtime does not yet enforce permission range boundaries",
-      });
-      continue;
-    }
-
-    if (node.type === "perm_end") {
-      const openRange = openRanges.get(node.rangeId);
-      if (openRange) {
-        ranges.push({
-          ...openRange,
-          end: nextCursor,
-        });
-        openRanges.delete(node.rangeId);
-      }
-      continue;
-    }
-
-    nextCursor += measureParsedInlineNode(node);
-  }
-
-  return nextCursor;
-}
-
-function measureParsedInlineNode(node: ParsedInlineNode): number {
-  switch (node.type) {
-    case "text":
-      return Array.from(node.text).length;
-    case "tab":
-    case "hard_break":
-    case "column_break":
-    case "footnote_ref":
-    case "image":
-    case "bookmark_start":
-    case "bookmark_end":
-      return 1;
-    case "hyperlink":
-      return node.children.reduce((size, child) => size + measureParsedInlineNode(child), 0);
-    case "field": {
-      const content = parseMainDocumentXml(
-        `<?xml version="1.0" encoding="UTF-8" standalone="yes"?><w:document xmlns:w="http://schemas.openxmlformats.org/wordprocessingml/2006/main"><w:body><w:p>${node.contentXml}</w:p></w:body></w:document>`,
-      );
-      if (content.blocks[0]?.type === "paragraph") {
-        return content.blocks[0].children.reduce(
-          (size, child) => size + measureParsedInlineNode(child),
-          0,
-        );
-      }
-      return 1;
-    }
-    default:
-      return 1;
-  }
-}
-
-function buildProtectionSnapshot(
-  documentProtection: DocumentProtectionMeta,
-  ranges: ProtectionRange[],
-): ProtectionSnapshot {
-  const hasDocumentProtection =
-    documentProtection.editType !== undefined || documentProtection.enforcement;
-  const enforceRanges =
-    documentProtection.editType === "readOnly" || documentProtection.editType === "comments";
-  const normalizedRanges = ranges.map((range) => {
-    const canEnforce =
-      hasDocumentProtection &&
-      documentProtection.enforcement &&
-      enforceRanges &&
-      typeof range.start === "number" &&
-      typeof range.end === "number" &&
-      range.end >= range.start;
-    return {
-      ...range,
-      enforced: canEnforce,
-      enforcementReason: canEnforce
-        ? "runtime-enforced: permission range is mapped to canonical positions"
-        : "preserve-only: runtime does not yet enforce permission range boundaries",
-    };
-  });
-  return {
-    hasDocumentProtection,
-    editType: documentProtection.editType,
-    enforcementActive: documentProtection.enforcement,
-    ranges: normalizedRanges,
-    enforcedRangeCount: normalizedRanges.filter((r) => r.enforced).length,
-    preservedRangeCount: normalizedRanges.filter((r) => !r.enforced).length,
-  };
-}
+// Back-compat shim.
+//
+// `src/io/docx-session.ts` was the pre-refactor home for session
+// orchestration. The Layer-01 refactor extracted the contents to
+// `src/session/**` (see `docs/architecture/01-package-session.md`).
+//
+// This file is retained so that the public export
+// `@beyondwork/docx-react-component/io/docx-session` (declared in
+// `package.json`) and any consumers of the old internal path keep
+// working. New code MUST import from `./session` / `src/session/**`
+// directly — see `MIGRATION.md`.
+//
+// Symbol map (old → new):
+//   loadDocxEditorSessionAsync         → loadDocxSessionAsync (renamed)
+//   LoadDocxEditorSessionAsyncOptions  → same name, new home
+//   LoadDocxEditorSessionOptions       → same name, new home
+//   LoadedDocxEditorSession            → same name, new home
+//   normalizeImportedCommentThreads    → same name, new home
+//   stripCommentMarkup                 → same name, new home
+//   NormalizedImportedCommentsResult   → same name, new home
+//
+// The sync `loadDocxEditorSession` entry point is not re-exported —
+// the runtime is async-first after the refactor. Migrate callers to
+// `DocxSession.open(bytes)` or `loadDocxSessionAsync(...)`.
+
+export { loadDocxSessionAsync as loadDocxEditorSessionAsync } from "../session/import/loader.ts";
+export type {
+  LoadDocxEditorSessionAsyncOptions,
+  LoadDocxEditorSessionOptions,
+  LoadedDocxEditorSession,
+} from "../session/import/loader-types.ts";
+export {
+  normalizeImportedCommentThreads,
+  stripCommentMarkup,
+  type NormalizedImportedCommentsResult,
+} from "../session/import/review-import.ts";