@beyondwork/docx-react-component 1.0.29 → 1.0.30

package/src/model/canonical-document.ts

@@ -0,0 +1,2722 @@
+import {
+  CDS_SCHEMA_VERSION,
+  type ISO8601DateTime,
+  type ModelValidationIssue,
+  type UUID,
+  asPlainObject,
+  assertValid,
+  expectExactString,
+  expectIso8601UtcTimestamp,
+  expectString,
+  expectStringAllowEmpty,
+  expectUuid,
+  stableStringify,
+} from "./cds-1.0.0.ts";
+
+const CANONICAL_DOCUMENT_TOP_LEVEL_KEYS = [
+  "schemaVersion",
+  "docId",
+  "createdAt",
+  "updatedAt",
+  "metadata",
+  "styles",
+  "numbering",
+  "media",
+  "content",
+  "review",
+  "preservation",
+  "diagnostics",
+] as const;
+
+const CANONICAL_DOCUMENT_OPTIONAL_KEYS = ["subParts", "fieldRegistry"] as const;
+
+const ID_PATTERNS = {
+  styleId: /^[A-Za-z_][A-Za-z0-9._-]{0,127}$/,
+  abstractNumberingId: /^abstract-num:[A-Za-z0-9._-]{1,120}$/,
+  numberingInstanceId: /^num:[A-Za-z0-9._-]{1,120}$/,
+  mediaId: /^media:[A-Za-z0-9._/-]{1,120}$/,
+  commentId:
+    /^(?:comment:[A-Za-z0-9._-]{1,120}|comment-[A-Za-z0-9._-]{1,120}|[0-9]{1,18})$/,
+  revisionId:
+    /^(?:revision:[A-Za-z0-9._-]{1,120}|change-[A-Za-z0-9._-]{1,120})$/,
+  fragmentId: /^fragment:[A-Za-z0-9._-]{1,120}$/,
+  warningId: /^warning:[A-Za-z0-9._:-]{1,120}$/,
+  diagnosticId: /^diagnostic:[A-Za-z0-9._-]{1,120}$/,
+  packagePartName: /^\/[A-Za-z0-9_.\-\/]+\.[A-Za-z0-9]+$/,
+  relationshipId: /^rId[A-Za-z0-9._-]{1,120}$/,
+} as const;
+
+type StableIdDomain = keyof typeof ID_PATTERNS;
+
+export interface CanonicalDocument {
+  schemaVersion: typeof CDS_SCHEMA_VERSION;
+  docId: UUID;
+  createdAt: ISO8601DateTime;
+  updatedAt: ISO8601DateTime;
+  metadata: DocumentMetadata;
+  styles: StylesCatalog;
+  numbering: NumberingCatalog;
+  media: MediaCatalog;
+  content: DocumentRootNode;
+  review: ReviewStore;
+  preservation: PreservationStore;
+  diagnostics: DiagnosticStore;
+  subParts?: SubPartsCatalog;
+  /** Package-backed field registry for supported field families. */
+  fieldRegistry?: FieldRegistry;
+}
+
+export interface DocumentMetadata {
+  title?: string;
+  subject?: string;
+  description?: string;
+  language?: string;
+  keywords?: string[];
+  category?: string;
+  importMode?: string;
+  customProperties: Record<string, string>;
+}
+
+export interface StylesCatalog {
+  paragraphs: Record<string, ParagraphStyleDefinition>;
+  characters: Record<string, CharacterStyleDefinition>;
+  tables: Record<string, TableStyleDefinition>;
+  latentStyles?: Record<string, LatentStyleDefinition>;
+  fromPackage?: boolean;
+}
+
+export interface ParagraphStyleDefinition {
+  styleId: string;
+  basedOn?: string;
+  nextStyle?: string;
+  outlineLevel?: number;
+  numbering?: ParagraphStyleNumberingReference;
+  displayName: string;
+  kind: "paragraph";
+  isDefault: boolean;
+}
+
+export interface ParagraphStyleNumberingReference {
+  numberingInstanceId: string;
+  level?: number;
+}
+
+export interface CharacterStyleDefinition {
+  styleId: string;
+  basedOn?: string;
+  displayName: string;
+  kind: "character";
+  isDefault: boolean;
+}
+
+export interface TableStyleDefinition {
+  styleId: string;
+  basedOn?: string;
+  displayName: string;
+  kind: "table";
+  isDefault: boolean;
+  formatting?: TableStyleFormatting;
+  conditionalFormatting?: Partial<Record<TableStyleConditionalRegion, TableStyleFormatting>>;
+}
+
+export interface LatentStyleDefinition {
+  name: string;
+  locked?: boolean;
+  semiHidden?: boolean;
+  unhideWhenUsed?: boolean;
+  qFormat?: boolean;
+  uiPriority?: number;
+}
+
+export interface NumberingCatalog {
+  abstractDefinitions: Record<string, AbstractNumberingDefinition>;
+  instances: Record<string, NumberingInstance>;
+}
+
+export interface AbstractNumberingDefinition {
+  abstractNumberingId: string;
+  levels: NumberingLevelDefinition[];
+}
+
+export interface NumberingLevelParagraphGeometry {
+  justification?: "left" | "center" | "right" | "both" | "distribute";
+  spacing?: ParagraphSpacing;
+  indentation?: ParagraphIndentation;
+  tabStops?: TabStop[];
+}
+
+export interface NumberingLevelDefinition {
+  level: number;
+  format: string;
+  text: string;
+  startAt?: number;
+  paragraphStyleId?: string;
+  isLegalNumbering?: boolean;
+  suffix?: "tab" | "space" | "nothing";
+  paragraphGeometry?: NumberingLevelParagraphGeometry;
+}
+
+export interface NumberingLevelOverrideDefinition {
+  level: number;
+  format?: string;
+  text?: string;
+  startAt?: number;
+  paragraphStyleId?: string;
+  isLegalNumbering?: boolean;
+  suffix?: "tab" | "space" | "nothing";
+  paragraphGeometry?: NumberingLevelParagraphGeometry;
+}
+
+export interface NumberingInstance {
+  numberingInstanceId: string;
+  abstractNumberingId: string;
+  overrides: NumberingLevelOverride[];
+}
+
+export interface NumberingLevelOverride {
+  level: number;
+  startAt?: number;
+  levelDefinition?: NumberingLevelOverrideDefinition;
+}
+
+export interface MediaCatalog {
+  items: Record<string, MediaItem>;
+}
+
+export interface MediaItem {
+  mediaId: string;
+  contentType: string;
+  filename: string;
+  relationshipId?: string;
+  packagePartName: string;
+  altText?: string;
+  display?: "inline" | "floating";
+  widthEmu?: number;
+  heightEmu?: number;
+}
+
+// ---- Sub-part canonical types ----
+
+export type HeaderFooterVariant = "default" | "first" | "even";
+
+export interface HeaderDocument {
+  variant: HeaderFooterVariant;
+  partPath: string;
+  relationshipId: string;
+  blocks: BlockNode[];
+  sectionIndex?: number;
+}
+
+export interface FooterDocument {
+  variant: HeaderFooterVariant;
+  partPath: string;
+  relationshipId: string;
+  blocks: BlockNode[];
+  sectionIndex?: number;
+}
+
+export interface FootnoteDefinition {
+  noteId: string;
+  kind: "footnote" | "endnote";
+  blocks: BlockNode[];
+}
+
+export interface FootnoteCollection {
+  footnotes: Record<string, FootnoteDefinition>;
+  endnotes: Record<string, FootnoteDefinition>;
+}
+
+export interface ThemeColorScheme {
+  name: string;
+  colors: Record<string, string>;
+}
+
+export interface ThemeFontScheme {
+  name: string;
+  majorFont?: string;
+  minorFont?: string;
+}
+
+export interface ThemeDefinition {
+  name?: string;
+  colorScheme?: ThemeColorScheme;
+  fontScheme?: ThemeFontScheme;
+}
+
+export interface DocumentSettings {
+  evenAndOddHeaders?: boolean;
+  zoomLevel?: "pageWidth" | "onePage" | number;
+}
+
+export interface SubPartsCatalog {
+  headers: HeaderDocument[];
+  footers: FooterDocument[];
+  footnoteCollection?: FootnoteCollection;
+  theme?: ThemeDefinition;
+  finalSectionProperties?: SectionProperties;
+  resolvedTheme?: ResolvedTheme;
+  settings?: DocumentSettings;
+}
+
+export interface ResolvedTheme {
+  colors: Record<string, string>;
+  majorFont?: string;
+  minorFont?: string;
+}
+
+// ---- Inline footnote reference node ----
+
+export interface FootnoteRefNode {
+  type: "footnote_ref";
+  noteId: string;
+  noteKind: "footnote" | "endnote";
+}
+
+export type DocumentNode =
+  | DocumentRootNode
+  | ParagraphNode
+  | TableNode
+  | TableRowNode
+  | TableCellNode
+  | SdtNode
+  | CustomXmlNode
+  | AltChunkNode
+  | TextNode
+  | HardBreakNode
+  | TabNode
+  | ColumnBreakNode
+  | SymbolNode
+  | HyperlinkNode
+  | ImageNode
+  | FieldNode
+  | BookmarkStartNode
+  | BookmarkEndNode
+  | SectionBreakNode
+  | OpaqueInlineNode
+  | OpaqueBlockNode
+  | FootnoteRefNode
+  | ChartPreviewNode
+  | SmartArtPreviewNode
+  | ShapeNode
+  | WordArtNode
+  | VmlShapeNode;
+
+export interface DocumentRootNode {
+  type: "doc";
+  children: BlockNode[];
+}
+
+export type BlockNode =
+  | ParagraphNode
+  | TableNode
+  | SdtNode
+  | CustomXmlNode
+  | AltChunkNode
+  | SectionBreakNode
+  | OpaqueBlockNode;
+
+export interface ParagraphSpacing {
+  before?: number;
+  after?: number;
+  line?: number;
+  lineRule?: "auto" | "exact" | "atLeast";
+}
+
+export interface ParagraphIndentation {
+  left?: number;
+  right?: number;
+  firstLine?: number;
+  hanging?: number;
+}
+
+export interface TabStop {
+  position: number;
+  align: "left" | "center" | "right" | "decimal" | "num" | "bar" | "clear";
+  leader?: "none" | "dot" | "hyphen" | "underscore" | "heavy" | "middleDot";
+}
+
+export interface ParagraphBorders {
+  top?: BorderSpec;
+  left?: BorderSpec;
+  bottom?: BorderSpec;
+  right?: BorderSpec;
+  bar?: BorderSpec;
+  between?: BorderSpec;
+}
+
+export interface ParagraphShading {
+  fill?: string;
+  color?: string;
+  val?: string;
+}
+
+export interface ParagraphNode {
+  type: "paragraph";
+  styleId?: string;
+  numbering?: {
+    numberingInstanceId: string;
+    level: number;
+  };
+  alignment?: "left" | "center" | "right" | "both" | "distribute";
+  spacing?: ParagraphSpacing;
+  contextualSpacing?: boolean;
+  indentation?: ParagraphIndentation;
+  tabStops?: TabStop[];
+  keepNext?: boolean;
+  keepLines?: boolean;
+  outlineLevel?: number;
+  pageBreakBefore?: boolean;
+  widowControl?: boolean;
+  borders?: ParagraphBorders;
+  shading?: ParagraphShading;
+  bidi?: boolean;
+  suppressLineNumbers?: boolean;
+  cnfStyle?: string;
+  children: InlineNode[];
+}
+
+export interface BorderSpec {
+  value?: string;
+  size?: number;
+  space?: number;
+  color?: string;
+}
+
+export interface TableBorders {
+  top?: BorderSpec;
+  left?: BorderSpec;
+  bottom?: BorderSpec;
+  right?: BorderSpec;
+  insideH?: BorderSpec;
+  insideV?: BorderSpec;
+}
+
+export interface TableCellBorders {
+  top?: BorderSpec;
+  left?: BorderSpec;
+  bottom?: BorderSpec;
+  right?: BorderSpec;
+  insideH?: BorderSpec;
+  insideV?: BorderSpec;
+}
+
+export interface TableWidth {
+  value: number;
+  type: "dxa" | "auto" | "pct" | "nil";
+}
+
+export interface CellShading {
+  fill?: string;
+  color?: string;
+  val?: string;
+}
+
+export interface TableCellMargins {
+  top?: number;
+  left?: number;
+  bottom?: number;
+  right?: number;
+}
+
+export interface TableLook {
+  val?: string;
+  firstRow?: boolean;
+  lastRow?: boolean;
+  firstColumn?: boolean;
+  lastColumn?: boolean;
+  noHBand?: boolean;
+  noVBand?: boolean;
+}
+
+export type TableStyleConditionalRegion =
+  | "firstRow"
+  | "lastRow"
+  | "firstColumn"
+  | "lastColumn"
+  | "band1Horz"
+  | "band2Horz"
+  | "band1Vert"
+  | "band2Vert";
+
+export interface TableStyleFormatting {
+  table?: {
+    width?: TableWidth;
+    alignment?: "left" | "center" | "right";
+    borders?: TableBorders;
+    cellMargins?: TableCellMargins;
+    tblLook?: TableLook;
+  };
+  row?: {
+    height?: number;
+    heightRule?: "auto" | "atLeast" | "exact";
+    isHeader?: boolean;
+  };
+  cell?: {
+    width?: TableWidth;
+    borders?: TableCellBorders;
+    shading?: CellShading;
+    verticalAlign?: "top" | "center" | "bottom";
+  };
+}
+
+export interface TableNode {
+  type: "table";
+  styleId?: string;
+  propertiesXml?: string;
+  gridColumns: number[];
+  rows: TableRowNode[];
+  width?: TableWidth;
+  alignment?: "left" | "center" | "right";
+  borders?: TableBorders;
+  cellMargins?: TableCellMargins;
+  tblLook?: TableLook;
+}
+
+export interface TableRowNode {
+  type: "table_row";
+  propertiesXml?: string;
+  cells: TableCellNode[];
+  gridBefore?: number;
+  widthBefore?: TableWidth;
+  gridAfter?: number;
+  widthAfter?: TableWidth;
+  height?: number;
+  heightRule?: "auto" | "atLeast" | "exact";
+  isHeader?: boolean;
+}
+
+export interface TableCellNode {
+  type: "table_cell";
+  propertiesXml?: string;
+  gridSpan?: number;
+  verticalMerge?: "restart" | "continue";
+  children: BlockNode[];
+  width?: TableWidth;
+  borders?: TableCellBorders;
+  shading?: CellShading;
+  verticalAlign?: "top" | "center" | "bottom";
+}
+
+export interface SdtCheckboxState {
+  checked: boolean;
+  checkedChar?: string;
+  uncheckedChar?: string;
+}
+
+export interface SdtDatePickerState {
+  fullDate?: string;
+  dateFormat?: string;
+  lid?: string;
+}
+
+export interface SdtDropdownListItem {
+  displayText?: string;
+  value: string;
+}
+
+export interface SdtNode {
+  type: "sdt";
+  properties: {
+    sdtType?: string;
+    alias?: string;
+    tag?: string;
+    lock?: string;
+    propertiesXml?: string;
+    checkbox?: SdtCheckboxState;
+    datePicker?: SdtDatePickerState;
+    dropdownList?: SdtDropdownListItem[];
+    comboBox?: SdtDropdownListItem[];
+    showingPlcHdr?: boolean;
+  };
+  children: BlockNode[];
+}
+
+export interface CustomXmlNode {
+  type: "custom_xml";
+  uri?: string;
+  element?: string;
+  rawXml?: string;
+  children: BlockNode[];
+}
+
+export interface AltChunkNode {
+  type: "alt_chunk";
+  relationshipId: string;
+}
+
+/**
+ * Supported field families that receive first-class canonical treatment.
+ * These families have stable registry IDs, dependency metadata, and
+ * runtime-owned refresh behavior.
+ */
+export type SupportedFieldFamily = "REF" | "PAGEREF" | "NOTEREF" | "TOC";
+
+/**
+ * Unsupported field families that remain preserve-only.
+ * They survive round-trip but do not participate in runtime refresh.
+ */
+export type PreserveOnlyFieldFamily =
+  | "PAGE"
+  | "NUMPAGES"
+  | "DATE"
+  | "TIME"
+  | "AUTHOR"
+  | "FILENAME"
+  | "MERGEFIELD"
+  | "IF"
+  | "SEQ"
+  | "INDEX"
+  | "TC"
+  | "STYLEREF"
+  | "FORMULA"
+  | "UNKNOWN";
+
+export type FieldFamily = SupportedFieldFamily | PreserveOnlyFieldFamily;
+
+/** Runtime refresh status for a field instance. */
+export type FieldRefreshStatus =
+  | "current"
+  | "stale"
+  | "unresolvable"
+  | "preserve-only";
+
+export interface FieldNode {
+  type: "field";
+  fieldType: "simple" | "complex";
+  instruction: string;
+  children: InlineNode[];
+  /** Classified field family. Undefined for legacy snapshots. */
+  fieldFamily?: FieldFamily;
+  /** Target bookmark name for REF/PAGEREF/NOTEREF fields. */
+  fieldTarget?: string;
+  /** Runtime refresh status. Undefined for legacy or preserve-only fields. */
+  refreshStatus?: FieldRefreshStatus;
+}
+
+// ─── Field registry ─────────────────────────────────────────────────────────
+
+/**
+ * Package-backed field registry that catalogs every field instance in the
+ * document, grouped by supported vs preserve-only families.
+ *
+ * Supported field entries carry dependency metadata (bookmark targets) and
+ * participate in deterministic refresh.  Preserve-only entries survive
+ * round-trip but are not refreshable.
+ */
+export interface FieldRegistry {
+  /** Supported field instances that participate in refresh. */
+  supported: FieldRegistryEntry[];
+  /** Preserve-only field instances cataloged for round-trip safety. */
+  preserveOnly: FieldRegistryEntry[];
+  /** Generated TOC structure extracted from heading-driven TOC fields. */
+  tocStructure?: TocStructure;
+}
+
+export interface FieldRegistryEntry {
+  /** Stable document-order index of this field (0-based). */
+  fieldIndex: number;
+  /** Classified field family. */
+  fieldFamily: FieldFamily;
+  /** Whether the field is in the supported refresh slice. */
+  supported: boolean;
+  /** Field instruction text. */
+  instruction: string;
+  /** Target bookmark name for REF/PAGEREF/NOTEREF fields. */
+  fieldTarget?: string;
+  /** Current display text extracted from field content. */
+  displayText: string;
+  /** Paragraph index in document order where this field appears. */
+  paragraphIndex: number;
+  /** Runtime refresh status. */
+  refreshStatus: FieldRefreshStatus;
+}
+
+/**
+ * Generated table-of-contents structure extracted from TOC fields and
+ * heading-styled paragraphs in the document.
+ */
+export interface TocStructure {
+  /** The raw TOC field instruction (e.g. "TOC \\o \"1-3\" \\h"). */
+  instruction: string;
+  /** Heading level range the TOC covers. */
+  levelRange: { from: number; to: number };
+  /** Ordered TOC entries derived from heading paragraphs. */
+  entries: TocEntry[];
+  /** Whether the TOC content is current with the heading structure. */
+  status: "current" | "stale";
+}
+
+export interface TocEntry {
+  /** Heading text. */
+  text: string;
+  /** Heading outline level (1-9). */
+  level: number;
+  /** Paragraph index of the heading in document order. */
+  paragraphIndex: number;
+  /** Style ID of the heading paragraph, if available. */
+  styleId?: string;
+  /** Bookmark name anchoring this heading, if present. */
+  bookmarkName?: string;
+}
+
+export interface BookmarkStartNode {
+  type: "bookmark_start";
+  bookmarkId: string;
+  name: string;
+}
+
+export interface BookmarkEndNode {
+  type: "bookmark_end";
+  bookmarkId: string;
+}
+
+export interface SectionBreakNode {
+  type: "section_break";
+  sectionPropertiesXml?: string;
+  /**
+   * @deprecated Legacy field from older snapshots. New exports should use
+   * sectionPropertiesXml and only contain raw <w:sectPr> content.
+   */
+  propertiesXml?: string;
+  sectionProperties?: SectionProperties;
+}
+
+export interface SectionProperties {
+  pageSize?: PageSize;
+  pageMargins?: PageMargins;
+  columns?: ColumnProperties;
+  pageNumbering?: PageNumbering;
+  lineNumbering?: SectionLineNumbering;
+  pageBorders?: SectionPageBorders;
+  documentGrid?: SectionDocumentGrid;
+  headerReferences?: HeaderFooterReference[];
+  footerReferences?: HeaderFooterReference[];
+  sectionType?: "continuous" | "nextPage" | "evenPage" | "oddPage" | "nextColumn";
+  titlePage?: boolean;
+}
+
+export interface PageSize {
+  width: number;
+  height: number;
+  orientation?: "portrait" | "landscape";
+}
+
+export interface PageMargins {
+  top: number;
+  right: number;
+  bottom: number;
+  left: number;
+  header?: number;
+  footer?: number;
+  gutter?: number;
+}
+
+export interface ColumnProperties {
+  count?: number;
+  space?: number;
+  equalWidth?: boolean;
+  columns?: Array<{ width: number; space?: number }>;
+  separator?: boolean;
+}
+
+export interface PageNumbering {
+  format?: string;
+  start?: number;
+  chapStyle?: string;
+  chapSep?: string;
+}
+
+export interface SectionLineNumbering {
+  countBy?: number;
+  start?: number;
+  distance?: number;
+  restart?: "newPage" | "newSection" | "continuous";
+}
+
+export interface SectionPageBorders {
+  top?: BorderSpec;
+  left?: BorderSpec;
+  bottom?: BorderSpec;
+  right?: BorderSpec;
+  offsetFrom?: "page" | "text";
+  display?: "allPages" | "firstPage" | "notFirstPage";
+  zOrder?: "front" | "back";
+}
+
+export interface SectionDocumentGrid {
+  type?: "default" | "lines" | "linesAndChars" | "snapToChars";
+  linePitch?: number;
+  charSpace?: number;
+}
+
+export interface HeaderFooterReference {
+  variant: HeaderFooterVariant;
+  relationshipId: string;
+}
+
+export type InlineNode =
+  | TextNode
+  | HardBreakNode
+  | ColumnBreakNode
+  | TabNode
+  | SymbolNode
+  | HyperlinkNode
+  | ImageNode
+  | FieldNode
+  | BookmarkStartNode
+  | BookmarkEndNode
+  | OpaqueInlineNode
+  | FootnoteRefNode
+  | ChartPreviewNode
+  | SmartArtPreviewNode
+  | ShapeNode
+  | WordArtNode
+  | VmlShapeNode;
+
+export interface TextNode {
+  type: "text";
+  text: string;
+  marks?: TextMark[];
+}
+
+export type TextMark =
+  | { type: "bold" }
+  | { type: "italic" }
+  | { type: "underline" }
+  | { type: "strikethrough" }
+  | { type: "doubleStrikethrough" }
+  | { type: "vanish" }
+  | { type: "lang"; val: string }
+  | { type: "highlight"; color: string; val: string }
+  | { type: "backgroundColor"; color: string }
+  | { type: "charSpacing"; val: number }
+  | { type: "kerning"; val: number }
+  | { type: "emboss" }
+  | { type: "imprint" }
+  | { type: "shadow" }
+  | { type: "position"; val: number }
+  | { type: "textFill"; xml: string }
+  | { type: "fontFamily"; val: string }
+  | { type: "fontSize"; val: number }
+  | { type: "textColor"; color: string }
+  | { type: "smallCaps" }
+  | { type: "allCaps" };
+
+export interface HardBreakNode {
+  type: "hard_break";
+}
+
+export interface ColumnBreakNode {
+  type: "column_break";
+}
+
+export interface TabNode {
+  type: "tab";
+}
+
+export interface SymbolNode {
+  type: "symbol";
+  char: string;
+  font?: string;
+  marks?: TextMark[];
+}
+
+export interface HyperlinkNode {
+  type: "hyperlink";
+  href: string;
+  children: Array<TextNode | HardBreakNode | ColumnBreakNode | TabNode | SymbolNode>;
+}
+
+export interface ImageNode {
+  type: "image";
+  mediaId: string;
+  altText?: string;
+  placementXml?: string;
+  display?: "inline" | "floating";
+  floating?: FloatingImageProperties;
+}
+
+export interface FloatingImageProperties {
+  horizontalPosition?: FloatingAxisPosition;
+  verticalPosition?: FloatingAxisPosition;
+  wrap?: "none" | "square" | "tight" | "through" | "topAndBottom";
+  behindDoc?: boolean;
+  layoutInCell?: boolean;
+  allowOverlap?: boolean;
+}
+
+export interface FloatingAxisPosition {
+  relativeFrom?: string;
+  align?: string;
+  offset?: number;
+}
+
+export interface OpaqueInlineNode {
+  type: "opaque_inline";
+  fragmentId: string;
+  warningId: string;
+}
+
+// ---- Complex rendering inline nodes (read-only previews) ----
+
+/**
+ * Read-only preview of a chart (c:chart). The original drawing XML is stored in
+ * rawXml for lossless round-trip export. If a fallback image was present in
+ * mc:AlternateContent it is referenced by previewMediaId.
+ */
+export interface ChartPreviewNode {
+  type: "chart_preview";
+  previewMediaId?: string;
+  rawXml: string;
+}
+
+/**
+ * Read-only preview of a SmartArt diagram (dgm:*). The original drawing XML is
+ * stored in rawXml for lossless round-trip export.
+ */
+export interface SmartArtPreviewNode {
+  type: "smartart_preview";
+  previewMediaId?: string;
+  rawXml: string;
+}
+
+/**
+ * Read-only rendering of a wps:wsp WordprocessingShape. Text content is
+ * extracted for display. The original drawing XML is preserved in rawXml.
+ */
+export interface ShapeNode {
+  type: "shape";
+  text?: string;
+  geometry?: string;
+  isTextBox?: boolean;
+  rawXml: string;
+}
+
+/**
+ * Read-only rendering of WordArt — a wps:wsp shape with a text-geometry preset.
+ * Text is extracted for display. The original drawing XML is preserved in rawXml.
+ */
+export interface WordArtNode {
+  type: "wordart";
+  text: string;
+  geometry?: string;
+  rawXml: string;
+}
+
+/**
+ * Read-only rendering of a VML shape (v:shape, v:rect, v:textbox) from a w:pict
+ * element. Text is extracted for display. The original w:pict XML is preserved
+ * in rawXml for lossless round-trip export.
+ */
+export interface VmlShapeNode {
+  type: "vml_shape";
+  text?: string;
+  shapeType?: string;
+  rawXml: string;
+}
+
+export interface OpaqueBlockNode {
+  type: "opaque_block";
+  fragmentId: string;
+  warningId: string;
+  rawXml?: string;
+}
+
+export interface DocRange {
+  from: number;
+  to: number;
+}
+
+export interface BoundaryAssoc {
+  start: -1 | 1;
+  end: -1 | 1;
+}
+
+export type CanonicalAnchor =
+  | {
+      kind: "range";
+      range: DocRange;
+      assoc: BoundaryAssoc;
+    }
+  | {
+      kind: "node";
+      at: number;
+      assoc: -1 | 1;
+    }
+  | {
+      kind: "detached";
+      lastKnownRange: DocRange;
+      reason: "deleted" | "invalidatedByStructureChange" | "importAmbiguity";
+    };
+
+export interface ReviewStore {
+  comments: Record<string, CommentThread>;
+  revisions: Record<string, RevisionRecord>;
+}
+
+export interface CommentThread {
+  commentId: string;
+  status: "open" | "resolved" | "detached";
+  anchor: CanonicalAnchor;
+  createdAt: ISO8601DateTime;
+  createdBy?: string;
+  authorId?: string;
+  body?: string;
+  entries?: CommentEntry[];
+  resolution?: CommentResolution;
+  resolvedAt?: ISO8601DateTime;
+  warningIds: string[];
+  isResolved?: boolean;
+  metadata?: CommentThreadMetadata;
+}
+
+export interface CommentEntry {
+  entryId: string;
+  authorId: string;
+  createdAt: ISO8601DateTime;
+  body: string;
+  metadata?: CommentEntryMetadata;
+}
+
+export interface CommentEntryMetadata {
+  ooxmlCommentId?: string;
+  paraId?: string;
+  parentParaId?: string;
+  durableId?: string;
+  initials?: string;
+}
+
+export interface CommentResolution {
+  resolvedAt: ISO8601DateTime;
+  resolvedBy: string;
+}
+
+export interface CommentThreadMetadata {
+  source?: "runtime" | "import";
+  rootOoxmlCommentId?: string;
+  rootParaId?: string;
+  detachedReason?: "incomplete-markers" | "multi-paragraph" | "opaque-region" | "revision-overlap";
+  actionabilityNote?: string;
+}
+
+export interface RevisionPropertyChangeData {
+  xmlTag: "pPrChange" | "sectPrChange" | "tblPrChange" | "rPrChange";
+  beforeXml: string;
+}
+
+export interface RevisionMoveData {
+  moveId: string;
+  direction: "from" | "to";
+  linkedRevisionId?: string;
+}
+
+export type RevisionStoryTargetRecord =
+  | { kind: "main" }
+  | {
+      kind: "header";
+      relationshipId: string;
+      variant: "default" | "first" | "even";
+      sectionIndex?: number;
+    }
+  | {
+      kind: "footer";
+      relationshipId: string;
+      variant: "default" | "first" | "even";
+      sectionIndex?: number;
+    }
+  | { kind: "footnote"; noteId: string }
+  | { kind: "endnote"; noteId: string };
+
+export interface RevisionRecord {
+  changeId: string;
+  kind: "insertion" | "deletion" | "formatting" | "move" | "property-change";
+  anchor: CanonicalAnchor;
+  authorId?: string;
+  createdAt: ISO8601DateTime;
+  warningIds?: string[];
+  metadata?: RevisionMetadataRecord;
+  status: "open" | "accepted" | "rejected" | "detached";
+}
+
+export interface RevisionMetadataRecord {
+  source?: "runtime" | "import";
+  storyTarget?: RevisionStoryTargetRecord;
+  preserveOnlyReason?: string;
+  suggestionId?: string;
+  semanticKind?:
+    | "insertion"
+    | "deletion"
+    | "replacement"
+    | "formatting-change"
+    | "paragraph-property-change"
+    | "structural-change"
+    | "object-change";
+  linkedRevisionIds?: string[];
+  predecessorSuggestionId?: string;
+  importedRevisionForm?:
+    | "run-insertion"
+    | "run-deletion"
+    | "paragraph-insertion"
+    | "paragraph-deletion";
+  originalRevisionType?: string;
+  ooxmlRevisionId?: string;
+  propertyChangeData?: RevisionPropertyChangeData;
+  moveData?: RevisionMoveData;
+}
+
+export interface PreservationStore {
+  opaqueFragments: Record<string, OpaqueFragmentRecord>;
+  packageParts: Record<string, PreservedPackagePart>;
+}
+
+export interface OpaqueFragmentRecord {
+  fragmentId: string;
+  payloadKind: "xml-subtree" | "package-part";
+  payloadReference: string;
+  featureClass: "preserve-only";
+  lastKnownRange: DocRange;
+  warningId: string;
+  packagePartName?: string;
+  relationshipId?: string;
+}
+
+export interface PreservedPackagePart {
+  packagePartName: string;
+  contentType: string;
+  relationshipIds: string[];
+}
+
+export interface DiagnosticStore {
+  warnings: DiagnosticWarningEntry[];
+  errors: DiagnosticErrorEntry[];
+}
+
+export interface DiagnosticWarningEntry {
+  diagnosticId: string;
+  warningId: string;
+  source:
+    | "import"
+    | "runtime"
+    | "review"
+    | "preservation"
+    | "validation"
+    | "export";
+  message: string;
+}
+
+export interface DiagnosticErrorEntry {
+  diagnosticId: string;
+  code:
+    | "load_failed"
+    | "import_failed"
+    | "export_failed"
+    | "package_corrupt"
+    | "validation_failed"
+    | "datastore_failed"
+    | "internal_invariant";
+  message: string;
+  isFatal: boolean;
+  source: "import" | "runtime" | "validation" | "datastore" | "host" | "export";
+  details?: unknown;
+}
+
+export function createCanonicalDocument(
+  input: Omit<CanonicalDocument, "schemaVersion">,
+): CanonicalDocument {
+  const document: CanonicalDocument = {
+    schemaVersion: CDS_SCHEMA_VERSION,
+    ...input,
+  };
+
+  assertCanonicalDocument(document);
+  return document;
+}
+
+export function serializeCanonicalDocument(document: CanonicalDocument): string {
+  assertCanonicalDocument(document);
+  return stableStringify(document);
+}
+
+export function createCanonicalDocumentSignature(document: unknown): string {
+  return stableStringify(document);
+}
+
+export function parseCanonicalDocument(json: string): CanonicalDocument {
+  const parsed = JSON.parse(json) as unknown;
+  assertCanonicalDocument(parsed);
+  return parsed;
+}
+
+export function projectCanonicalDocument(
+  document: CanonicalDocument,
+): CanonicalDocument {
+  assertCanonicalDocument(document);
+  return JSON.parse(stableStringify(document)) as CanonicalDocument;
+}
+
+export function assertCanonicalDocument(
+  value: unknown,
+): asserts value is CanonicalDocument {
+  const issues = validateCanonicalDocument(value);
+  assertValid(issues, "Invalid canonical document.");
+}
+
+export function validateCanonicalDocument(
+  value: unknown,
+): ModelValidationIssue[] {
+  const issues: ModelValidationIssue[] = [];
+  const record = asPlainObject(value, "$", issues);
+  if (!record) {
+    return issues;
+  }
+
+  validateExactObjectKeys(record, CANONICAL_DOCUMENT_TOP_LEVEL_KEYS, "$", issues, CANONICAL_DOCUMENT_OPTIONAL_KEYS);
+  expectExactString(record.schemaVersion, CDS_SCHEMA_VERSION, "$.schemaVersion", issues);
+  expectUuid(record.docId, "$.docId", issues);
+  expectIso8601UtcTimestamp(record.createdAt, "$.createdAt", issues);
+  expectIso8601UtcTimestamp(record.updatedAt, "$.updatedAt", issues);
+
+  validateMetadata(record.metadata, "$.metadata", issues);
+  validateStylesCatalog(record.styles, "$.styles", issues);
+  validateNumberingCatalog(record.numbering, "$.numbering", issues);
+  validateMediaCatalog(record.media, "$.media", issues);
+  validateDocumentNode(record.content, "$.content", issues);
+  validateReviewStore(record.review, "$.review", issues);
+  validatePreservationStore(record.preservation, "$.preservation", issues);
+  validateDiagnosticStore(record.diagnostics, "$.diagnostics", issues);
+  if (record.subParts !== undefined) {
+    validateSubPartsCatalog(record.subParts, "$.subParts", issues);
+  }
+  validateDocumentReferences(record, issues);
+
+  return issues;
+}
+
+function validateMetadata(
+  value: unknown,
+  path: string,
+  issues: ModelValidationIssue[],
+): void {
+  const record = asPlainObject(value, path, issues);
+  if (!record) {
+    return;
+  }
+
+  const customProperties = asPlainObject(record.customProperties, `${path}.customProperties`, issues);
+  if (!customProperties) {
+    return;
+  }
+
+  for (const [propertyKey, propertyValue] of Object.entries(customProperties)) {
+    if (typeof propertyValue !== "string") {
+      issues.push({
+        path: `${path}.customProperties.${propertyKey}`,
+        message: "customProperties values must be strings.",
+      });
+    }
+  }
+}
+
+function validateStylesCatalog(
+  value: unknown,
+  path: string,
+  issues: ModelValidationIssue[],
+): void {
+  const record = asPlainObject(value, path, issues);
+  if (!record) {
+    return;
+  }
+
+  validateStyleMap(record.paragraphs, `${path}.paragraphs`, issues);
+  validateStyleMap(record.characters, `${path}.characters`, issues);
+  validateStyleMap(record.tables, `${path}.tables`, issues);
+  if (record.latentStyles !== undefined) {
+    validateLatentStyleMap(record.latentStyles, `${path}.latentStyles`, issues);
+  }
+}
+
+function validateStyleMap(
+  value: unknown,
+  path: string,
+  issues: ModelValidationIssue[],
+): void {
+  const record = asPlainObject(value, path, issues);
+  if (!record) {
+    return;
+  }
+
+  for (const [styleId, definition] of Object.entries(record)) {
+    expectDomainString(styleId, "styleId", `${path}.${styleId}`, issues);
+    const definitionRecord = asPlainObject(definition, `${path}.${styleId}`, issues);
+    if (!definitionRecord) {
+      continue;
+    }
+    if (definitionRecord.styleId !== styleId) {
+      issues.push({
+        path: `${path}.${styleId}.styleId`,
+        message: "styleId must match the map key.",
+      });
+    }
+  }
+}
+
+function validateLatentStyleMap(
+  value: unknown,
+  path: string,
+  issues: ModelValidationIssue[],
+): void {
+  const record = asPlainObject(value, path, issues);
+  if (!record) {
+    return;
+  }
+
+  for (const [styleName, definition] of Object.entries(record)) {
+    const definitionRecord = asPlainObject(definition, `${path}.${styleName}`, issues);
+    if (!definitionRecord) {
+      continue;
+    }
+    if (definitionRecord.name !== styleName) {
+      issues.push({
+        path: `${path}.${styleName}.name`,
+        message: "name must match the map key.",
+      });
+    }
+    if (definitionRecord.uiPriority !== undefined && typeof definitionRecord.uiPriority !== "number") {
+      issues.push({
+        path: `${path}.${styleName}.uiPriority`,
+        message: "uiPriority must be a number.",
+      });
+    }
+  }
+}
+
+function validateNumberingCatalog(
+  value: unknown,
+  path: string,
+  issues: ModelValidationIssue[],
+): void {
+  const record = asPlainObject(value, path, issues);
+  if (!record) {
+    return;
+  }
+
+  const abstractDefinitions = asPlainObject(
+    record.abstractDefinitions,
+    `${path}.abstractDefinitions`,
+    issues,
+  );
+  if (abstractDefinitions) {
+    for (const [abstractId, definition] of Object.entries(abstractDefinitions)) {
+      expectDomainString(
+        abstractId,
+        "abstractNumberingId",
+        `${path}.abstractDefinitions.${abstractId}`,
+        issues,
+      );
+      const definitionRecord = asPlainObject(
+        definition,
+        `${path}.abstractDefinitions.${abstractId}`,
+        issues,
+      );
+      if (definitionRecord && definitionRecord.abstractNumberingId !== abstractId) {
+        issues.push({
+          path: `${path}.abstractDefinitions.${abstractId}.abstractNumberingId`,
+          message: "abstractNumberingId must match the map key.",
+        });
+      }
+    }
+  }
+
+  const instances = asPlainObject(record.instances, `${path}.instances`, issues);
+  if (instances) {
+    for (const [instanceId, instance] of Object.entries(instances)) {
+      expectDomainString(
+        instanceId,
+        "numberingInstanceId",
+        `${path}.instances.${instanceId}`,
+        issues,
+      );
+      const instanceRecord = asPlainObject(
+        instance,
+        `${path}.instances.${instanceId}`,
+        issues,
+      );
+      if (!instanceRecord) {
+        continue;
+      }
+      if (instanceRecord.numberingInstanceId !== instanceId) {
+        issues.push({
+          path: `${path}.instances.${instanceId}.numberingInstanceId`,
+          message: "numberingInstanceId must match the map key.",
+        });
+      }
+      expectDomainString(
+        instanceRecord.abstractNumberingId,
+        "abstractNumberingId",
+        `${path}.instances.${instanceId}.abstractNumberingId`,
+        issues,
+      );
+    }
+  }
+}
+
+function validateMediaCatalog(
+  value: unknown,
+  path: string,
+  issues: ModelValidationIssue[],
+): void {
+  const record = asPlainObject(value, path, issues);
+  if (!record) {
+    return;
+  }
+
+  const items = asPlainObject(record.items, `${path}.items`, issues);
+  if (!items) {
+    return;
+  }
+
+  for (const [mediaId, item] of Object.entries(items)) {
+    expectDomainString(mediaId, "mediaId", `${path}.items.${mediaId}`, issues);
+    const itemRecord = asPlainObject(item, `${path}.items.${mediaId}`, issues);
+    if (!itemRecord) {
+      continue;
+    }
+    if (itemRecord.mediaId !== mediaId) {
+      issues.push({
+        path: `${path}.items.${mediaId}.mediaId`,
+        message: "mediaId must match the map key.",
+      });
+    }
+    expectDomainString(
+      itemRecord.packagePartName,
+      "packagePartName",
+      `${path}.items.${mediaId}.packagePartName`,
+      issues,
+    );
+    if (itemRecord.relationshipId !== undefined) {
+      expectDomainString(
+        itemRecord.relationshipId,
+        "relationshipId",
+        `${path}.items.${mediaId}.relationshipId`,
+        issues,
+      );
+    }
+  }
+}
+
+function validateDocumentNode(
+  value: unknown,
+  path: string,
+  issues: ModelValidationIssue[],
+): void {
+  const record = asPlainObject(value, path, issues);
+  if (!record) {
+    return;
+  }
+
+  const type = expectString(record.type, `${path}.type`, issues);
+  if (!type) {
+    return;
+  }
+
+  switch (type) {
+    case "doc":
+    case "paragraph":
+    case "sdt":
+    case "custom_xml":
+    case "hyperlink":
+      if (!Array.isArray(record.children)) {
+        issues.push({ path: `${path}.children`, message: "children must be an array." });
+      } else {
+        record.children.forEach((child, index) =>
+          validateDocumentNode(child, `${path}.children[${index}]`, issues),
+        );
+      }
+      if (type === "paragraph" && record.styleId !== undefined) {
+        expectDomainString(record.styleId, "styleId", `${path}.styleId`, issues);
+      }
+      if (type === "paragraph" && record.numbering !== undefined) {
+        const numbering = asPlainObject(record.numbering, `${path}.numbering`, issues);
+        if (numbering) {
+          expectDomainString(
+            numbering.numberingInstanceId,
+            "numberingInstanceId",
+            `${path}.numbering.numberingInstanceId`,
+            issues,
+          );
+          if (typeof numbering.level !== "number") {
+            issues.push({
+              path: `${path}.numbering.level`,
+              message: "level must be a number.",
+            });
+          }
+        }
+      }
+      if (type === "hyperlink") {
+        expectString(record.href, `${path}.href`, issues);
+      }
+      return;
+    case "alt_chunk":
+      expectDomainString(record.relationshipId, "relationshipId", `${path}.relationshipId`, issues);
+      return;
+    case "image":
+      expectDomainString(record.mediaId, "mediaId", `${path}.mediaId`, issues);
+      if (record.placementXml !== undefined) {
+        expectString(record.placementXml, `${path}.placementXml`, issues);
+      }
+      if (record.display !== undefined) {
+        const display = expectString(record.display, `${path}.display`, issues);
+        if (display && display !== "inline" && display !== "floating") {
+          issues.push({
+            path: `${path}.display`,
+            message: "display must be 'inline' or 'floating'.",
+          });
+        }
+      }
+      if (record.floating !== undefined) {
+        validateFloatingImageProperties(record.floating, `${path}.floating`, issues);
+      }
+      return;
+    case "opaque_inline":
+    case "opaque_block":
+      expectDomainString(record.fragmentId, "fragmentId", `${path}.fragmentId`, issues);
+      expectDomainString(record.warningId, "warningId", `${path}.warningId`, issues);
+      if (record.rawXml !== undefined) {
+        expectString(record.rawXml, `${path}.rawXml`, issues);
+      }
+      return;
+    case "table":
+      if (!Array.isArray(record.gridColumns)) {
+        issues.push({ path: `${path}.gridColumns`, message: "gridColumns must be an array." });
+      }
+      if (!Array.isArray(record.rows)) {
+        issues.push({ path: `${path}.rows`, message: "rows must be an array." });
+      } else {
+        record.rows.forEach((row, rowIndex) =>
+          validateDocumentNode(row, `${path}.rows[${rowIndex}]`, issues),
+        );
+      }
+      return;
+    case "table_row":
+      if (!Array.isArray(record.cells)) {
+        issues.push({ path: `${path}.cells`, message: "cells must be an array." });
+      } else {
+        record.cells.forEach((cell, cellIndex) =>
+          validateDocumentNode(cell, `${path}.cells[${cellIndex}]`, issues),
+        );
+      }
+      return;
+    case "table_cell":
+      if (!Array.isArray(record.children)) {
+        issues.push({ path: `${path}.children`, message: "children must be an array." });
+      } else {
+        record.children.forEach((child, childIndex) =>
+          validateDocumentNode(child, `${path}.children[${childIndex}]`, issues),
+        );
+      }
+      return;
+    case "field":
+      expectString(record.fieldType, `${path}.fieldType`, issues);
+      expectString(record.instruction, `${path}.instruction`, issues);
+      if (!Array.isArray(record.children)) {
+        issues.push({ path: `${path}.children`, message: "children must be an array." });
+      } else {
+        record.children.forEach((child, index) =>
+          validateDocumentNode(child, `${path}.children[${index}]`, issues),
+        );
+      }
+      return;
+    case "bookmark_start":
+      expectString(record.bookmarkId, `${path}.bookmarkId`, issues);
+      expectString(record.name, `${path}.name`, issues);
+      return;
+    case "bookmark_end":
+      expectString(record.bookmarkId, `${path}.bookmarkId`, issues);
+      return;
+    case "section_break":
+      return;
+    case "text":
+      if (typeof record.text !== "string") {
+        issues.push({
+          path: `${path}.text`,
+          message: "text must be a string.",
+        });
+      }
+      return;
+    case "hard_break":
+    case "column_break":
+    case "tab":
+      return;
+    case "symbol":
+      expectString(record.char, `${path}.char`, issues);
+      if (record.font !== undefined) {
+        expectString(record.font, `${path}.font`, issues);
+      }
+      return;
+    case "footnote_ref":
+      expectString(record.noteId, `${path}.noteId`, issues);
+      if (record.noteKind !== "footnote" && record.noteKind !== "endnote") {
+        issues.push({
+          path: `${path}.noteKind`,
+          message: "noteKind must be 'footnote' or 'endnote'.",
+        });
+      }
+      return;
+    case "chart_preview":
+    case "smartart_preview":
+    case "shape":
+    case "wordart":
+    case "vml_shape":
+      expectString(record.rawXml, `${path}.rawXml`, issues);
+      return;
+    default:
+      issues.push({
+        path: `${path}.type`,
+        message: `Unsupported node type ${JSON.stringify(type)}.`,
+      });
+  }
+}
+
+function validateFloatingImageProperties(
+  value: unknown,
+  path: string,
+  issues: ModelValidationIssue[],
+): void {
+  const record = asPlainObject(value, path, issues);
+  if (!record) {
+    return;
+  }
+
+  if (record.horizontalPosition !== undefined) {
+    validateFloatingAxisPosition(record.horizontalPosition, `${path}.horizontalPosition`, issues);
+  }
+  if (record.verticalPosition !== undefined) {
+    validateFloatingAxisPosition(record.verticalPosition, `${path}.verticalPosition`, issues);
+  }
+  if (record.wrap !== undefined) {
+    const wrap = expectString(record.wrap, `${path}.wrap`, issues);
+    if (
+      wrap &&
+      wrap !== "none" &&
+      wrap !== "square" &&
+      wrap !== "tight" &&
+      wrap !== "through" &&
+      wrap !== "topAndBottom"
+    ) {
+      issues.push({
+        path: `${path}.wrap`,
+        message: "wrap must be one of none, square, tight, through, or topAndBottom.",
+      });
+    }
+  }
+}
+
+function validateFloatingAxisPosition(
+  value: unknown,
+  path: string,
+  issues: ModelValidationIssue[],
+): void {
+  const record = asPlainObject(value, path, issues);
+  if (!record) {
+    return;
+  }
+
+  if (record.relativeFrom !== undefined) {
+    expectString(record.relativeFrom, `${path}.relativeFrom`, issues);
+  }
+  if (record.align !== undefined) {
+    expectString(record.align, `${path}.align`, issues);
+  }
+  if (record.offset !== undefined && typeof record.offset !== "number") {
+    issues.push({
+      path: `${path}.offset`,
+      message: "offset must be a number.",
+    });
+  }
+}
+
+function validateReviewStore(
+  value: unknown,
+  path: string,
+  issues: ModelValidationIssue[],
+): void {
+  const record = asPlainObject(value, path, issues);
+  if (!record) {
+    return;
+  }
+
+  const comments = asPlainObject(record.comments, `${path}.comments`, issues);
+  if (comments) {
+    for (const [commentId, thread] of Object.entries(comments)) {
+      expectDomainString(commentId, "commentId", `${path}.comments.${commentId}`, issues);
+      const threadRecord = asPlainObject(thread, `${path}.comments.${commentId}`, issues);
+      if (!threadRecord) {
+        continue;
+      }
+      if (threadRecord.commentId !== commentId) {
+        issues.push({
+          path: `${path}.comments.${commentId}.commentId`,
+          message: "commentId must match the map key.",
+        });
+      }
+      validateAnchor(threadRecord.anchor, `${path}.comments.${commentId}.anchor`, issues);
+      expectIso8601UtcTimestamp(
+        threadRecord.createdAt,
+        `${path}.comments.${commentId}.createdAt`,
+        issues,
+      );
+      validateCommentStatus(threadRecord.status, `${path}.comments.${commentId}.status`, issues);
+      if (threadRecord.createdBy !== undefined) {
+        expectString(
+          threadRecord.createdBy,
+          `${path}.comments.${commentId}.createdBy`,
+          issues,
+        );
+      }
+      if (threadRecord.authorId !== undefined) {
+        expectString(
+          threadRecord.authorId,
+          `${path}.comments.${commentId}.authorId`,
+          issues,
+        );
+      }
+      if (threadRecord.body !== undefined) {
+        expectStringAllowEmpty(
+          threadRecord.body,
+          `${path}.comments.${commentId}.body`,
+          issues,
+        );
+      }
+      if (!Array.isArray(threadRecord.warningIds)) {
+        issues.push({
+          path: `${path}.comments.${commentId}.warningIds`,
+          message: "warningIds must be an array.",
+        });
+      } else {
+        threadRecord.warningIds.forEach((warningId, index) =>
+          expectDomainString(
+            warningId,
+            "warningId",
+            `${path}.comments.${commentId}.warningIds[${index}]`,
+            issues,
+          ),
+        );
+      }
+      if (threadRecord.entries !== undefined) {
+        validateCommentEntries(
+          threadRecord.entries,
+          `${path}.comments.${commentId}.entries`,
+          issues,
+        );
+      }
+      if (threadRecord.resolution !== undefined) {
+        validateCommentResolution(
+          threadRecord.resolution,
+          `${path}.comments.${commentId}.resolution`,
+          issues,
+        );
+      }
+      if (threadRecord.resolvedAt !== undefined) {
+        expectIso8601UtcTimestamp(
+          threadRecord.resolvedAt,
+          `${path}.comments.${commentId}.resolvedAt`,
+          issues,
+        );
+      }
+      if (
+        threadRecord.isResolved !== undefined &&
+        typeof threadRecord.isResolved !== "boolean"
+      ) {
+        issues.push({
+          path: `${path}.comments.${commentId}.isResolved`,
+          message: "isResolved must be a boolean.",
+        });
+      }
+      if (threadRecord.metadata !== undefined) {
+        validateCommentThreadMetadata(
+          threadRecord.metadata,
+          `${path}.comments.${commentId}.metadata`,
+          issues,
+        );
+      }
+    }
+  }
+
+  const revisions = asPlainObject(record.revisions, `${path}.revisions`, issues);
+  if (revisions) {
+    for (const [revisionId, revision] of Object.entries(revisions)) {
+      expectDomainString(revisionId, "revisionId", `${path}.revisions.${revisionId}`, issues);
+      const revisionRecord = asPlainObject(
+        revision,
+        `${path}.revisions.${revisionId}`,
+        issues,
+      );
+      if (!revisionRecord) {
+        continue;
+      }
+      if (revisionRecord.changeId !== revisionId) {
+        issues.push({
+          path: `${path}.revisions.${revisionId}.changeId`,
+          message: "changeId must match the map key.",
+        });
+      }
+      validateAnchor(revisionRecord.anchor, `${path}.revisions.${revisionId}.anchor`, issues);
+      validateRevisionKind(revisionRecord.kind, `${path}.revisions.${revisionId}.kind`, issues);
+      validateRevisionStatus(
+        revisionRecord.status,
+        `${path}.revisions.${revisionId}.status`,
+        issues,
+      );
+      expectIso8601UtcTimestamp(
+        revisionRecord.createdAt,
+        `${path}.revisions.${revisionId}.createdAt`,
+        issues,
+      );
+      if (revisionRecord.authorId !== undefined) {
+        expectString(
+          revisionRecord.authorId,
+          `${path}.revisions.${revisionId}.authorId`,
+          issues,
+        );
+      }
+      if (revisionRecord.warningIds !== undefined) {
+        validateWarningIds(
+          revisionRecord.warningIds,
+          `${path}.revisions.${revisionId}.warningIds`,
+          issues,
+        );
+      }
+      if (revisionRecord.metadata !== undefined) {
+        validateRevisionMetadata(
+          revisionRecord.metadata,
+          `${path}.revisions.${revisionId}.metadata`,
+          issues,
+        );
+      }
+    }
+  }
+}
+
+function validateCommentStatus(
+  value: unknown,
+  path: string,
+  issues: ModelValidationIssue[],
+): void {
+  if (value === "open" || value === "resolved" || value === "detached") {
+    return;
+  }
+  issues.push({
+    path,
+    message: "status must be one of open, resolved, or detached.",
+  });
+}
+
+function validateCommentEntries(
+  value: unknown,
+  path: string,
+  issues: ModelValidationIssue[],
+): void {
+  if (!Array.isArray(value)) {
+    issues.push({
+      path,
+      message: "entries must be an array.",
+    });
+    return;
+  }
+
+  value.forEach((entry, index) => {
+    const record = asPlainObject(entry, `${path}[${index}]`, issues);
+    if (!record) {
+      return;
+    }
+    expectString(record.entryId, `${path}[${index}].entryId`, issues);
+    expectString(record.authorId, `${path}[${index}].authorId`, issues);
+    expectStringAllowEmpty(record.body, `${path}[${index}].body`, issues);
+    expectIso8601UtcTimestamp(record.createdAt, `${path}[${index}].createdAt`, issues);
+    if (record.metadata !== undefined) {
+      validateCommentEntryMetadata(record.metadata, `${path}[${index}].metadata`, issues);
+    }
+  });
+}
+
+function validateCommentEntryMetadata(
+  value: unknown,
+  path: string,
+  issues: ModelValidationIssue[],
+): void {
+  const record = asPlainObject(value, path, issues);
+  if (!record) {
+    return;
+  }
+
+  for (const field of [
+    "ooxmlCommentId",
+    "paraId",
+    "parentParaId",
+    "durableId",
+    "initials",
+  ] as const) {
+    if (record[field] !== undefined) {
+      expectString(record[field], `${path}.${field}`, issues);
+    }
+  }
+}
+
+function validateCommentResolution(
+  value: unknown,
+  path: string,
+  issues: ModelValidationIssue[],
+): void {
+  const record = asPlainObject(value, path, issues);
+  if (!record) {
+    return;
+  }
+
+  expectIso8601UtcTimestamp(record.resolvedAt, `${path}.resolvedAt`, issues);
+  expectString(record.resolvedBy, `${path}.resolvedBy`, issues);
+}
+
+function validateCommentThreadMetadata(
+  value: unknown,
+  path: string,
+  issues: ModelValidationIssue[],
+): void {
+  const record = asPlainObject(value, path, issues);
+  if (!record) {
+    return;
+  }
+
+  if (
+    record.source !== undefined &&
+    record.source !== "runtime" &&
+    record.source !== "import"
+  ) {
+    issues.push({
+      path: `${path}.source`,
+      message: "source must be either runtime or import.",
+    });
+  }
+  if (record.rootOoxmlCommentId !== undefined) {
+    expectString(record.rootOoxmlCommentId, `${path}.rootOoxmlCommentId`, issues);
+  }
+  if (record.rootParaId !== undefined) {
+    expectString(record.rootParaId, `${path}.rootParaId`, issues);
+  }
+}
+
+function validateRevisionKind(
+  value: unknown,
+  path: string,
+  issues: ModelValidationIssue[],
+): void {
+  if (
+    value === "insertion" ||
+    value === "deletion" ||
+    value === "formatting" ||
+    value === "move" ||
+    value === "property-change"
+  ) {
+    return;
+  }
+  issues.push({
+    path,
+    message: "kind must be insertion, deletion, formatting, move, or property-change.",
+  });
+}
+
+function validateRevisionStatus(
+  value: unknown,
+  path: string,
+  issues: ModelValidationIssue[],
+): void {
+  if (
+    value === "open" ||
+    value === "accepted" ||
+    value === "rejected" ||
+    value === "detached"
+  ) {
+    return;
+  }
+  issues.push({
+    path,
+    message: "status must be one of open, accepted, rejected, or detached.",
+  });
+}
+
+function validateWarningIds(
+  value: unknown,
+  path: string,
+  issues: ModelValidationIssue[],
+): void {
+  if (!Array.isArray(value)) {
+    issues.push({
+      path,
+      message: "warningIds must be an array.",
+    });
+    return;
+  }
+
+  value.forEach((warningId, index) =>
+    expectDomainString(warningId, "warningId", `${path}[${index}]`, issues),
+  );
+}
+
+function validateRevisionMetadata(
+  value: unknown,
+  path: string,
+  issues: ModelValidationIssue[],
+): void {
+  const record = asPlainObject(value, path, issues);
+  if (!record) {
+    return;
+  }
+
+  if (
+    record.source !== undefined &&
+    record.source !== "runtime" &&
+    record.source !== "import"
+  ) {
+    issues.push({
+      path: `${path}.source`,
+      message: "source must be either runtime or import.",
+    });
+  }
+  for (const field of [
+    "preserveOnlyReason",
+    "suggestionId",
+    "semanticKind",
+    "predecessorSuggestionId",
+    "importedRevisionForm",
+    "originalRevisionType",
+    "ooxmlRevisionId",
+  ] as const) {
+    if (record[field] !== undefined) {
+      expectString(record[field], `${path}.${field}`, issues);
+    }
+  }
+
+  if (record.linkedRevisionIds !== undefined) {
+    if (!Array.isArray(record.linkedRevisionIds)) {
+      issues.push({
+        path: `${path}.linkedRevisionIds`,
+        message: "linkedRevisionIds must be an array of strings.",
+      });
+    } else {
+      for (const [index, value] of record.linkedRevisionIds.entries()) {
+        expectString(value, `${path}.linkedRevisionIds.${index}`, issues);
+      }
+    }
+  }
+
+  if (record.propertyChangeData !== undefined) {
+    const pcd = asPlainObject(record.propertyChangeData, `${path}.propertyChangeData`, issues);
+    if (pcd) {
+      expectString(pcd.xmlTag, `${path}.propertyChangeData.xmlTag`, issues);
+      expectString(pcd.beforeXml, `${path}.propertyChangeData.beforeXml`, issues);
+    }
+  }
+
+  if (record.moveData !== undefined) {
+    const md = asPlainObject(record.moveData, `${path}.moveData`, issues);
+    if (md) {
+      expectString(md.moveId, `${path}.moveData.moveId`, issues);
+      expectString(md.direction, `${path}.moveData.direction`, issues);
+    }
+  }
+}
+
+function validatePreservationStore(
+  value: unknown,
+  path: string,
+  issues: ModelValidationIssue[],
+): void {
+  const record = asPlainObject(value, path, issues);
+  if (!record) {
+    return;
+  }
+
+  const opaqueFragments = asPlainObject(
+    record.opaqueFragments,
+    `${path}.opaqueFragments`,
+    issues,
+  );
+  if (opaqueFragments) {
+    for (const [fragmentId, fragment] of Object.entries(opaqueFragments)) {
+      expectDomainString(fragmentId, "fragmentId", `${path}.opaqueFragments.${fragmentId}`, issues);
+      const fragmentRecord = asPlainObject(
+        fragment,
+        `${path}.opaqueFragments.${fragmentId}`,
+        issues,
+      );
+      if (!fragmentRecord) {
+        continue;
+      }
+      if (fragmentRecord.fragmentId !== fragmentId) {
+        issues.push({
+          path: `${path}.opaqueFragments.${fragmentId}.fragmentId`,
+          message: "fragmentId must match the map key.",
+        });
+      }
+      validateRange(
+        fragmentRecord.lastKnownRange,
+        `${path}.opaqueFragments.${fragmentId}.lastKnownRange`,
+        issues,
+      );
+      expectDomainString(
+        fragmentRecord.warningId,
+        "warningId",
+        `${path}.opaqueFragments.${fragmentId}.warningId`,
+        issues,
+      );
+      if (fragmentRecord.packagePartName !== undefined) {
+        expectDomainString(
+          fragmentRecord.packagePartName,
+          "packagePartName",
+          `${path}.opaqueFragments.${fragmentId}.packagePartName`,
+          issues,
+        );
+      }
+      if (fragmentRecord.relationshipId !== undefined) {
+        expectDomainString(
+          fragmentRecord.relationshipId,
+          "relationshipId",
+          `${path}.opaqueFragments.${fragmentId}.relationshipId`,
+          issues,
+        );
+      }
+    }
+  }
+
+  const packageParts = asPlainObject(record.packageParts, `${path}.packageParts`, issues);
+  if (packageParts) {
+    for (const [packagePartName, packagePart] of Object.entries(packageParts)) {
+      expectDomainString(
+        packagePartName,
+        "packagePartName",
+        `${path}.packageParts.${packagePartName}`,
+        issues,
+      );
+      const packagePartRecord = asPlainObject(
+        packagePart,
+        `${path}.packageParts.${packagePartName}`,
+        issues,
+      );
+      if (!packagePartRecord) {
+        continue;
+      }
+      if (packagePartRecord.packagePartName !== packagePartName) {
+        issues.push({
+          path: `${path}.packageParts.${packagePartName}.packagePartName`,
+          message: "packagePartName must match the map key.",
+        });
+      }
+      if (Array.isArray(packagePartRecord.relationshipIds)) {
+        packagePartRecord.relationshipIds.forEach((relationshipId, index) =>
+          expectDomainString(
+            relationshipId,
+            "relationshipId",
+            `${path}.packageParts.${packagePartName}.relationshipIds[${index}]`,
+            issues,
+          ),
+        );
+      }
+    }
+  }
+}
+
+function validateDiagnosticStore(
+  value: unknown,
+  path: string,
+  issues: ModelValidationIssue[],
+): void {
+  const record = asPlainObject(value, path, issues);
+  if (!record) {
+    return;
+  }
+
+  if (Array.isArray(record.warnings)) {
+    record.warnings.forEach((warning, index) => {
+      const warningRecord = asPlainObject(warning, `${path}.warnings[${index}]`, issues);
+      if (!warningRecord) {
+        return;
+      }
+      expectDomainString(
+        warningRecord.diagnosticId,
+        "diagnosticId",
+        `${path}.warnings[${index}].diagnosticId`,
+        issues,
+      );
+      expectDomainString(
+        warningRecord.warningId,
+        "warningId",
+        `${path}.warnings[${index}].warningId`,
+        issues,
+      );
+    });
+  }
+
+  if (Array.isArray(record.errors)) {
+    record.errors.forEach((error, index) => {
+      const errorRecord = asPlainObject(error, `${path}.errors[${index}]`, issues);
+      if (!errorRecord) {
+        return;
+      }
+      expectDomainString(
+        errorRecord.diagnosticId,
+        "diagnosticId",
+        `${path}.errors[${index}].diagnosticId`,
+        issues,
+      );
+    });
+  }
+}
+
+function validateAnchor(
+  value: unknown,
+  path: string,
+  issues: ModelValidationIssue[],
+): void {
+  const record = asPlainObject(value, path, issues);
+  if (!record) {
+    return;
+  }
+
+  const kind = expectString(record.kind, `${path}.kind`, issues);
+  if (!kind) {
+    return;
+  }
+
+  if (kind === "range") {
+    validateRange(record.range, `${path}.range`, issues);
+    validateBoundaryAssoc(record.assoc, `${path}.assoc`, issues);
+  } else if (kind === "node") {
+    if (typeof record.at !== "number") {
+      issues.push({
+        path: `${path}.at`,
+        message: "node anchors must contain a numeric at value.",
+      });
+    }
+    if (record.assoc !== -1 && record.assoc !== 1) {
+      issues.push({
+        path: `${path}.assoc`,
+        message: "node anchor assoc must be -1 or 1.",
+      });
+    }
+  } else if (kind === "detached") {
+    validateRange(record.lastKnownRange, `${path}.lastKnownRange`, issues);
+    if (
+      record.reason !== "deleted" &&
+      record.reason !== "invalidatedByStructureChange" &&
+      record.reason !== "importAmbiguity"
+    ) {
+      issues.push({
+        path: `${path}.reason`,
+        message: "detached anchor reason must be deleted, invalidatedByStructureChange, or importAmbiguity.",
+      });
+    }
+  } else {
+    issues.push({
+      path: `${path}.kind`,
+      message: "anchor kind must be range, node, or detached.",
+    });
+  }
+}
+
+function validateBoundaryAssoc(
+  value: unknown,
+  path: string,
+  issues: ModelValidationIssue[],
+): void {
+  const record = asPlainObject(value, path, issues);
+  if (!record) {
+    return;
+  }
+
+  if (record.start !== -1 && record.start !== 1) {
+    issues.push({
+      path: `${path}.start`,
+      message: "assoc.start must be -1 or 1.",
+    });
+  }
+  if (record.end !== -1 && record.end !== 1) {
+    issues.push({
+      path: `${path}.end`,
+      message: "assoc.end must be -1 or 1.",
+    });
+  }
+}
+
+function validateDocumentReferences(
+  record: Record<string, unknown>,
+  issues: ModelValidationIssue[],
+): void {
+  const paragraphStyleIds = new Set(
+    Object.keys(asPlainObject(asPlainObject(record.styles, "$.styles", [])?.paragraphs, "$.styles.paragraphs", []) ?? {}),
+  );
+  const numberingInstanceIds = new Set(
+    Object.keys(asPlainObject(asPlainObject(record.numbering, "$.numbering", [])?.instances, "$.numbering.instances", []) ?? {}),
+  );
+  const abstractNumberingIds = new Set(
+    Object.keys(asPlainObject(asPlainObject(record.numbering, "$.numbering", [])?.abstractDefinitions, "$.numbering.abstractDefinitions", []) ?? {}),
+  );
+  const mediaIds = new Set(
+    Object.keys(asPlainObject(asPlainObject(record.media, "$.media", [])?.items, "$.media.items", []) ?? {}),
+  );
+  const warningIds = new Set(
+    (Array.isArray(asPlainObject(record.diagnostics, "$.diagnostics", [])?.warnings)
+      ? (asPlainObject(record.diagnostics, "$.diagnostics", [])?.warnings as Array<Record<string, unknown>>)
+      : []
+    ).flatMap((warning) => typeof warning.warningId === "string" ? [warning.warningId] : []),
+  );
+  const fragmentIds = new Set(
+    Object.keys(asPlainObject(asPlainObject(record.preservation, "$.preservation", [])?.opaqueFragments, "$.preservation.opaqueFragments", []) ?? {}),
+  );
+  const noteIds = collectNoteIds(record);
+
+  const numberingInstances = asPlainObject(
+    asPlainObject(record.numbering, "$.numbering", [])?.instances,
+    "$.numbering.instances",
+    [],
+  );
+  if (numberingInstances) {
+    for (const [instanceId, instance] of Object.entries(numberingInstances)) {
+      const instanceRecord = asPlainObject(instance, `$.numbering.instances.${instanceId}`, []);
+      if (
+        instanceRecord &&
+        typeof instanceRecord.abstractNumberingId === "string" &&
+        !abstractNumberingIds.has(instanceRecord.abstractNumberingId)
+      ) {
+        issues.push({
+          path: `$.numbering.instances.${instanceId}.abstractNumberingId`,
+          message: "abstractNumberingId must reference an existing abstract numbering definition.",
+        });
+      }
+    }
+  }
+
+  validateDocumentNodeReferences(record.content, "$.content", issues, {
+    paragraphStyleIds,
+    numberingInstanceIds,
+    mediaIds,
+    warningIds,
+    fragmentIds,
+    noteIds,
+  });
+  validateSubPartReferences(record.subParts, "$.subParts", issues, {
+    paragraphStyleIds,
+    numberingInstanceIds,
+    mediaIds,
+    warningIds,
+    fragmentIds,
+    noteIds,
+  });
+  validateReviewReferences(record.review, "$.review", issues, warningIds);
+}
+
+function validateDocumentNodeReferences(
+  value: unknown,
+  path: string,
+  issues: ModelValidationIssue[],
+  references: {
+    paragraphStyleIds: ReadonlySet<string>;
+    numberingInstanceIds: ReadonlySet<string>;
+    mediaIds: ReadonlySet<string>;
+    warningIds: ReadonlySet<string>;
+    fragmentIds: ReadonlySet<string>;
+    noteIds: ReadonlySet<string>;
+  },
+): void {
+  const record = asPlainObject(value, path, issues);
+  if (!record) {
+    return;
+  }
+
+  const type = typeof record.type === "string" ? record.type : undefined;
+  if (type === "paragraph") {
+    if (
+      typeof record.styleId === "string" &&
+      !references.paragraphStyleIds.has(record.styleId)
+    ) {
+      issues.push({
+        path: `${path}.styleId`,
+        message: "styleId must reference an existing paragraph style definition.",
+      });
+    }
+    const numbering = asPlainObject(record.numbering, `${path}.numbering`, []);
+    if (
+      numbering &&
+      typeof numbering.numberingInstanceId === "string" &&
+      !references.numberingInstanceIds.has(numbering.numberingInstanceId)
+    ) {
+      issues.push({
+        path: `${path}.numbering.numberingInstanceId`,
+        message: "numberingInstanceId must reference an existing numbering instance.",
+      });
+    }
+  } else if (type === "image") {
+    if (typeof record.mediaId === "string" && !references.mediaIds.has(record.mediaId)) {
+      issues.push({
+        path: `${path}.mediaId`,
+        message: "mediaId must reference an existing media catalog item.",
+      });
+    }
+  } else if (type === "opaque_inline" || type === "opaque_block") {
+    if (typeof record.fragmentId === "string" && !references.fragmentIds.has(record.fragmentId)) {
+      issues.push({
+        path: `${path}.fragmentId`,
+        message: "fragmentId must reference an existing opaque fragment.",
+      });
+    }
+    if (typeof record.warningId === "string" && !references.warningIds.has(record.warningId)) {
+      issues.push({
+        path: `${path}.warningId`,
+        message: "warningId must reference an existing diagnostic warning.",
+      });
+    }
+  } else if (type === "footnote_ref") {
+    if (typeof record.noteId === "string" && !references.noteIds.has(`${record.noteKind}:${record.noteId}`)) {
+      issues.push({
+        path: `${path}.noteId`,
+        message: "noteId must reference an existing footnote or endnote definition.",
+      });
+    }
+  }
+
+  if (Array.isArray(record.children)) {
+    record.children.forEach((child, index) =>
+      validateDocumentNodeReferences(child, `${path}.children[${index}]`, issues, references),
+    );
+  }
+  if (Array.isArray(record.rows)) {
+    record.rows.forEach((row, index) =>
+      validateDocumentNodeReferences(row, `${path}.rows[${index}]`, issues, references),
+    );
+  }
+  if (Array.isArray(record.cells)) {
+    record.cells.forEach((cell, index) =>
+      validateDocumentNodeReferences(cell, `${path}.cells[${index}]`, issues, references),
+    );
+  }
+}
+
+function validateReviewReferences(
+  value: unknown,
+  path: string,
+  issues: ModelValidationIssue[],
+  warningIds: ReadonlySet<string>,
+): void {
+  const record = asPlainObject(value, path, issues);
+  if (!record) {
+    return;
+  }
+
+  const comments = asPlainObject(record.comments, `${path}.comments`, []);
+  if (comments) {
+    for (const [commentId, thread] of Object.entries(comments)) {
+      const threadRecord = asPlainObject(thread, `${path}.comments.${commentId}`, []);
+      if (!threadRecord || !Array.isArray(threadRecord.warningIds)) {
+        continue;
+      }
+      threadRecord.warningIds.forEach((warningId, index) => {
+        if (typeof warningId === "string" && !warningIds.has(warningId)) {
+          issues.push({
+            path: `${path}.comments.${commentId}.warningIds[${index}]`,
+            message: "warningIds must reference existing diagnostic warnings.",
+          });
+        }
+      });
+    }
+  }
+
+  const revisions = asPlainObject(record.revisions, `${path}.revisions`, []);
+  if (revisions) {
+    for (const [revisionId, revision] of Object.entries(revisions)) {
+      const revisionRecord = asPlainObject(revision, `${path}.revisions.${revisionId}`, []);
+      if (!revisionRecord || !Array.isArray(revisionRecord.warningIds)) {
+        continue;
+      }
+      revisionRecord.warningIds.forEach((warningId, index) => {
+        if (typeof warningId === "string" && !warningIds.has(warningId)) {
+          issues.push({
+            path: `${path}.revisions.${revisionId}.warningIds[${index}]`,
+            message: "warningIds must reference existing diagnostic warnings.",
+          });
+        }
+      });
+    }
+  }
+}
+
+function validateSubPartReferences(
+  value: unknown,
+  path: string,
+  issues: ModelValidationIssue[],
+  references: {
+    paragraphStyleIds: ReadonlySet<string>;
+    numberingInstanceIds: ReadonlySet<string>;
+    mediaIds: ReadonlySet<string>;
+    warningIds: ReadonlySet<string>;
+    fragmentIds: ReadonlySet<string>;
+    noteIds: ReadonlySet<string>;
+  },
+): void {
+  if (value === undefined) {
+    return;
+  }
+  const record = asPlainObject(value, path, issues);
+  if (!record) {
+    return;
+  }
+
+  const headers = Array.isArray(record.headers) ? record.headers : [];
+  headers.forEach((header, index) => {
+    const headerRecord = asPlainObject(header, `${path}.headers[${index}]`, []);
+    if (!headerRecord || !Array.isArray(headerRecord.blocks)) {
+      return;
+    }
+    headerRecord.blocks.forEach((block, blockIndex) =>
+      validateDocumentNodeReferences(block, `${path}.headers[${index}].blocks[${blockIndex}]`, issues, references),
+    );
+  });
+
+  const footers = Array.isArray(record.footers) ? record.footers : [];
+  footers.forEach((footer, index) => {
+    const footerRecord = asPlainObject(footer, `${path}.footers[${index}]`, []);
+    if (!footerRecord || !Array.isArray(footerRecord.blocks)) {
+      return;
+    }
+    footerRecord.blocks.forEach((block, blockIndex) =>
+      validateDocumentNodeReferences(block, `${path}.footers[${index}].blocks[${blockIndex}]`, issues, references),
+    );
+  });
+
+  if (record.footnoteCollection !== undefined) {
+    const footnoteCollection = asPlainObject(record.footnoteCollection, `${path}.footnoteCollection`, []);
+    const footnotes = asPlainObject(footnoteCollection?.footnotes, `${path}.footnoteCollection.footnotes`, []);
+    if (footnotes) {
+      for (const [noteId, note] of Object.entries(footnotes)) {
+        const noteRecord = asPlainObject(note, `${path}.footnoteCollection.footnotes.${noteId}`, []);
+        if (!noteRecord || !Array.isArray(noteRecord.blocks)) {
+          continue;
+        }
+        noteRecord.blocks.forEach((block, blockIndex) =>
+          validateDocumentNodeReferences(
+            block,
+            `${path}.footnoteCollection.footnotes.${noteId}.blocks[${blockIndex}]`,
+            issues,
+            references,
+          ),
+        );
+      }
+    }
+
+    const endnotes = asPlainObject(footnoteCollection?.endnotes, `${path}.footnoteCollection.endnotes`, []);
+    if (endnotes) {
+      for (const [noteId, note] of Object.entries(endnotes)) {
+        const noteRecord = asPlainObject(note, `${path}.footnoteCollection.endnotes.${noteId}`, []);
+        if (!noteRecord || !Array.isArray(noteRecord.blocks)) {
+          continue;
+        }
+        noteRecord.blocks.forEach((block, blockIndex) =>
+          validateDocumentNodeReferences(
+            block,
+            `${path}.footnoteCollection.endnotes.${noteId}.blocks[${blockIndex}]`,
+            issues,
+            references,
+          ),
+        );
+      }
+    }
+  }
+}
+
+function collectNoteIds(record: Record<string, unknown>): Set<string> {
+  const noteIds = new Set<string>();
+  const subParts = asPlainObject(record.subParts, "$.subParts", []);
+  const footnoteCollection = asPlainObject(subParts?.footnoteCollection, "$.subParts.footnoteCollection", []);
+  const footnotes = asPlainObject(footnoteCollection?.footnotes, "$.subParts.footnoteCollection.footnotes", []);
+  if (footnotes) {
+    Object.keys(footnotes).forEach((noteId) => noteIds.add(`footnote:${noteId}`));
+  }
+  const endnotes = asPlainObject(footnoteCollection?.endnotes, "$.subParts.footnoteCollection.endnotes", []);
+  if (endnotes) {
+    Object.keys(endnotes).forEach((noteId) => noteIds.add(`endnote:${noteId}`));
+  }
+  return noteIds;
+}
+
+function validateRange(
+  value: unknown,
+  path: string,
+  issues: ModelValidationIssue[],
+): void {
+  const record = asPlainObject(value, path, issues);
+  if (!record) {
+    return;
+  }
+
+  if (typeof record.from !== "number" || typeof record.to !== "number") {
+    issues.push({
+      path,
+      message: "Range must contain numeric from and to values.",
+    });
+  }
+}
+
+function validateExactObjectKeys(
+  record: Record<string, unknown>,
+  expectedKeys: readonly string[],
+  path: string,
+  issues: ModelValidationIssue[],
+  allowedOptionalKeys?: readonly string[],
+): void {
+  const actualKeys = new Set(Object.keys(record));
+  const expected = new Set(expectedKeys);
+  const optional = new Set(allowedOptionalKeys ?? []);
+
+  for (const expectedKey of expectedKeys) {
+    if (!actualKeys.has(expectedKey)) {
+      issues.push({
+        path,
+        message: `Missing required key ${JSON.stringify(expectedKey)}.`,
+      });
+    }
+  }
+
+  for (const actualKey of actualKeys) {
+    if (!expected.has(actualKey) && !optional.has(actualKey)) {
+      issues.push({
+        path: `${path}.${actualKey}`,
+        message:
+          "Unexpected canonical document key. Render/UI state is not part of the canonical envelope.",
+      });
+    }
+  }
+}
+
+function validateSubPartsCatalog(
+  value: unknown,
+  path: string,
+  issues: ModelValidationIssue[],
+): void {
+  if (value === undefined) {
+    return;
+  }
+  const record = asPlainObject(value, path, issues);
+  if (!record) {
+    return;
+  }
+
+  if (record.headers !== undefined) {
+    if (!Array.isArray(record.headers)) {
+      issues.push({ path: `${path}.headers`, message: "headers must be an array." });
+    } else {
+      record.headers.forEach((header, index) => {
+        const headerRecord = asPlainObject(header, `${path}.headers[${index}]`, issues);
+        if (headerRecord) {
+          expectString(headerRecord.variant, `${path}.headers[${index}].variant`, issues);
+          expectString(headerRecord.partPath, `${path}.headers[${index}].partPath`, issues);
+          expectString(headerRecord.relationshipId, `${path}.headers[${index}].relationshipId`, issues);
+          if (!Array.isArray(headerRecord.blocks)) {
+            issues.push({ path: `${path}.headers[${index}].blocks`, message: "blocks must be an array." });
+          } else {
+            headerRecord.blocks.forEach((block, blockIndex) =>
+              validateDocumentNode(block, `${path}.headers[${index}].blocks[${blockIndex}]`, issues),
+            );
+          }
+        }
+      });
+    }
+  }
+
+  if (record.footers !== undefined) {
+    if (!Array.isArray(record.footers)) {
+      issues.push({ path: `${path}.footers`, message: "footers must be an array." });
+    } else {
+      record.footers.forEach((footer, index) => {
+        const footerRecord = asPlainObject(footer, `${path}.footers[${index}]`, issues);
+        if (footerRecord) {
+          expectString(footerRecord.variant, `${path}.footers[${index}].variant`, issues);
+          expectString(footerRecord.partPath, `${path}.footers[${index}].partPath`, issues);
+          expectString(footerRecord.relationshipId, `${path}.footers[${index}].relationshipId`, issues);
+          if (!Array.isArray(footerRecord.blocks)) {
+            issues.push({ path: `${path}.footers[${index}].blocks`, message: "blocks must be an array." });
+          } else {
+            footerRecord.blocks.forEach((block, blockIndex) =>
+              validateDocumentNode(block, `${path}.footers[${index}].blocks[${blockIndex}]`, issues),
+            );
+          }
+        }
+      });
+    }
+  }
+
+  if (record.footnoteCollection !== undefined) {
+    const footnoteCollection = asPlainObject(record.footnoteCollection, `${path}.footnoteCollection`, issues);
+    if (footnoteCollection) {
+      validateSubPartNoteMap(footnoteCollection.footnotes, "footnote", `${path}.footnoteCollection.footnotes`, issues);
+      validateSubPartNoteMap(footnoteCollection.endnotes, "endnote", `${path}.footnoteCollection.endnotes`, issues);
+    }
+  }
+}
+
+function validateSubPartNoteMap(
+  value: unknown,
+  expectedKind: "footnote" | "endnote",
+  path: string,
+  issues: ModelValidationIssue[],
+): void {
+  const record = asPlainObject(value, path, issues);
+  if (!record) {
+    return;
+  }
+
+  for (const [noteId, note] of Object.entries(record)) {
+    const noteRecord = asPlainObject(note, `${path}.${noteId}`, issues);
+    if (!noteRecord) {
+      continue;
+    }
+    expectString(noteRecord.noteId, `${path}.${noteId}.noteId`, issues);
+    if (noteRecord.noteId !== noteId) {
+      issues.push({
+        path: `${path}.${noteId}.noteId`,
+        message: "noteId must match the map key.",
+      });
+    }
+    if (noteRecord.kind !== expectedKind) {
+      issues.push({
+        path: `${path}.${noteId}.kind`,
+        message: `kind must be ${expectedKind}.`,
+      });
+    }
+    if (!Array.isArray(noteRecord.blocks)) {
+      issues.push({ path: `${path}.${noteId}.blocks`, message: "blocks must be an array." });
+    } else {
+      noteRecord.blocks.forEach((block, blockIndex) =>
+        validateDocumentNode(block, `${path}.${noteId}.blocks[${blockIndex}]`, issues),
+      );
+    }
+  }
+}
+
+function expectDomainString(
+  value: unknown,
+  domain: StableIdDomain,
+  path: string,
+  issues: ModelValidationIssue[],
+): string | null {
+  const stableId = expectString(value, path, issues);
+  if (!stableId) {
+    return null;
+  }
+
+  if (!ID_PATTERNS[domain].test(stableId)) {
+    issues.push({
+      path,
+      message: `Expected a valid ${domain}.`,
+    });
+    return null;
+  }
+
+  return stableId;
+}