@beyondwork/docx-react-component 1.0.106 → 1.0.109

package/src/io/opc/package-reader.ts

@@ -29,21 +29,54 @@ export interface OpcPackage {
   sourceByteLength: number;
 }
 
+export interface OpcPackageReadLimits {
+  maxEntries?: number;
+  maxEntryUncompressedBytes?: number;
+  maxTotalUncompressedBytes?: number;
+}
+
+export interface ReadOpcPackageOptions {
+  limits?: OpcPackageReadLimits;
+}
+
 const EOCD_SIGNATURE = 0x06054b50;
 const CENTRAL_DIRECTORY_SIGNATURE = 0x02014b50;
 const LOCAL_FILE_HEADER_SIGNATURE = 0x04034b50;
 
-export function readOpcPackage(source: Uint8Array | ArrayBuffer): OpcPackage {
+const DEFAULT_MAX_ZIP_ENTRIES = 4096;
+const DEFAULT_MAX_ENTRY_UNCOMPRESSED_BYTES = 64 * 1024 * 1024;
+const DEFAULT_MAX_TOTAL_UNCOMPRESSED_BYTES = 256 * 1024 * 1024;
+
+interface ResolvedOpcPackageReadLimits {
+  maxEntries: number;
+  maxEntryUncompressedBytes: number;
+  maxTotalUncompressedBytes: number;
+}
+
+export function readOpcPackage(
+  source: Uint8Array | ArrayBuffer,
+  options: ReadOpcPackageOptions = {},
+): OpcPackage {
   const bytes = source instanceof Uint8Array ? source : new Uint8Array(source);
-  const centralDirectory = readCentralDirectory(bytes);
+  const limits = resolveReadLimits(options.limits);
+  const centralDirectory = readCentralDirectory(bytes, limits);
   const parts = new Map<string, OpcPackagePart>();
+  let totalUncompressedBytes = 0;
 
   for (const entry of centralDirectory) {
     if (entry.path.endsWith("/")) {
       continue;
     }
 
-    const storedBytes = readZipEntry(bytes, entry);
+    assertEntryWithinLimits(entry, limits);
+    totalUncompressedBytes += entry.uncompressedSize;
+    if (totalUncompressedBytes > limits.maxTotalUncompressedBytes) {
+      throw new Error(
+        `Invalid ZIP archive: cumulative uncompressed size ${totalUncompressedBytes} exceeds limit ${limits.maxTotalUncompressedBytes}.`,
+      );
+    }
+
+    const storedBytes = readZipEntry(bytes, entry, limits);
     const normalizedPath = normalizePartPath(entry.path);
     const surfaceKind = getSurfaceKind(normalizedPath);
 
@@ -111,15 +144,38 @@ export function readOpcPackage(source: Uint8Array | ArrayBuffer): OpcPackage {
   };
 }
 
-function readCentralDirectory(archive: Uint8Array): ZipCentralDirectoryEntry[] {
+function resolveReadLimits(
+  limits: OpcPackageReadLimits | undefined,
+): ResolvedOpcPackageReadLimits {
+  return {
+    maxEntries: limits?.maxEntries ?? DEFAULT_MAX_ZIP_ENTRIES,
+    maxEntryUncompressedBytes:
+      limits?.maxEntryUncompressedBytes ?? DEFAULT_MAX_ENTRY_UNCOMPRESSED_BYTES,
+    maxTotalUncompressedBytes:
+      limits?.maxTotalUncompressedBytes ?? DEFAULT_MAX_TOTAL_UNCOMPRESSED_BYTES,
+  };
+}
+
+function readCentralDirectory(
+  archive: Uint8Array,
+  limits: ResolvedOpcPackageReadLimits,
+): ZipCentralDirectoryEntry[] {
   const view = new DataView(archive.buffer, archive.byteOffset, archive.byteLength);
   const eocdOffset = findEndOfCentralDirectory(archive, view);
   const entryCount = view.getUint16(eocdOffset + 10, true);
+  if (entryCount > limits.maxEntries) {
+    throw new Error(
+      `Invalid ZIP archive: entry count ${entryCount} exceeds limit ${limits.maxEntries}.`,
+    );
+  }
   const centralDirectoryOffset = view.getUint32(eocdOffset + 16, true);
   const entries: ZipCentralDirectoryEntry[] = [];
   let offset = centralDirectoryOffset;
 
   for (let index = 0; index < entryCount; index += 1) {
+    if (offset + 46 > archive.byteLength) {
+      throw new Error(`Invalid ZIP central directory entry at offset ${offset}.`);
+    }
     const signature = view.getUint32(offset, true);
     if (signature !== CENTRAL_DIRECTORY_SIGNATURE) {
       throw new Error(`Invalid ZIP central directory signature at offset ${offset}.`);
@@ -135,6 +191,10 @@ function readCentralDirectory(archive: Uint8Array): ZipCentralDirectoryEntry[] {
     const fileCommentLength = view.getUint16(offset + 32, true);
     const localHeaderOffset = view.getUint32(offset + 42, true);
     const fileNameOffset = offset + 46;
+    const nextOffset = fileNameOffset + fileNameLength + extraFieldLength + fileCommentLength;
+    if (nextOffset > archive.byteLength) {
+      throw new Error(`Invalid ZIP central directory entry at offset ${offset}.`);
+    }
     const fileName = decodeUtf8(archive.subarray(fileNameOffset, fileNameOffset + fileNameLength));
 
     entries.push({
@@ -147,7 +207,7 @@ function readCentralDirectory(archive: Uint8Array): ZipCentralDirectoryEntry[] {
       generalPurposeBitFlag,
     });
 
-    offset += 46 + fileNameLength + extraFieldLength + fileCommentLength;
+    offset = nextOffset;
   }
 
   return entries;
@@ -167,9 +227,27 @@ function findEndOfCentralDirectory(archive: Uint8Array, view: DataView): number
   throw new Error("Invalid ZIP archive: end of central directory not found.");
 }
 
-function readZipEntry(archive: Uint8Array, entry: ZipCentralDirectoryEntry): Uint8Array {
+function assertEntryWithinLimits(
+  entry: ZipCentralDirectoryEntry,
+  limits: ResolvedOpcPackageReadLimits,
+): void {
+  if (entry.uncompressedSize > limits.maxEntryUncompressedBytes) {
+    throw new Error(
+      `Invalid ZIP archive: entry ${entry.path} uncompressed size ${entry.uncompressedSize} exceeds limit ${limits.maxEntryUncompressedBytes}.`,
+    );
+  }
+}
+
+function readZipEntry(
+  archive: Uint8Array,
+  entry: ZipCentralDirectoryEntry,
+  limits: ResolvedOpcPackageReadLimits,
+): Uint8Array {
   const view = new DataView(archive.buffer, archive.byteOffset, archive.byteLength);
   const headerOffset = entry.localHeaderOffset;
+  if (headerOffset + 30 > archive.byteLength) {
+    throw new Error(`Invalid ZIP local file header offset ${headerOffset}.`);
+  }
   const signature = view.getUint32(headerOffset, true);
   if (signature !== LOCAL_FILE_HEADER_SIGNATURE) {
     throw new Error(`Invalid ZIP local file header signature at offset ${headerOffset}.`);
@@ -178,16 +256,28 @@ function readZipEntry(archive: Uint8Array, entry: ZipCentralDirectoryEntry): Uin
   const fileNameLength = view.getUint16(headerOffset + 26, true);
   const extraFieldLength = view.getUint16(headerOffset + 28, true);
   const dataOffset = headerOffset + 30 + fileNameLength + extraFieldLength;
+  if (dataOffset + entry.compressedSize > archive.byteLength) {
+    throw new Error(`Invalid ZIP entry ${entry.path}: compressed data exceeds archive bounds.`);
+  }
   const compressed = archive.subarray(dataOffset, dataOffset + entry.compressedSize);
 
+  let inflated: Uint8Array;
   switch (entry.compression) {
     case "store":
-      return new Uint8Array(compressed);
+      inflated = new Uint8Array(compressed);
+      break;
     case "deflate":
-      return inflateSync(compressed);
+      inflated = inflateSync(compressed);
+      break;
     default:
       throw new Error(`Unsupported ZIP compression for ${entry.path}.`);
   }
+  if (inflated.byteLength > limits.maxEntryUncompressedBytes) {
+    throw new Error(
+      `Invalid ZIP archive: entry ${entry.path} inflated size ${inflated.byteLength} exceeds limit ${limits.maxEntryUncompressedBytes}.`,
+    );
+  }
+  return inflated;
 }
 
 function mapCompressionMethod(method: number): OpcCompressionMethod {

package/src/model/anchor.ts

@@ -28,14 +28,15 @@ export interface BoundaryAssoc {
 /**
  * Range anchor — flat shape `{ kind: "range", from, to, assoc }` after the
  * 2026-04-23 flat-wins collapse. Prior to the collapse this carried a nested
- * `{ range: DocRange, assoc }` shape. See `canonical-document.ts` CanonicalAnchor
- * for the matching canonical shape + `repairCanonicalDocumentEnvelope` for the
- * persisted-snapshot legacy-to-flat migration.
+ * `{ range: DocRange, assoc }` shape. `range` remains as a readback-compatible
+ * mirror for review/package round-trip consumers that still inspect nested
+ * active ranges; `from` / `to` remain authoritative.
  */
 export interface RangeAnchor {
   kind: "range";
   from: Position;
   to: Position;
+  range?: DocRange;
   assoc: BoundaryAssoc;
 }
 

package/src/model/canonical-document.ts

@@ -108,6 +108,43 @@ export interface CanonicalDocumentFragment {
   readonly blocks: BlockNode[];
 }
 
+/**
+ * Durable source-package pointer for canonical facts that must reconcile with
+ * Word-first telemetry without exposing package XML or document text.
+ */
+export interface CanonicalSourceRef {
+  readonly sourceId: string;
+  readonly partPath?: string;
+  readonly storyKind?: string;
+  readonly element?: string;
+  readonly ordinal?: number;
+  readonly startOffset?: number;
+  readonly endOffset?: number;
+}
+
+/**
+ * Redacted field evidence used by layout/runtime telemetry. Raw instruction
+ * and result text remain on editable field nodes and registry entries where
+ * they already exist; this shape is the hash-addressable comparison surface.
+ */
+export interface CanonicalFieldEvidenceRef {
+  readonly sourceRef?: CanonicalSourceRef;
+  readonly instructionHash?: string;
+  readonly resultHash?: string;
+  readonly locked?: boolean;
+  readonly dirty?: boolean;
+}
+
+export interface CanonicalHyperlinkFieldCarrier {
+  readonly sourceRef?: CanonicalSourceRef;
+  readonly fieldFamily?: FieldFamily;
+  readonly refreshStatus?: FieldRefreshStatus;
+  readonly instructionHash?: string;
+  readonly resultHash?: string;
+  readonly locked?: boolean;
+  readonly dirty?: boolean;
+}
+
 /**
  * Draft-only mutable view of `CanonicalDocumentFragment`. Same
  * semantics as {@link Mutable}. Used at fragment-construction sites;
@@ -370,6 +407,8 @@ export interface NumPicBullet {
 
 export interface AbstractNumberingDefinition {
   readonly abstractNumberingId: string;
+  /** Source numbering-part pointer for Word telemetry joins. */
+  readonly sourceRef?: CanonicalSourceRef;
   readonly levels: NumberingLevelDefinition[];
   readonly nsid?: string;
   readonly multiLevelType?: "singleLevel" | "multilevel" | "hybridMultilevel";
@@ -421,6 +460,8 @@ export interface NumberingLevelOverrideDefinition {
 
 export interface NumberingInstance {
   readonly numberingInstanceId: string;
+  /** Source numbering-part pointer for Word telemetry joins. */
+  readonly sourceRef?: CanonicalSourceRef;
   readonly abstractNumberingId: string;
   readonly overrides: NumberingLevelOverride[];
 }
@@ -1049,9 +1090,12 @@ export interface CanonicalFontEntry {
 
 export interface ParagraphNode {
   readonly type: "paragraph";
+  readonly sourceRef?: CanonicalSourceRef;
   readonly styleId?: string;
   numbering?: {
     readonly numberingInstanceId: string;
+    /** Source `<w:numPr>` pointer for Word telemetry joins. */
+    readonly sourceRef?: CanonicalSourceRef;
     readonly level: number;
   };
   readonly alignment?: "left" | "center" | "right" | "both" | "distribute";
@@ -1230,6 +1274,7 @@ export interface TableStyleFormatting {
 
 export interface TableNode {
   readonly type: "table";
+  readonly sourceRef?: CanonicalSourceRef;
   readonly styleId?: string;
   /** @deprecated Use `unknownPropertyChildren`. Kept for snapshot back-compat. */
   readonly propertiesXml?: string;
@@ -1358,6 +1403,7 @@ export type PreserveOnlyFieldFamily =
   | "TIME"
   | "AUTHOR"
   | "FILENAME"
+  | "HYPERLINK"
   | "MERGEFIELD"
   | "IF"
   | "SEQ"
@@ -1381,14 +1427,20 @@ export type FieldRefreshStatus =
 export interface FieldNode {
   readonly type: "field";
   readonly fieldType: "simple" | "complex";
+  /** Stable canonical field identity for source/runtime telemetry joins. */
+  readonly canonicalFieldId?: string;
   readonly instruction: string;
   readonly children: InlineNode[];
+  readonly sourceRef?: CanonicalSourceRef;
   /** Classified field family. Undefined for legacy snapshots. */
   readonly fieldFamily?: FieldFamily;
   /** Target bookmark name for REF/PAGEREF/NOTEREF fields. */
   readonly fieldTarget?: string;
   /** Runtime refresh status. Undefined for legacy or preserve-only fields. */
   readonly refreshStatus?: FieldRefreshStatus;
+  /** Word field state flags when parsed from source package evidence. */
+  readonly locked?: boolean;
+  readonly dirty?: boolean;
   /** Parsed field switches. Present only when the instruction contains recognized switches. */
   switches?: {
     readonly hyperlink?: boolean;
@@ -1460,6 +1512,8 @@ export interface FieldRegistry {
 export interface FieldRegistryEntry {
   /** Stable document-order index of this field (0-based). */
   readonly fieldIndex: number;
+  /** Stable canonical field identity for source/runtime telemetry joins. */
+  readonly canonicalFieldId?: string;
   /** Classified field family. */
   readonly fieldFamily: FieldFamily;
   /** Whether the field is in the supported refresh slice. */
@@ -1474,8 +1528,13 @@ export interface FieldRegistryEntry {
   readonly paragraphIndex: number;
   /** Stable story key for the story that owns this field instance. */
   readonly storyKey?: string;
+  /** Source-package pointer for joining this field to Word oracle telemetry. */
+  readonly sourceRef?: CanonicalSourceRef;
   /** Runtime refresh status. */
   readonly refreshStatus: FieldRefreshStatus;
+  /** Word field state flags when parsed from source package evidence. */
+  readonly locked?: boolean;
+  readonly dirty?: boolean;
   /** Parsed field switches carried from FieldNode.switches. Present only for REF/PAGEREF/NOTEREF/TOC entries with recognized switches. */
   readonly switches?: FieldNode["switches"];
 }
@@ -1813,12 +1872,16 @@ export interface SymbolNode {
 export interface HyperlinkNode {
   readonly type: "hyperlink";
   readonly href: string;
+  readonly sourceRef?: CanonicalSourceRef;
+  /** Treats `<w:hyperlink>` as a Word field carrier without forcing raw text into telemetry. */
+  readonly fieldCarrier?: CanonicalHyperlinkFieldCarrier;
   readonly children: Array<TextNode | HardBreakNode | ColumnBreakNode | PageBreakNode | TabNode | SymbolNode>;
 }
 
 export interface ImageNode {
   readonly type: "image";
   readonly mediaId: string;
+  readonly sourceRef?: CanonicalSourceRef;
   readonly altText?: string;
   readonly placementXml?: string;
   readonly display?: "inline" | "floating";
@@ -2150,6 +2213,7 @@ export interface TextBoxBodyProperties {
 
 export interface DrawingFrameNode {
   readonly type: "drawing_frame";
+  readonly sourceRef?: CanonicalSourceRef;
   readonly anchor: AnchorGeometry;
   content:
     | PictureContent
@@ -2251,7 +2315,13 @@ export interface CommentThreadMetadata {
 }
 
 export interface RevisionPropertyChangeData {
-  readonly xmlTag: "pPrChange" | "sectPrChange" | "tblPrChange" | "rPrChange";
+  readonly xmlTag:
+    | "pPrChange"
+    | "sectPrChange"
+    | "tblPrChange"
+    | "trPrChange"
+    | "tcPrChange"
+    | "rPrChange";
   readonly beforeXml: string;
 }
 
@@ -2868,6 +2938,13 @@ function validateNumberingCatalog(
           message: "abstractNumberingId must match the map key.",
         });
       }
+      if (definitionRecord?.sourceRef !== undefined) {
+        validateCanonicalSourceRef(
+          definitionRecord.sourceRef,
+          `${path}.abstractDefinitions.${abstractId}.sourceRef`,
+          issues,
+        );
+      }
     }
   }
 
@@ -2900,6 +2977,13 @@ function validateNumberingCatalog(
         `${path}.instances.${instanceId}.abstractNumberingId`,
         issues,
       );
+      if (instanceRecord.sourceRef !== undefined) {
+        validateCanonicalSourceRef(
+          instanceRecord.sourceRef,
+          `${path}.instances.${instanceId}.sourceRef`,
+          issues,
+        );
+      }
     }
   }
 }
@@ -2979,6 +3063,9 @@ function validateDocumentNode(
       if (type === "paragraph" && record.styleId !== undefined) {
         expectDomainString(record.styleId, "styleId", `${path}.styleId`, issues);
       }
+      if (type === "paragraph" && record.sourceRef !== undefined) {
+        validateCanonicalSourceRef(record.sourceRef, `${path}.sourceRef`, issues);
+      }
       if (type === "paragraph" && record.numbering !== undefined) {
         const numbering = asPlainObject(record.numbering, `${path}.numbering`, issues);
         if (numbering) {
@@ -2988,6 +3075,9 @@ function validateDocumentNode(
             `${path}.numbering.numberingInstanceId`,
             issues,
           );
+          if (numbering.sourceRef !== undefined) {
+            validateCanonicalSourceRef(numbering.sourceRef, `${path}.numbering.sourceRef`, issues);
+          }
           if (typeof numbering.level !== "number") {
             issues.push({
               path: `${path}.numbering.level`,
@@ -2998,6 +3088,12 @@ function validateDocumentNode(
       }
       if (type === "hyperlink") {
         expectString(record.href, `${path}.href`, issues);
+        if (record.sourceRef !== undefined) {
+          validateCanonicalSourceRef(record.sourceRef, `${path}.sourceRef`, issues);
+        }
+        if (record.fieldCarrier !== undefined) {
+          validateHyperlinkFieldCarrier(record.fieldCarrier, `${path}.fieldCarrier`, issues);
+        }
       }
       return;
     case "alt_chunk":
@@ -3005,6 +3101,9 @@ function validateDocumentNode(
       return;
     case "image":
       expectDomainString(record.mediaId, "mediaId", `${path}.mediaId`, issues);
+      if (record.sourceRef !== undefined) {
+        validateCanonicalSourceRef(record.sourceRef, `${path}.sourceRef`, issues);
+      }
       if (record.placementXml !== undefined) {
         expectString(record.placementXml, `${path}.placementXml`, issues);
       }
@@ -3030,6 +3129,9 @@ function validateDocumentNode(
       }
       return;
     case "table":
+      if (record.sourceRef !== undefined) {
+        validateCanonicalSourceRef(record.sourceRef, `${path}.sourceRef`, issues);
+      }
       if (!Array.isArray(record.gridColumns)) {
         issues.push({ path: `${path}.gridColumns`, message: "gridColumns must be an array." });
       }
@@ -3061,7 +3163,15 @@ function validateDocumentNode(
       return;
     case "field":
       expectString(record.fieldType, `${path}.fieldType`, issues);
+      if (record.canonicalFieldId !== undefined) {
+        expectString(record.canonicalFieldId, `${path}.canonicalFieldId`, issues);
+      }
       expectString(record.instruction, `${path}.instruction`, issues);
+      if (record.sourceRef !== undefined) {
+        validateCanonicalSourceRef(record.sourceRef, `${path}.sourceRef`, issues);
+      }
+      validateOptionalBoolean(record.locked, `${path}.locked`, issues);
+      validateOptionalBoolean(record.dirty, `${path}.dirty`, issues);
       if (!Array.isArray(record.children)) {
         issues.push({ path: `${path}.children`, message: "children must be an array." });
       } else {
@@ -3137,6 +3247,9 @@ function validateDocumentNode(
       }
       return;
     case "drawing_frame": {
+      if (record.sourceRef !== undefined) {
+        validateCanonicalSourceRef(record.sourceRef, `${path}.sourceRef`, issues);
+      }
       const anchor = asPlainObject(record.anchor, `${path}.anchor`, issues);
       const content = asPlainObject(record.content, `${path}.content`, issues);
       if (anchor) {
@@ -3230,6 +3343,99 @@ function validateDocumentNode(
   }
 }
 
+function validateOptionalBoolean(
+  value: unknown,
+  path: string,
+  issues: ModelValidationIssue[],
+): void {
+  if (value !== undefined && typeof value !== "boolean") {
+    issues.push({ path, message: "must be a boolean when present." });
+  }
+}
+
+function validateCanonicalSourceRef(
+  value: unknown,
+  path: string,
+  issues: ModelValidationIssue[],
+): void {
+  const record = asPlainObject(value, path, issues);
+  if (!record) {
+    return;
+  }
+
+  expectString(record.sourceId, `${path}.sourceId`, issues);
+
+  for (const key of ["partPath", "storyKind", "element"] as const) {
+    if (record[key] !== undefined) {
+      expectString(record[key], `${path}.${key}`, issues);
+    }
+  }
+
+  for (const key of ["ordinal", "startOffset", "endOffset"] as const) {
+    if (record[key] !== undefined && (!Number.isInteger(record[key]) || (record[key] as number) < 0)) {
+      issues.push({
+        path: `${path}.${key}`,
+        message: `${key} must be a non-negative integer when present.`,
+      });
+    }
+  }
+}
+
+function validateHashRef(
+  value: unknown,
+  path: string,
+  issues: ModelValidationIssue[],
+): void {
+  if (value === undefined) return;
+  const hash = expectString(value, path, issues);
+  if (hash && !/^[A-Fa-f0-9]{64}$/.test(hash)) {
+    issues.push({
+      path,
+      message: "hash must be a 64-character hex SHA-256 digest.",
+    });
+  }
+}
+
+function validateHyperlinkFieldCarrier(
+  value: unknown,
+  path: string,
+  issues: ModelValidationIssue[],
+): void {
+  const record = asPlainObject(value, path, issues);
+  if (!record) {
+    return;
+  }
+
+  if (record.sourceRef !== undefined) {
+    validateCanonicalSourceRef(record.sourceRef, `${path}.sourceRef`, issues);
+  }
+  if (
+    record.fieldFamily !== undefined &&
+    !(
+      SUPPORTED_FIELD_FAMILIES.has(record.fieldFamily as SupportedFieldFamily) ||
+      PRESERVE_ONLY_FIELD_FAMILIES.has(record.fieldFamily as PreserveOnlyFieldFamily)
+    )
+  ) {
+    issues.push({
+      path: `${path}.fieldFamily`,
+      message: "fieldFamily must be a SupportedFieldFamily or PreserveOnlyFieldFamily when present.",
+    });
+  }
+  if (
+    record.refreshStatus !== undefined &&
+    !FIELD_REFRESH_STATUSES.has(record.refreshStatus as FieldRefreshStatus)
+  ) {
+    issues.push({
+      path: `${path}.refreshStatus`,
+      message: "refreshStatus must be one of: current, stale, unresolvable, preserve-only.",
+    });
+  }
+  validateHashRef(record.instructionHash, `${path}.instructionHash`, issues);
+  validateHashRef(record.resultHash, `${path}.resultHash`, issues);
+  validateOptionalBoolean(record.locked, `${path}.locked`, issues);
+  validateOptionalBoolean(record.dirty, `${path}.dirty`, issues);
+}
+
 function validateFloatingImageProperties(
   value: unknown,
   path: string,
@@ -4290,6 +4496,7 @@ const PRESERVE_ONLY_FIELD_FAMILIES: ReadonlySet<PreserveOnlyFieldFamily> = new S
   "TIME",
   "AUTHOR",
   "FILENAME",
+  "HYPERLINK",
   "MERGEFIELD",
   "IF",
   "SEQ",
@@ -4381,6 +4588,10 @@ function validateFieldRegistryEntry(
     });
   }
 
+  if (record.canonicalFieldId !== undefined) {
+    expectString(record.canonicalFieldId, `${path}.canonicalFieldId`, issues);
+  }
+
   if (
     typeof record.fieldFamily !== "string" ||
     !(
@@ -4419,6 +4630,10 @@ function validateFieldRegistryEntry(
     expectString(record.storyKey, `${path}.storyKey`, issues);
   }
 
+  if (record.sourceRef !== undefined) {
+    validateCanonicalSourceRef(record.sourceRef, `${path}.sourceRef`, issues);
+  }
+
   if (
     typeof record.refreshStatus !== "string" ||
     !FIELD_REFRESH_STATUSES.has(record.refreshStatus as FieldRefreshStatus)
@@ -4426,9 +4641,12 @@ function validateFieldRegistryEntry(
     issues.push({
       path: `${path}.refreshStatus`,
       message:
-        "refreshStatus must be one of: current, stale, unresolvable, preserve-only.",
+      "refreshStatus must be one of: current, stale, unresolvable, preserve-only.",
     });
   }
+
+  validateOptionalBoolean(record.locked, `${path}.locked`, issues);
+  validateOptionalBoolean(record.dirty, `${path}.dirty`, issues);
 }
 
 function validateTocStructure(