open-agreements 0.7.6 → 0.8.0

package/node_modules/@usejunior/docx-core/dist/baselines/atomizer/pipeline.js

@@ -21,6 +21,10 @@ import { modifyRevisedDocument, ContainerResolutionError } from './inPlaceModifi
 import { acceptAllChanges, rejectAllChanges, extractTextWithParagraphs, compareTexts, } from './trackChangesAcceptorAst.js';
 import { virtualizeNumberingLabels, DEFAULT_NUMBERING_OPTIONS, } from './numberingIntegration.js';
 import { premergeAdjacentRuns } from './premergeRuns.js';
+export { hasFldCharInsideDel, validateFieldStructure, } from '../../shared/field-structure.js';
+import { hasFldCharInsideDel, validateFieldStructure, } from '../../shared/field-structure.js';
+import { AUXILIARY_PARTS, parseEntries, renumberCollidingAuxiliaryIds, restampCollidingCommentParaIds, } from './auxiliaryIdCollision.js';
+import { maybeCaptureEmittedDocumentXml } from '../../primitives/schema-corpus-capture.js';
 function arraysEqual(a, b) {
     if (a.length !== b.length)
         return false;
@@ -215,70 +219,56 @@ function buildFailureSummary(failureDetails) {
     }
     return Object.keys(summary).length > 0 ? summary : undefined;
 }
+// Declared above splitStories so the function body never observes an
+// uninitialized binding under circular imports.
+const serializer = new XMLSerializer();
 /**
- * Validate field structure integrity in document XML.
+ * Split a docx into per-story XML fragments for field-closure validation.
+ *
+ * Each footnote/endnote entry is treated as an isolated story: a complex
+ * field whose `begin` and `end` markers straddle stories breaks Word's
+ * field state machine. We therefore validate each `<w:footnote>` and
+ * `<w:endnote>` entry independently rather than treating the whole
+ * `footnotes.xml`/`endnotes.xml` as one stream.
+ *
+ * Accepts arrays of sidecar XMLs (one per source archive) so callers can
+ * validate the union of entries from every archive that may contribute to the
+ * final result. Step 12 of `compareDocumentsAtomizer` merges entries from a
+ * mode-dependent source archive into the base archive; passing both archives'
+ * sidecars guarantees that whichever path the merge takes, the entries it
+ * could publish have already been screened. Duplicates (same `w:id` in both
+ * archives) yield redundant but harmless validation work.
  *
- * Checks that fldChar begin/end are balanced and that w:instrText only
- * appears inside a proper field sequence (between begin and separate).
- * Orphaned instrText elements render as visible text in Word.
+ * Header/footer stories are not yet covered — they require relationship
+ * walking to enumerate `headerN.xml`/`footerN.xml`.
+ *
+ * @conformance ECMA-376 edition 5, Part 4 § 17.16.5
+ * @see https://github.com/UseJunior/safe-docx/issues/212
  */
-function validateFieldStructure(documentXml) {
-    const root = parseDocumentXml(documentXml);
-    // Walk the document in order, tracking field nesting
-    const allFldChars = findAllByTagName(root, 'w:fldChar');
-    const allInstrTexts = findAllByTagName(root, 'w:instrText');
-    // Quick balance check
-    let begins = 0;
-    let ends = 0;
-    for (const fc of allFldChars) {
-        const type = fc.getAttribute('w:fldCharType');
-        if (type === 'begin')
-            begins++;
-        else if (type === 'end')
-            ends++;
-    }
-    if (begins !== ends)
-        return false;
-    // Check that instrText elements are inside a field (between begin and separate).
-    // Walk all elements in document order using a recursive scan.
-    if (allInstrTexts.length === 0)
-        return true; // No instrText, nothing to validate
-    // Depth-first scan to check instrText placement
-    let depth = 0;
-    const pastSeparatorAtDepth = []; // track separator state per depth
-    function scan(node) {
-        for (let child = node.firstChild; child; child = child.nextSibling) {
-            if (child.nodeType !== 1)
-                continue; // skip non-elements
-            const el = child;
-            if (el.tagName === 'w:fldChar') {
-                const type = el.getAttribute('w:fldCharType');
-                if (type === 'begin') {
-                    depth++;
-                    pastSeparatorAtDepth[depth] = 0;
-                }
-                else if (type === 'separate') {
-                    if (depth > 0)
-                        pastSeparatorAtDepth[depth] = 1;
-                }
-                else if (type === 'end') {
-                    if (depth > 0)
-                        depth--;
-                }
-            }
-            else if (el.tagName === 'w:instrText') {
-                // instrText must be inside a field (depth > 0) and before the separator
-                if (depth === 0 || pastSeparatorAtDepth[depth])
-                    return false;
+export function splitStories(documentXml, footnotesXmls, endnotesXmls) {
+    const stories = [{ label: 'document', xml: documentXml }];
+    const collectEntries = (sidecars, entryTag, labelPrefix) => {
+        for (let s = 0; s < sidecars.length; s++) {
+            const sidecarXml = sidecars[s];
+            if (!sidecarXml)
+                continue;
+            const doc = parseXml(sidecarXml);
+            const entries = doc.getElementsByTagName(entryTag);
+            for (let i = 0; i < entries.length; i++) {
+                const entry = entries[i];
+                const id = entry.getAttribute('w:id') ?? String(i);
+                stories.push({
+                    label: `${labelPrefix}[${s}]:${id}`,
+                    xml: serializer.serializeToString(entry),
+                });
             }
-            if (!scan(el))
-                return false;
         }
-        return true;
-    }
-    return scan(root);
+    };
+    collectEntries(footnotesXmls, 'w:footnote', 'footnote');
+    collectEntries(endnotesXmls, 'w:endnote', 'endnote');
+    return stories;
 }
-function evaluateSafetyChecks(originalTextForRoundTrip, revisedTextForRoundTrip, originalBookmarkDiagnostics, revisedBookmarkDiagnostics, candidateXml) {
+function evaluateSafetyChecks(originalTextForRoundTrip, revisedTextForRoundTrip, originalBookmarkDiagnostics, revisedBookmarkDiagnostics, candidateXml, auxiliarySidecars) {
     const acceptedXml = acceptAllChanges(candidateXml);
     const rejectedXml = rejectAllChanges(candidateXml);
     const acceptedText = extractTextWithParagraphs(acceptedXml);
@@ -289,11 +279,28 @@ function evaluateSafetyChecks(originalTextForRoundTrip, revisedTextForRoundTrip,
     const rejectTextComparison = compareTexts(originalTextForRoundTrip, rejectedText);
     const acceptBookmarksOk = bookmarkDiagnosticsSemanticallyEqual(revisedBookmarkDiagnostics, acceptedBookmarkDiagnostics);
     const rejectBookmarksOk = bookmarkDiagnosticsSemanticallyEqual(originalBookmarkDiagnostics, rejectedBookmarkDiagnostics);
-    // Validate field structure: after accept-all and reject-all, every
-    // w:instrText must be inside a proper field sequence (between fldChar
-    // begin and fldChar separate). Orphaned instrText renders as visible
-    // text in Word.
-    const fieldStructureOk = validateFieldStructure(acceptedXml) && validateFieldStructure(rejectedXml);
+    // Validate field structure per-story. Each footnote/endnote entry is its own
+    // ECMA-376 story; a complex field that crosses a story boundary breaks
+    // Word's field state machine even when global begin/end counts balance.
+    // Sidecars from BOTH archives are validated because Step 12's auxiliary-part
+    // merge picks its base and source archives by reconstruction mode (inplace
+    // base = revised; rebuild base = original) and validating only one side
+    // would miss field issues that would still ship in the merged result.
+    // `acceptAllChanges` / `rejectAllChanges` only transform document.xml, so
+    // the sidecar set is identical for both transforms.
+    const acceptedStories = splitStories(acceptedXml, auxiliarySidecars.footnotesXmls, auxiliarySidecars.endnotesXmls);
+    const rejectedStories = splitStories(rejectedXml, auxiliarySidecars.footnotesXmls, auxiliarySidecars.endnotesXmls);
+    // Issue #217 conformance gate on the COMBINED output: w:fldChar MUST NOT
+    // appear inside <w:del>. ECMA-376 Part 4 § 17.16.5 makes this fatal for
+    // Word's field state machine. The full validateFieldStructure check is run
+    // on the accept/reject projections (per-story); on the combined view we
+    // only gate the strict no-fldChar-in-del rule because some legacy emit
+    // paths (e.g. delInstrText inside <w:moveFrom>) are non-conformant in shape
+    // but out of scope for #217.
+    const combinedNoFldCharInDel = !hasFldCharInsideDel(candidateXml);
+    const fieldStructureOk = combinedNoFldCharInDel &&
+        validateFieldStructure(acceptedStories) &&
+        validateFieldStructure(rejectedStories);
     const checks = {
         acceptText: acceptTextComparison.normalizedIdentical,
         rejectText: rejectTextComparison.normalizedIdentical,
@@ -369,12 +376,36 @@ export async function compareDocumentsAtomizer(original, revised, options = {})
     // Step 1: Load DOCX archives
     const originalArchive = await DocxArchive.load(original);
     const revisedArchive = await DocxArchive.load(revised);
+    // Step 1b: Resolve auxiliary ID collisions. When both sides define
+    // different content under the same comment/footnote/endnote w:id or the
+    // same comment paraId, rewrite the revised side so no anchor or ancillary
+    // row in the merged output can bind to the other document's definition.
+    // Must run before any document.xml extraction so every downstream step sees
+    // the rewritten archive.
+    await renumberCollidingAuxiliaryIds(originalArchive, revisedArchive);
+    await restampCollidingCommentParaIds(originalArchive, revisedArchive);
     // Step 2: Extract document.xml
     const originalXml = await originalArchive.getDocumentXml();
     const revisedXml = await revisedArchive.getDocumentXml();
     // Extract numbering.xml if available
     const originalNumberingXml = await originalArchive.getNumberingXml() ?? undefined;
     const revisedNumberingXml = await revisedArchive.getNumberingXml() ?? undefined;
+    // Extract footnote/endnote sidecars from BOTH archives for per-story
+    // field-closure validation (issue #212). Step 12 picks the base archive by
+    // reconstruction mode (inplace = revised, rebuild = original) and merges
+    // missing referenced entries from the opposite archive. Validating both
+    // archives' sidecars covers the union of entries that could ship without
+    // having to duplicate the merge logic at safety-check time.
+    const [originalFootnotesXml, originalEndnotesXml, revisedFootnotesXml, revisedEndnotesXml,] = await Promise.all([
+        originalArchive.getFile('word/footnotes.xml'),
+        originalArchive.getFile('word/endnotes.xml'),
+        revisedArchive.getFile('word/footnotes.xml'),
+        revisedArchive.getFile('word/endnotes.xml'),
+    ]);
+    const auxiliarySidecars = {
+        footnotesXmls: [originalFootnotesXml, revisedFootnotesXml],
+        endnotesXmls: [originalEndnotesXml, revisedEndnotesXml],
+    };
     const originalPart = {
         uri: 'word/document.xml',
         contentType: 'application/vnd.openxmlformats-officedocument.wordprocessingml.document.main+xml',
@@ -383,8 +414,13 @@ export async function compareDocumentsAtomizer(original, revised, options = {})
         uri: 'word/document.xml',
         contentType: 'application/vnd.openxmlformats-officedocument.wordprocessingml.document.main+xml',
     };
-    const originalTextForRoundTrip = extractTextWithParagraphs(originalXml);
-    const revisedTextForRoundTrip = extractTextWithParagraphs(revisedXml);
+    // Project each input through the SAME accept/reject operation the candidate is
+    // checked under, so the round-trip comparison is like-for-like even when an
+    // input already carries its own tracked changes (pre-tracked w:ins / w:del,
+    // comment anchors, multi-author stacks). For a clean input these equal the raw
+    // extraction, so behavior on the common case is unchanged. (#347)
+    const originalTextForRoundTrip = extractTextWithParagraphs(rejectAllChanges(originalXml));
+    const revisedTextForRoundTrip = extractTextWithParagraphs(acceptAllChanges(revisedXml));
     const originalBookmarkDiagnostics = collectBookmarkDiagnostics(originalXml);
     const revisedBookmarkDiagnostics = collectBookmarkDiagnostics(revisedXml);
     const runComparisonPass = (atomizeOptions, outputMode) => {
@@ -445,7 +481,7 @@ export async function compareDocumentsAtomizer(original, revised, options = {})
         }
         return { mergedAtoms, newDocumentXml, outputMode };
     };
-    const evaluateRoundTripSafety = (candidateXml) => evaluateSafetyChecks(originalTextForRoundTrip, revisedTextForRoundTrip, originalBookmarkDiagnostics, revisedBookmarkDiagnostics, candidateXml);
+    const evaluateRoundTripSafety = (candidateXml) => evaluateSafetyChecks(originalTextForRoundTrip, revisedTextForRoundTrip, originalBookmarkDiagnostics, revisedBookmarkDiagnostics, candidateXml, auxiliarySidecars);
     let comparisonResult;
     let fallbackReason;
     let fallbackDiagnostics;
@@ -530,7 +566,7 @@ export async function compareDocumentsAtomizer(original, revised, options = {})
             comparisonResult = selected;
         }
         else {
-            comparisonResult = runComparisonPass(undefined, 'rebuild');
+            comparisonResult = runComparisonPass({ atomizeParagraphLevelMarkers: true }, 'rebuild');
             fallbackReason = 'round_trip_safety_check_failed';
             fallbackDiagnostics = {
                 attempts: failedAttempts,
@@ -538,34 +574,56 @@ export async function compareDocumentsAtomizer(original, revised, options = {})
         }
     }
     else {
-        comparisonResult = runComparisonPass(undefined, 'rebuild');
+        comparisonResult = runComparisonPass({ atomizeParagraphLevelMarkers: true }, 'rebuild');
+    }
+    // Rebuild output gets the same safety screening as inplace attempts, whether
+    // rebuild was requested directly or reached via inplace fallback. Rebuild is
+    // the terminal strategy, so failures are surfaced in diagnostics rather than
+    // blocking the output.
+    // @see https://github.com/UseJunior/safe-docx/issues/226
+    let rebuildSafetyDiagnostics;
+    if (comparisonResult.outputMode === 'rebuild') {
+        const safety = evaluateRoundTripSafety(comparisonResult.newDocumentXml);
+        if (!safety.safe) {
+            rebuildSafetyDiagnostics = {
+                checks: safety.checks,
+                failedChecks: safety.failedChecks,
+                failureDetails: safety.failureDetails,
+                firstDiffSummary: safety.failureSummary,
+            };
+        }
     }
     const { mergedAtoms, newDocumentXml } = comparisonResult;
     // Step 12: Clone appropriate archive and update document.xml.
     // Use the revised archive only for true inplace output.
     const baseArchive = comparisonResult.outputMode === 'inplace' ? revisedArchive : originalArchive;
+    // The merge source is the *opposite* archive from the base: inplace pulls
+    // deleted-but-still-referenced definitions from the original, rebuild pulls
+    // added-but-still-referenced definitions from the revised. Without this,
+    // rebuild output ships dangling references when the original lacks an
+    // auxiliary part that the revised side introduced (issue #94).
+    const mergeSourceArchive = comparisonResult.outputMode === 'inplace' ? originalArchive : revisedArchive;
     const resultArchive = await baseArchive.clone();
+    maybeCaptureEmittedDocumentXml(newDocumentXml);
     resultArchive.setDocumentXml(newDocumentXml);
-    // Step 12b: For inplace mode, merge auxiliary part definitions (footnotes,
-    // endnotes, comments) from the original document. Inplace reconstruction
-    // inserts deleted content that may reference definitions not present in the
-    // revised archive.
-    if (comparisonResult.outputMode === 'inplace') {
-        const mergeResults = new Map();
-        for (const descriptor of AUXILIARY_PARTS) {
-            const result = await mergeAuxiliaryPartDefinitions(originalArchive, resultArchive, newDocumentXml, descriptor);
-            if (result.mergedIds.size > 0) {
-                mergeResults.set(descriptor.label, result);
-            }
-        }
-        // Post-merge hook for comment ancillary parts
-        if (mergeResults.has('comment')) {
-            await mergeCommentAncillaryParts(originalArchive, resultArchive, mergeResults.get('comment'));
-        }
+    // Step 12b: Merge auxiliary part definitions (footnotes, endnotes, comments).
+    // Reconstruction may insert content (deleted in inplace, added in rebuild)
+    // whose definitions are missing from the base archive.
+    for (const descriptor of AUXILIARY_PARTS) {
+        await mergeAuxiliaryPartDefinitions(mergeSourceArchive, resultArchive, newDocumentXml, descriptor);
+    }
+    // Comment-specific post-pass: walk reply threads via commentsExtended.xml.
+    // Gated on root comment IDs in the *result* document (not on what the
+    // generic merge appended), so the pass runs even when the original already
+    // contains the root and revised only adds replies under it (issue #108).
+    // Comments anchored on footnote/endnote text count as roots too.
+    const rootCommentIds = await collectStoryReferenceIds(resultArchive, newDocumentXml, 'w:commentReference', null);
+    if (rootCommentIds.size > 0) {
+        await mergeCommentAncillaryParts(mergeSourceArchive, resultArchive, rootCommentIds);
     }
     // Step 13: Save result and compute stats
     const resultBuffer = await resultArchive.save();
-    const stats = computeStats(mergedAtoms);
+    const stats = computeAtomizerStats(mergedAtoms);
     return {
         document: resultBuffer,
         stats,
@@ -574,37 +632,29 @@ export async function compareDocumentsAtomizer(original, revised, options = {})
         reconstructionModeUsed: comparisonResult.outputMode,
         fallbackReason,
         fallbackDiagnostics,
+        rebuildSafetyDiagnostics,
     };
 }
-const AUXILIARY_PARTS = [
-    {
-        label: 'footnote',
-        partPath: 'word/footnotes.xml',
-        referenceTag: 'w:footnoteReference',
-        entryTag: 'w:footnote',
-        rootTag: 'w:footnotes',
-        contentType: 'application/vnd.openxmlformats-officedocument.wordprocessingml.footnotes+xml',
-        relationshipType: 'http://schemas.openxmlformats.org/officeDocument/2006/relationships/footnotes',
-    },
-    {
-        label: 'endnote',
-        partPath: 'word/endnotes.xml',
-        referenceTag: 'w:endnoteReference',
-        entryTag: 'w:endnote',
-        rootTag: 'w:endnotes',
-        contentType: 'application/vnd.openxmlformats-officedocument.wordprocessingml.endnotes+xml',
-        relationshipType: 'http://schemas.openxmlformats.org/officeDocument/2006/relationships/endnotes',
-    },
-    {
-        label: 'comment',
-        partPath: 'word/comments.xml',
-        referenceTag: 'w:commentReference',
-        entryTag: 'w:comment',
-        rootTag: 'w:comments',
-        contentType: 'application/vnd.openxmlformats-officedocument.wordprocessingml.comments+xml',
-        relationshipType: 'http://schemas.openxmlformats.org/officeDocument/2006/relationships/comments',
-    },
-];
+/**
+ * Collect reference IDs across every result story that can host anchors: the
+ * merged document.xml plus the result archive's footnote/endnote parts (Word
+ * allows comments anchored on note text). `excludePartPath` skips the part
+ * whose own definitions are being merged — entries can't reference
+ * themselves.
+ */
+async function collectStoryReferenceIds(resultArchive, documentXml, referenceTag, excludePartPath) {
+    const ids = collectReferenceIds(documentXml, referenceTag);
+    for (const storyPath of ['word/footnotes.xml', 'word/endnotes.xml']) {
+        if (storyPath === excludePartPath)
+            continue;
+        const storyXml = await resultArchive.getFile(storyPath);
+        if (!storyXml)
+            continue;
+        for (const id of collectReferenceIds(storyXml, referenceTag))
+            ids.add(id);
+    }
+    return ids;
+}
 /**
  * Collect reference IDs from document.xml using DOM parsing.
  */
@@ -619,43 +669,33 @@ function collectReferenceIds(documentXml, referenceTag) {
     }
     return ids;
 }
-/**
- * Parse an auxiliary part and extract entry elements by ID.
- */
-function parseEntries(xml, entryTag) {
-    const doc = parseXml(xml);
-    const entries = new Map();
-    const elements = doc.getElementsByTagName(entryTag);
-    for (let i = 0; i < elements.length; i++) {
-        const el = elements[i];
-        const id = el.getAttribute('w:id');
-        if (id)
-            entries.set(id, el);
-    }
-    return { doc, entries };
-}
-const serializer = new XMLSerializer();
 /**
  * Merge auxiliary part definitions (footnotes, endnotes, comments) from the
- * original archive into the result archive. When inplace mode inserts deleted
- * content, the corresponding definitions must exist in the auxiliary part.
+ * source archive into the result archive. The source archive is whichever
+ * side reconstruction may have introduced references to: original in inplace
+ * mode (deleted-but-referenced definitions), revised in rebuild mode
+ * (added-but-referenced definitions).
  */
-async function mergeAuxiliaryPartDefinitions(originalArchive, resultArchive, documentXml, descriptor) {
+async function mergeAuxiliaryPartDefinitions(sourceArchive, resultArchive, documentXml, descriptor) {
     const result = { mergedIds: new Set(), createdPart: false };
-    const referencedIds = collectReferenceIds(documentXml, descriptor.referenceTag);
+    // Anchors may live in the merged body or on note text in the result's
+    // footnote/endnote stories. AUXILIARY_PARTS merges notes before comments,
+    // so by the comment pass the note stories already carry any merged-in
+    // comment anchors.
+    const referencedIds = await collectStoryReferenceIds(resultArchive, documentXml, descriptor.referenceTag, descriptor.partPath);
     if (referencedIds.size === 0)
         return result;
-    const originalPartXml = await originalArchive.getFile(descriptor.partPath);
-    if (!originalPartXml)
+    const sourcePartXml = await sourceArchive.getFile(descriptor.partPath);
+    if (!sourcePartXml)
         return result;
     const resultPartXml = await resultArchive.getFile(descriptor.partPath);
-    const originalParsed = parseEntries(originalPartXml, descriptor.entryTag);
+    const sourceParsed = parseEntries(sourcePartXml, descriptor.entryTag);
     const resultParsed = resultPartXml ? parseEntries(resultPartXml, descriptor.entryTag) : null;
     // Find missing entries: referenced in document.xml but not in result
     const missingElements = [];
     for (const id of referencedIds) {
-        if (!(resultParsed?.entries.has(id)) && originalParsed.entries.has(id)) {
-            missingElements.push(originalParsed.entries.get(id));
+        if (!(resultParsed?.entries.has(id)) && sourceParsed.entries.has(id)) {
+            missingElements.push(sourceParsed.entries.get(id));
             result.mergedIds.add(id);
         }
     }
@@ -673,27 +713,33 @@ async function mergeAuxiliaryPartDefinitions(originalArchive, resultArchive, doc
         }
     }
     else {
-        // Create part from scratch: clone root from original, insert missing entries
-        const newDoc = parseXml(originalPartXml);
+        // Create part from scratch: clone root from merge source, drop every
+        // non-reserved entry, then append the missing referenced ones.
+        // Reserved entries are footnote/endnote separators identified by
+        // w:type="separator" / w:type="continuationSeparator" — Word expects
+        // them to exist and they don't carry user content. Filtering by w:type
+        // (not by magic w:id values) keeps this robust across authoring tools.
+        const newDoc = parseXml(sourcePartXml);
         const rootEl = newDoc.getElementsByTagName(descriptor.rootTag)[0];
         if (rootEl) {
-            // Remove all existing entries — we only want the missing ones
             const existingEntries = rootEl.getElementsByTagName(descriptor.entryTag);
             const toRemove = [];
             for (let i = 0; i < existingEntries.length; i++) {
-                toRemove.push(existingEntries[i]);
+                const el = existingEntries[i];
+                const type = el.getAttribute('w:type');
+                if (type !== 'separator' && type !== 'continuationSeparator') {
+                    toRemove.push(el);
+                }
             }
             for (const el of toRemove) {
                 rootEl.removeChild(el);
             }
-            // Add back only the missing entries
             for (const el of missingElements) {
                 const imported = newDoc.importNode(el, true);
                 rootEl.appendChild(imported);
             }
             resultArchive.setFile(descriptor.partPath, serializer.serializeToString(newDoc));
             result.createdPart = true;
-            // Bootstrap OPC metadata for the newly created part
             await ensureOpcMetadata(resultArchive, descriptor);
         }
     }
@@ -765,52 +811,154 @@ async function ensureOpcMetadata(archive, descriptor) {
 // Comment Ancillary Parts Merging
 // =============================================================================
 /**
- * After merging comment definitions, copy related entries from
- * commentsExtended.xml and people.xml for author fidelity and reply threading.
+ * Walk the comment reply graph from each root referenced in the result
+ * document, merging reply <w:comment> entries, their commentsExtended.xml
+ * threading entries, and people.xml authors. Replies have no
+ * <w:commentReference> in document.xml — they're discoverable only via
+ * w15:paraIdParent in commentsExtended.xml. Without this expansion, rebuild
+ * mode silently drops reply threads (issue #108).
  */
-async function mergeCommentAncillaryParts(originalArchive, resultArchive, commentMergeResult) {
-    // Collect authors and paraIds from the merged comment entries
-    const originalCommentsXml = await originalArchive.getFile('word/comments.xml');
-    if (!originalCommentsXml)
+async function mergeCommentAncillaryParts(sourceArchive, resultArchive, rootCommentIds) {
+    const sourceCommentsXml = await sourceArchive.getFile('word/comments.xml');
+    if (!sourceCommentsXml)
         return;
-    const origDoc = parseXml(originalCommentsXml);
-    const mergedAuthors = new Set();
-    const mergedParaIds = new Set();
-    const commentEls = origDoc.getElementsByTagName('w:comment');
-    for (let i = 0; i < commentEls.length; i++) {
-        const el = commentEls[i];
+    const sourceDoc = parseXml(sourceCommentsXml);
+    // Build full source comment maps. Canonical paraId is the first <w:p>
+    // child's w14:paraId, matching getCommentElParaId() in primitives/comments.ts.
+    const commentById = new Map();
+    const paraIdByCommentId = new Map();
+    const commentIdByParaId = new Map();
+    const authorByCommentId = new Map();
+    const allCommentEls = sourceDoc.getElementsByTagName('w:comment');
+    for (let i = 0; i < allCommentEls.length; i++) {
+        const el = allCommentEls[i];
         const id = el.getAttribute('w:id');
-        if (!id || !commentMergeResult.mergedIds.has(id))
+        if (!id)
             continue;
+        commentById.set(id, el);
         const author = el.getAttribute('w:author');
         if (author)
-            mergedAuthors.add(author);
-        // Collect paraIds from <w:p> children inside the comment
-        const paras = el.getElementsByTagName('w:p');
-        for (let j = 0; j < paras.length; j++) {
-            const p = paras[j];
-            const paraId = p.getAttribute('w14:paraId');
-            if (paraId)
-                mergedParaIds.add(paraId);
-        }
-    }
-    // Merge commentsExtended.xml entries matching merged paraIds
-    await mergeCommentsExtended(originalArchive, resultArchive, mergedParaIds);
-    // Merge people.xml entries matching merged authors
-    await mergePeople(originalArchive, resultArchive, mergedAuthors);
+            authorByCommentId.set(id, author);
+        const firstP = el.getElementsByTagName('w:p')[0];
+        const paraId = firstP?.getAttribute('w14:paraId');
+        if (paraId) {
+            paraIdByCommentId.set(id, paraId);
+            commentIdByParaId.set(paraId, id);
+        }
+    }
+    // Seed inclusion sets from the root IDs that appear in the result document.
+    const includedCommentIds = new Set();
+    const includedParaIds = new Set();
+    const includedAuthors = new Set();
+    for (const id of rootCommentIds) {
+        if (!commentById.has(id))
+            continue;
+        includedCommentIds.add(id);
+        const pid = paraIdByCommentId.get(id);
+        if (pid)
+            includedParaIds.add(pid);
+        const author = authorByCommentId.get(id);
+        if (author)
+            includedAuthors.add(author);
+    }
+    // BFS over commentsExtended.xml's paraIdParent graph from each included
+    // root paraId. Skip entries that don't resolve to a real source comment so
+    // we never pull in dangling commentEx/people without a backing definition.
+    const sourceExtendedXml = await sourceArchive.getFile('word/commentsExtended.xml');
+    if (sourceExtendedXml) {
+        const exDoc = parseXml(sourceExtendedXml);
+        const exEls = exDoc.getElementsByTagName('w15:commentEx');
+        const childrenOf = new Map();
+        for (let i = 0; i < exEls.length; i++) {
+            const ex = exEls[i];
+            const childPid = ex.getAttribute('w15:paraId');
+            const parentPid = ex.getAttribute('w15:paraIdParent');
+            if (!childPid || !parentPid)
+                continue;
+            const arr = childrenOf.get(parentPid);
+            if (arr)
+                arr.push(childPid);
+            else
+                childrenOf.set(parentPid, [childPid]);
+        }
+        const queue = [...includedParaIds];
+        while (queue.length > 0) {
+            const pid = queue.shift();
+            const children = childrenOf.get(pid);
+            if (!children)
+                continue;
+            for (const childPid of children) {
+                if (includedParaIds.has(childPid))
+                    continue;
+                const childCommentId = commentIdByParaId.get(childPid);
+                if (!childCommentId)
+                    continue;
+                includedParaIds.add(childPid);
+                includedCommentIds.add(childCommentId);
+                const author = authorByCommentId.get(childCommentId);
+                if (author)
+                    includedAuthors.add(author);
+                queue.push(childPid);
+            }
+        }
+    }
+    // Append any reply <w:comment> definitions still missing from result.
+    // The generic merge already added roots when needed; we add the replies
+    // (and any roots not yet present in the result, defensively).
+    await mergeMissingCommentDefinitions(resultArchive, commentById, includedCommentIds);
+    // Merge commentsExtended and people for the expanded set.
+    await mergeCommentsExtended(sourceArchive, resultArchive, includedParaIds);
+    await mergePeople(sourceArchive, resultArchive, includedAuthors);
 }
-async function mergeCommentsExtended(originalArchive, resultArchive, mergedParaIds) {
+/**
+ * Append any source <w:comment> definitions in `includedCommentIds` that
+ * aren't already in result/word/comments.xml. Mirrors the append-with-importNode
+ * pattern used by mergeCommentsExtended below.
+ */
+async function mergeMissingCommentDefinitions(resultArchive, commentById, includedCommentIds) {
+    if (includedCommentIds.size === 0)
+        return;
+    const resultXml = await resultArchive.getFile('word/comments.xml');
+    if (!resultXml) {
+        // If result has no comments.xml at all, the generic merge would have
+        // bootstrapped it for any included root. Nothing to do here.
+        return;
+    }
+    const resultDoc = parseXml(resultXml);
+    const rootEl = resultDoc.documentElement;
+    const existingIds = new Set();
+    const existing = rootEl.getElementsByTagName('w:comment');
+    for (let i = 0; i < existing.length; i++) {
+        const id = existing[i].getAttribute('w:id');
+        if (id)
+            existingIds.add(id);
+    }
+    let appended = false;
+    for (const id of includedCommentIds) {
+        if (existingIds.has(id))
+            continue;
+        const sourceEl = commentById.get(id);
+        if (!sourceEl)
+            continue;
+        rootEl.appendChild(resultDoc.importNode(sourceEl, true));
+        appended = true;
+    }
+    if (appended) {
+        resultArchive.setFile('word/comments.xml', serializer.serializeToString(resultDoc));
+    }
+}
+async function mergeCommentsExtended(sourceArchive, resultArchive, mergedParaIds) {
     if (mergedParaIds.size === 0)
         return;
-    const originalXml = await originalArchive.getFile('word/commentsExtended.xml');
-    if (!originalXml)
+    const sourceXml = await sourceArchive.getFile('word/commentsExtended.xml');
+    if (!sourceXml)
         return;
-    const origDoc = parseXml(originalXml);
-    const origEntries = origDoc.getElementsByTagName('w15:commentEx');
+    const sourceDoc = parseXml(sourceXml);
+    const sourceEntries = sourceDoc.getElementsByTagName('w15:commentEx');
     // Collect entries whose paraId matches a merged comment's paragraph
     const entriesToMerge = [];
-    for (let i = 0; i < origEntries.length; i++) {
-        const el = origEntries[i];
+    for (let i = 0; i < sourceEntries.length; i++) {
+        const el = sourceEntries[i];
         const paraId = el.getAttribute('w15:paraId');
         if (paraId && mergedParaIds.has(paraId)) {
             entriesToMerge.push(el);
@@ -818,11 +966,10 @@ async function mergeCommentsExtended(originalArchive, resultArchive, mergedParaI
     }
     if (entriesToMerge.length === 0)
         return;
-    let resultXml = await resultArchive.getFile('word/commentsExtended.xml');
+    const resultXml = await resultArchive.getFile('word/commentsExtended.xml');
     if (resultXml) {
         const resultDoc = parseXml(resultXml);
         const rootEl = resultDoc.documentElement;
-        // Check existing paraIds to avoid duplicates
         const existingParaIds = new Set();
         const existing = rootEl.getElementsByTagName('w15:commentEx');
         for (let i = 0; i < existing.length; i++) {
@@ -837,21 +984,57 @@ async function mergeCommentsExtended(originalArchive, resultArchive, mergedParaI
             }
         }
         resultArchive.setFile('word/commentsExtended.xml', serializer.serializeToString(resultDoc));
+        return;
     }
-    // If commentsExtended.xml doesn't exist in result, we don't create it —
-    // the file is optional and its absence won't cause crashes.
+    // Bootstrap: result lacks commentsExtended.xml but the merged comments
+    // depend on it for reply threading / done state. Clone the source's root
+    // (preserves namespaces), drop non-matching entries, then add OPC metadata.
+    const newDoc = parseXml(sourceXml);
+    const newRoot = newDoc.documentElement;
+    const allEntries = newRoot.getElementsByTagName('w15:commentEx');
+    const toRemove = [];
+    for (let i = 0; i < allEntries.length; i++) {
+        const el = allEntries[i];
+        const paraId = el.getAttribute('w15:paraId');
+        if (!paraId || !mergedParaIds.has(paraId))
+            toRemove.push(el);
+    }
+    for (const el of toRemove)
+        newRoot.removeChild(el);
+    resultArchive.setFile('word/commentsExtended.xml', serializer.serializeToString(newDoc));
+    await ensureOpcMetadata(resultArchive, COMMENTS_EXTENDED_DESCRIPTOR);
 }
-async function mergePeople(originalArchive, resultArchive, mergedAuthors) {
+const COMMENTS_EXTENDED_DESCRIPTOR = {
+    label: 'commentsExtended',
+    partPath: 'word/commentsExtended.xml',
+    referenceTag: '',
+    entryTag: 'w15:commentEx',
+    rootTag: 'w15:commentsEx',
+    contentType: 'application/vnd.ms-word.commentsExtended+xml',
+    relationshipType: 'http://schemas.microsoft.com/office/2011/relationships/commentsExtended',
+    idBearingTags: [], // keyed by w15:paraId, not w:id
+};
+const PEOPLE_DESCRIPTOR = {
+    label: 'people',
+    partPath: 'word/people.xml',
+    referenceTag: '',
+    entryTag: 'w15:person',
+    rootTag: 'w15:people',
+    contentType: 'application/vnd.ms-word.people+xml',
+    relationshipType: 'http://schemas.microsoft.com/office/2011/relationships/people',
+    idBearingTags: [], // keyed by w15:author, not w:id
+};
+async function mergePeople(sourceArchive, resultArchive, mergedAuthors) {
     if (mergedAuthors.size === 0)
         return;
-    const originalXml = await originalArchive.getFile('word/people.xml');
-    if (!originalXml)
+    const sourceXml = await sourceArchive.getFile('word/people.xml');
+    if (!sourceXml)
         return;
-    const origDoc = parseXml(originalXml);
-    const origPersons = origDoc.getElementsByTagName('w15:person');
+    const sourceDoc = parseXml(sourceXml);
+    const sourcePersons = sourceDoc.getElementsByTagName('w15:person');
     const personsToMerge = [];
-    for (let i = 0; i < origPersons.length; i++) {
-        const el = origPersons[i];
+    for (let i = 0; i < sourcePersons.length; i++) {
+        const el = sourcePersons[i];
         const author = el.getAttribute('w15:author');
         if (author && mergedAuthors.has(author)) {
             personsToMerge.push(el);
@@ -859,11 +1042,10 @@ async function mergePeople(originalArchive, resultArchive, mergedAuthors) {
     }
     if (personsToMerge.length === 0)
         return;
-    let resultXml = await resultArchive.getFile('word/people.xml');
+    const resultXml = await resultArchive.getFile('word/people.xml');
     if (resultXml) {
         const resultDoc = parseXml(resultXml);
         const rootEl = resultDoc.documentElement;
-        // Check existing authors to avoid duplicates
         const existingAuthors = new Set();
         const existing = rootEl.getElementsByTagName('w15:person');
         for (let i = 0; i < existing.length; i++) {
@@ -878,51 +1060,101 @@ async function mergePeople(originalArchive, resultArchive, mergedAuthors) {
             }
         }
         resultArchive.setFile('word/people.xml', serializer.serializeToString(resultDoc));
+        return;
     }
-    // If people.xml doesn't exist in result, we don't create it —
-    // the file is optional and its absence won't cause crashes.
+    // Bootstrap: result lacks people.xml. Clone source root (preserves
+    // namespaces), remove non-matching authors, then add OPC metadata.
+    const newDoc = parseXml(sourceXml);
+    const newRoot = newDoc.documentElement;
+    const allPersons = newRoot.getElementsByTagName('w15:person');
+    const toRemove = [];
+    for (let i = 0; i < allPersons.length; i++) {
+        const el = allPersons[i];
+        const author = el.getAttribute('w15:author');
+        if (!author || !mergedAuthors.has(author))
+            toRemove.push(el);
+    }
+    for (const el of toRemove)
+        newRoot.removeChild(el);
+    resultArchive.setFile('word/people.xml', serializer.serializeToString(newDoc));
+    await ensureOpcMetadata(resultArchive, PEOPLE_DESCRIPTOR);
+}
+const fallbackParagraphStatsKeys = new WeakMap();
+let nextFallbackParagraphStatsKey = 0;
+function paragraphStatsKey(atom) {
+    if (atom.paragraphIndex !== undefined) {
+        return `${atom.part.uri}:${atom.paragraphIndex}`;
+    }
+    const pAncestor = atom.ancestorElements.find((a) => a.tagName === 'w:p');
+    if (!pAncestor)
+        return undefined;
+    let key = fallbackParagraphStatsKeys.get(pAncestor);
+    if (!key) {
+        key = `${atom.part.uri}:paragraph-ref:${nextFallbackParagraphStatsKey++}`;
+        fallbackParagraphStatsKeys.set(pAncestor, key);
+    }
+    return key;
 }
 /**
  * Compute comparison statistics from merged atoms.
+ *
+ * Range counts are contiguous same-status runs in the merged atom stream, scoped
+ * to a paragraph. Atom counts remain available under explicit names for callers
+ * that need the old granular benchmark signal.
  */
-function computeStats(mergedAtoms) {
+export function computeAtomizerStats(mergedAtoms) {
     const reconstructionStats = computeReconstructionStats(mergedAtoms);
-    // Count unique paragraphs for modifications
-    // A modification is when we have both deleted and inserted atoms in the same paragraph
-    const modifiedParagraphs = new Set();
-    let currentParagraph = '';
-    let hasDeleted = false;
-    let hasInserted = false;
+    let insertedRanges = 0;
+    let deletedRanges = 0;
+    let formatChanges = 0;
+    let previousRangeStatus = null;
+    let previousRangeParagraph;
+    const paragraphs = new Map();
     for (const atom of mergedAtoms) {
-        // Detect paragraph boundaries
-        const pAncestor = atom.ancestorElements.find((a) => a.tagName === 'w:p');
-        const paragraphId = pAncestor
-            ? `${atom.part.uri}:${atom.ancestorElements.indexOf(pAncestor)}`
-            : '';
-        if (paragraphId !== currentParagraph) {
-            // Check previous paragraph
-            if (currentParagraph && hasDeleted && hasInserted) {
-                modifiedParagraphs.add(currentParagraph);
+        const paragraphKey = paragraphStatsKey(atom);
+        const status = atom.correlationStatus;
+        const rangeStatus = status === CorrelationStatus.Inserted ||
+            status === CorrelationStatus.Deleted ||
+            status === CorrelationStatus.FormatChanged
+            ? status
+            : null;
+        if (rangeStatus) {
+            if (rangeStatus !== previousRangeStatus || paragraphKey !== previousRangeParagraph) {
+                if (rangeStatus === CorrelationStatus.Inserted)
+                    insertedRanges++;
+                if (rangeStatus === CorrelationStatus.Deleted)
+                    deletedRanges++;
+                if (rangeStatus === CorrelationStatus.FormatChanged)
+                    formatChanges++;
             }
-            currentParagraph = paragraphId;
-            hasDeleted = false;
-            hasInserted = false;
+            previousRangeStatus = rangeStatus;
+            previousRangeParagraph = paragraphKey;
         }
-        if (atom.correlationStatus === CorrelationStatus.Deleted) {
-            hasDeleted = true;
+        else {
+            previousRangeStatus = null;
+            previousRangeParagraph = undefined;
         }
-        else if (atom.correlationStatus === CorrelationStatus.Inserted) {
-            hasInserted = true;
+        if (paragraphKey && (status === CorrelationStatus.Deleted || status === CorrelationStatus.Inserted)) {
+            const flags = paragraphs.get(paragraphKey) ?? { hasDeleted: false, hasInserted: false };
+            if (status === CorrelationStatus.Deleted)
+                flags.hasDeleted = true;
+            if (status === CorrelationStatus.Inserted)
+                flags.hasInserted = true;
+            paragraphs.set(paragraphKey, flags);
         }
     }
-    // Check last paragraph
-    if (currentParagraph && hasDeleted && hasInserted) {
-        modifiedParagraphs.add(currentParagraph);
-    }
+    const modifiedParagraphs = Array.from(paragraphs.values()).filter((flags) => flags.hasDeleted && flags.hasInserted).length;
     return {
-        insertions: reconstructionStats.insertions,
-        deletions: reconstructionStats.deletions,
-        modifications: modifiedParagraphs.size + reconstructionStats.formatChanges,
+        insertions: insertedRanges,
+        deletions: deletedRanges,
+        modifications: modifiedParagraphs,
+        insertedRanges,
+        deletedRanges,
+        insertedAtoms: reconstructionStats.insertions,
+        deletedAtoms: reconstructionStats.deletions,
+        modifiedParagraphs,
+        formatChanges,
+        formatChangeAtoms: reconstructionStats.formatChanges,
     };
 }
 //# sourceMappingURL=pipeline.js.map