@beyondwork/docx-react-component 1.0.102 → 1.0.104

package/src/model/canonical-document.ts

@@ -105,7 +105,7 @@ export interface CanonicalDocument {
  */
 export interface CanonicalDocumentFragment {
   /** Block-level children of the fragment, in document order. */
-  readonly blocks: ReadonlyArray<BlockNode>;
+  readonly blocks: BlockNode[];
 }
 
 /**
@@ -138,18 +138,20 @@ export type MutableCanonicalDocumentFragment = Mutable<CanonicalDocumentFragment
  * Never cast a value received as a parameter. Only cast values you just
  * created via object literal, spread, `structuredClone`, or `createCanonicalDocument`.
  *
- * **Shallow only.** `Mutable<T>` strips `readonly` at the top level of `T`;
- * nested `ReadonlyArray<…>`, `Readonly<…>`, and inner `readonly` modifiers
- * declared inside referenced types are preserved. For example,
- * `Mutable<CanonicalDocument>` does NOT make `draft.content.children`
- * mutable — `content` is `DocumentRootNode`, whose `children` field is
- * declared as it is in the source type. If you need to mutate nested
- * structure, build the nested value first (also as a `Mutable<…>` of the
- * nested type) and assign it onto the draft as a complete replacement.
- * Deep-readonly propagation across nested catalogs/stores/nodes is a
- * deferred D1 follow-up (see `docs/plans/refactor/02-canonical-document-deferred.md`).
+ * `Mutable<T>` strips readonly recursively, including `…[]`,
+ * `Readonly<…>`, and inner readonly modifiers declared inside referenced
+ * types. That is intentional for D1: parser/runtime producers can build a
+ * fully local draft with normal assignment and array operations, then return
+ * it widened to the readonly canonical type at the function boundary.
  */
-export type Mutable<T> = { -readonly [K in keyof T]: T[K] };
+export type Mutable<T> =
+  T extends (...args: infer Args) => infer Return
+    ? (...args: Args) => Return
+    : T extends (infer Item)[]
+      ? Mutable<Item>[]
+      : T extends object
+        ? { -readonly [K in keyof T]: Mutable<T[K]> }
+        : T;
 
 /**
  * Draft-only mutable view of `CanonicalDocument`. Equivalent to
@@ -186,92 +188,92 @@ export type MutableCanonicalFontTable = Mutable<CanonicalFontTable>;
 
 
 export interface DocumentMetadata {
-  title?: string;
-  subject?: string;
-  description?: string;
-  creator?: string;
-  language?: string;
-  keywords?: string[];
-  category?: string;
-  lastModifiedBy?: string;
-  contentStatus?: string;
-  revision?: string;
-  version?: string;
-  createdUtc?: string;
-  modifiedUtc?: string;
-  importMode?: string;
-  appProperties?: DocumentAppProperties;
-  customProperties: Record<string, string>;
+  readonly title?: string;
+  readonly subject?: string;
+  readonly description?: string;
+  readonly creator?: string;
+  readonly language?: string;
+  readonly keywords?: string[];
+  readonly category?: string;
+  readonly lastModifiedBy?: string;
+  readonly contentStatus?: string;
+  readonly revision?: string;
+  readonly version?: string;
+  readonly createdUtc?: string;
+  readonly modifiedUtc?: string;
+  readonly importMode?: string;
+  readonly appProperties?: DocumentAppProperties;
+  readonly customProperties: Record<string, string>;
 }
 
 export interface DocumentAppProperties {
-  application?: string;
-  appVersion?: string;
-  template?: string;
-  pages?: number;
-  words?: number;
-  characters?: number;
-  charactersWithSpaces?: number;
-  totalTime?: number;
-  company?: string;
-  manager?: string;
-  docSecurity?: number;
+  readonly application?: string;
+  readonly appVersion?: string;
+  readonly template?: string;
+  readonly pages?: number;
+  readonly words?: number;
+  readonly characters?: number;
+  readonly charactersWithSpaces?: number;
+  readonly totalTime?: number;
+  readonly company?: string;
+  readonly manager?: string;
+  readonly docSecurity?: number;
 }
 
 export interface StylesCatalog {
-  paragraphs: Record<string, ParagraphStyleDefinition>;
-  characters: Record<string, CharacterStyleDefinition>;
-  tables: Record<string, TableStyleDefinition>;
+  readonly paragraphs: Record<string, ParagraphStyleDefinition>;
+  readonly characters: Record<string, CharacterStyleDefinition>;
+  readonly tables: Record<string, TableStyleDefinition>;
   /**
    * `w:type="numbering"` styles — preserve-only. Word emits these for
    * style-linked list families (List Bullet, List Number). Canonical
    * consumers do not apply numbering via these styles; they survive
    * only for round-trip fidelity.
    */
-  numberingStyles?: Record<string, NumberingStyleDefinition>;
-  latentStyles?: Record<string, LatentStyleDefinition>;
-  fromPackage?: boolean;
-  docDefaults?: DocumentDefaults;
+  readonly numberingStyles?: Record<string, NumberingStyleDefinition>;
+  readonly latentStyles?: Record<string, LatentStyleDefinition>;
+  readonly fromPackage?: boolean;
+  readonly docDefaults?: DocumentDefaults;
 }
 
 /** A `<w:style w:type="numbering">` entry. Preserve-only. */
 export interface NumberingStyleDefinition {
-  styleId: string;
-  displayName: string;
-  kind: "numbering";
-  isDefault: boolean;
-  basedOn?: string;
-  aliases?: string[];
+  readonly styleId: string;
+  readonly displayName: string;
+  readonly kind: "numbering";
+  readonly isDefault: boolean;
+  readonly basedOn?: string;
+  readonly aliases?: string[];
   /**
    * The `<w:numId w:val="..."/>` inside the `<w:pPr><w:numPr>` subtree,
    * when present. Consumers that later resolve numbering-type styles to
    * numbering instances (Lane 3a) will use this.
    */
-  numberingInstanceId?: string;
+  readonly numberingInstanceId?: string;
 }
 
 export interface ParagraphStyleDefinition {
-  styleId: string;
-  basedOn?: string;
-  nextStyle?: string;
-  outlineLevel?: number;
-  numbering?: ParagraphStyleNumberingReference;
-  displayName: string;
+  readonly styleId: string;
+  readonly basedOn?: string;
+  readonly nextStyle?: string;
+  readonly outlineLevel?: number;
+  readonly numbering?: ParagraphStyleNumberingReference;
+  readonly displayName: string;
   /**
    * Alternate display names parsed from `<w:aliases w:val="A,B"/>`
    * (ECMA-376 §17.7.4.2). Comma-separated in source; stored as array.
    */
-  aliases?: string[];
+  readonly aliases?: string[];
   /**
    * `<w:autoRedefine/>` — when true, Word re-records paragraph direct
    * formatting into the style definition as the user types (ECMA-376
    * §17.7.4.3). Round-trip preservation only; no render effect.
    */
-  autoRedefine?: boolean;
-  kind: "paragraph";
-  isDefault: boolean;
-  paragraphProperties?: CanonicalParagraphFormatting;
-  runProperties?: CanonicalRunFormatting;
+  readonly autoRedefine?: boolean;
+  readonly kind: "paragraph";
+  readonly isDefault: boolean;
+  readonly paragraphProperties?: CanonicalParagraphFormatting;
+  readonly runProperties?: CanonicalRunFormatting;
   /**
    * Style ID of the linked character style (from `<w:link w:val="..."/>`).
    * Populated during parse; the second-pass resolver in `parse-styles.ts`
@@ -279,55 +281,55 @@ export interface ParagraphStyleDefinition {
    * declares the relationship on one side. Mirrors LibreOffice's
    * `StyleSheetTable.cxx:535` second pass.
    */
-  linkedStyleId?: string;
+  readonly linkedStyleId?: string;
 }
 
 export interface ParagraphStyleNumberingReference {
-  numberingInstanceId: string;
-  level?: number;
+  readonly numberingInstanceId: string;
+  readonly level?: number;
 }
 
 export interface CharacterStyleDefinition {
-  styleId: string;
-  basedOn?: string;
-  displayName: string;
+  readonly styleId: string;
+  readonly basedOn?: string;
+  readonly displayName: string;
   /** See `ParagraphStyleDefinition.aliases`. */
-  aliases?: string[];
-  kind: "character";
-  isDefault: boolean;
-  runProperties?: CanonicalRunFormatting;
+  readonly aliases?: string[];
+  readonly kind: "character";
+  readonly isDefault: boolean;
+  readonly runProperties?: CanonicalRunFormatting;
   /**
    * Style ID of the linked paragraph style (from `<w:link w:val="..."/>`).
    * See `ParagraphStyleDefinition.linkedStyleId` for the second-pass
    * reciprocal-resolution contract.
    */
-  linkedStyleId?: string;
+  readonly linkedStyleId?: string;
 }
 
 export interface TableStyleDefinition {
-  styleId: string;
-  basedOn?: string;
-  displayName: string;
+  readonly styleId: string;
+  readonly basedOn?: string;
+  readonly displayName: string;
   /** See `ParagraphStyleDefinition.aliases`. */
-  aliases?: string[];
-  kind: "table";
-  isDefault: boolean;
-  formatting?: TableStyleFormatting;
-  conditionalFormatting?: Partial<Record<TableStyleConditionalRegion, TableStyleFormatting>>;
+  readonly aliases?: string[];
+  readonly kind: "table";
+  readonly isDefault: boolean;
+  readonly formatting?: TableStyleFormatting;
+  readonly conditionalFormatting?: Partial<Record<TableStyleConditionalRegion, TableStyleFormatting>>;
 }
 
 export interface LatentStyleDefinition {
-  name: string;
-  locked?: boolean;
-  semiHidden?: boolean;
-  unhideWhenUsed?: boolean;
-  qFormat?: boolean;
-  uiPriority?: number;
+  readonly name: string;
+  readonly locked?: boolean;
+  readonly semiHidden?: boolean;
+  readonly unhideWhenUsed?: boolean;
+  readonly qFormat?: boolean;
+  readonly uiPriority?: number;
 }
 
 export interface NumberingCatalog {
-  abstractDefinitions: Record<string, AbstractNumberingDefinition>;
-  instances: Record<string, NumberingInstance>;
+  readonly abstractDefinitions: Record<string, AbstractNumberingDefinition>;
+  readonly instances: Record<string, NumberingInstance>;
   /**
    * `<w:numPicBullet>` media-catalog entries keyed by `w:numPicBulletId`.
    * Each entry preserves the raw drawing/pic XML plus a resolved media
@@ -335,7 +337,7 @@ export interface NumberingCatalog {
    * Consumed by numbering-prefix when `NumberingLevelDefinition.picBulletId`
    * is set (ECMA-376 §17.9.19). Rendering is Lane 6 territory.
    */
-  numPicBullets?: Record<string, NumPicBullet>;
+  readonly numPicBullets?: Record<string, NumPicBullet>;
 }
 
 /**
@@ -348,101 +350,101 @@ export interface NumberingCatalog {
  */
 export interface NumPicBullet {
   /** `w:numPicBulletId` attribute value — the lookup key. */
-  numPicBulletId: string;
+  readonly numPicBulletId: string;
   /** Verbatim XML for the `<w:numPicBullet>` element. */
-  rawXml: string;
+  readonly rawXml: string;
   /**
    * Resolved media-catalog media id when the bullet's inner image references
    * a relationship we could resolve at parse time. Undefined when the
    * bullet uses an unresolved blipRef or a VML path.
    */
-  mediaId?: string;
+  readonly mediaId?: string;
   /**
    * Bullet cell extent in EMU (English Metric Units) when parsed from the
    * drawing's `wp:extent` — lets the renderer size the bullet image without
    * round-tripping through a new measurement pass. Undefined for VML paths.
    */
-  widthEmu?: number;
-  heightEmu?: number;
+  readonly widthEmu?: number;
+  readonly heightEmu?: number;
 }
 
 export interface AbstractNumberingDefinition {
-  abstractNumberingId: string;
-  levels: NumberingLevelDefinition[];
-  nsid?: string;
-  multiLevelType?: "singleLevel" | "multilevel" | "hybridMultilevel";
+  readonly abstractNumberingId: string;
+  readonly levels: NumberingLevelDefinition[];
+  readonly nsid?: string;
+  readonly multiLevelType?: "singleLevel" | "multilevel" | "hybridMultilevel";
   /** ECMA-376 17.9.26 `<w:tmpl>` — template code identifying the abstractNum's origin template (ST_LongHexNumber). Preserved for round-trip. */
-  tplc?: string;
-  styleLink?: string;
-  numStyleLink?: string;
+  readonly tplc?: string;
+  readonly styleLink?: string;
+  readonly numStyleLink?: string;
 }
 
 export interface NumberingLevelParagraphGeometry {
-  justification?: "left" | "center" | "right" | "both" | "distribute";
-  spacing?: ParagraphSpacing;
-  indentation?: ParagraphIndentation;
-  tabStops?: TabStop[];
+  readonly justification?: "left" | "center" | "right" | "both" | "distribute";
+  readonly spacing?: ParagraphSpacing;
+  readonly indentation?: ParagraphIndentation;
+  readonly tabStops?: TabStop[];
 }
 
 export interface NumberingLevelDefinition {
-  level: number;
-  format: string;
-  text: string;
-  startAt?: number;
-  paragraphStyleId?: string;
-  isLegalNumbering?: boolean;
-  suffix?: "tab" | "space" | "nothing";
-  paragraphGeometry?: NumberingLevelParagraphGeometry;
-  runProperties?: CanonicalRunFormatting;
-  restartAfterLevel?: number;
+  readonly level: number;
+  readonly format: string;
+  readonly text: string;
+  readonly startAt?: number;
+  readonly paragraphStyleId?: string;
+  readonly isLegalNumbering?: boolean;
+  readonly suffix?: "tab" | "space" | "nothing";
+  readonly paragraphGeometry?: NumberingLevelParagraphGeometry;
+  readonly runProperties?: CanonicalRunFormatting;
+  readonly restartAfterLevel?: number;
   /**
    * `<w:lvlPicBulletId w:val="N"/>` reference — picks the matching entry
    * from `NumberingCatalog.numPicBullets`. When set, the marker renders as
    * an inline image instead of a text glyph. ECMA-376 §17.9.12.
    */
-  picBulletId?: string;
+  readonly picBulletId?: string;
 }
 
 export interface NumberingLevelOverrideDefinition {
-  level: number;
-  format?: string;
-  text?: string;
-  startAt?: number;
-  paragraphStyleId?: string;
-  isLegalNumbering?: boolean;
-  suffix?: "tab" | "space" | "nothing";
-  paragraphGeometry?: NumberingLevelParagraphGeometry;
-  runProperties?: CanonicalRunFormatting;
-  restartAfterLevel?: number;
-  picBulletId?: string;
+  readonly level: number;
+  readonly format?: string;
+  readonly text?: string;
+  readonly startAt?: number;
+  readonly paragraphStyleId?: string;
+  readonly isLegalNumbering?: boolean;
+  readonly suffix?: "tab" | "space" | "nothing";
+  readonly paragraphGeometry?: NumberingLevelParagraphGeometry;
+  readonly runProperties?: CanonicalRunFormatting;
+  readonly restartAfterLevel?: number;
+  readonly picBulletId?: string;
 }
 
 export interface NumberingInstance {
-  numberingInstanceId: string;
-  abstractNumberingId: string;
-  overrides: NumberingLevelOverride[];
+  readonly numberingInstanceId: string;
+  readonly abstractNumberingId: string;
+  readonly overrides: NumberingLevelOverride[];
 }
 
 export interface NumberingLevelOverride {
-  level: number;
-  startAt?: number;
-  levelDefinition?: NumberingLevelOverrideDefinition;
+  readonly level: number;
+  readonly startAt?: number;
+  readonly levelDefinition?: NumberingLevelOverrideDefinition;
 }
 
 export interface MediaCatalog {
-  items: Record<string, MediaItem>;
+  readonly 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;
+  readonly mediaId: string;
+  readonly contentType: string;
+  readonly filename: string;
+  readonly relationshipId?: string;
+  readonly packagePartName: string;
+  readonly altText?: string;
+  readonly display?: "inline" | "floating";
+  readonly widthEmu?: number;
+  readonly heightEmu?: number;
 }
 
 // ---- Sub-part canonical types ----
@@ -450,25 +452,25 @@ export interface MediaItem {
 export type HeaderFooterVariant = "default" | "first" | "even";
 
 export interface HeaderDocument {
-  variant: HeaderFooterVariant;
-  partPath: string;
-  relationshipId: string;
-  blocks: BlockNode[];
-  sectionIndex?: number;
+  readonly variant: HeaderFooterVariant;
+  readonly partPath: string;
+  readonly relationshipId: string;
+  readonly blocks: BlockNode[];
+  readonly sectionIndex?: number;
 }
 
 export interface FooterDocument {
-  variant: HeaderFooterVariant;
-  partPath: string;
-  relationshipId: string;
-  blocks: BlockNode[];
-  sectionIndex?: number;
+  readonly variant: HeaderFooterVariant;
+  readonly partPath: string;
+  readonly relationshipId: string;
+  readonly blocks: BlockNode[];
+  readonly sectionIndex?: number;
 }
 
 export interface FootnoteDefinition {
-  noteId: string;
-  kind: "footnote" | "endnote";
-  blocks: BlockNode[];
+  readonly noteId: string;
+  readonly kind: "footnote" | "endnote";
+  readonly blocks: BlockNode[];
 }
 
 /**
@@ -483,33 +485,33 @@ export interface FootnoteDefinition {
  */
 export interface FootnoteSeparators {
   /** Raw XML of the <w:r> children inside the separator paragraph. */
-  separatorContent?: string;
+  readonly separatorContent?: string;
   /** Full XML of the first separator paragraph. */
-  separatorParagraphXml?: string;
+  readonly separatorParagraphXml?: string;
   /** Raw XML of the <w:r> children inside the continuationSeparator paragraph. */
-  continuationSeparatorContent?: string;
+  readonly continuationSeparatorContent?: string;
   /** Full XML of the first continuation-separator paragraph. */
-  continuationSeparatorParagraphXml?: string;
+  readonly continuationSeparatorParagraphXml?: string;
 }
 
 export interface FootnoteCollection {
-  footnotes: Record<string, FootnoteDefinition>;
-  endnotes: Record<string, FootnoteDefinition>;
+  readonly footnotes: Record<string, FootnoteDefinition>;
+  readonly endnotes: Record<string, FootnoteDefinition>;
   /** Separator content parsed from footnotes.xml special entries. */
-  footnoteSeparators?: FootnoteSeparators;
+  readonly footnoteSeparators?: FootnoteSeparators;
   /** Separator content parsed from endnotes.xml special entries. */
-  endnoteSeparators?: FootnoteSeparators;
+  readonly endnoteSeparators?: FootnoteSeparators;
 }
 
 export interface ThemeColorScheme {
-  name: string;
-  colors: Record<string, string>;
+  readonly name: string;
+  readonly colors: Record<string, string>;
 }
 
 export interface ThemeFontScheme {
-  name: string;
-  majorFont?: string;
-  minorFont?: string;
+  readonly name: string;
+  readonly majorFont?: string;
+  readonly minorFont?: string;
 }
 
 /**
@@ -541,9 +543,9 @@ export type ThemeFontSlot =
   | "minorBidi";
 
 export interface ThemeDefinition {
-  name?: string;
-  colorScheme?: ThemeColorScheme;
-  fontScheme?: ThemeFontScheme;
+  readonly name?: string;
+  readonly colorScheme?: ThemeColorScheme;
+  readonly fontScheme?: ThemeFontScheme;
 }
 
 /**
@@ -555,49 +557,49 @@ export interface ThemeDefinition {
  * future serializer can re-emit byte-stable diffs.
  */
 export interface CompatSetting {
-  name: string;
-  uri: string;
-  value: string;
+  readonly name: string;
+  readonly uri: string;
+  readonly value: string;
 }
 
 export interface DocumentSettings {
-  evenAndOddHeaders?: boolean;
-  zoomLevel?: "pageWidth" | "onePage" | number;
+  readonly evenAndOddHeaders?: boolean;
+  readonly zoomLevel?: "pageWidth" | "onePage" | number;
   /**
    * Document-wide default tab stop interval from `<w:defaultTabStop w:val>`.
    * Value is stored in twips and feeds layout measurement whenever a paragraph
    * does not declare an explicit next tab stop.
    */
-  defaultTabStop?: number;
+  readonly defaultTabStop?: number;
   /**
    * Settings-level default footnote configuration from `<w:footnotePr>`.
    * Section-level `SectionProperties.footnotePr` overrides this when present.
    */
-  footnotePr?: FootnoteProperties;
+  readonly footnotePr?: FootnoteProperties;
   /**
    * Settings-level default endnote configuration from `<w:endnotePr>`.
    * Section-level `SectionProperties.endnotePr` overrides this when present.
    */
-  endnotePr?: EndnoteProperties;
+  readonly endnotePr?: EndnoteProperties;
   /**
    * Ordered list of <w:compatSetting> entries inside <w:compat>. Insertion
    * order is preserved for serializer diff stability.
    */
-  compatSettings?: CompatSetting[];
+  readonly compatSettings?: CompatSetting[];
   /**
    * Boolean flag children of <w:compat> that are NOT <w:compatSetting>
    * (e.g. <w:spaceForUL/>, <w:doNotExpandShiftReturn/>). Keyed by local
    * element name. The value reflects ST_OnOff semantics: missing `w:val` is
    * true; explicit `w:val="0"`/`"false"` is false.
    */
-  compatFlags?: Record<string, boolean>;
+  readonly compatFlags?: Record<string, boolean>;
   /**
    * Settings-level (NOT inside <w:compat>) compat-adjacent boolean flags
    * such as <w:doNotEmbedSmartTags/>. Kept in a separate field from
    * compatFlags because the OOXML location differs and the future
    * serializer must re-emit them at root, not inside <w:compat>.
    */
-  rootCompatFlags?: Record<string, boolean>;
+  readonly rootCompatFlags?: Record<string, boolean>;
   /**
    * <w:themeFontLang> attribute bag, captured verbatim so the future
    * serializer can re-emit unknown attributes Word may add.
@@ -608,7 +610,7 @@ export interface DocumentSettings {
    *   - { "w:val": "en-US", … }: attributes preserved with their qualified
    *     names so the serializer round-trips namespace prefixes intact.
    */
-  themeFontLang?: Record<string, string>;
+  readonly themeFontLang?: Record<string, string>;
   /**
    * Local names of every direct child of <w:settings> that this parser does
    * not model individually. Insertion order preserved; duplicates retained.
@@ -618,35 +620,35 @@ export interface DocumentSettings {
    * use this list as a validator assertion that every preserved child still
    * appears in the re-emitted output.
    */
-  unmodelledSettingsChildren?: string[];
+  readonly unmodelledSettingsChildren?: string[];
   /**
    * Parsed from `<w:clrSchemeMapping>` in settings.xml. Maps document-level
    * color style slot names to physical clrScheme slots. Absent when the
    * element was not present in the document (identity mapping applies).
    */
-  clrSchemeMapping?: ClrSchemeMapping;
+  readonly clrSchemeMapping?: ClrSchemeMapping;
 }
 
 export interface SubPartsCatalog {
-  headers: HeaderDocument[];
-  footers: FooterDocument[];
-  footnoteCollection?: FootnoteCollection;
-  theme?: ThemeDefinition;
-  finalSectionProperties?: SectionProperties;
-  resolvedTheme?: ResolvedTheme;
-  settings?: DocumentSettings;
+  readonly headers: HeaderDocument[];
+  readonly footers: FooterDocument[];
+  readonly footnoteCollection?: FootnoteCollection;
+  readonly theme?: ThemeDefinition;
+  readonly finalSectionProperties?: SectionProperties;
+  readonly resolvedTheme?: ResolvedTheme;
+  readonly settings?: DocumentSettings;
   /**
    * Fully materialized theme for runtime resolution — combines theme1.xml
    * color/font scheme with the clrSchemeMapping from settings.xml.
    * Available after CO1 load wiring lands in docx-session.ts.
    */
-  canonicalTheme?: CanonicalTheme;
+  readonly canonicalTheme?: CanonicalTheme;
 }
 
 export interface ResolvedTheme {
-  colors: Record<string, string>;
-  majorFont?: string;
-  minorFont?: string;
+  readonly colors: Record<string, string>;
+  readonly majorFont?: string;
+  readonly minorFont?: string;
 }
 
 /**
@@ -688,22 +690,22 @@ export type ClrSchemeMapping = Partial<Record<ClrSchemeMappingSlot, ThemeColorSl
  * documents with no theme part.
  */
 export interface CanonicalTheme {
-  clrScheme: ThemeColorScheme;
-  fontScheme?: ThemeFontScheme;
+  readonly clrScheme: ThemeColorScheme;
+  readonly fontScheme?: ThemeFontScheme;
   /** Resolved clrSchemeMapping: styleSlot → clrScheme slot name. Empty = identity. */
-  clrMap: ClrSchemeMapping;
+  readonly clrMap: ClrSchemeMapping;
   /** Stable content hash of clrScheme.colors (sorted key:value pairs). */
-  themeHash: string;
+  readonly themeHash: string;
   /** Stable content hash of clrMap (sorted key:value pairs). */
-  clrMapHash: string;
+  readonly clrMapHash: string;
 }
 
 // ---- Inline footnote reference node ----
 
 export interface FootnoteRefNode {
-  type: "footnote_ref";
-  noteId: string;
-  noteKind: "footnote" | "endnote";
+  readonly type: "footnote_ref";
+  readonly noteId: string;
+  readonly noteKind: "footnote" | "endnote";
 }
 
 export type DocumentNode =
@@ -741,8 +743,8 @@ export type DocumentNode =
   | OleEmbedNode;
 
 export interface DocumentRootNode {
-  type: "doc";
-  children: BlockNode[];
+  readonly type: "doc";
+  readonly children: BlockNode[];
 }
 
 export type BlockNode =
@@ -755,74 +757,74 @@ export type BlockNode =
   | OpaqueBlockNode;
 
 export interface ParagraphSpacing {
-  before?: number;
-  after?: number;
-  line?: number;
-  lineRule?: "auto" | "exact" | "atLeast";
+  readonly before?: number;
+  readonly after?: number;
+  readonly line?: number;
+  readonly lineRule?: "auto" | "exact" | "atLeast";
 }
 
 export interface ParagraphIndentation {
-  left?: number;
-  right?: number;
-  firstLine?: number;
-  hanging?: number;
+  readonly left?: number;
+  readonly right?: number;
+  readonly firstLine?: number;
+  readonly hanging?: number;
 }
 
 export interface TabStop {
-  position: number;
-  align: "left" | "center" | "right" | "decimal" | "num" | "bar" | "clear";
-  leader?: "none" | "dot" | "hyphen" | "underscore" | "heavy" | "middleDot";
+  readonly position: number;
+  readonly align: "left" | "center" | "right" | "decimal" | "num" | "bar" | "clear";
+  readonly leader?: "none" | "dot" | "hyphen" | "underscore" | "heavy" | "middleDot";
 }
 
 export interface ParagraphBorders {
-  top?: BorderSpec;
-  left?: BorderSpec;
-  bottom?: BorderSpec;
-  right?: BorderSpec;
-  bar?: BorderSpec;
-  between?: BorderSpec;
+  readonly top?: BorderSpec;
+  readonly left?: BorderSpec;
+  readonly bottom?: BorderSpec;
+  readonly right?: BorderSpec;
+  readonly bar?: BorderSpec;
+  readonly between?: BorderSpec;
 }
 
 export interface ParagraphShading {
-  fill?: string;
-  color?: string;
-  val?: string;
+  readonly fill?: string;
+  readonly color?: string;
+  readonly val?: string;
   /**
    * Theme shading references (§17.3.5). When `themeFill` is set and `fill`
    * is absent or `"auto"`, render-time shading resolves through the theme
    * color resolver. The raw theme attrs remain on the canonical model so
    * export can round-trip the original `<w:shd>` byte-for-byte.
    */
-  themeFill?: string;
-  themeFillTint?: string;
-  themeFillShade?: string;
-  themeColor?: string;
-  themeColorTint?: string;
-  themeColorShade?: string;
+  readonly themeFill?: string;
+  readonly themeFillTint?: string;
+  readonly themeFillShade?: string;
+  readonly themeColor?: string;
+  readonly themeColorTint?: string;
+  readonly themeColorShade?: string;
 }
 
 /** Body of an OOXML `<w:rPr>` (run properties). All fields optional; absence = "not specified at this level". */
 export interface CanonicalRunFormatting {
-  bold?: boolean;
-  italic?: boolean;
-  underline?: "single" | "double" | "thick" | "dotted" | "dash" | "wave" | "none";
-  strikethrough?: boolean;
-  doubleStrikethrough?: boolean;
-  vanish?: boolean;
-  allCaps?: boolean;
-  smallCaps?: boolean;
-  verticalAlign?: "baseline" | "superscript" | "subscript";
+  readonly bold?: boolean;
+  readonly italic?: boolean;
+  readonly underline?: "single" | "double" | "thick" | "dotted" | "dash" | "wave" | "none";
+  readonly strikethrough?: boolean;
+  readonly doubleStrikethrough?: boolean;
+  readonly vanish?: boolean;
+  readonly allCaps?: boolean;
+  readonly smallCaps?: boolean;
+  readonly verticalAlign?: "baseline" | "superscript" | "subscript";
   /**
    * Convenience alias for the primary font family — the first non-empty of
    * `fontFamilyAscii` → `fontFamilyHAnsi` → `fontFamilyEastAsia` → `fontFamilyCs`.
    * Script-aware consumers should read the specific `fontFamily{Ascii,HAnsi,EastAsia,Cs}`
    * fields directly.
    */
-  fontFamily?: string;
-  fontFamilyAscii?: string;
-  fontFamilyHAnsi?: string;
-  fontFamilyEastAsia?: string;
-  fontFamilyCs?: string;
+  readonly fontFamily?: string;
+  readonly fontFamilyAscii?: string;
+  readonly fontFamilyHAnsi?: string;
+  readonly fontFamilyEastAsia?: string;
+  readonly fontFamilyCs?: string;
   /**
    * ECMA-376 §17.3.2.26 theme-slot bindings on `<w:rFonts>`
    * (`w:asciiTheme`, `w:hAnsiTheme`, `w:eastAsiaTheme`, `w:cstheme`).
@@ -837,18 +839,18 @@ export interface CanonicalRunFormatting {
    * concrete name wins. Keep the theme slot on the canonical so the
    * export path can re-emit it byte-identically.
    */
-  asciiTheme?: ThemeFontSlot;
-  hAnsiTheme?: ThemeFontSlot;
-  eastAsiaTheme?: ThemeFontSlot;
-  csTheme?: ThemeFontSlot;
-  fontSizeHalfPoints?: number;
-  fontSizeCsHalfPoints?: number;
+  readonly asciiTheme?: ThemeFontSlot;
+  readonly hAnsiTheme?: ThemeFontSlot;
+  readonly eastAsiaTheme?: ThemeFontSlot;
+  readonly csTheme?: ThemeFontSlot;
+  readonly fontSizeHalfPoints?: number;
+  readonly fontSizeCsHalfPoints?: number;
   /**
    * Color value from `<w:color w:val>`. Either an OOXML hex (e.g., `"2E74B5"`)
    * or the sentinel `"auto"` (which serializers must round-trip verbatim).
    */
-  colorHex?: string;
-  colorThemeSlot?: string;
+  readonly colorHex?: string;
+  readonly colorThemeSlot?: string;
   /**
    * `w:themeTint` hex byte (0x00–0xFF) read from `<w:color>`. ECMA-376
    * §17.18.85. Applied at render/cascade time against `colorThemeSlot`:
@@ -857,17 +859,17 @@ export interface CanonicalRunFormatting {
    * for byte-stable round-trip; resolution math lives in the runtime
    * theme-color resolver.
    */
-  colorThemeTint?: string;
+  readonly colorThemeTint?: string;
   /**
    * `w:themeShade` hex byte (0x00–0xFF) from `<w:color>`. ECMA-376
    * §17.18.83. Applied at render/cascade time: luminance mod =
    * shade/255 * L (darkens toward black; 0xFF means no modulation).
    */
-  colorThemeShade?: string;
-  highlight?: string;
-  characterSpacingTwips?: number;
-  characterStyleId?: string;
-  languageCode?: string;
+  readonly colorThemeShade?: string;
+  readonly highlight?: string;
+  readonly characterSpacingTwips?: number;
+  readonly characterStyleId?: string;
+  readonly languageCode?: string;
   /**
    * Unmodelled direct children of `<w:rPr>` captured verbatim for round-trip.
    * See `src/io/ooxml/property-grab-bag.ts` and
@@ -876,27 +878,27 @@ export interface CanonicalRunFormatting {
    * `<w:em>`, `<w:kern>` through parse→serialize round-trip even though the
    * runtime does not model them.
    */
-  unknownPropertyChildren?: UnknownPropertyChild[];
+  readonly unknownPropertyChildren?: UnknownPropertyChild[];
 }
 
 /** Body of an OOXML `<w:pPr>` (paragraph properties). All fields optional; absence = "not specified at this level". */
 export interface CanonicalParagraphFormatting {
-  spacing?: ParagraphSpacing;
-  indentation?: ParagraphIndentation;
-  alignment?: "left" | "center" | "right" | "both" | "distribute" | "start" | "end";
-  borders?: ParagraphBorders;
-  shading?: ParagraphShading;
-  tabStops?: TabStop[];
-  contextualSpacing?: boolean;
-  keepNext?: boolean;
-  keepLines?: boolean;
-  widowControl?: boolean;
-  pageBreakBefore?: boolean;
-  outlineLevel?: number;
-  bidi?: boolean;
-  suppressLineNumbers?: boolean;
-  suppressAutoHyphens?: boolean;
-  paragraphMarkRunProperties?: CanonicalRunFormatting;
+  readonly spacing?: ParagraphSpacing;
+  readonly indentation?: ParagraphIndentation;
+  readonly alignment?: "left" | "center" | "right" | "both" | "distribute" | "start" | "end";
+  readonly borders?: ParagraphBorders;
+  readonly shading?: ParagraphShading;
+  readonly tabStops?: TabStop[];
+  readonly contextualSpacing?: boolean;
+  readonly keepNext?: boolean;
+  readonly keepLines?: boolean;
+  readonly widowControl?: boolean;
+  readonly pageBreakBefore?: boolean;
+  readonly outlineLevel?: number;
+  readonly bidi?: boolean;
+  readonly suppressLineNumbers?: boolean;
+  readonly suppressAutoHyphens?: boolean;
+  readonly paragraphMarkRunProperties?: CanonicalRunFormatting;
   /**
    * `<w:framePr>` — paragraph text-frame properties (ECMA-376 §17.3.1.11).
    * Absent on ordinary paragraphs. When present, the paragraph renders
@@ -904,13 +906,13 @@ export interface CanonicalParagraphFormatting {
    * templates for side-by-side "instructional column + body column"
    * paragraphs and for drop-caps.
    *
-   * Added 2026-04-23 per `docs/KNOWN-ISSUES-VISUAL.md §2.3 "w:framePr
-   * 2-column inset text frames"`. Before this type existed, L01's parser
+   * Added 2026-04-23 after the visual issue-register finding on `w:framePr`
+   * 2-column inset text frames. Before this type existed, L01's parser
    * fell through to `OpaqueBlockNode` whenever `<w:pPr>` contained
    * `<w:framePr>`, which hid the paragraph from L04 pagination and L11
    * render. Canonical representation unblocks downstream adoption.
    */
-  frameProperties?: FrameProperties;
+  readonly frameProperties?: FrameProperties;
   /**
    * Unmodelled direct children of `<w:pPr>` captured verbatim for round-trip.
    * See `src/io/ooxml/property-grab-bag.ts` for the mechanism and Lane 3 O2
@@ -922,7 +924,7 @@ export interface CanonicalParagraphFormatting {
    * or `<w:kinsoku>` survive a parse→serialize round-trip even though the
    * runtime doesn't understand them.
    */
-  unknownPropertyChildren?: UnknownPropertyChild[];
+  readonly unknownPropertyChildren?: UnknownPropertyChild[];
 }
 
 /**
@@ -937,57 +939,57 @@ export interface CanonicalParagraphFormatting {
  */
 export interface FrameProperties {
   /** `w:w` — frame width in twips. Absence = auto-width from content. */
-  widthTwips?: number;
+  readonly widthTwips?: number;
   /** `w:h` — frame height in twips. Interpretation depends on `hRule`. */
-  heightTwips?: number;
+  readonly heightTwips?: number;
   /**
    * `w:hRule` — height rule.
    * - `"auto"` (default): height follows content.
    * - `"atLeast"`: content grows the frame; `heightTwips` is the floor.
    * - `"exact"`: content is clipped to `heightTwips`.
    */
-  hRule?: "auto" | "atLeast" | "exact";
+  readonly hRule?: "auto" | "atLeast" | "exact";
   /** `w:x` — horizontal absolute position in twips from `hAnchor`. */
-  xTwips?: number;
+  readonly xTwips?: number;
   /** `w:y` — vertical absolute position in twips from `vAnchor`. */
-  yTwips?: number;
+  readonly yTwips?: number;
   /**
    * `w:xAlign` — horizontal alignment keyword; overrides `xTwips` if
    * both are set (Word behavior). `"inside"` / `"outside"` are
    * mirror-aware for even/odd pages.
    */
-  xAlign?: "left" | "center" | "right" | "inside" | "outside";
+  readonly xAlign?: "left" | "center" | "right" | "inside" | "outside";
   /**
    * `w:yAlign` — vertical alignment keyword; overrides `yTwips` if
    * both are set. `"inline"` places the frame in the text flow.
    */
-  yAlign?: "top" | "center" | "bottom" | "inside" | "outside" | "inline";
+  readonly yAlign?: "top" | "center" | "bottom" | "inside" | "outside" | "inline";
   /** `w:hAnchor` — what `x` / `xAlign` is measured from. */
-  hAnchor?: "text" | "margin" | "page";
+  readonly hAnchor?: "text" | "margin" | "page";
   /** `w:vAnchor` — what `y` / `yAlign` is measured from. */
-  vAnchor?: "text" | "margin" | "page";
+  readonly vAnchor?: "text" | "margin" | "page";
   /**
    * `w:wrap` — how surrounding text flows around the frame.
    * `"around"`: text wraps on both sides; `"notBeside"`: text stops
    * above/below the frame; `"none"`: no text on the frame line;
    * `"auto"` / `"tight"` / `"through"`: extended wrap modes.
    */
-  wrap?: "around" | "auto" | "none" | "notBeside" | "tight" | "through";
+  readonly wrap?: "around" | "auto" | "none" | "notBeside" | "tight" | "through";
   /** `w:hSpace` — horizontal clear-space around the frame, twips. */
-  hSpaceTwips?: number;
+  readonly hSpaceTwips?: number;
   /** `w:vSpace` — vertical clear-space around the frame, twips. */
-  vSpaceTwips?: number;
+  readonly vSpaceTwips?: number;
   /**
    * `w:dropCap` — drop-cap semantics when the frame holds an initial
    * letter. `"none"` (default): not a drop-cap frame.
    * `"drop"`: character spans `lines` lines, text wraps around it.
    * `"margin"`: character hangs in the margin.
    */
-  dropCap?: "none" | "drop" | "margin";
+  readonly dropCap?: "none" | "drop" | "margin";
   /** `w:lines` — number of lines the drop-cap spans. Only meaningful when `dropCap !== "none"`. */
-  lines?: number;
+  readonly lines?: number;
   /** `w:anchorLock` — prevents the frame's anchor paragraph from moving between pages during reflow. */
-  anchorLock?: boolean;
+  readonly anchorLock?: boolean;
   /**
    * Verbatim source XML of the `<w:framePr>` element. Populated by
    * the parser for lossless round-trip of extension attributes
@@ -996,7 +998,7 @@ export interface FrameProperties {
    * modeled fields and merge in any extension attributes from
    * `rawXml` that aren't covered by the modeled set.
    */
-  rawXml?: string;
+  readonly rawXml?: string;
 }
 
 /**
@@ -1008,65 +1010,65 @@ export interface FrameProperties {
  */
 export interface UnknownPropertyChild {
   /** Qualified element name as it appeared in source, e.g. "w15:collapsed". */
-  elementName: string;
+  readonly elementName: string;
   /** Verbatim source XML for the child element, including closing/self-closing form. */
-  rawXml: string;
+  readonly rawXml: string;
 }
 
 /** Body of an OOXML `<w:docDefaults>` — baseline formatting applied before style chain. */
 export interface DocumentDefaults {
-  paragraph?: CanonicalParagraphFormatting;
-  run?: CanonicalRunFormatting;
+  readonly paragraph?: CanonicalParagraphFormatting;
+  readonly run?: CanonicalRunFormatting;
 }
 
 /** Materialized `fontTable.xml` — one entry per `<w:font>` element. */
 export interface CanonicalFontTable {
-  fonts: Record<string, CanonicalFontEntry>;
+  readonly fonts: Record<string, CanonicalFontEntry>;
 }
 
 /** Metadata for a single `<w:font>` element from fontTable.xml. */
 export interface CanonicalFontEntry {
   /** `w:name` attribute — the key used in rFonts references. */
-  name: string;
+  readonly name: string;
   /**
    * `w:family` value. Qualitative category per ECMA-376 §17.8.3.10.
    * "roman" = proportional serif, "swiss" = proportional sans-serif,
    * "modern" = fixed-pitch, "script" = handwriting, "decorative" = display.
    */
-  family?: "roman" | "swiss" | "modern" | "script" | "decorative";
+  readonly family?: "roman" | "swiss" | "modern" | "script" | "decorative";
   /** `w:pitch` value — "fixed" maps to monospace metrics. */
-  pitch?: "fixed" | "variable" | "default";
+  readonly pitch?: "fixed" | "variable" | "default";
   /**
    * Windows charset code from `w:charset w:val`.
    * 2 = Symbol font (charset override required for correct glyph mapping).
    */
-  charset?: number;
+  readonly charset?: number;
   /** `w:altName` — substitution name when the primary font is unavailable. */
-  altName?: string;
+  readonly altName?: string;
 }
 
 export interface ParagraphNode {
-  type: "paragraph";
-  styleId?: string;
+  readonly type: "paragraph";
+  readonly styleId?: string;
   numbering?: {
-    numberingInstanceId: string;
-    level: number;
+    readonly numberingInstanceId: string;
+    readonly 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;
+  readonly alignment?: "left" | "center" | "right" | "both" | "distribute";
+  readonly spacing?: ParagraphSpacing;
+  readonly contextualSpacing?: boolean;
+  readonly indentation?: ParagraphIndentation;
+  readonly tabStops?: TabStop[];
+  readonly keepNext?: boolean;
+  readonly keepLines?: boolean;
+  readonly outlineLevel?: number;
+  readonly pageBreakBefore?: boolean;
+  readonly widowControl?: boolean;
+  readonly borders?: ParagraphBorders;
+  readonly shading?: ParagraphShading;
+  readonly bidi?: boolean;
+  readonly suppressLineNumbers?: boolean;
+  readonly cnfStyle?: string;
   /**
    * `<w:framePr>` — inline paragraph text-frame properties set
    * directly on the paragraph (not through the style cascade).
@@ -1084,7 +1086,7 @@ export interface ParagraphNode {
    * to `OpaqueBlockNode` because the parser had no canonical target
    * at the node level.
    */
-  frameProperties?: FrameProperties;
+  readonly frameProperties?: FrameProperties;
   /**
    * Preserved w14 extension identifiers for this paragraph.
    * Round-trip (§2 A.7) requires these to survive import → export so the
@@ -1093,65 +1095,65 @@ export interface ParagraphNode {
    * 8-hex uppercase strings per ECMA-376 Part 1 Appendix A.
    */
   wordExtensionIds?: {
-    paraId?: string;
-    textId?: string;
+    readonly paraId?: string;
+    readonly textId?: string;
   };
-  children: InlineNode[];
+  readonly children: InlineNode[];
 }
 
 export interface BorderSpec {
-  value?: string;
-  size?: number;
-  space?: number;
-  color?: string;
+  readonly value?: string;
+  readonly size?: number;
+  readonly space?: number;
+  readonly color?: string;
 }
 
 export interface TableBorders {
-  top?: BorderSpec;
-  left?: BorderSpec;
-  bottom?: BorderSpec;
-  right?: BorderSpec;
-  insideH?: BorderSpec;
-  insideV?: BorderSpec;
+  readonly top?: BorderSpec;
+  readonly left?: BorderSpec;
+  readonly bottom?: BorderSpec;
+  readonly right?: BorderSpec;
+  readonly insideH?: BorderSpec;
+  readonly insideV?: BorderSpec;
 }
 
 export interface TableCellBorders {
-  top?: BorderSpec;
-  left?: BorderSpec;
-  bottom?: BorderSpec;
-  right?: BorderSpec;
-  insideH?: BorderSpec;
-  insideV?: BorderSpec;
+  readonly top?: BorderSpec;
+  readonly left?: BorderSpec;
+  readonly bottom?: BorderSpec;
+  readonly right?: BorderSpec;
+  readonly insideH?: BorderSpec;
+  readonly insideV?: BorderSpec;
 }
 
 export interface TableWidth {
-  value: number;
-  type: "dxa" | "auto" | "pct" | "nil";
+  readonly value: number;
+  readonly type: "dxa" | "auto" | "pct" | "nil";
 }
 
 export interface TableIndent {
-  value: number;
-  type: "dxa" | "auto" | "pct" | "nil";
+  readonly value: number;
+  readonly type: "dxa" | "auto" | "pct" | "nil";
 }
 
 export interface TableFloatingProperties {
-  horizontalAnchor?: "margin" | "page" | "text";
-  verticalAnchor?: "margin" | "page" | "text";
-  horizontalAlign?: "left" | "center" | "right" | "inside" | "outside";
-  horizontalOffset?: number;
-  verticalAlign?: "top" | "center" | "bottom" | "inside" | "outside";
-  verticalOffset?: number;
-  leftFromText?: number;
-  rightFromText?: number;
-  topFromText?: number;
-  bottomFromText?: number;
-  overlap?: boolean;
+  readonly horizontalAnchor?: "margin" | "page" | "text";
+  readonly verticalAnchor?: "margin" | "page" | "text";
+  readonly horizontalAlign?: "left" | "center" | "right" | "inside" | "outside";
+  readonly horizontalOffset?: number;
+  readonly verticalAlign?: "top" | "center" | "bottom" | "inside" | "outside";
+  readonly verticalOffset?: number;
+  readonly leftFromText?: number;
+  readonly rightFromText?: number;
+  readonly topFromText?: number;
+  readonly bottomFromText?: number;
+  readonly overlap?: boolean;
 }
 
 export interface CellShading {
-  fill?: string;
-  color?: string;
-  val?: string;
+  readonly fill?: string;
+  readonly color?: string;
+  readonly val?: string;
   /**
    * SOW gap G3 — theme-shading references (§17.3.5). When `themeFill` is set
    * and `fill` is absent or "auto", the runtime resolves the shading via
@@ -1159,29 +1161,29 @@ export interface CellShading {
    * themeFillShade)`. Fields are kept verbatim so export can round-trip the
    * original `w:shd` element without re-encoding the resolved hex.
    */
-  themeFill?: string;
-  themeFillTint?: string;
-  themeFillShade?: string;
-  themeColor?: string;
-  themeColorTint?: string;
-  themeColorShade?: string;
+  readonly themeFill?: string;
+  readonly themeFillTint?: string;
+  readonly themeFillShade?: string;
+  readonly themeColor?: string;
+  readonly themeColorTint?: string;
+  readonly themeColorShade?: string;
 }
 
 export interface TableCellMargins {
-  top?: number;
-  left?: number;
-  bottom?: number;
-  right?: number;
+  readonly top?: number;
+  readonly left?: number;
+  readonly bottom?: number;
+  readonly right?: number;
 }
 
 export interface TableLook {
-  val?: string;
-  firstRow?: boolean;
-  lastRow?: boolean;
-  firstColumn?: boolean;
-  lastColumn?: boolean;
-  noHBand?: boolean;
-  noVBand?: boolean;
+  readonly val?: string;
+  readonly firstRow?: boolean;
+  readonly lastRow?: boolean;
+  readonly firstColumn?: boolean;
+  readonly lastColumn?: boolean;
+  readonly noHBand?: boolean;
+  readonly noVBand?: boolean;
 }
 
 export type TableStyleConditionalRegion =
@@ -1196,140 +1198,140 @@ export type TableStyleConditionalRegion =
 
 export interface TableStyleFormatting {
   table?: {
-    width?: TableWidth;
-    alignment?: "left" | "center" | "right";
-    borders?: TableBorders;
-    cellMargins?: TableCellMargins;
-    tblLook?: TableLook;
+    readonly width?: TableWidth;
+    readonly alignment?: "left" | "center" | "right";
+    readonly borders?: TableBorders;
+    readonly cellMargins?: TableCellMargins;
+    readonly tblLook?: TableLook;
   };
   row?: {
-    height?: number;
-    heightRule?: "auto" | "atLeast" | "exact";
-    isHeader?: boolean;
+    readonly height?: number;
+    readonly heightRule?: "auto" | "atLeast" | "exact";
+    readonly isHeader?: boolean;
   };
   cell?: {
-    width?: TableWidth;
-    borders?: TableCellBorders;
-    shading?: CellShading;
-    verticalAlign?: "top" | "center" | "bottom";
+    readonly width?: TableWidth;
+    readonly borders?: TableCellBorders;
+    readonly shading?: CellShading;
+    readonly verticalAlign?: "top" | "center" | "bottom";
   };
   /**
    * `<w:pPr>` directly inside the table style body — applies to every
    * cell paragraph by default. Conditional-region pPr (inside
    * `<w:tblStylePr>`) is not captured here; see Lane 3a follow-up.
    */
-  paragraphProperties?: CanonicalParagraphFormatting;
+  readonly paragraphProperties?: CanonicalParagraphFormatting;
   /**
    * `<w:rPr>` directly inside the table style body — applies to every
    * run in every cell paragraph by default.
    */
-  runProperties?: CanonicalRunFormatting;
+  readonly runProperties?: CanonicalRunFormatting;
 }
 
 export interface TableNode {
-  type: "table";
-  styleId?: string;
+  readonly type: "table";
+  readonly styleId?: string;
   /** @deprecated Use `unknownPropertyChildren`. Kept for snapshot back-compat. */
-  propertiesXml?: string;
-  unknownPropertyChildren?: UnknownPropertyChild[];
-  gridColumns: number[];
-  rows: TableRowNode[];
-  width?: TableWidth;
-  alignment?: "left" | "center" | "right";
-  borders?: TableBorders;
-  cellMargins?: TableCellMargins;
-  tblLook?: TableLook;
-  indent?: TableIndent;
-  layoutMode?: "fixed" | "autofit";
-  cellSpacing?: TableWidth;
-  caption?: string;
-  description?: string;
-  bidiVisual?: boolean;
-  floating?: TableFloatingProperties;
+  readonly propertiesXml?: string;
+  readonly unknownPropertyChildren?: UnknownPropertyChild[];
+  readonly gridColumns: number[];
+  readonly rows: TableRowNode[];
+  readonly width?: TableWidth;
+  readonly alignment?: "left" | "center" | "right";
+  readonly borders?: TableBorders;
+  readonly cellMargins?: TableCellMargins;
+  readonly tblLook?: TableLook;
+  readonly indent?: TableIndent;
+  readonly layoutMode?: "fixed" | "autofit";
+  readonly cellSpacing?: TableWidth;
+  readonly caption?: string;
+  readonly description?: string;
+  readonly bidiVisual?: boolean;
+  readonly floating?: TableFloatingProperties;
 }
 
 export interface TableRowNode {
-  type: "table_row";
+  readonly type: "table_row";
   /** @deprecated Use `unknownPropertyChildren`. Kept for snapshot back-compat. */
-  propertiesXml?: string;
-  unknownPropertyChildren?: UnknownPropertyChild[];
-  cells: TableCellNode[];
-  gridBefore?: number;
-  widthBefore?: TableWidth;
-  gridAfter?: number;
-  widthAfter?: TableWidth;
-  height?: number;
-  heightRule?: "auto" | "atLeast" | "exact";
-  isHeader?: boolean;
-  cantSplit?: boolean;
-  horizontalAlignment?: "left" | "center" | "right";
-  cnfStyle?: string;
+  readonly propertiesXml?: string;
+  readonly unknownPropertyChildren?: UnknownPropertyChild[];
+  readonly cells: TableCellNode[];
+  readonly gridBefore?: number;
+  readonly widthBefore?: TableWidth;
+  readonly gridAfter?: number;
+  readonly widthAfter?: TableWidth;
+  readonly height?: number;
+  readonly heightRule?: "auto" | "atLeast" | "exact";
+  readonly isHeader?: boolean;
+  readonly cantSplit?: boolean;
+  readonly horizontalAlignment?: "left" | "center" | "right";
+  readonly cnfStyle?: string;
 }
 
 export interface TableCellNode {
-  type: "table_cell";
+  readonly type: "table_cell";
   /** @deprecated Use `unknownPropertyChildren`. Kept for snapshot back-compat. */
-  propertiesXml?: string;
-  unknownPropertyChildren?: UnknownPropertyChild[];
-  gridSpan?: number;
-  verticalMerge?: "restart" | "continue";
-  children: BlockNode[];
-  width?: TableWidth;
-  borders?: TableCellBorders;
-  shading?: CellShading;
-  verticalAlign?: "top" | "center" | "bottom";
-  textDirection?: "lrTb" | "tbRl" | "btLr";
-  noWrap?: boolean;
-  fitText?: boolean;
-  margins?: TableCellMargins;
-  cnfStyle?: string;
+  readonly propertiesXml?: string;
+  readonly unknownPropertyChildren?: UnknownPropertyChild[];
+  readonly gridSpan?: number;
+  readonly verticalMerge?: "restart" | "continue";
+  readonly children: BlockNode[];
+  readonly width?: TableWidth;
+  readonly borders?: TableCellBorders;
+  readonly shading?: CellShading;
+  readonly verticalAlign?: "top" | "center" | "bottom";
+  readonly textDirection?: "lrTb" | "tbRl" | "btLr";
+  readonly noWrap?: boolean;
+  readonly fitText?: boolean;
+  readonly margins?: TableCellMargins;
+  readonly cnfStyle?: string;
 }
 
 export interface SdtCheckboxState {
-  checked: boolean;
-  checkedChar?: string;
-  uncheckedChar?: string;
+  readonly checked: boolean;
+  readonly checkedChar?: string;
+  readonly uncheckedChar?: string;
 }
 
 export interface SdtDatePickerState {
-  fullDate?: string;
-  dateFormat?: string;
-  lid?: string;
+  readonly fullDate?: string;
+  readonly dateFormat?: string;
+  readonly lid?: string;
 }
 
 export interface SdtDropdownListItem {
-  displayText?: string;
-  value: string;
+  readonly displayText?: string;
+  readonly value: string;
 }
 
 export interface SdtNode {
-  type: "sdt";
+  readonly type: "sdt";
   properties: {
-    sdtType?: string;
-    alias?: string;
-    tag?: string;
-    lock?: string;
-    propertiesXml?: string;
-    checkbox?: SdtCheckboxState;
-    datePicker?: SdtDatePickerState;
-    dropdownList?: SdtDropdownListItem[];
-    comboBox?: SdtDropdownListItem[];
-    showingPlcHdr?: boolean;
+    readonly sdtType?: string;
+    readonly alias?: string;
+    readonly tag?: string;
+    readonly lock?: string;
+    readonly propertiesXml?: string;
+    readonly checkbox?: SdtCheckboxState;
+    readonly datePicker?: SdtDatePickerState;
+    readonly dropdownList?: SdtDropdownListItem[];
+    readonly comboBox?: SdtDropdownListItem[];
+    readonly showingPlcHdr?: boolean;
   };
-  children: BlockNode[];
+  readonly children: BlockNode[];
 }
 
 export interface CustomXmlNode {
-  type: "custom_xml";
-  uri?: string;
-  element?: string;
-  rawXml?: string;
-  children: BlockNode[];
+  readonly type: "custom_xml";
+  readonly uri?: string;
+  readonly element?: string;
+  readonly rawXml?: string;
+  readonly children: BlockNode[];
 }
 
 export interface AltChunkNode {
-  type: "alt_chunk";
-  relationshipId: string;
+  readonly type: "alt_chunk";
+  readonly relationshipId: string;
 }
 
 /**
@@ -1377,53 +1379,53 @@ export type FieldRefreshStatus =
   | "preserve-only";
 
 export interface FieldNode {
-  type: "field";
-  fieldType: "simple" | "complex";
-  instruction: string;
-  children: InlineNode[];
+  readonly type: "field";
+  readonly fieldType: "simple" | "complex";
+  readonly instruction: string;
+  readonly children: InlineNode[];
   /** Classified field family. Undefined for legacy snapshots. */
-  fieldFamily?: FieldFamily;
+  readonly fieldFamily?: FieldFamily;
   /** Target bookmark name for REF/PAGEREF/NOTEREF fields. */
-  fieldTarget?: string;
+  readonly fieldTarget?: string;
   /** Runtime refresh status. Undefined for legacy or preserve-only fields. */
-  refreshStatus?: FieldRefreshStatus;
+  readonly refreshStatus?: FieldRefreshStatus;
   /** Parsed field switches. Present only when the instruction contains recognized switches. */
   switches?: {
-    hyperlink?: boolean;
-    relativePosition?: boolean;
-    numericRef?: boolean;
-    recursive?: boolean;
-    suppressNonDelimiter?: boolean;
-    includeNumbering?: boolean;
-    includeLevel?: boolean;
+    readonly hyperlink?: boolean;
+    readonly relativePosition?: boolean;
+    readonly numericRef?: boolean;
+    readonly recursive?: boolean;
+    readonly suppressNonDelimiter?: boolean;
+    readonly includeNumbering?: boolean;
+    readonly includeLevel?: boolean;
   };
   /** Legacy form-field metadata from w:ffData (textInput, checkBox, ddList). Round-trip only; no UI for MVP. */
-  legacyFormField?: LegacyFormFieldNode;
+  readonly legacyFormField?: LegacyFormFieldNode;
 }
 
 export type LegacyFormFieldKind = "textInput" | "checkBox" | "ddList";
 
 export interface LegacyFormFieldNode {
-  kind: LegacyFormFieldKind;
-  name?: string;
-  enabled?: boolean;
-  calcOnExit?: boolean;
+  readonly kind: LegacyFormFieldKind;
+  readonly name?: string;
+  readonly enabled?: boolean;
+  readonly calcOnExit?: boolean;
   textInput?: {
-    default?: string;
-    maxLength?: number;
-    format?: string;
+    readonly default?: string;
+    readonly maxLength?: number;
+    readonly format?: string;
   };
   checkBox?: {
-    size?: number;
-    default?: boolean;
-    checked?: boolean;
+    readonly size?: number;
+    readonly default?: boolean;
+    readonly checked?: boolean;
   };
   ddList?: {
-    default?: number;
-    listEntry?: string[];
+    readonly default?: number;
+    readonly listEntry?: string[];
   };
   /** Verbatim <w:ffData>…</w:ffData> XML for lossless round-trip. */
-  rawXml: string;
+  readonly rawXml: string;
   /**
    * Phase V.a: set to `true` when typed fields have been mutated via
    * `setLegacyFormFieldValue` since parse. On serialize, the `rawXml` is
@@ -1431,7 +1433,7 @@ export interface LegacyFormFieldNode {
    * Un-mutated nodes emit the preserved `rawXml` verbatim for lossless
    * round-trip.
    */
-  mutated?: boolean;
+  readonly mutated?: boolean;
 }
 
 // ─── Field registry ─────────────────────────────────────────────────────────
@@ -1446,34 +1448,36 @@ export interface LegacyFormFieldNode {
  */
 export interface FieldRegistry {
   /** Supported field instances that participate in refresh. */
-  supported: FieldRegistryEntry[];
+  readonly supported: FieldRegistryEntry[];
   /** Preserve-only field instances cataloged for round-trip safety. */
-  preserveOnly: FieldRegistryEntry[];
+  readonly preserveOnly: FieldRegistryEntry[];
   /** First-class TOC regions, including cached field-result rows and generated heading rows. */
-  tocRegions?: TocRegion[];
+  readonly tocRegions?: TocRegion[];
   /** Generated TOC structure extracted from heading-driven TOC fields. */
-  tocStructure?: TocStructure;
+  readonly tocStructure?: TocStructure;
 }
 
 export interface FieldRegistryEntry {
   /** Stable document-order index of this field (0-based). */
-  fieldIndex: number;
+  readonly fieldIndex: number;
   /** Classified field family. */
-  fieldFamily: FieldFamily;
+  readonly fieldFamily: FieldFamily;
   /** Whether the field is in the supported refresh slice. */
-  supported: boolean;
+  readonly supported: boolean;
   /** Field instruction text. */
-  instruction: string;
+  readonly instruction: string;
   /** Target bookmark name for REF/PAGEREF/NOTEREF fields. */
-  fieldTarget?: string;
+  readonly fieldTarget?: string;
   /** Current display text extracted from field content. */
-  displayText: string;
+  readonly displayText: string;
   /** Paragraph index in document order where this field appears. */
-  paragraphIndex: number;
+  readonly paragraphIndex: number;
+  /** Stable story key for the story that owns this field instance. */
+  readonly storyKey?: string;
   /** Runtime refresh status. */
-  refreshStatus: FieldRefreshStatus;
+  readonly refreshStatus: FieldRefreshStatus;
   /** Parsed field switches carried from FieldNode.switches. Present only for REF/PAGEREF/NOTEREF/TOC entries with recognized switches. */
-  switches?: FieldNode["switches"];
+  readonly switches?: FieldNode["switches"];
 }
 
 /**
@@ -1482,138 +1486,138 @@ export interface FieldRegistryEntry {
  */
 export interface TocStructure {
   /** The raw TOC field instruction (e.g. "TOC \\o \"1-3\" \\h"). */
-  instruction: string;
+  readonly instruction: string;
   /** Heading level range the TOC covers. */
-  levelRange: { from: number; to: number };
+  readonly levelRange: { from: number; to: number };
   /** Ordered TOC entries derived from heading paragraphs. */
-  entries: TocEntry[];
+  readonly entries: TocEntry[];
   /** Whether the TOC content is current with the heading structure. */
-  status: "current" | "stale";
+  readonly status: "current" | "stale";
 }
 
 export interface TocInstructionModel {
   /** The raw TOC field instruction (e.g. "TOC \\o \"1-3\" \\h"). */
-  raw: string;
+  readonly raw: string;
   /** Heading level range selected by \\o, or defaulted to 1-9. */
-  outlineRange: { from: number; to: number };
+  readonly outlineRange: { from: number; to: number };
   /** \\h — result entries should hyperlink to their anchors. */
-  hyperlink?: boolean;
+  readonly hyperlink?: boolean;
   /** \\z — hide tab leader and page numbers in web layout. */
-  hidePageNumbersInWeb?: boolean;
+  readonly hidePageNumbersInWeb?: boolean;
   /** \\u — include paragraphs with outline levels. */
-  useOutlineLevels?: boolean;
+  readonly useOutlineLevels?: boolean;
   /** \\t "Style,Level,..." — style-driven TOC mapping. */
-  styleMap?: TocStyleMapEntry[];
+  readonly styleMap?: TocStyleMapEntry[];
   /** \\b bookmark — bound source content to a bookmark. */
-  bookmarkName?: string;
+  readonly bookmarkName?: string;
   /** \\c identifier — table-of-figures / sequence identifier. */
-  sequenceIdentifier?: string;
+  readonly sequenceIdentifier?: string;
   /** \\f identifier — TC-entry identifier. */
-  tcIdentifier?: string;
+  readonly tcIdentifier?: string;
   /** \\p separator — custom entry/page separator. */
-  entryPageSeparator?: string;
+  readonly entryPageSeparator?: string;
   /** \\d separator — custom sequence separator. */
-  sequenceSeparator?: string;
+  readonly sequenceSeparator?: string;
   /** \\n optional range — omit page numbers. */
-  omitPageNumbers?: true | { from: number; to: number };
+  readonly omitPageNumbers?: true | { from: number; to: number };
   /** Switches parsed but not yet semantically implemented. */
-  unsupportedSwitches?: string[];
+  readonly unsupportedSwitches?: string[];
 }
 
 export interface TocStyleMapEntry {
-  styleName: string;
-  level: number;
+  readonly styleName: string;
+  readonly level: number;
 }
 
 export interface TocCachedEntry {
   /** Text extracted from the cached field-result row before the page-number tab. */
-  text: string;
+  readonly text: string;
   /** TOC level inferred from TOC1/TOC2/etc. paragraph style. */
-  level: number;
+  readonly level: number;
   /** Paragraph index of the cached result row in document order. */
-  paragraphIndex: number;
+  readonly paragraphIndex: number;
   /** Style ID of the cached result paragraph, if available. */
-  styleId?: string;
+  readonly styleId?: string;
   /** Bookmark/hyperlink anchor used by the cached result row, if present. */
-  bookmarkName?: string;
+  readonly bookmarkName?: string;
   /** Page label extracted from the cached field result. */
-  pageText?: string;
+  readonly pageText?: string;
   /** Full visible row text, including tabs/page labels. */
-  displayText: string;
+  readonly displayText: string;
 }
 
 export interface TocRegion {
   /** Stable document-order id for this imported TOC region. */
-  tocId: string;
+  readonly tocId: string;
   /** Source TOC field index in FieldRegistry.supported. */
-  sourceFieldIndex: number;
+  readonly sourceFieldIndex: number;
   /** Parsed instruction metadata and switches. */
-  instruction: TocInstructionModel;
+  readonly instruction: TocInstructionModel;
   /** Inclusive paragraph range containing the cached/generated result rows. */
-  resultRange: { fromParagraphIndex: number; toParagraphIndex: number };
+  readonly resultRange: { fromParagraphIndex: number; toParagraphIndex: number };
   /** Parent container kind where the region was found. */
-  parentKind: "body" | "sdt" | "custom_xml" | "table_cell";
+  readonly parentKind: "body" | "sdt" | "custom_xml" | "table_cell";
   /** Structural path to the parent block sequence, for diagnostics. */
-  sourcePath: string;
+  readonly sourcePath: string;
   /** Cached rows imported from the DOCX field result. */
-  cachedEntries: TocCachedEntry[];
+  readonly cachedEntries: TocCachedEntry[];
   /** Heading-derived rows generated from the canonical document. */
-  generatedEntries: TocEntry[];
+  readonly generatedEntries: TocEntry[];
   /** Whether cached entries match the generated heading model. */
-  status: "current" | "stale";
+  readonly status: "current" | "stale";
 }
 
 export interface TocEntry {
   /** Heading text. */
-  text: string;
+  readonly text: string;
   /** Heading outline level (1-9). */
-  level: number;
+  readonly level: number;
   /** Paragraph index of the heading in document order. */
-  paragraphIndex: number;
+  readonly paragraphIndex: number;
   /** Style ID of the heading paragraph, if available. */
-  styleId?: string;
+  readonly styleId?: string;
   /** Bookmark name anchoring this heading, if present. */
-  bookmarkName?: string;
+  readonly bookmarkName?: string;
 }
 
 export interface BookmarkStartNode {
-  type: "bookmark_start";
-  bookmarkId: string;
-  name: string;
+  readonly type: "bookmark_start";
+  readonly bookmarkId: string;
+  readonly name: string;
 }
 
 export interface BookmarkEndNode {
-  type: "bookmark_end";
-  bookmarkId: string;
+  readonly type: "bookmark_end";
+  readonly bookmarkId: string;
 }
 
 export interface SectionBreakNode {
-  type: "section_break";
-  sectionPropertiesXml?: string;
+  readonly type: "section_break";
+  readonly sectionPropertiesXml?: string;
   /**
    * @deprecated Legacy field from older snapshots. New exports should use
    * sectionPropertiesXml and only contain raw <w:sectPr> content.
    */
-  propertiesXml?: string;
-  sectionProperties?: SectionProperties;
+  readonly propertiesXml?: string;
+  readonly 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;
+  readonly pageSize?: PageSize;
+  readonly pageMargins?: PageMargins;
+  readonly columns?: ColumnProperties;
+  readonly pageNumbering?: PageNumbering;
+  readonly lineNumbering?: SectionLineNumbering;
+  readonly pageBorders?: SectionPageBorders;
+  readonly documentGrid?: SectionDocumentGrid;
+  readonly headerReferences?: HeaderFooterReference[];
+  readonly footerReferences?: HeaderFooterReference[];
+  readonly sectionType?: "continuous" | "nextPage" | "evenPage" | "oddPage" | "nextColumn";
+  readonly titlePage?: boolean;
   /** Per-section footnote configuration (ECMA-376 §17.11.12). Overrides file-level defaults. */
-  footnotePr?: FootnoteProperties;
+  readonly footnotePr?: FootnoteProperties;
   /** Per-section endnote configuration (ECMA-376 §17.11.4). Overrides file-level defaults. */
-  endnotePr?: EndnoteProperties;
+  readonly endnotePr?: EndnoteProperties;
   /**
    * Unmodelled direct children of `<w:sectPr>` captured verbatim for
    * round-trip. Mirrors `CanonicalParagraphFormatting.unknownPropertyChildren`
@@ -1622,7 +1626,7 @@ export interface SectionProperties {
    * `<w15:footnoteColumns>` and Word-internal section knobs through a
    * parse→serialize round-trip when the runtime mutates section properties.
    */
-  unknownPropertyChildren?: UnknownPropertyChild[];
+  readonly unknownPropertyChildren?: UnknownPropertyChild[];
 }
 
 /**
@@ -1641,13 +1645,13 @@ export interface SectionProperties {
  * counterpart; `EndnoteProperties` aliases this shape.
  */
 export interface FootnoteProperties {
-  pos?: "pageBottom" | "beneathText" | "sectEnd" | "docEnd";
+  readonly pos?: "pageBottom" | "beneathText" | "sectEnd" | "docEnd";
   numFmt?: "decimal" | "upperRoman" | "lowerRoman" | "upperLetter" | "lowerLetter"
     | "ordinal" | "cardinalText" | "ordinalText" | "hex" | "chicago" | "bullet"
     | "ideographDigital" | "japaneseCounting" | "arabicAbjad" | "arabicAlpha"
     | "none";
-  numStart?: number;
-  numRestart?: "continuous" | "eachSect" | "eachPage";
+  readonly numStart?: number;
+  readonly numRestart?: "continuous" | "eachSect" | "eachPage";
 }
 
 /**
@@ -1658,62 +1662,62 @@ export interface FootnoteProperties {
 export type EndnoteProperties = FootnoteProperties;
 
 export interface PageSize {
-  width: number;
-  height: number;
-  orientation?: "portrait" | "landscape";
+  readonly width: number;
+  readonly height: number;
+  readonly orientation?: "portrait" | "landscape";
 }
 
 export interface PageMargins {
-  top: number;
-  right: number;
-  bottom: number;
-  left: number;
-  header?: number;
-  footer?: number;
-  gutter?: number;
+  readonly top: number;
+  readonly right: number;
+  readonly bottom: number;
+  readonly left: number;
+  readonly header?: number;
+  readonly footer?: number;
+  readonly gutter?: number;
 }
 
 export interface ColumnProperties {
-  count?: number;
-  space?: number;
-  equalWidth?: boolean;
-  columns?: Array<{ width: number; space?: number }>;
-  separator?: boolean;
+  readonly count?: number;
+  readonly space?: number;
+  readonly equalWidth?: boolean;
+  readonly columns?: Array<{ width: number; space?: number }>;
+  readonly separator?: boolean;
 }
 
 export interface PageNumbering {
-  format?: string;
-  start?: number;
-  chapStyle?: string;
-  chapSep?: string;
+  readonly format?: string;
+  readonly start?: number;
+  readonly chapStyle?: string;
+  readonly chapSep?: string;
 }
 
 export interface SectionLineNumbering {
-  countBy?: number;
-  start?: number;
-  distance?: number;
-  restart?: "newPage" | "newSection" | "continuous";
+  readonly countBy?: number;
+  readonly start?: number;
+  readonly distance?: number;
+  readonly 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";
+  readonly top?: BorderSpec;
+  readonly left?: BorderSpec;
+  readonly bottom?: BorderSpec;
+  readonly right?: BorderSpec;
+  readonly offsetFrom?: "page" | "text";
+  readonly display?: "allPages" | "firstPage" | "notFirstPage";
+  readonly zOrder?: "front" | "back";
 }
 
 export interface SectionDocumentGrid {
-  type?: "default" | "lines" | "linesAndChars" | "snapToChars";
-  linePitch?: number;
-  charSpace?: number;
+  readonly type?: "default" | "lines" | "linesAndChars" | "snapToChars";
+  readonly linePitch?: number;
+  readonly charSpace?: number;
 }
 
 export interface HeaderFooterReference {
-  variant: HeaderFooterVariant;
-  relationshipId: string;
+  readonly variant: HeaderFooterVariant;
+  readonly relationshipId: string;
 }
 
 export type InlineNode =
@@ -1741,9 +1745,9 @@ export type InlineNode =
   | OleEmbedNode;
 
 export interface TextNode {
-  type: "text";
-  text: string;
-  marks?: TextMark[];
+  readonly type: "text";
+  readonly text: string;
+  readonly marks?: TextMark[];
 }
 
 export type TextMark =
@@ -1770,11 +1774,11 @@ export type TextMark =
   | { type: "allCaps" };
 
 export interface HardBreakNode {
-  type: "hard_break";
+  readonly type: "hard_break";
 }
 
 export interface ColumnBreakNode {
-  type: "column_break";
+  readonly type: "column_break";
 }
 
 /**
@@ -1792,66 +1796,85 @@ export interface ColumnBreakNode {
  * section properties; `PageBreakNode` is inline inside a run.
  */
 export interface PageBreakNode {
-  type: "page_break";
+  readonly type: "page_break";
 }
 
 export interface TabNode {
-  type: "tab";
+  readonly type: "tab";
 }
 
 export interface SymbolNode {
-  type: "symbol";
-  char: string;
-  font?: string;
-  marks?: TextMark[];
+  readonly type: "symbol";
+  readonly char: string;
+  readonly font?: string;
+  readonly marks?: TextMark[];
 }
 
 export interface HyperlinkNode {
-  type: "hyperlink";
-  href: string;
-  children: Array<TextNode | HardBreakNode | ColumnBreakNode | PageBreakNode | TabNode | SymbolNode>;
+  readonly type: "hyperlink";
+  readonly href: string;
+  readonly children: Array<TextNode | HardBreakNode | ColumnBreakNode | PageBreakNode | TabNode | SymbolNode>;
 }
 
 export interface ImageNode {
-  type: "image";
-  mediaId: string;
-  altText?: string;
-  placementXml?: string;
-  display?: "inline" | "floating";
-  floating?: FloatingImageProperties;
+  readonly type: "image";
+  readonly mediaId: string;
+  readonly altText?: string;
+  readonly placementXml?: string;
+  readonly display?: "inline" | "floating";
+  readonly floating?: FloatingImageProperties;
 }
 
 export interface FloatingImageProperties {
-  horizontalPosition?: FloatingAxisPosition;
-  verticalPosition?: FloatingAxisPosition;
-  wrap?: "none" | "square" | "tight" | "through" | "topAndBottom";
-  behindDoc?: boolean;
-  layoutInCell?: boolean;
-  allowOverlap?: boolean;
+  readonly horizontalPosition?: FloatingAxisPosition;
+  readonly verticalPosition?: FloatingAxisPosition;
+  readonly wrap?: "none" | "square" | "tight" | "through" | "topAndBottom";
+  readonly behindDoc?: boolean;
+  readonly layoutInCell?: boolean;
+  readonly allowOverlap?: boolean;
 }
 
 export interface FloatingAxisPosition {
-  relativeFrom?: string;
-  align?: string;
-  offset?: number;
+  readonly relativeFrom?: string;
+  readonly align?: string;
+  readonly offset?: number;
 }
 
 export interface OpaqueInlineNode {
-  type: "opaque_inline";
-  fragmentId: string;
-  warningId: string;
+  readonly type: "opaque_inline";
+  readonly fragmentId: string;
+  readonly warningId: string;
 }
 
 // ---- Complex rendering inline nodes (read-only previews) ----
 
+export type PreserveOnlyObjectFallbackHint =
+  | "drawing-inline"
+  | "drawing-floating"
+  | "chart"
+  | "smartart"
+  | "shape"
+  | "wordart"
+  | "vml-shape"
+  | "ole-object"
+  | "opaque-object";
+
+export interface PreserveOnlyObjectSizing {
+  readonly sourceId?: string;
+  readonly display: "inline" | "floating" | "unknown";
+  readonly extentEmu?: { widthEmu: number; heightEmu: number };
+  readonly fallbackHint: PreserveOnlyObjectFallbackHint;
+  readonly relationshipIds?: string[];
+}
+
 /**
  * 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;
+  readonly type: "chart_preview";
+  readonly previewMediaId?: string;
   /**
    * Typed chart data model parsed from the `c:chartSpace` part, when
    * available. Populated at import time by the Stage 1 chart parser
@@ -1869,7 +1892,8 @@ export interface ChartPreviewNode {
    * `parsedData` in place.
    */
   readonly parsedData?: ChartModel;
-  rawXml: string;
+  readonly rawXml: string;
+  readonly preserveOnlyObject?: PreserveOnlyObjectSizing;
 }
 
 /**
@@ -1877,9 +1901,10 @@ export interface ChartPreviewNode {
  * stored in rawXml for lossless round-trip export.
  */
 export interface SmartArtPreviewNode {
-  type: "smartart_preview";
-  previewMediaId?: string;
-  rawXml: string;
+  readonly type: "smartart_preview";
+  readonly previewMediaId?: string;
+  readonly rawXml: string;
+  readonly preserveOnlyObject?: PreserveOnlyObjectSizing;
 }
 
 /**
@@ -1894,14 +1919,14 @@ export interface SmartArtPreviewNode {
  * runtime contract was confirmed canonical).
  */
 export interface ShapeNode {
-  type: "shape";
-  text?: string;
-  geometry?: string;
-  isTextBox?: boolean;
+  readonly type: "shape";
+  readonly text?: string;
+  readonly geometry?: string;
+  readonly isTextBox?: boolean;
   /** Text box body layout from `wps:bodyPr` / `a:bodyPr`. */
-  textBoxBody?: TextBoxBodyProperties;
+  readonly textBoxBody?: TextBoxBodyProperties;
   /** Raw `<w:txbxContent>` XML, preserved for serialization + round-trip. */
-  txbxContentXml?: string;
+  readonly txbxContentXml?: string;
   /**
    * Parsed canonical block-level structure from `<w:txbxContent>`,
    * populated when the parse path supplies a `blockParser` callback
@@ -1909,8 +1934,9 @@ export interface ShapeNode {
    * body via `src/io/ooxml/parse-main-document.ts`). Shape + semantics
    * identical to `ShapeContent.txbxBlocks` on the drawing-frame path.
    */
-  txbxBlocks?: ReadonlyArray<BlockNode>;
-  rawXml: string;
+  readonly txbxBlocks?: BlockNode[];
+  readonly rawXml: string;
+  readonly preserveOnlyObject?: PreserveOnlyObjectSizing;
 }
 
 /**
@@ -1918,10 +1944,11 @@ export interface ShapeNode {
  * Text is extracted for display. The original drawing XML is preserved in rawXml.
  */
 export interface WordArtNode {
-  type: "wordart";
-  text: string;
-  geometry?: string;
-  rawXml: string;
+  readonly type: "wordart";
+  readonly text: string;
+  readonly geometry?: string;
+  readonly rawXml: string;
+  readonly preserveOnlyObject?: PreserveOnlyObjectSizing;
 }
 
 /**
@@ -1930,10 +1957,11 @@ export interface WordArtNode {
  * in rawXml for lossless round-trip export.
  */
 export interface VmlShapeNode {
-  type: "vml_shape";
-  text?: string;
-  shapeType?: string;
-  rawXml: string;
+  readonly type: "vml_shape";
+  readonly text?: string;
+  readonly shapeType?: string;
+  readonly rawXml: string;
+  readonly preserveOnlyObject?: PreserveOnlyObjectSizing;
 }
 
 /**
@@ -1956,111 +1984,111 @@ export interface VmlShapeNode {
  * through when `<o:OLEObject>` is absent.
  */
 export interface OleEmbedNode {
-  type: "ole_embed";
-  id: string;
-  progId?: string;
-  embedType: "oleObject";
-  relationshipId: string;
+  readonly type: "ole_embed";
+  readonly id: string;
+  readonly progId?: string;
+  readonly embedType: "oleObject";
+  readonly relationshipId: string;
   metadata: {
-    originalFilename?: string;
-    classId?: string;
-    shapeId?: string;
+    readonly originalFilename?: string;
+    readonly classId?: string;
+    readonly shapeId?: string;
   };
-  rawXml: string;
+  readonly rawXml: string;
 }
 
 export interface AnchorGeometry {
-  display: "inline" | "floating";
-  extent: { widthEmu: number; heightEmu: number };
-  wrapMode: "none" | "square" | "tight" | "through" | "topAndBottom";
+  readonly display: "inline" | "floating";
+  readonly extent: { widthEmu: number; heightEmu: number };
+  readonly wrapMode: "none" | "square" | "tight" | "through" | "topAndBottom";
   /**
    * Polygon coords (in OOXML's 21600ths-of-image units) when wrapMode is
    * "tight" or "through" and `wp:wrapPolygon` is present. First point from
    * `wp:start`; subsequent points from sequential `wp:lineTo`. Consumed by
    * Lane 6 P7 float-wrap for proper polygon text flow.
    */
-  wrapPolygon?: Array<{ x: number; y: number }>;
-  positionH?: { relativeFrom: string; align?: string; offset?: number };
-  positionV?: { relativeFrom: string; align?: string; offset?: number };
-  distMargins?: { top?: number; bottom?: number; left?: number; right?: number };
-  relativeHeight?: number;
-  behindDoc?: boolean;
-  layoutInCell?: boolean;
-  allowOverlap?: boolean;
-  simplePos?: boolean;
+  readonly wrapPolygon?: Array<{ x: number; y: number }>;
+  readonly positionH?: { relativeFrom: string; align?: string; offset?: number };
+  readonly positionV?: { relativeFrom: string; align?: string; offset?: number };
+  readonly distMargins?: { top?: number; bottom?: number; left?: number; right?: number };
+  readonly relativeHeight?: number;
+  readonly behindDoc?: boolean;
+  readonly layoutInCell?: boolean;
+  readonly allowOverlap?: boolean;
+  readonly simplePos?: boolean;
   docPr?: {
-    id: string;
-    name?: string;
-    descr?: string;
+    readonly id: string;
+    readonly name?: string;
+    readonly descr?: string;
     /** `wp:docPr hidden="1"` — Word UI hides the frame from the user. */
-    hidden?: boolean;
+    readonly hidden?: boolean;
   };
   /**
    * `wp:cNvGraphicFramePr/a:graphicFrameLocks` — object-manipulation locks
    * consumed by Lane 6 object chrome (disable resize handles / move, etc.).
    */
   frameLocks?: {
-    noChangeAspect?: boolean;
-    noResize?: boolean;
-    noMove?: boolean;
-    noRot?: boolean;
-    noSelect?: boolean;
-    noGrp?: boolean;
+    readonly noChangeAspect?: boolean;
+    readonly noResize?: boolean;
+    readonly noMove?: boolean;
+    readonly noRot?: boolean;
+    readonly noSelect?: boolean;
+    readonly noGrp?: boolean;
   };
 }
 
 export interface PictureContent {
-  type: "picture";
-  blipRef: string;
+  readonly type: "picture";
+  readonly blipRef: string;
   /**
    * Phase 4.4 G4 — true when the image references an external URL via
    * `a:blip r:link` (bytes not in the .docx package) rather than embedded
    * via `r:embed`. External-linked images can't resolve to mediaId;
    * `state: "missing"` in surface projection.
    */
-  isLinked?: boolean;
+  readonly isLinked?: boolean;
   /** Resolved media catalog ID (e.g. "media:word/media/image1.png"), populated by parse-drawing. */
-  mediaId?: string;
+  readonly mediaId?: string;
   /** Absolute package path for media catalog lookup. */
-  packagePartName?: string;
+  readonly packagePartName?: string;
   /** MIME resolved from the OPC media part, when known. */
-  contentType?: string;
+  readonly contentType?: string;
   /** DrawingML a:lum brightness/contrast adjustments on the blip. Values are OOXML fixed percentages. */
-  lum?: { bright?: number; contrast?: number };
-  srcRect?: { top: number; bottom: number; left: number; right: number };
-  stretch?: boolean;
+  readonly lum?: { bright?: number; contrast?: number };
+  readonly srcRect?: { top: number; bottom: number; left: number; right: number };
+  readonly stretch?: boolean;
   /**
    * Phase 4.5 G7 — `pic:blipFill/a:tile` (tiled image repeat). Mutually
    * exclusive with `stretch`. tx/ty = offset (EMUs), sx/sy = scale ×1000,
    * flip = "x"|"y"|"xy", algn = alignment token.
    */
   tile?: {
-    tx?: number;
-    ty?: number;
-    sx?: number;
-    sy?: number;
-    flip?: "x" | "y" | "xy";
-    algn?: string;
+    readonly tx?: number;
+    readonly ty?: number;
+    readonly sx?: number;
+    readonly sy?: number;
+    readonly flip?: "x" | "y" | "xy";
+    readonly algn?: string;
   };
-  rotation?: number;
-  flipH?: boolean;
-  flipV?: boolean;
-  presetGeom?: string;
+  readonly rotation?: number;
+  readonly flipH?: boolean;
+  readonly flipV?: boolean;
+  readonly presetGeom?: string;
   /** N11.b — DrawingML a:softEdge feather radius in EMU. */
-  softEdgeRadius?: number;
+  readonly softEdgeRadius?: number;
   /** N11.b — DrawingML a:outerShdw attributes. `dir` is in 60000ths of a degree; `blurRad`/`dist` in EMU. */
-  outerShadow?: { blurRad: number; dist: number; dir: number; color: string; colorType: "srgbClr" | "schemeClr" };
+  readonly outerShadow?: { blurRad: number; dist: number; dir: number; color: string; colorType: "srgbClr" | "schemeClr" };
   /** N11.b — DrawingML a:glow radius in EMU + color. */
-  glow?: { radius: number; color: string; colorType: "srgbClr" | "schemeClr" };
+  readonly glow?: { radius: number; color: string; colorType: "srgbClr" | "schemeClr" };
   /** Original w:drawing XML slice, preserved for lossless round-trip serialization. */
-  rawXml?: string;
+  readonly rawXml?: string;
 }
 
 export interface ShapeContent {
-  type: "shape";
+  readonly type: "shape";
   /** Plain-text fallback extracted from `w:txbxContent` when present. */
-  text?: string;
-  geometry?: string;
+  readonly text?: string;
+  readonly geometry?: string;
   /**
    * Shape fill — solid, gradient, pattern, or none. srgbClr values on solid +
    * gradient stops + pattern fg/bg are normalized to uppercase hex. schemeClr
@@ -2073,26 +2101,26 @@ export interface ShapeContent {
     | { kind: "solid"; color: string; colorType: "srgbClr" | "schemeClr" }
     | { kind: "none" }
     | {
-        kind: "gradient";
-        stops: Array<{ pos: number; color: string; colorType: "srgbClr" | "schemeClr" }>;
+        readonly kind: "gradient";
+        readonly stops: Array<{ pos: number; color: string; colorType: "srgbClr" | "schemeClr" }>;
         direction:
           | { kind: "linear"; angle: number; scaled?: boolean }
           | { kind: "path"; path: "circle" | "rect" | "shape" };
-        rotWithShape?: boolean;
+        readonly rotWithShape?: boolean;
       }
     | {
-        kind: "pattern";
-        preset: string;
-        fg?: { color: string; colorType: "srgbClr" | "schemeClr" };
-        bg?: { color: string; colorType: "srgbClr" | "schemeClr" };
+        readonly kind: "pattern";
+        readonly preset: string;
+        readonly fg?: { color: string; colorType: "srgbClr" | "schemeClr" };
+        readonly bg?: { color: string; colorType: "srgbClr" | "schemeClr" };
       };
-  line?: { color?: string; widthEmu?: number; noLine?: boolean };
+  readonly line?: { color?: string; widthEmu?: number; noLine?: boolean };
   /** True when the shape's geometry + txbxContent presence make it a text box. */
-  isTextBox?: boolean;
+  readonly isTextBox?: boolean;
   /** Text box body layout from `wps:bodyPr` / `a:bodyPr`. */
-  textBoxBody?: TextBoxBodyProperties;
+  readonly textBoxBody?: TextBoxBodyProperties;
   /** Raw w:txbxContent XML, preserved for serialization + lossless round-trip. */
-  txbxContentXml?: string;
+  readonly txbxContentXml?: string;
   /**
    * Parsed block-level structure from `w:txbxContent`, populated when a
    * `blockParser` callback is supplied during parse (CO4 F3.3).
@@ -2106,45 +2134,46 @@ export interface ShapeContent {
    * contract — unblocks L03 cascade + L11 render walking `txbxBlocks`
    * without `as unknown as BlockNode[]` casts at the consumer site.
    */
-  txbxBlocks?: ReadonlyArray<BlockNode>;
-  rawXml: string;
+  readonly txbxBlocks?: BlockNode[];
+  readonly rawXml: string;
+  readonly preserveOnlyObject?: PreserveOnlyObjectSizing;
 }
 
 export interface TextBoxBodyProperties {
   /** OOXML bodyPr anchor: top, center, or bottom. */
-  anchor?: "t" | "ctr" | "b";
-  insetLeftEmu?: number;
-  insetTopEmu?: number;
-  insetRightEmu?: number;
-  insetBottomEmu?: number;
+  readonly anchor?: "t" | "ctr" | "b";
+  readonly insetLeftEmu?: number;
+  readonly insetTopEmu?: number;
+  readonly insetRightEmu?: number;
+  readonly insetBottomEmu?: number;
 }
 
 export interface DrawingFrameNode {
-  type: "drawing_frame";
-  anchor: AnchorGeometry;
+  readonly type: "drawing_frame";
+  readonly anchor: AnchorGeometry;
   content:
     | PictureContent
     | ShapeContent
     | ChartPreviewNode
     | SmartArtPreviewNode
-    | { type: "opaque"; rawXml: string };
+    | { type: "opaque"; rawXml: string; preserveOnlyObject?: PreserveOnlyObjectSizing };
 }
 
 export interface OpaqueBlockNode {
-  type: "opaque_block";
-  fragmentId: string;
-  warningId: string;
-  rawXml?: string;
+  readonly type: "opaque_block";
+  readonly fragmentId: string;
+  readonly warningId: string;
+  readonly rawXml?: string;
 }
 
 export interface DocRange {
-  from: number;
-  to: number;
+  readonly from: number;
+  readonly to: number;
 }
 
 export interface BoundaryAssoc {
-  start: -1 | 1;
-  end: -1 | 1;
+  readonly start: -1 | 1;
+  readonly end: -1 | 1;
 }
 
 export type CanonicalAnchor =
@@ -2166,70 +2195,70 @@ export type CanonicalAnchor =
     };
 
 export interface ReviewStore {
-  comments: Record<string, CommentThread>;
-  revisions: Record<string, RevisionRecord>;
+  readonly comments: Record<string, CommentThread>;
+  readonly 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;
+  readonly commentId: string;
+  readonly status: "open" | "resolved" | "detached";
+  readonly anchor: CanonicalAnchor;
+  readonly createdAt: ISO8601DateTime;
+  readonly createdBy?: string;
+  readonly authorId?: string;
+  readonly body?: string;
+  readonly entries?: CommentEntry[];
+  readonly resolution?: CommentResolution;
+  readonly resolvedAt?: ISO8601DateTime;
+  readonly warningIds: string[];
+  readonly isResolved?: boolean;
+  readonly metadata?: CommentThreadMetadata;
 }
 
 export interface CommentEntry {
-  entryId: string;
-  authorId: string;
-  createdAt: ISO8601DateTime;
-  body: string;
-  metadata?: CommentEntryMetadata;
+  readonly entryId: string;
+  readonly authorId: string;
+  readonly createdAt: ISO8601DateTime;
+  readonly body: string;
+  readonly metadata?: CommentEntryMetadata;
 }
 
 export interface CommentEntryMetadata {
-  ooxmlCommentId?: string;
-  paraId?: string;
-  parentParaId?: string;
-  durableId?: string;
-  initials?: string;
+  readonly ooxmlCommentId?: string;
+  readonly paraId?: string;
+  readonly parentParaId?: string;
+  readonly durableId?: string;
+  readonly initials?: string;
 }
 
 export interface CommentResolution {
-  resolvedAt: ISO8601DateTime;
-  resolvedBy: string;
+  readonly resolvedAt: ISO8601DateTime;
+  readonly resolvedBy: string;
 }
 
 export interface CommentThreadMetadata {
-  source?: "runtime" | "import";
-  rootOoxmlCommentId?: string;
-  rootParaId?: string;
+  readonly source?: "runtime" | "import";
+  readonly rootOoxmlCommentId?: string;
+  readonly rootParaId?: string;
   /**
    * Runtime-authored discussion thread for a tracked change. The comment
    * anchor points at the revision range; this metadata keeps the review
    * relation stable after remaps and lets suggestion cards surface replies.
    */
-  linkedRevisionId?: string;
-  detachedReason?: "incomplete-markers" | "multi-paragraph" | "opaque-region" | "revision-overlap";
-  actionabilityNote?: string;
+  readonly linkedRevisionId?: string;
+  readonly detachedReason?: "incomplete-markers" | "multi-paragraph" | "opaque-region" | "revision-overlap";
+  readonly actionabilityNote?: string;
 }
 
 export interface RevisionPropertyChangeData {
-  xmlTag: "pPrChange" | "sectPrChange" | "tblPrChange" | "rPrChange";
-  beforeXml: string;
+  readonly xmlTag: "pPrChange" | "sectPrChange" | "tblPrChange" | "rPrChange";
+  readonly beforeXml: string;
 }
 
 export interface RevisionMoveData {
-  moveId: string;
-  direction: "from" | "to";
-  linkedRevisionId?: string;
+  readonly moveId: string;
+  readonly direction: "from" | "to";
+  readonly linkedRevisionId?: string;
 }
 
 export type RevisionStoryTargetRecord =
@@ -2250,21 +2279,21 @@ export type RevisionStoryTargetRecord =
   | { 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";
+  readonly changeId: string;
+  readonly kind: "insertion" | "deletion" | "formatting" | "move" | "property-change";
+  readonly anchor: CanonicalAnchor;
+  readonly authorId?: string;
+  readonly createdAt: ISO8601DateTime;
+  readonly warningIds?: string[];
+  readonly metadata?: RevisionMetadataRecord;
+  readonly status: "open" | "accepted" | "rejected" | "detached";
 }
 
 export interface RevisionMetadataRecord {
-  source?: "runtime" | "import";
-  storyTarget?: RevisionStoryTargetRecord;
-  preserveOnlyReason?: string;
-  suggestionId?: string;
+  readonly source?: "runtime" | "import";
+  readonly storyTarget?: RevisionStoryTargetRecord;
+  readonly preserveOnlyReason?: string;
+  readonly suggestionId?: string;
   semanticKind?:
     | "insertion"
     | "deletion"
@@ -2273,49 +2302,49 @@ export interface RevisionMetadataRecord {
     | "paragraph-property-change"
     | "structural-change"
     | "object-change";
-  linkedRevisionIds?: string[];
-  predecessorSuggestionId?: string;
+  readonly linkedRevisionIds?: string[];
+  readonly predecessorSuggestionId?: string;
   importedRevisionForm?:
     | "run-insertion"
     | "run-deletion"
     | "paragraph-insertion"
     | "paragraph-deletion";
-  originalRevisionType?: string;
-  ooxmlRevisionId?: string;
-  propertyChangeData?: RevisionPropertyChangeData;
-  moveData?: RevisionMoveData;
+  readonly originalRevisionType?: string;
+  readonly ooxmlRevisionId?: string;
+  readonly propertyChangeData?: RevisionPropertyChangeData;
+  readonly moveData?: RevisionMoveData;
 }
 
 export interface PreservationStore {
-  opaqueFragments: Record<string, OpaqueFragmentRecord>;
-  packageParts: Record<string, PreservedPackagePart>;
+  readonly opaqueFragments: Record<string, OpaqueFragmentRecord>;
+  readonly 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;
+  readonly fragmentId: string;
+  readonly payloadKind: "xml-subtree" | "package-part";
+  readonly payloadReference: string;
+  readonly featureClass: "preserve-only";
+  readonly lastKnownRange: DocRange;
+  readonly warningId: string;
+  readonly packagePartName?: string;
+  readonly relationshipId?: string;
 }
 
 export interface PreservedPackagePart {
-  packagePartName: string;
-  contentType: string;
-  relationshipIds: string[];
+  readonly packagePartName: string;
+  readonly contentType: string;
+  readonly relationshipIds: string[];
 }
 
 export interface DiagnosticStore {
-  warnings: DiagnosticWarningEntry[];
-  errors: DiagnosticErrorEntry[];
+  readonly warnings: DiagnosticWarningEntry[];
+  readonly errors: DiagnosticErrorEntry[];
 }
 
 export interface DiagnosticWarningEntry {
-  diagnosticId: string;
-  warningId: string;
+  readonly diagnosticId: string;
+  readonly warningId: string;
   source:
     | "import"
     | "runtime"
@@ -2323,11 +2352,11 @@ export interface DiagnosticWarningEntry {
     | "preservation"
     | "validation"
     | "export";
-  message: string;
+  readonly message: string;
 }
 
 export interface DiagnosticErrorEntry {
-  diagnosticId: string;
+  readonly diagnosticId: string;
   code:
     | "load_failed"
     | "import_failed"
@@ -2336,10 +2365,10 @@ export interface DiagnosticErrorEntry {
     | "validation_failed"
     | "datastore_failed"
     | "internal_invariant";
-  message: string;
-  isFatal: boolean;
-  source: "import" | "runtime" | "validation" | "datastore" | "host" | "export";
-  details?: unknown;
+  readonly message: string;
+  readonly isFatal: boolean;
+  readonly source: "import" | "runtime" | "validation" | "datastore" | "host" | "export";
+  readonly details?: unknown;
 }
 
 export function createCanonicalDocument(
@@ -4386,6 +4415,10 @@ function validateFieldRegistryEntry(
     });
   }
 
+  if (record.storyKey !== undefined) {
+    expectString(record.storyKey, `${path}.storyKey`, issues);
+  }
+
   if (
     typeof record.refreshStatus !== "string" ||
     !FIELD_REFRESH_STATUSES.has(record.refreshStatus as FieldRefreshStatus)