@ansonlai/docx-redline-js 0.7.2 → 0.8.1

package/services/operation-preflight.js

@@ -6,35 +6,35 @@ import { parseOoxmlSafe } from '../adapters/xml-adapter.js';
 import { getDefaultAuthor } from '../adapters/config.js';
 import { containsTrackedChanges, getTrackedChangeAuthors } from '../core/word-xml.js';
 import { NS_W } from '../core/types.js';
-import { extractCanonicalParagraphText } from '../core/paragraph-text.js';
-import {
-    getParagraphRestorationRefusal,
-    inspectForeignDeletedParagraphTarget
-} from '../core/paragraph-revision-safety.js';
+import { extractCanonicalParagraphText } from '../core/paragraph-text.js';
+import {
+    getParagraphRestorationRefusal,
+    inspectForeignDeletedParagraphTarget
+} from '../core/paragraph-revision-safety.js';
 import {
     buildParagraphMetadataIndex,
     createParagraphFingerprint,
     findContainingWordElement,
     getDocumentParagraphNodes,
     getParagraphId,
-    normalizeWhitespaceForTargeting,
-    resolveParagraphRangeByRefs,
-    resolveTargetParagraph,
+    normalizeWhitespaceForTargeting,
+    resolveParagraphRangeByRefs,
+    resolveTargetParagraph,
     validateParagraphBoundaryMutation
 } from '../core/paragraph-targeting.js';
 import { createParagraphTextIndex, resolveTextInParagraphIndex } from './comment-locator.js';
-import {
-    isExistingRevisionsPolicy,
-    normalizeDocumentOperation,
+import {
+    isExistingRevisionsPolicy,
+    normalizeDocumentOperation,
     resolveDocumentOperationAuthor,
     validateDocumentOperation
 } from './document-operation-contract.js';
-import { buildOperationDependencyPlan } from './batch-operation-orchestrator.js';
-import { compileOperationBatch } from './operation-batch-compiler.js';
-import { normalizeErrorWithRecovery } from './error-recovery.js';
-
-function normalizedError(error, context = {}) {
-    return normalizeErrorWithRecovery(error, context);
+import { buildOperationDependencyPlan } from './batch-operation-orchestrator.js';
+import { compileOperationBatch } from './operation-batch-compiler.js';
+import { normalizeErrorWithRecovery } from './error-recovery.js';
+
+function normalizedError(error, context = {}) {
+    return normalizeErrorWithRecovery(error, context);
 }
 
 function operationNeedsNumbering(operation) {
@@ -79,27 +79,27 @@ function getCommentIdsInParagraph(paragraph) {
     return Array.from(ids).sort((a, b) => Number(a) - Number(b) || a.localeCompare(b));
 }
 
-export function preflightOperations(documentXml, operations, author, options = {}) {
-    if (options.existingRevisions != null && !isExistingRevisionsPolicy(options.existingRevisions)) {
-        return {
-            valid: false,
-            status: 'error',
-            error: normalizedError({
-                code: 'INVALID_OPERATION',
-                message: `Unsupported existingRevisions policy: "${String(options.existingRevisions)}".`
-            }),
-            results: [],
-            conflicts: [],
-            authorsUsed: [],
-            requiredArtifacts: { comments: false, numbering: false }
-        };
-    }
-    const parsed = parseOoxmlSafe(documentXml, 'application/xml');
+export function preflightOperations(documentXml, operations, author, options = {}) {
+    if (options.existingRevisions != null && !isExistingRevisionsPolicy(options.existingRevisions)) {
+        return {
+            valid: false,
+            status: 'error',
+            error: normalizedError({
+                code: 'INVALID_OPERATION',
+                message: `Unsupported existingRevisions policy: "${String(options.existingRevisions)}".`
+            }),
+            results: [],
+            conflicts: [],
+            authorsUsed: [],
+            requiredArtifacts: { comments: false, numbering: false }
+        };
+    }
+    const parsed = parseOoxmlSafe(documentXml, 'application/xml');
     if (parsed.error || !parsed.doc) {
         return {
             valid: false,
             status: 'error',
-            error: normalizedError(parsed.error),
+            error: normalizedError(parsed.error),
             results: [],
             conflicts: [],
             authorsUsed: [],
@@ -113,39 +113,39 @@ export function preflightOperations(documentXml, operations, author, options = {
         rejected: null
     };
     const sourceOperations = Array.isArray(operations) ? operations : [];
-    const batchCompilation = compileOperationBatch(xmlDoc, sourceOperations, {
-        strictTargets: options.strictTargets !== false,
-        onInfo: options.onInfo,
-        onWarn: options.onWarn
-    });
-    const dependencyPlan = buildOperationDependencyPlan(batchCompilation.compiledOperations);
-    if (!dependencyPlan.valid) {
+    const batchCompilation = compileOperationBatch(xmlDoc, sourceOperations, {
+        strictTargets: options.strictTargets !== false,
+        onInfo: options.onInfo,
+        onWarn: options.onWarn
+    });
+    const dependencyPlan = buildOperationDependencyPlan(batchCompilation.compiledOperations);
+    if (!dependencyPlan.valid) {
         return {
             valid: false,
             status: 'error',
-            error: normalizedError(dependencyPlan.error),
+            error: normalizedError(dependencyPlan.error),
             results: [],
             conflicts: [],
             authorsUsed: [],
             requiredArtifacts: { comments: false, numbering: false }
         };
-    }
+    }
     const strictTargets = options.strictTargets !== false;
     const results = [];
     const authorsUsed = new Set();
     let commentsRequired = false;
     let numberingRequired = false;
 
-    for (let index = 0; index < sourceOperations.length; index++) {
-        const sourceOperation = sourceOperations[index];
-        const compiledBinding = batchCompilation.bindings[index];
-        const compiledOperation = batchCompilation.compiledOperations[index];
-        const operationInput = !compiledBinding?.error && compiledOperation?._localizedReplacementCompilation
-            ? compiledOperation
-            : sourceOperation;
-        const validation = validateDocumentOperation(operationInput);
-        const fallbackOperation = normalizeDocumentOperation(sourceOperation);
-        const operation = validation.operation || fallbackOperation;
+    for (let index = 0; index < sourceOperations.length; index++) {
+        const sourceOperation = sourceOperations[index];
+        const compiledBinding = batchCompilation.bindings[index];
+        const compiledOperation = batchCompilation.compiledOperations[index];
+        const operationInput = !compiledBinding?.error && compiledOperation?._localizedReplacementCompilation
+            ? compiledOperation
+            : sourceOperation;
+        const validation = validateDocumentOperation(operationInput);
+        const fallbackOperation = normalizeDocumentOperation(sourceOperation);
+        const operation = validation.operation || fallbackOperation;
         const authorUsed = resolveDocumentOperationAuthor(operation, author, getDefaultAuthor());
         authorsUsed.add(authorUsed);
 
@@ -164,6 +164,19 @@ export function preflightOperations(documentXml, operations, author, options = {
         commentsRequired = commentsRequired || operation.operationKind === 'comment' || operation.operationKind === 'comment_reply';
         numberingRequired = numberingRequired || operationNeedsNumbering(operation);
 
+        if (operation.operationKind === 'comment_resolve') {
+            const commentId = String(operation.commentId);
+            results.push(options._existingCommentDetails?.[commentId] ? {
+                index: index + 1, type: sourceOperation.type, operationType: operation.operationKind,
+                status: 'ready', authorUsed, resolvedBy: 'comment_id', commentId
+            } : {
+                index: index + 1, type: sourceOperation.type, operationType: operation.operationKind,
+                status: 'error', authorUsed,
+                error: { code: 'COMMENT_NOT_FOUND', message: `Comment '${commentId}' was not found.` }
+            });
+            continue;
+        }
+
         if (operation.operationKind === 'comment_reply') {
             const parentId = String(operation.parentCommentId);
             const parent = options._existingCommentDetails?.[parentId];
@@ -178,7 +191,7 @@ export function preflightOperations(documentXml, operations, author, options = {
             continue;
         }
 
-        if (operation.targetDescriptor?.captureRef) {
+        if (operation.targetDescriptor?.captureRef) {
             results.push({
                 index: index + 1,
                 type: sourceOperation?.type || 'redline',
@@ -189,34 +202,34 @@ export function preflightOperations(documentXml, operations, author, options = {
                 captureRef: operation.targetDescriptor.captureRef,
                 ...(operation.targetDescriptor.select ? { select: operation.targetDescriptor.select } : {})
             });
-            continue;
-        }
-
-        if (compiledBinding?.error) {
-            results.push({
-                index: index + 1,
-                type: sourceOperation?.type || 'redline',
-                operationType: operation.operationKind,
-                status: 'error',
-                authorUsed,
-                error: compiledBinding.error
-            });
-            continue;
-        }
-        if (compiledBinding?.createdByOperation) {
-            results.push({
-                index: index + 1,
-                type: sourceOperation?.type || 'redline',
-                operationType: operation.operationKind,
-                status: 'deferred',
-                authorUsed,
-                resolvedBy: 'created_content_dependency',
-                captureRef: compiledBinding.captureRef,
-                select: operation.targetDescriptor.text,
-                createdByOperation: compiledBinding.createdByOperation
-            });
-            continue;
-        }
+            continue;
+        }
+
+        if (compiledBinding?.error) {
+            results.push({
+                index: index + 1,
+                type: sourceOperation?.type || 'redline',
+                operationType: operation.operationKind,
+                status: 'error',
+                authorUsed,
+                error: compiledBinding.error
+            });
+            continue;
+        }
+        if (compiledBinding?.createdByOperation) {
+            results.push({
+                index: index + 1,
+                type: sourceOperation?.type || 'redline',
+                operationType: operation.operationKind,
+                status: 'deferred',
+                authorUsed,
+                resolvedBy: 'created_content_dependency',
+                captureRef: compiledBinding.captureRef,
+                select: operation.targetDescriptor.text,
+                createdByOperation: compiledBinding.createdByOperation
+            });
+            continue;
+        }
 
         const targetView = operation.targetDescriptor?.revisionView === 'rejected' ? 'rejected' : 'accepted';
         let currentMetadataIndex = targetView === 'rejected'
@@ -224,28 +237,28 @@ export function preflightOperations(documentXml, operations, author, options = {
             : metadataIndices.accepted;
 
         try {
-            let resolved;
-            if (compiledBinding.dynamic) {
-                resolved = resolveTargetParagraph(xmlDoc, {
-                    targetText: operation.target,
-                    targetRef: operation.targetRef,
-                    targetDescriptor: operation.targetDescriptor,
-                    opType: operation.operationKind,
-                    strictAmbiguity: strictTargets,
-                    paragraphMetadataIndex: currentMetadataIndex,
-                    metadataIndices,
-                    onInfo: options.onInfo,
-                    onWarn: options.onWarn
-                });
-            } else {
-                const bound = batchCompilation.registry.resolve(compiledBinding.sourceIds[0], xmlDoc);
-                if (bound.error) throw Object.assign(new Error(bound.error.message), bound.error);
-                resolved = {
-                    paragraph: bound.paragraph,
-                    resolvedBy: compiledBinding.resolvedBy,
-                    warnings: compiledBinding.warnings
-                };
-            }
+            let resolved;
+            if (compiledBinding.dynamic) {
+                resolved = resolveTargetParagraph(xmlDoc, {
+                    targetText: operation.target,
+                    targetRef: operation.targetRef,
+                    targetDescriptor: operation.targetDescriptor,
+                    opType: operation.operationKind,
+                    strictAmbiguity: strictTargets,
+                    paragraphMetadataIndex: currentMetadataIndex,
+                    metadataIndices,
+                    onInfo: options.onInfo,
+                    onWarn: options.onWarn
+                });
+            } else {
+                const bound = batchCompilation.registry.resolve(compiledBinding.sourceIds[0], xmlDoc);
+                if (bound.error) throw Object.assign(new Error(bound.error.message), bound.error);
+                resolved = {
+                    paragraph: bound.paragraph,
+                    resolvedBy: compiledBinding.resolvedBy,
+                    warnings: compiledBinding.warnings
+                };
+            }
             const paragraph = resolved.paragraph;
             const metadata = targetMetadata(xmlDoc, paragraph, resolved.resolvedBy, operation.target, currentMetadataIndex, targetView);
             const paragraphText = metadata.resolvedTarget.text;
@@ -264,69 +277,69 @@ export function preflightOperations(documentXml, operations, author, options = {
                 || options.existingRevisions
                 || 'merge-same-author';
             const deletingWholeParagraph = operation.operationKind === 'redline' && operation.modified === '';
-            const commentIds = deletingWholeParagraph ? getCommentIdsInParagraph(paragraph) : [];
-
-            let error = null;
-            if (operation.operationKind === 'restore') {
-                let restorationParagraphs = operation.targetEndRef
-                    ? resolveParagraphRangeByRefs(xmlDoc, operation.targetRef, operation.targetEndRef, {
-                        opType: 'restore',
-                        targetRefSnapshot: options.targetRefSnapshot || null,
-                        onInfo: options.onInfo,
-                        onWarn: options.onWarn
-                    })
-                    : [paragraph];
-                if (!operation.targetEndRef && operation.targetEndDescriptor) {
-                    const endResolved = resolveTargetParagraph(xmlDoc, {
-                        targetText: operation.targetEndDescriptor.text,
-                        targetRef: operation.targetEndDescriptor.index,
-                        targetDescriptor: operation.targetEndDescriptor,
-                        opType: 'restore',
-                        strictAmbiguity: strictTargets,
-                        paragraphMetadataIndex: currentMetadataIndex,
-                        metadataIndices,
-                        onInfo: options.onInfo,
-                        onWarn: options.onWarn
-                    });
-                    const allParagraphs = getDocumentParagraphNodes(xmlDoc);
-                    const startIndex = allParagraphs.indexOf(paragraph);
-                    const endIndex = allParagraphs.indexOf(endResolved?.paragraph);
-                    restorationParagraphs = startIndex >= 0 && endIndex >= startIndex
-                        ? allParagraphs.slice(startIndex, endIndex + 1)
-                        : null;
-                }
-                const replacements = Array.isArray(operation.modified) ? operation.modified : [operation.modified];
-                if (!restorationParagraphs || restorationParagraphs[0] !== paragraph || replacements.length !== restorationParagraphs.length) {
-                    error = {
-                        code: 'RESTORATION_COUNT_MISMATCH',
-                        message: 'Restoration requires one replacement for every paragraph in a contiguous resolved range.'
-                    };
-                } else {
-                    for (const restorationParagraph of restorationParagraphs) {
-                        const structuralRefusal = getParagraphRestorationRefusal(restorationParagraph);
-                        if (structuralRefusal?.code === 'UNSUPPORTED_MOVE_REVISION') {
-                            error = structuralRefusal;
-                            break;
-                        }
-                        const state = inspectForeignDeletedParagraphTarget(restorationParagraph, authorUsed);
-                        const refusal = state.matches
-                            ? (structuralRefusal || getParagraphRestorationRefusal(restorationParagraph))
-                            : null;
-                        if (!state.matches) {
-                            error = {
-                                code: 'RESTORATION_STATE_REQUIRED',
-                                message: 'Explicit restoration requires a foreign paragraph-mark deletion with every pre-existing content node deleted.',
-                                ...(state.ownerAuthor ? { ownerAuthor: state.ownerAuthor } : {})
-                            };
-                            break;
-                        }
-                        if (refusal) {
-                            error = refusal;
-                            break;
-                        }
-                    }
-                }
-            } else if (!anchorFound) {
+            const commentIds = deletingWholeParagraph ? getCommentIdsInParagraph(paragraph) : [];
+
+            let error = null;
+            if (operation.operationKind === 'restore') {
+                let restorationParagraphs = operation.targetEndRef
+                    ? resolveParagraphRangeByRefs(xmlDoc, operation.targetRef, operation.targetEndRef, {
+                        opType: 'restore',
+                        targetRefSnapshot: options.targetRefSnapshot || null,
+                        onInfo: options.onInfo,
+                        onWarn: options.onWarn
+                    })
+                    : [paragraph];
+                if (!operation.targetEndRef && operation.targetEndDescriptor) {
+                    const endResolved = resolveTargetParagraph(xmlDoc, {
+                        targetText: operation.targetEndDescriptor.text,
+                        targetRef: operation.targetEndDescriptor.index,
+                        targetDescriptor: operation.targetEndDescriptor,
+                        opType: 'restore',
+                        strictAmbiguity: strictTargets,
+                        paragraphMetadataIndex: currentMetadataIndex,
+                        metadataIndices,
+                        onInfo: options.onInfo,
+                        onWarn: options.onWarn
+                    });
+                    const allParagraphs = getDocumentParagraphNodes(xmlDoc);
+                    const startIndex = allParagraphs.indexOf(paragraph);
+                    const endIndex = allParagraphs.indexOf(endResolved?.paragraph);
+                    restorationParagraphs = startIndex >= 0 && endIndex >= startIndex
+                        ? allParagraphs.slice(startIndex, endIndex + 1)
+                        : null;
+                }
+                const replacements = Array.isArray(operation.modified) ? operation.modified : [operation.modified];
+                if (!restorationParagraphs || restorationParagraphs[0] !== paragraph || replacements.length !== restorationParagraphs.length) {
+                    error = {
+                        code: 'RESTORATION_COUNT_MISMATCH',
+                        message: 'Restoration requires one replacement for every paragraph in a contiguous resolved range.'
+                    };
+                } else {
+                    for (const restorationParagraph of restorationParagraphs) {
+                        const structuralRefusal = getParagraphRestorationRefusal(restorationParagraph);
+                        if (structuralRefusal?.code === 'UNSUPPORTED_MOVE_REVISION') {
+                            error = structuralRefusal;
+                            break;
+                        }
+                        const state = inspectForeignDeletedParagraphTarget(restorationParagraph, authorUsed);
+                        const refusal = state.matches
+                            ? (structuralRefusal || getParagraphRestorationRefusal(restorationParagraph))
+                            : null;
+                        if (!state.matches) {
+                            error = {
+                                code: 'RESTORATION_STATE_REQUIRED',
+                                message: 'Explicit restoration requires a foreign paragraph-mark deletion with every pre-existing content node deleted.',
+                                ...(state.ownerAuthor ? { ownerAuthor: state.ownerAuthor } : {})
+                            };
+                            break;
+                        }
+                        if (refusal) {
+                            error = refusal;
+                            break;
+                        }
+                    }
+                }
+            } else if (!anchorFound) {
                 error = anchorResolution?.error || {
                     code: 'ANCHOR_NOT_FOUND',
                     message: `Anchor text was not found in target paragraph: "${anchor}".`
@@ -347,40 +360,40 @@ export function preflightOperations(documentXml, operations, author, options = {
                 && existingPolicy !== 'accept-all-first'
                 && existingPolicy !== 'accept-all-first-keep-normalized'
             ) {
-                if (existingPolicy === 'merge-same-author' || existingPolicy === 'slice-cross-author') {
-                    const authors = getTrackedChangeAuthors(paragraph);
-                    const opAuthor = String(authorUsed || '').trim().toLowerCase();
-                    const allSame = authors.length > 0 && authors.every(a => a.trim().toLowerCase() === opAuthor);
-                    if (!allSame && existingPolicy === 'merge-same-author') {
-                        error = {
-                            code: 'EXISTING_REVISIONS',
-                            message: `Target paragraph contains tracked changes from another author (${authors.length ? authors.join(', ') : 'unattributed'}). Use existingRevisions: "slice-cross-author" for a surgical edit that preserves reviewer history; accepting or rejecting revisions requires separate authorization.`,
-                            revisionAuthors: authors,
-                            currentPolicy: existingPolicy
-                        };
-                    } else if (allSame) {
-                        const mergeCommentIds = getCommentIdsInParagraph(paragraph);
-                        if (mergeCommentIds.length > 0) {
-                            const comments = mergeCommentIds
-                                .map(id => options._existingCommentDetails?.[id])
-                                .filter(Boolean);
-                            error = {
-                                code: 'COMMENTED_CONTENT_MERGE',
-                                message: 'Refusing to merge existing revisions in commented content because reverting the prior revisions could remove or orphan comment anchors.',
-                                commentIds: mergeCommentIds,
-                                ...(comments.length > 0 ? { comments } : {})
-                            };
-                        }
-                    } else {
-                        const hasMove = paragraph.getElementsByTagNameNS(NS_W, 'moveFrom').length > 0
-                            || paragraph.getElementsByTagNameNS(NS_W, 'moveTo').length > 0;
-                        if (hasMove) {
-                            error = {
-                                code: 'UNSAFE_REVISION_NESTING',
-                                message: 'Cross-author slicing does not support pending move revisions.'
-                            };
-                        }
-                    }
+                if (existingPolicy === 'merge-same-author' || existingPolicy === 'slice-cross-author') {
+                    const authors = getTrackedChangeAuthors(paragraph);
+                    const opAuthor = String(authorUsed || '').trim().toLowerCase();
+                    const allSame = authors.length > 0 && authors.every(a => a.trim().toLowerCase() === opAuthor);
+                    if (!allSame && existingPolicy === 'merge-same-author') {
+                        error = {
+                            code: 'EXISTING_REVISIONS',
+                            message: `Target paragraph contains tracked changes from another author (${authors.length ? authors.join(', ') : 'unattributed'}). Use existingRevisions: "slice-cross-author" for a surgical edit that preserves reviewer history; accepting or rejecting revisions requires separate authorization.`,
+                            revisionAuthors: authors,
+                            currentPolicy: existingPolicy
+                        };
+                    } else if (allSame) {
+                        const mergeCommentIds = getCommentIdsInParagraph(paragraph);
+                        if (mergeCommentIds.length > 0) {
+                            const comments = mergeCommentIds
+                                .map(id => options._existingCommentDetails?.[id])
+                                .filter(Boolean);
+                            error = {
+                                code: 'COMMENTED_CONTENT_MERGE',
+                                message: 'Refusing to merge existing revisions in commented content because reverting the prior revisions could remove or orphan comment anchors.',
+                                commentIds: mergeCommentIds,
+                                ...(comments.length > 0 ? { comments } : {})
+                            };
+                        }
+                    } else {
+                        const hasMove = paragraph.getElementsByTagNameNS(NS_W, 'moveFrom').length > 0
+                            || paragraph.getElementsByTagNameNS(NS_W, 'moveTo').length > 0;
+                        if (hasMove) {
+                            error = {
+                                code: 'UNSAFE_REVISION_NESTING',
+                                message: 'Cross-author slicing does not support pending move revisions.'
+                            };
+                        }
+                    }
                 } else {
                     const hasDel = paragraph.getElementsByTagNameNS(NS_W, 'del').length > 0;
                     const hasMove = paragraph.getElementsByTagNameNS(NS_W, 'moveFrom').length > 0
@@ -450,24 +463,24 @@ export function preflightOperations(documentXml, operations, author, options = {
         }
     }
 
-    const conflicts = batchCompilation.conflicts;
+    const conflicts = batchCompilation.conflicts;
 
-    const enrichedResults = results.map(result => result.error ? {
-        ...result,
-        error: normalizedError(result.error, {
-            operationIndex: result.index,
-            ...(sourceOperations[result.index - 1]?.operationId
-                ? { operationId: sourceOperations[result.index - 1].operationId }
-                : {})
-        })
-    } : result);
-    const enrichedConflicts = conflicts.map(conflict => normalizedError(conflict));
-    const hasErrors = enrichedResults.some(result => result.status === 'error');
-    return {
-        valid: !hasErrors && enrichedConflicts.length === 0,
-        status: !hasErrors && enrichedConflicts.length === 0 ? 'ok' : 'error',
-        results: enrichedResults,
-        conflicts: enrichedConflicts,
+    const enrichedResults = results.map(result => result.error ? {
+        ...result,
+        error: normalizedError(result.error, {
+            operationIndex: result.index,
+            ...(sourceOperations[result.index - 1]?.operationId
+                ? { operationId: sourceOperations[result.index - 1].operationId }
+                : {})
+        })
+    } : result);
+    const enrichedConflicts = conflicts.map(conflict => normalizedError(conflict));
+    const hasErrors = enrichedResults.some(result => result.status === 'error');
+    return {
+        valid: !hasErrors && enrichedConflicts.length === 0,
+        status: !hasErrors && enrichedConflicts.length === 0 ? 'ok' : 'error',
+        results: enrichedResults,
+        conflicts: enrichedConflicts,
         authorsUsed: Array.from(authorsUsed),
         requiredArtifacts: {
             comments: commentsRequired,

package/services/package-parts.js

@@ -0,0 +1,80 @@
+/**
+ * Registry of OPC package parts this library reads or writes.
+ *
+ * Single source of truth for part paths, content types and relationship types so the
+ * package plumbing never hard-codes them. Every `verified` entry is checked against
+ * documents saved by real Word in tests/package_parts_registry_tests.mjs
+ * (fixtures under tests/fixtures/word-authored/).
+ */
+
+const WORD_ML = 'application/vnd.openxmlformats-officedocument.wordprocessingml';
+const REL_OFFICE_DOC = 'http://schemas.openxmlformats.org/officeDocument/2006/relationships';
+
+/**
+ * @typedef {object} PackagePartSpec
+ * @property {string} id
+ * @property {string|null} path       Fixed part path, or null when the name is not fixed (headers/footers).
+ * @property {RegExp|null} pathPattern Matches every part name of this kind, when the name is not fixed.
+ * @property {string} contentType     The value Word writes in [Content_Types].xml.
+ * @property {string[]} legacyContentTypes Known-wrong values written by earlier versions; safe to rewrite.
+ * @property {string} relType         Relationship type from word/_rels/document.xml.rels.
+ * @property {string|null} relTarget  Relative target for a fixed-path part.
+ * @property {boolean} verified       Confirmed against a Word-saved document.
+ */
+
+/** @type {ReadonlyArray<Readonly<PackagePartSpec>>} */
+const PART_SPECS = Object.freeze([
+    { id: 'document', path: 'word/document.xml', pathPattern: null, contentType: `${WORD_ML}.document.main+xml`, legacyContentTypes: [], relType: `${REL_OFFICE_DOC}/officeDocument`, relTarget: null, verified: true },
+    { id: 'numbering', path: 'word/numbering.xml', pathPattern: null, contentType: `${WORD_ML}.numbering+xml`, legacyContentTypes: [], relType: `${REL_OFFICE_DOC}/numbering`, relTarget: 'numbering.xml', verified: false },
+    { id: 'comments', path: 'word/comments.xml', pathPattern: null, contentType: `${WORD_ML}.comments+xml`, legacyContentTypes: [], relType: `${REL_OFFICE_DOC}/comments`, relTarget: 'comments.xml', verified: true },
+    {
+        id: 'commentsExtended', path: 'word/commentsExtended.xml', pathPattern: null,
+        contentType: `${WORD_ML}.commentsExtended+xml`,
+        // Written by this package through 0.8.0; Word does not recognize it and offers to repair the file.
+        legacyContentTypes: ['application/vnd.ms-word.commentsExtended+xml'],
+        relType: 'http://schemas.microsoft.com/office/2011/relationships/commentsExtended', relTarget: 'commentsExtended.xml', verified: true
+    },
+    { id: 'commentsIds', path: 'word/commentsIds.xml', pathPattern: null, contentType: `${WORD_ML}.commentsIds+xml`, legacyContentTypes: [], relType: 'http://schemas.microsoft.com/office/2016/09/relationships/commentsIds', relTarget: 'commentsIds.xml', verified: true },
+    { id: 'commentsExtensible', path: 'word/commentsExtensible.xml', pathPattern: null, contentType: `${WORD_ML}.commentsExtensible+xml`, legacyContentTypes: [], relType: 'http://schemas.microsoft.com/office/2018/08/relationships/commentsExtensible', relTarget: 'commentsExtensible.xml', verified: true },
+    // Not yet produced by any Word fixture (Word only writes people.xml for signed-in authors): unverified.
+    { id: 'people', path: 'word/people.xml', pathPattern: null, contentType: `${WORD_ML}.people+xml`, legacyContentTypes: [], relType: 'http://schemas.microsoft.com/office/2011/relationships/people', relTarget: 'people.xml', verified: false },
+    { id: 'header', path: null, pathPattern: /^word\/header\d+\.xml$/i, contentType: `${WORD_ML}.header+xml`, legacyContentTypes: [], relType: `${REL_OFFICE_DOC}/header`, relTarget: null, verified: true },
+    { id: 'footer', path: null, pathPattern: /^word\/footer\d+\.xml$/i, contentType: `${WORD_ML}.footer+xml`, legacyContentTypes: [], relType: `${REL_OFFICE_DOC}/footer`, relTarget: null, verified: true }
+].map(spec => Object.freeze(spec)));
+
+const BY_ID = new Map(PART_SPECS.map(spec => [spec.id, spec]));
+
+/** Returns the spec for a registry id; throws for an unknown id so typos fail loudly. */
+export function getPartSpec(id) {
+    const spec = BY_ID.get(id);
+    if (!spec) throw new Error(`Unknown package part: ${id}`);
+    return spec;
+}
+
+/** All registered part specs. */
+export function listPartSpecs() {
+    return PART_SPECS;
+}
+
+/** Normalizes '/word/x.xml' or 'word/x.xml' to 'word/x.xml'. */
+function toEntryName(partName) {
+    return String(partName || '').replace(/^\/+/, '');
+}
+
+/** Finds the spec that owns a part name (with or without a leading slash), or null. */
+export function findPartSpecByPartName(partName) {
+    const name = toEntryName(partName);
+    const lower = name.toLowerCase();
+    return PART_SPECS.find(spec => spec.path ? spec.path.toLowerCase() === lower : spec.pathPattern?.test(name)) || null;
+}
+
+/**
+ * When an override's content type is a value earlier versions of this package are known to have
+ * written wrongly for that part, returns the correct one; otherwise null. Deliberately does not
+ * "correct" types it has no evidence about (for example macro-enabled document types).
+ */
+export function correctedContentTypeFor(partName, actualContentType) {
+    const spec = findPartSpecByPartName(partName);
+    if (!spec || !spec.legacyContentTypes.includes(actualContentType)) return null;
+    return spec.contentType;
+}