@ansonlai/docx-redline-js 0.8.3 → 0.9.0

package/services/document-operation-mutations.js

@@ -3,15 +3,27 @@
  */
 
 import { createSerializer, parseOoxmlSafe } from '../adapters/xml-adapter.js';
+import {
+    resolveListDiagnosticPolicy,
+    detectUnboundListMarker,
+    buildUnboundListMarkerDiagnostic,
+    detectRequestedListFormatMismatch,
+    buildListFormatDiagnostic,
+    findUnknownParagraphFormatKeys,
+    PARAGRAPH_FORMAT_REVISION_CONFLICT,
+    PARAGRAPH_NUMBERING_NOT_FOUND,
+    buildUnknownParagraphFormatDiagnostic,
+    diagnosticWarningText
+} from './list-conversion-diagnostics.js';
+import { getAllReferencedNumIdElements, getCurrentChild } from '../core/current-properties.js';
 import { findReconstructionParagraphRange } from '../engine/reconstruction-mapper.js';
 import { createRevisionMetadata } from '../core/types.js';
 import { containsTrackedChanges, getTrackedChangeAuthors, createWordElement, withOoxmlSourceType } from '../core/word-xml.js';
 import {
-    markParagraphMarkInserted,
-    markParagraphMarkDeleted,
     snapshotAndAttachRPrChange,
     snapshotAndAttachPPrChange
 } from '../engine/run-builders.js';
+import { markParagraphInserted, markParagraphDeleted } from '../engine/paragraph-mark-revisions.js';
 import {
     applyCharacterFormatToRPr,
     checkRunPropertiesChanged,
@@ -42,6 +54,7 @@ import {
     getParagraphId,
     createParagraphFingerprint,
     isMarkdownTableText,
+    normalizeWhitespaceForTargeting,
     findContainingWordElement,
     resolveTargetParagraphWithSnapshot as resolveTargetParagraphWithSnapshotShared,
     resolveParagraphRangeByRefs,
@@ -70,11 +83,19 @@ import {
 import {
     reserveNextNumberingIdPair,
     remapNumberingPayloadForDocument,
-    reuseSourceListNumbering,
     overwriteParagraphNumIds,
     extractFirstParagraphNumId,
     buildExplicitDecimalMultilevelNumberingXml
 } from './numbering-helpers.js';
+import {
+    allocateNumberingForReplacement,
+    checkNumberingBinding,
+    continueBatchListSequence,
+    mergeNumberingParts
+} from './numbering-allocation.js';
+import { convertPlainParagraphsToList, numIdIsLive, sequenceMapOf } from './list-format-mutation.js';
+import { changeListParagraphsFormat, joinListParagraphs } from './list-format-change.js';
+import { LIST_FORMAT_UNCHANGED, normalizeListFormatRequest } from './list-format.js';
 import {
     extractReplacementNodesFromOoxml,
     normalizeBodySectionOrderStandalone
@@ -82,9 +103,12 @@ import {
 import { prepareRevisionAllocator } from './document-operation-session.js';
 import {
     buildExplicitRangeInsertionEntries,
+    deriveParagraphThenTableAppend,
     deriveSingleParagraphListAdjacencyInsertion,
     deriveSingleParagraphPlainAdjacencyInsertion
 } from './operation-heuristics.js';
+import { generateTableOoxml } from './table-reconciliation.js';
+import { preprocessMarkdown } from '../pipeline/markdown-processor.js';
 import { resolveTargetFromCapture, ensureParagraphIdsOnImportedNode } from './capture-engine.js';
 import {
     acceptTrackedChangesInOoxml,
@@ -320,6 +344,52 @@ function resolveTargetParagraph(xmlDoc, targetText, targetRef, opType, runtimeCo
     return resolved;
 }
 
+/**
+ * Zero-based document-order positions `{ from, to }` of an operation's target (and its targetEnd, when it
+ * is a range), resolved against the current DOM without mutating, capturing or warning. Used by the
+ * revision fidelity verifier to scope accept-first baselines and the accepted-intent check exactly.
+ * Returns null when the target or its end cannot be resolved.
+ */
+export function resolveOperationSourceRange(xmlDoc, targetText, targetRef, targetEndRef, runtimeContext, options = {}) {
+    const quiet = { ...options, _resolutionCapture: null, onInfo: () => { }, onWarn: () => { } };
+    const positionOf = paragraph => {
+        if (!paragraph) return null;
+        const position = getDocumentParagraphNodes(xmlDoc).indexOf(paragraph);
+        return position >= 0 ? position : null;
+    };
+    let start;
+    try {
+        start = resolveTargetParagraph(xmlDoc, targetText, targetRef, 'redline', runtimeContext, quiet);
+    } catch {
+        return null;
+    }
+    const from = positionOf(start?.paragraph);
+    if (from === null) return null;
+    const descriptor = options.targetEndDescriptor || null;
+    let endParagraph = null;
+    if (options._compiledSourceEndId && options._sourceTargetRegistry) {
+        endParagraph = options._sourceTargetRegistry.resolve(options._compiledSourceEndId, xmlDoc)?.paragraph || null;
+    } else if (descriptor) {
+        endParagraph = resolveTargetParagraph(xmlDoc, descriptor.text || '', descriptor.index, 'redline', runtimeContext, {
+            ...quiet,
+            targetDescriptor: descriptor,
+            _compiledSourceId: null
+        })?.paragraph || null;
+    } else if (targetEndRef) {
+        endParagraph = resolveTargetParagraphWithSnapshotShared(xmlDoc, {
+            targetRef: targetEndRef,
+            opType: 'redline',
+            targetRefSnapshot: runtimeContext?.targetRefSnapshot || null,
+            onInfo: () => { },
+            onWarn: () => { }
+        })?.paragraph || null;
+    } else {
+        return { from, to: from };
+    }
+    const to = positionOf(endParagraph);
+    return to !== null && to >= from ? { from, to } : null;
+}
+
 function extractReplacementNodes(outputOxml) {
     return extractReplacementNodesFromOoxml(outputOxml);
 }
@@ -426,7 +496,7 @@ function buildInsertedListParagraph(xmlDoc, anchorParagraph, entry, revisionMeta
     // remove the list paragraph itself on Reject All instead of leaving an
     // empty bullet or number behind.
     if (generateRedlines) {
-        markParagraphMarkInserted(xmlDoc, paragraph, author);
+        markParagraphInserted(paragraph, { author });
     }
 
     const run = createWordElement(xmlDoc, 'w:r');
@@ -518,7 +588,7 @@ function buildFallbackInsertedPlainParagraph(xmlDoc, text, revisionMetadata, aut
 
     if (generateRedlines) {
         if (options.trackParagraphMark === true) {
-            markParagraphMarkInserted(xmlDoc, paragraph, author);
+            markParagraphInserted(paragraph, { author });
         }
         const metadata = revisionMetadata || createRevisionMetadata(author, xmlDoc, 'ins');
         const ins = createWordElement(xmlDoc, 'w:ins');
@@ -559,7 +629,7 @@ function wrapParagraphContentInInsertion(xmlDoc, paragraph, revisionMetadata, au
     if (pPr) wrappedParagraph.appendChild(pPr);
     if (options.paragraphId) wrappedParagraph.setAttributeNS(NS_W14, 'w14:paraId', options.paragraphId);
     if (options.trackParagraphMark === true) {
-        markParagraphMarkInserted(xmlDoc, wrappedParagraph, author);
+        markParagraphInserted(wrappedParagraph, { author });
     }
 
     const ins = createWordElement(xmlDoc, 'w:ins');
@@ -620,8 +690,9 @@ async function buildInsertedPlainParagraph(xmlDoc, anchorParagraph, text, revisi
 function collectNumberingIdsFromNodes(nodes) {
     const ids = new Set();
     for (const node of nodes || []) {
-        const numIdNodes = Array.from(node?.getElementsByTagNameNS?.('*', 'numId') || []);
-        for (const numIdNode of numIdNodes) {
+        // Deliberately historical-inclusive: the numbering-part merge must define every id the content can
+        // reference, including ids held only by pPrChange snapshots (Reject restores them).
+        for (const numIdNode of getAllReferencedNumIdElements(node)) {
             const val = numIdNode.getAttribute('w:val') || numIdNode.getAttribute('val');
             if (val != null && val !== '') {
                 ids.add(String(val));
@@ -1379,20 +1450,6 @@ async function tryExplicitDecimalHeaderListConversion({
     if (!strippedContent) return null;
 
     onInfo('[List] Applying explicit numeric header conversion with direct list binding.');
-    const redlineResult = await applyRedlineToOxml(
-        serializer.serializeToString(targetParagraph),
-        currentParagraphText,
-        strippedContent,
-        {
-            author,
-            generateRedlines,
-            _revisionIdAllocator: revisionIdAllocator
-        }
-    );
-    if (!redlineResult?.hasChanges || typeof redlineResult?.oxml !== 'string') return null;
-
-    const extracted = extractReplacementNodes(redlineResult.oxml);
-    const replacementNodes = extracted.replacementNodes;
     const numberingAction = resolveSingleLineListFallbackNumberingAction(
         explicitPlan,
         runtimeContext?.listFallbackSequenceState || null
@@ -1423,6 +1480,22 @@ async function tryExplicitDecimalHeaderListConversion({
         onInfo(`[List] Using isolated explicit-start numbering (start ${explicitStart}, numId ${appliedNumId}, abstractNumId ${reservedPair.abstractNumId}).`);
     }
 
+    // Redline only after numbering reservation succeeded so an aborted conversion never records receipt revisions.
+    const redlineResult = await applyRedlineToOxml(
+        serializer.serializeToString(targetParagraph),
+        currentParagraphText,
+        strippedContent,
+        {
+            author,
+            generateRedlines,
+            _revisionIdAllocator: revisionIdAllocator
+        }
+    );
+    if (!redlineResult?.hasChanges || typeof redlineResult?.oxml !== 'string') return null;
+
+    const extracted = extractReplacementNodes(redlineResult.oxml);
+    const replacementNodes = extracted.replacementNodes;
+
     if (explicitPlan.numberingKey && runtimeContext?.listFallbackSharedNumIdByKey instanceof Map) {
         runtimeContext.listFallbackSharedNumIdByKey.delete(explicitPlan.numberingKey);
     }
@@ -1445,7 +1518,8 @@ async function tryExplicitDecimalHeaderListConversion({
         numId: appliedNumId,
         ilvl: 0,
         clearParagraphPropertyChanges: true,
-        removeListPropertyNode: true
+        removeListPropertyNode: true,
+        trackPropertyChange: generateRedlines ? { author, revisionIdAllocator } : null
     });
 
     const parent = targetParagraph.parentNode;
@@ -1472,6 +1546,145 @@ async function tryExplicitDecimalHeaderListConversion({
     };
 }
 
+const FALLBACK_STYLE_TO_LIST_FORMAT = Object.freeze({
+    upperAlpha: 'upperLetter',
+    lowerAlpha: 'lowerLetter',
+    upperRoman: 'upperRoman',
+    lowerRoman: 'lowerRoman',
+    bullet: 'bullet'
+});
+
+/**
+ * Text-equal marker conversion ("A. Header" -> "A. Header") of a plain paragraph, done in place through the
+ * list-format convert-plain core: the typed marker becomes a tracked deletion and the binding a tracked pPrChange
+ * in the same paragraph. This replaces the whole-paragraph delete/insert for letters, roman numerals and bullets,
+ * which lost w14:paraId, bookmarks and direct formatting and reviewed as one deleted and one inserted line. Shapes
+ * the core refuses (marker inside a hyperlink, field or revision; changed marker punctuation) keep the structural
+ * fallback below, which is still reject-exact.
+ */
+function tryInPlaceMarkerListConversion({
+    xmlDoc,
+    serializer,
+    documentXml,
+    operationSession,
+    targetParagraph,
+    currentParagraphText,
+    modifiedText,
+    author,
+    runtimeContext,
+    revisionIdAllocator,
+    generateRedlines = true,
+    onInfo = () => { },
+    options = {}
+}) {
+    if (!targetParagraph || getParagraphListInfo(targetParagraph)) return null;
+    if (normalizeWhitespaceForTargeting(currentParagraphText) !== normalizeWhitespaceForTargeting(modifiedText)) return null;
+    const plan = buildSingleLineListStructuralFallbackPlan({
+        oxml: serializer.serializeToString(targetParagraph),
+        originalText: currentParagraphText,
+        modifiedText,
+        allowExistingList: false
+    });
+    const format = plan ? FALLBACK_STYLE_TO_LIST_FORMAT[plan.numberingStyle] : null;
+    if (!format) return null;
+    const allParagraphs = getDocumentParagraphNodes(xmlDoc);
+    const conversion = convertPlainParagraphsToList(xmlDoc, [targetParagraph], normalizeListFormatRequest({
+        mode: 'convert-plain',
+        format,
+        strip: 'marker'
+    }), {
+        author: author || getDefaultAuthor(),
+        generateRedlines,
+        revisionIdAllocator,
+        runtimeContext,
+        stylesXml: runtimeContext?.stylesXml || options.stylesXml || null,
+        numberingXml: runtimeContext?.numberingXml || options.numberingXml || null,
+        paragraphIndexOf: paragraph => allParagraphs.indexOf(paragraph) + 1
+    });
+    if (!conversion.ok) {
+        onInfo(`[List] In-place marker conversion declined (${conversion.error.code}); using the structural fallback.`);
+        return null;
+    }
+    onInfo(`[List] Converted typed ${format} marker in place (numId ${conversion.items[0].numId}).`);
+    ensureParagraphIdsOnImportedNode(targetParagraph, operationSession);
+    options?._mutationLiveNodes?.push(targetParagraph);
+    for (const numId of conversion.allocatedNumIds) operationSession?.receiptCollector?.recordNumbering(numId);
+    normalizeBodySectionOrder(xmlDoc);
+    return {
+        documentXml: completedDocumentXml(xmlDoc, serializer, documentXml, operationSession),
+        hasChanges: true,
+        numberingXml: conversion.numberingXml
+    };
+}
+
+// CT_PPrBase child order (ECMA-376), used to place copied direct properties on the new list paragraph.
+const PPR_CHILD_ORDER = [
+    'pStyle', 'keepNext', 'keepLines', 'pageBreakBefore', 'framePr', 'widowControl', 'numPr', 'suppressLineNumbers',
+    'pBdr', 'shd', 'tabs', 'suppressAutoHyphens', 'kinsoku', 'wordWrap', 'overflowPunct', 'topLinePunct',
+    'autoSpaceDE', 'autoSpaceDN', 'bidi', 'adjustRightInd', 'snapToGrid', 'spacing', 'ind', 'contextualSpacing',
+    'mirrorIndents', 'suppressOverlap', 'jc', 'textDirection', 'textAlignment', 'textboxTightWrap', 'outlineLvl',
+    'divId', 'cnfStyle', 'rPr', 'sectPr', 'pPrChange'
+];
+const PPR_NOT_COPIED = new Set(['pStyle', 'numPr', 'rPr', 'sectPr', 'pPrChange']);
+
+/**
+ * The list structural fallback rebuilds the paragraph as a tracked-deleted source paragraph plus a new list
+ * paragraph from text alone. The deleted paragraph must keep the source `pPr` (Reject All restores it, so the
+ * Reject All verifier sees no property change), the new paragraph carries the source's direct properties that the
+ * list binding does not own (`keepNext`, spacing, alignment...), and the paragraph that survives Accept All
+ * keeps the source `w14:paraId` / `w14:textId`.
+ */
+function restoreSourceIdentityAndPropertiesOnFallback(xmlDoc, replacementNodes, targetParagraph) {
+    const paragraphs = replacementNodes.filter(node => node?.nodeType === 1 && node.localName === 'p');
+    const markOf = (paragraph, kind) => {
+        const rPr = getDirectWordChild(getDirectWordChild(paragraph, 'pPr'), 'rPr');
+        return !!rPr && !!getDirectWordChild(rPr, kind);
+    };
+    const deleted = paragraphs.find(paragraph => markOf(paragraph, 'del'));
+    const created = paragraphs.find(paragraph => !markOf(paragraph, 'del'));
+    const sourcePPr = getDirectWordChild(targetParagraph, 'pPr');
+    if (deleted && sourcePPr) {
+        const restored = xmlDoc.importNode(sourcePPr, true);
+        const mark = getDirectWordChild(getDirectWordChild(deleted, 'pPr'), 'rPr');
+        const delMarker = mark && getDirectWordChild(mark, 'del');
+        if (delMarker) {
+            let rPr = getDirectWordChild(restored, 'rPr');
+            if (!rPr) {
+                rPr = createWordElement(xmlDoc, 'w:rPr');
+                const successor = getDirectWordChild(restored, 'sectPr') || getDirectWordChild(restored, 'pPrChange');
+                restored.insertBefore(rPr, successor || null);
+            }
+            Array.from(rPr.childNodes).forEach(child => {
+                if (child.nodeType === 1 && (child.localName === 'ins' || child.localName === 'del')) rPr.removeChild(child);
+            });
+            rPr.appendChild(xmlDoc.importNode(delMarker, true));
+            deleted.replaceChild(restored, getDirectWordChild(deleted, 'pPr'));
+        }
+    }
+    if (created && sourcePPr) {
+        let createdPPr = getDirectWordChild(created, 'pPr');
+        if (!createdPPr) {
+            createdPPr = createWordElement(xmlDoc, 'w:pPr');
+            created.insertBefore(createdPPr, created.firstChild || null);
+        }
+        for (const child of Array.from(sourcePPr.childNodes)) {
+            if (child.nodeType !== 1 || PPR_NOT_COPIED.has(child.localName)) continue;
+            if (getDirectWordChild(createdPPr, child.localName)) continue;
+            const rank = PPR_CHILD_ORDER.indexOf(child.localName);
+            const successor = Array.from(createdPPr.childNodes).find(node => (
+                node.nodeType === 1 && PPR_CHILD_ORDER.indexOf(node.localName) > rank
+            ));
+            createdPPr.insertBefore(xmlDoc.importNode(child, true), successor || null);
+        }
+    }
+    if (created) {
+        for (const name of ['paraId', 'textId']) {
+            const value = targetParagraph.getAttributeNS?.(NS_W14, name) || targetParagraph.getAttribute?.(`w14:${name}`);
+            if (value) created.setAttributeNS(NS_W14, `w14:${name}`, value);
+        }
+    }
+}
+
 async function trySingleParagraphListStructuralFallback({
     xmlDoc,
     serializer,
@@ -1513,7 +1726,11 @@ async function trySingleParagraphListStructuralFallback({
     const extracted = extractReplacementNodes(fallbackResult.oxml);
     let replacementNodes = extracted.replacementNodes;
     let numberingXml = extracted.numberingXml || fallbackResult?.numberingXml || null;
-    const hasExplicitStartAt = Number.isInteger(fallbackPlan?.startAt) && fallbackPlan.startAt > 0;
+    const hasPositiveStart = Number.isInteger(fallbackPlan?.startAt) && fallbackPlan.startAt > 0;
+    // Only decimal starts use the explicit multilevel-decimal definition. Letter and roman starts (`C.`, `iv.`)
+    // keep the generated definition, whose level-0 startOverride is already applied by the fallback executor.
+    const hasExplicitStartAt = hasPositiveStart && fallbackPlan?.numberingStyle === 'decimal';
+    const hasNonDecimalStart = hasPositiveStart && !hasExplicitStartAt;
     const numberingKey = fallbackResult?.listStructuralFallbackKey || fallbackPlan?.numberingKey || null;
     const numberingAction = resolveSingleLineListFallbackNumberingAction(
         fallbackPlan,
@@ -1569,7 +1786,8 @@ async function trySingleParagraphListStructuralFallback({
                 numId: explicitNumIdForBinding,
                 ilvl: 0,
                 clearParagraphPropertyChanges: true,
-                removeListPropertyNode: true
+                removeListPropertyNode: true,
+                trackPropertyChange: generateRedlines ? { author, revisionIdAllocator } : null
             });
         }
     } else {
@@ -1584,7 +1802,23 @@ async function trySingleParagraphListStructuralFallback({
         );
     }
 
-    if (!hasExplicitStartAt && runtimeContext?.listFallbackSharedNumIdByKey instanceof Map) {
+    if (!hasExplicitStartAt && numberingXml && runtimeContext) {
+        // Separate operations of one batch that convert continuing markers (`A.` then `B.`) join one numbering
+        // instance, through the same sequence state `list-format convert-plain` uses.
+        const batch = continueBatchListSequence({
+            numberingXml,
+            replacementNodes,
+            sequence: sequenceMapOf(runtimeContext),
+            isNumIdLive: numId => numIdIsLive(xmlDoc, numId)
+        });
+        if (batch) {
+            replacementNodes = batch.replacementNodes;
+            numberingXml = null;
+            onInfo(`[List] Continuing batch list numbering (numId ${batch.numId}).`);
+        }
+    }
+
+    if (!hasExplicitStartAt && !hasNonDecimalStart && runtimeContext?.listFallbackSharedNumIdByKey instanceof Map) {
         const sharedNumId = numberingKey ? runtimeContext.listFallbackSharedNumIdByKey.get(numberingKey) : null;
         if (sharedNumId) {
             overwriteParagraphNumIds(replacementNodes, sharedNumId);
@@ -1601,6 +1835,7 @@ async function trySingleParagraphListStructuralFallback({
 
     const parent = targetParagraph.parentNode;
     if (!parent) return null;
+    if (generateRedlines) restoreSourceIdentityAndPropertiesOnFallback(xmlDoc, replacementNodes, targetParagraph);
     for (const node of replacementNodes) {
         const imported = xmlDoc.importNode(node, true);
         ensureParagraphIdsOnImportedNode(imported, operationSession);
@@ -1623,6 +1858,43 @@ async function trySingleParagraphListStructuralFallback({
     };
 }
 
+function listDiagnosticFailure(documentXml, diagnostic) {
+    const { severity: _severity, ...error } = diagnostic;
+    return { documentXml, hasChanges: false, numberingXml: null, status: 'error', error };
+}
+
+function listDiagnosticFields(diagnostics) {
+    return diagnostics.length > 0
+        ? { diagnostics, warnings: diagnostics.map(diagnosticWarningText) }
+        : {};
+}
+
+/**
+ * Compares the markers of a list edit with the numbering definition the source paragraphs keep.
+ * Returns a diagnostic (warning or error severity per policy) or null.
+ */
+function diagnoseListFormatNotApplied({ sourceParagraphs, modifiedText, runtimeContext, options }) {
+    const policy = resolveListDiagnosticPolicy(options);
+    if (policy === 'off') return null;
+    const sourceNumberingXml = runtimeContext?.numberingIdState?.sourceNumberingXml;
+    if (!sourceNumberingXml) return null;
+    const sourceItems = [];
+    for (const paragraph of sourceParagraphs || []) {
+        const info = getParagraphListInfo(paragraph);
+        if (info) sourceItems.push({ text: getParagraphText(paragraph), numId: info.numId, ilvl: info.ilvl });
+    }
+    const found = detectRequestedListFormatMismatch({ modifiedText, sourceItems, sourceNumberingXml });
+    if (!found) return null;
+    return buildListFormatDiagnostic(found.mismatch, {
+        policy,
+        numId: found.numId,
+        level: found.level,
+        marker: found.marker,
+        targetText: found.targetText,
+        operationIndex: options?._operationIndex
+    });
+}
+
 export async function applyToParagraphByExactText(documentXml, targetText, modifiedText, author, targetRef = null, targetEndRef = null, runtimeContext = null, options = {}) {
     const generateRedlines = options.generateRedlines !== false;
     const onInfo = typeof options?.onInfo === 'function' ? options.onInfo : () => { };
@@ -1798,7 +2070,7 @@ export async function applyToParagraphByExactText(documentXml, targetText, modif
         && !(hasRevisions && existingPolicy === 'merge-same-author')
     ) {
         if (generateRedlines) {
-            markParagraphMarkDeleted(xmlDoc, targetParagraph, author, createRevisionMetadata(author, xmlDoc));
+            markParagraphDeleted(targetParagraph, { author });
             options?._mutationLiveNodes?.push(targetParagraph);
         } else {
             options?._mutationRemovedNodes?.push(targetParagraph);
@@ -1843,7 +2115,31 @@ export async function applyToParagraphByExactText(documentXml, targetText, modif
     let effectiveModifiedText = synthesizedTableMarkdown || modifiedText;
     const useTableScope = !!containingTable && isMarkdownTableText(effectiveModifiedText);
     const isTableMarkdownEdit = isMarkdownTableText(effectiveModifiedText);
-    const explicitRangeParagraphs = targetEndRef
+    // A targetEnd given as a compact handle (paragraphId + fingerprint, no numeric index) has no targetEndRef;
+    // its range comes from the batch-compiled end or the end descriptor, never silently dropped.
+    let compiledEndRange = null;
+    if (!targetEndRef && (options._compiledSourceEndId || options.targetEndDescriptor)) {
+        const rangeResolution = resolveOperationParagraphRange(xmlDoc, targetText, targetRef, targetEndRef, 'redline', runtimeContext, {
+            ...options,
+            _resolutionCapture: null
+        });
+        if (rangeResolution.error) {
+            return { documentXml, hasChanges: false, status: 'error', error: rangeResolution.error };
+        }
+        if (rangeResolution.paragraphs.length > 1) {
+            const container = rangeResolution.paragraphs[0].parentNode;
+            if (rangeResolution.paragraphs.some(paragraph => paragraph.parentNode !== container)) {
+                return {
+                    documentXml,
+                    hasChanges: false,
+                    status: 'error',
+                    error: { code: 'TARGET_RANGE_INVALID', message: 'A redline target range must stay inside one container (body, table cell, header, ...); it spans a table or other container boundary. Edit the paragraphs on each side separately.' }
+                };
+            }
+            compiledEndRange = rangeResolution.paragraphs;
+        }
+    }
+    const explicitRangeParagraphs = compiledEndRange ? compiledEndRange : targetEndRef
         ? resolveParagraphRangeByRefs(xmlDoc, targetRef, targetEndRef, {
             opType: 'redline',
             targetRefSnapshot: runtimeContext?.targetRefSnapshot || null,
@@ -1861,6 +2157,13 @@ export async function applyToParagraphByExactText(documentXml, targetText, modif
             for (const entry of insertionEntries) {
                 onInfo(`[List] Explicit-range insertion: ilvl=${entry.ilvl}, markerType=${entry.markerType}, text="${String(entry.text || '').slice(0, 80)}${String(entry.text || '').length > 80 ? '…' : ''}"`);
             }
+            const rangeFormatDiagnostic = diagnoseListFormatNotApplied({
+                sourceParagraphs: explicitRangeParagraphs,
+                modifiedText: effectiveModifiedText,
+                runtimeContext,
+                options
+            });
+            if (rangeFormatDiagnostic?.severity === 'error') return listDiagnosticFailure(documentXml, rangeFormatDiagnostic);
             const applied = applyExplicitRangeListInsertions({
                 xmlDoc,
                 explicitRangeParagraphs,
@@ -1872,7 +2175,8 @@ export async function applyToParagraphByExactText(documentXml, targetText, modif
                 return {
                     documentXml: completedDocumentXml(xmlDoc, serializer, documentXml, operationSession),
                     hasChanges: true,
-                    numberingXml: null
+                    numberingXml: null,
+                    ...listDiagnosticFields(rangeFormatDiagnostic ? [rangeFormatDiagnostic] : [])
                 };
             }
         }
@@ -1945,6 +2249,105 @@ export async function applyToParagraphByExactText(documentXml, targetText, modif
         };
     }
 
+    // Retained paragraph followed by a Markdown table: keep the source paragraph in place (so its own
+    // content, formatting and revisions are untouched), apply any requested inline formatting to it,
+    // and insert the table after it instead of rewriting the paragraph as a deletion plus a copy.
+    const tableAppendCandidate = (
+        !useTableScope
+        && !hasExplicitRangeScope
+        && !targetListInfo
+        && !containingTable
+        && !targetEndRef
+    )
+        ? deriveParagraphThenTableAppend(effectiveModifiedText)
+        : null;
+    const tableAppendParagraph = tableAppendCandidate
+        ? preprocessMarkdown(tableAppendCandidate.paragraphMarkdown)
+        : null;
+    if (
+        tableAppendCandidate
+        && normalizeWhitespaceForTargeting(tableAppendParagraph.cleanText) === normalizeWhitespaceForTargeting(currentParagraphText)
+    ) {
+        const tableData = parseMarkdownTable(tableAppendCandidate.tableText);
+        if (tableData.headers.length > 0 || tableData.rows.length > 0) {
+            onInfo('[Table] Applying retained-paragraph table append heuristic.');
+            const parent = targetParagraph.parentNode;
+            if (!parent) throw new Error('Target paragraph has no parent for table append');
+            const followingNode = targetParagraph.nextSibling;
+            if (tableAppendParagraph.formatHints.length > 0) {
+                const formatted = await applyRedlineToOxml(
+                    serializer.serializeToString(targetParagraph),
+                    currentParagraphText || targetText,
+                    tableAppendCandidate.paragraphMarkdown,
+                    {
+                        author,
+                        generateRedlines,
+                        existingRevisions: options.existingRevisions || 'merge-same-author',
+                        structuredContent: false,
+                        _revisionIdAllocator: revisionIdAllocator
+                    }
+                );
+                if (formatted?.status === 'error') {
+                    return {
+                        documentXml,
+                        hasChanges: false,
+                        numberingXml: null,
+                        status: 'error',
+                        error: formatted.error
+                    };
+                }
+                if (formatted?.hasChanges) {
+                    if (typeof formatted.oxml !== 'string') {
+                        throw new Error('Reconciliation engine did not return OOXML for a changed paragraph format');
+                    }
+                    for (const node of extractReplacementNodes(formatted.oxml).replacementNodes) {
+                        const imported = xmlDoc.importNode(node, true);
+                        ensureParagraphIdsOnImportedNode(imported, operationSession);
+                        options?._mutationLiveNodes?.push(parent.insertBefore(imported, targetParagraph));
+                    }
+                    options?._mutationRemovedNodes?.push(targetParagraph);
+                    parent.removeChild(targetParagraph);
+                }
+            }
+            const tableOoxml = generateTableOoxml(tableData, {
+                generateRedlines,
+                author,
+                revisionIdAllocator,
+                trackAsBlock: true
+            });
+            for (const node of extractReplacementNodes(tableOoxml).replacementNodes) {
+                options?._mutationLiveNodes?.push(parent.insertBefore(xmlDoc.importNode(node, true), followingNode));
+            }
+            // Word cannot end the body (or a container) with a table: it would add an untracked paragraph
+            // there that Reject All leaves behind. Supply the paragraph ourselves with a tracked-inserted
+            // mark so Reject All removes it and the source paragraph count is restored.
+            // Skip whitespace/comment nodes of pretty-printed documents when deciding what follows the table.
+            let followingElement = followingNode;
+            while (followingElement && followingElement.nodeType !== 1) followingElement = followingElement.nextSibling;
+            const endsContainer = !followingElement
+                || (followingElement.namespaceURI === NS_W && followingElement.localName === 'sectPr');
+            if (endsContainer) {
+                const trailing = createWordElement(xmlDoc, 'w:p');
+                const trailingPPr = clonePropertiesWithoutRevisionHistory(getDirectWordChild(targetParagraph, 'pPr'));
+                if (trailingPPr) {
+                    for (const child of Array.from(trailingPPr.childNodes)) {
+                        if (child.nodeType === 1 && ['sectPr', 'numPr'].includes(child.localName)) trailingPPr.removeChild(child);
+                    }
+                    trailing.appendChild(trailingPPr);
+                }
+                if (generateRedlines) markParagraphInserted(trailing, { author });
+                ensureParagraphIdsOnImportedNode(trailing, operationSession);
+                options?._mutationLiveNodes?.push(parent.insertBefore(trailing, followingNode));
+            }
+            normalizeBodySectionOrder(xmlDoc);
+            return {
+                documentXml: completedDocumentXml(xmlDoc, serializer, documentXml, operationSession),
+                hasChanges: true,
+                numberingXml: null
+            };
+        }
+    }
+
     const plainAdjacencyInsertionCandidate = (
         !bypassSingleParagraphHeuristics
         && !useTableScope
@@ -1998,6 +2401,13 @@ export async function applyToParagraphByExactText(documentXml, targetText, modif
         })
         : null;
     if (insertionOnlyPlan && insertionOnlyPlan.entries.length > 0) {
+        const insertionFormatDiagnostic = diagnoseListFormatNotApplied({
+            sourceParagraphs: [targetParagraph],
+            modifiedText: effectiveModifiedText,
+            runtimeContext,
+            options
+        });
+        if (insertionFormatDiagnostic?.severity === 'error') return listDiagnosticFailure(documentXml, insertionFormatDiagnostic);
         onInfo(`[List] Applying insertion-only list redline heuristic (${insertionOnlyPlan.entries.length} new item(s)).`);
         for (const entry of insertionOnlyPlan.entries) {
             onInfo(`[List] Insertion entry resolved: ilvl=${entry.ilvl}, markerType=${entry.markerType}, text="${String(entry.text || '').slice(0, 80)}${String(entry.text || '').length > 80 ? '…' : ''}"`);
@@ -2022,7 +2432,8 @@ export async function applyToParagraphByExactText(documentXml, targetText, modif
         return {
             documentXml: completedDocumentXml(xmlDoc, serializer, documentXml, operationSession),
             hasChanges: true,
-            numberingXml: null
+            numberingXml: null,
+            ...listDiagnosticFields(insertionFormatDiagnostic ? [insertionFormatDiagnostic] : [])
         };
     }
 
@@ -2038,6 +2449,7 @@ export async function applyToParagraphByExactText(documentXml, targetText, modif
         effectiveModifiedText = listScopeEdit.modifiedText;
     }
 
+    let unboundMarkerDiagnostic = null;
     if (!bypassSingleParagraphHeuristics && !useTableScope && !useListScope && !hasExplicitRangeScope) {
         const explicitHeaderListConversion = await tryExplicitDecimalHeaderListConversion({
             xmlDoc,
@@ -2056,6 +2468,23 @@ export async function applyToParagraphByExactText(documentXml, targetText, modif
         });
         if (explicitHeaderListConversion) return explicitHeaderListConversion;
 
+        const inPlaceConversion = tryInPlaceMarkerListConversion({
+            xmlDoc,
+            serializer,
+            documentXml,
+            operationSession,
+            targetParagraph,
+            currentParagraphText,
+            modifiedText: effectiveModifiedText,
+            author,
+            runtimeContext,
+            revisionIdAllocator,
+            generateRedlines,
+            onInfo,
+            options
+        });
+        if (inPlaceConversion) return inPlaceConversion;
+
         const listFallback = await trySingleParagraphListStructuralFallback({
             xmlDoc,
             serializer,
@@ -2072,6 +2501,25 @@ export async function applyToParagraphByExactText(documentXml, targetText, modif
             options
         });
         if (listFallback) return listFallback;
+
+        // Both structural fallbacks declined. A plain paragraph whose new text starts a list marker
+        // would be written as literal text: report that instead of returning a silent success.
+        const unboundPolicy = resolveListDiagnosticPolicy(options);
+        if (unboundPolicy !== 'off' && !targetListInfo) {
+            const requestedMarker = detectUnboundListMarker({
+                originalText: currentParagraphText,
+                modifiedText: effectiveModifiedText,
+                targetIsListItem: false
+            });
+            if (requestedMarker) {
+                unboundMarkerDiagnostic = buildUnboundListMarkerDiagnostic(requestedMarker, {
+                    policy: unboundPolicy,
+                    targetText: currentParagraphText,
+                    operationIndex: options?._operationIndex
+                });
+                if (unboundPolicy === 'error') return listDiagnosticFailure(documentXml, unboundMarkerDiagnostic);
+            }
+        }
     }
 
     const originalTextForApply = useListScope
@@ -2115,6 +2563,7 @@ export async function applyToParagraphByExactText(documentXml, targetText, modif
             explicitStructuredContent: options.explicitStructuredContent === true,
             pairReplacements: options.pairReplacements === true,
             insertionAffinity: options.insertionAffinity || null,
+            literalTextEdit: options.literalTextEdit === true,
             _revisionIdAllocator: revisionIdAllocator,
             _isolatedTableCell: useTableScope
         });
@@ -2138,18 +2587,16 @@ export async function applyToParagraphByExactText(documentXml, targetText, modif
     const extracted = extractReplacementNodes(result.oxml);
     let replacementNodes = removeListPackagingSentinel(extracted.replacementNodes, result.warnings);
     let numberingXml = extracted.numberingXml;
-    if (numberingXml && runtimeContext?.numberingIdState && !useTableScope) {
-        const sourceParagraphs = useListScope ? listScopeEdit.paragraphs : (explicitRangeParagraphs || [targetParagraph]);
-        const continued = reuseSourceListNumbering(numberingXml, replacementNodes, sourceParagraphs, runtimeContext.numberingIdState);
-        if (continued) {
-            replacementNodes = continued.replacementNodes;
-            numberingXml = null;
-        }
-    }
     if (numberingXml && runtimeContext?.numberingIdState) {
-        const normalizedNumbering = remapNumberingPayloadForDocument(numberingXml, replacementNodes, runtimeContext.numberingIdState);
-        replacementNodes = normalizedNumbering.replacementNodes;
-        numberingXml = normalizedNumbering.numberingXml;
+        const allocated = allocateNumberingForReplacement({
+            numberingXml,
+            replacementNodes,
+            sourceParagraphs: useListScope ? listScopeEdit.paragraphs : (explicitRangeParagraphs || [targetParagraph]),
+            numberingIdState: runtimeContext.numberingIdState,
+            allowContinueSource: !useTableScope
+        });
+        replacementNodes = allocated.replacementNodes;
+        numberingXml = allocated.numberingXml;
     }
     const scopeNodes = useTableScope
         ? [containingTable]
@@ -2191,7 +2638,10 @@ export async function applyToParagraphByExactText(documentXml, targetText, modif
         hasChanges: true,
         numberingXml,
         status: 'ok',
-        ...(Array.isArray(result.warnings) && result.warnings.length > 0 ? { warnings: result.warnings } : {})
+        ...(unboundMarkerDiagnostic ? {
+            diagnostics: [unboundMarkerDiagnostic],
+            warnings: [...(Array.isArray(result.warnings) ? result.warnings : []), diagnosticWarningText(unboundMarkerDiagnostic)]
+        } : (Array.isArray(result.warnings) && result.warnings.length > 0 ? { warnings: result.warnings } : {}))
     };
 }
 
@@ -2429,7 +2879,12 @@ export async function applyFormattingToParagraphByExactText(
     }
 
     const targetDescriptor = options.targetDescriptor;
-    const occurrence = targetDescriptor?.occurrence ?? null;
+    // `textOccurrence` is the dedicated in-paragraph selector. Legacy calls without it keep
+    // reading `target.occurrence` (which also selects the N-th matching paragraph).
+    const explicitTextOccurrence = Number.isInteger(options.textOccurrence) && options.textOccurrence > 0
+        ? options.textOccurrence
+        : null;
+    const occurrence = explicitTextOccurrence ?? targetDescriptor?.occurrence ?? null;
     let matchStart = -1;
     if (occurrence != null && occurrence > 0) {
         let count = 0;
@@ -2448,6 +2903,18 @@ export async function applyFormattingToParagraphByExactText(
         matchStart = fullParaText.indexOf(textToFormat);
     }
 
+    if (matchStart === -1 && explicitTextOccurrence != null && fullParaText.includes(textToFormat)) {
+        return {
+            documentXml,
+            hasChanges: false,
+            status: 'error',
+            error: {
+                code: 'PATCH_SOURCE_NOT_FOUND',
+                message: `Occurrence ${explicitTextOccurrence} of text to format was not found in target paragraph: "${textToFormat}".`
+            }
+        };
+    }
+
     if (matchStart === -1) {
         return {
             documentXml,
@@ -2581,13 +3048,63 @@ export async function applyParagraphFormatToParagraphByExactText(
         targetParagraph.insertBefore(pPr, targetParagraph.firstChild);
     }
 
+    const unknownPropertyKeys = findUnknownParagraphFormatKeys(properties);
+    const propertyDiagnostics = unknownPropertyKeys.length > 0
+        ? [buildUnknownParagraphFormatDiagnostic(unknownPropertyKeys)]
+        : [];
+    if (properties?.numbering) {
+        const binding = checkNumberingBinding(
+            runtimeContext?.numberingIdState,
+            properties.numbering.numId,
+            Number(properties.numbering.level) || 0
+        );
+        if (!binding.ok) {
+            return {
+                documentXml,
+                hasChanges: false,
+                status: 'error',
+                error: {
+                    code: PARAGRAPH_NUMBERING_NOT_FOUND,
+                    message: `${binding.message} paragraph-format.numbering binds to an existing list; it never creates one.`,
+                    field: 'properties.numbering',
+                    numId: Number(properties.numbering.numId),
+                    level: Number(properties.numbering.level) || 0,
+                    reason: binding.reason,
+                    recovery: {
+                        action: 'inspect_numbering',
+                        hint: 'Inspect a paragraph already in the target list and pass its list.numId and list.level. To start a new list, use a list-change/redline operation.'
+                    }
+                }
+            };
+        }
+    }
     const hasChanges = checkParagraphPropertiesChanged(pPr, properties);
     if (!hasChanges) {
-        return { documentXml, hasChanges: false, status: 'no-op' };
+        return { documentXml, hasChanges: false, status: 'no-op', ...listDiagnosticFields(propertyDiagnostics) };
     }
 
     if (generateRedlines) {
-        snapshotAndAttachPPrChange(xmlDoc, pPr, author || getDefaultAuthor());
+        const authorUsed = author || getDefaultAuthor();
+        const pendingChange = getCurrentChild(pPr, 'pPrChange');
+        const pendingAuthor = pendingChange?.getAttribute('w:author') ?? pendingChange?.getAttribute('author') ?? '';
+        if (pendingChange && pendingAuthor !== authorUsed) {
+            return {
+                documentXml,
+                hasChanges: false,
+                status: 'error',
+                error: {
+                    code: PARAGRAPH_FORMAT_REVISION_CONFLICT,
+                    message: `Target paragraph already has a pending paragraph-property change by "${pendingAuthor || 'unattributed'}". Overwriting its snapshot would change what Reject All restores.`,
+                    pendingAuthor,
+                    recovery: {
+                        action: 'resolve_pending_revision',
+                        hint: 'Ask the user to accept or reject the existing paragraph formatting change first; this tool does not resolve revisions by other reviewers.'
+                    }
+                }
+            };
+        }
+        // A same-author pending snapshot already records the earliest "before" state; keep it.
+        if (!pendingChange) snapshotAndAttachPPrChange(xmlDoc, pPr, authorUsed);
     }
 
     applyParagraphPropertiesToPPr(xmlDoc, pPr, properties);
@@ -2598,6 +3115,232 @@ export async function applyParagraphFormatToParagraphByExactText(
     return {
         documentXml: completedDocumentXml(xmlDoc, serializer, documentXml, operationSession),
         hasChanges: true,
-        status: 'ok'
+        status: 'ok',
+        ...listDiagnosticFields(propertyDiagnostics)
+    };
+}
+
+/**
+ * Resolves an operation's target range (target plus optional targetEnd) to paragraphs in document order, the
+ * same way restore does: batch-compiled source ids first, then legacy refs, then an end descriptor.
+ */
+function resolveOperationParagraphRange(xmlDoc, targetText, targetRef, targetEndRef, opType, runtimeContext, options) {
+    const resolved = resolveTargetParagraph(xmlDoc, targetText, targetRef, opType, runtimeContext, options);
+    if (resolved?.error || !resolved?.paragraph) {
+        return { error: resolved?.error || { code: 'TARGET_NOT_FOUND', message: 'Target paragraph not found.' } };
+    }
+    const first = resolved.paragraph;
+    const hasEnd = options._compiledSourceEndId || targetEndRef != null || options.targetEndDescriptor;
+    if (!hasEnd) return { paragraphs: [first] };
+    let paragraphs = null;
+    if (options._compiledSourceEndId || options.targetEndDescriptor) {
+        const endResolved = resolveTargetParagraph(
+            xmlDoc,
+            options.targetEndDescriptor?.text || '',
+            options._compiledSourceEndId ? targetEndRef : (options.targetEndDescriptor?.index ?? targetEndRef),
+            opType,
+            runtimeContext,
+            {
+                ...options,
+                ...(options.targetEndDescriptor ? { targetDescriptor: options.targetEndDescriptor } : {}),
+                _compiledSourceId: options._compiledSourceEndId || null,
+                _resolutionCapture: null
+            }
+        );
+        if (endResolved?.error) return { error: endResolved.error };
+        const all = endResolved?.paragraph ? getDocumentParagraphNodes(xmlDoc) : [];
+        const startIndex = all.indexOf(first);
+        const endIndex = all.indexOf(endResolved?.paragraph);
+        paragraphs = startIndex >= 0 && endIndex >= startIndex ? all.slice(startIndex, endIndex + 1) : null;
+    } else {
+        paragraphs = resolveParagraphRangeByRefs(xmlDoc, targetRef, targetEndRef, {
+            opType,
+            targetRefSnapshot: runtimeContext?.targetRefSnapshot || null,
+            onInfo: options.onInfo,
+            onWarn: options.onWarn
+        });
+    }
+    if (!Array.isArray(paragraphs) || paragraphs.length === 0 || paragraphs[0] !== first) {
+        return { error: { code: 'TARGET_RANGE_INVALID', message: 'targetEnd must resolve to the target paragraph or a paragraph after it.' } };
+    }
+    return { paragraphs };
+}
+
+/**
+ * `list-format` (`convert-plain`): binds plain paragraphs to a new list in place; see services/list-format-mutation.js.
+ */
+export async function applyListFormatToParagraphByExactText(
+    documentXml,
+    targetText,
+    list,
+    author,
+    targetRef = null,
+    targetEndRef = null,
+    runtimeContext = null,
+    options = {}
+) {
+    const generateRedlines = options.generateRedlines !== false;
+    const onInfo = typeof options?.onInfo === 'function' ? options.onInfo : () => { };
+    const onWarn = typeof options?.onWarn === 'function' ? options.onWarn : () => { };
+    const { serializer, xmlDoc, operationSession } = resolveMutationDocument(documentXml, options);
+    if (!xmlDoc) {
+        return { documentXml, hasChanges: false, status: 'error', error: { code: 'PARSE_ERROR', message: 'Could not parse document OOXML.' } };
+    }
+    const revisionIdAllocator = operationSession?.revisionIdAllocator || prepareRevisionAllocator(xmlDoc, options);
+    const range = resolveOperationParagraphRange(xmlDoc, targetText, targetRef, targetEndRef, 'list-format', runtimeContext, {
+        ...options,
+        onInfo,
+        onWarn
+    });
+    if (range.error) return { documentXml, hasChanges: false, status: 'error', error: range.error };
+    const paragraphs = range.paragraphs;
+    if (paragraphs.some(paragraph => paragraph.parentNode !== paragraphs[0].parentNode)) {
+        return {
+            documentXml,
+            hasChanges: false,
+            status: 'error',
+            error: {
+                code: 'TARGET_RANGE_INVALID',
+                message: 'A list-format range must stay inside one container (the body, or one table cell).'
+            }
+        };
+    }
+    const allParagraphs = getDocumentParagraphNodes(xmlDoc);
+    const request = normalizeListFormatRequest(list);
+    if (request.mode === 'change-format' || request.mode === 'join') {
+        return applyListRebinding(xmlDoc, paragraphs, request, {
+            documentXml, serializer, operationSession, runtimeContext, options, author, generateRedlines, onInfo, onWarn,
+            paragraphIndexOf: paragraph => {
+                const index = allParagraphs.indexOf(paragraph);
+                return index >= 0 ? index + 1 : null;
+            }
+        });
+    }
+    const conversion = convertPlainParagraphsToList(xmlDoc, paragraphs, request, {
+        author: author || getDefaultAuthor(),
+        generateRedlines,
+        revisionIdAllocator,
+        runtimeContext,
+        stylesXml: runtimeContext?.stylesXml || options.stylesXml || null,
+        numberingXml: runtimeContext?.numberingXml || options.numberingXml || null,
+        paragraphIndexOf: paragraph => allParagraphs.indexOf(paragraph) + 1
+    });
+    if (!conversion.ok) return { documentXml, hasChanges: false, status: 'error', error: conversion.error };
+
+    for (const item of conversion.items) {
+        ensureParagraphIdsOnImportedNode(item.paragraph, operationSession);
+        options?._mutationLiveNodes?.push(item.paragraph);
+    }
+    for (const numId of conversion.allocatedNumIds) operationSession?.receiptCollector?.recordNumbering(numId);
+    normalizeBodySectionOrder(xmlDoc);
+    onInfo(`[List] list-format convert-plain bound ${conversion.items.length} paragraph(s) as ${conversion.format} (numId ${[...new Set(conversion.items.map(item => item.numId))].join(', ')}).`);
+
+    return {
+        documentXml: completedDocumentXml(xmlDoc, serializer, documentXml, operationSession),
+        hasChanges: true,
+        status: 'ok',
+        numberingXml: conversion.numberingXml,
+        list: {
+            mode: 'convert-plain',
+            format: conversion.format,
+            level: conversion.level,
+            strip: conversion.strip,
+            items: conversion.items.map(item => ({
+                paragraphIndex: item.paragraphIndex,
+                paragraphId: getParagraphId(item.paragraph),
+                marker: item.marker,
+                value: item.value,
+                numId: item.numId
+            })),
+            skipped: conversion.skipped.map(item => ({ paragraphIndex: item.paragraphIndex, reason: item.reason }))
+        }
+    };
+}
+
+/**
+ * `list-format` `change-format` / `join`: rebinds existing list items (see services/list-format-change.js). The
+ * definitions are read from the source numbering part plus the parts earlier operations of this batch allocated,
+ * so a later operation can change a list an earlier one created or rebound.
+ */
+function applyListRebinding(xmlDoc, paragraphs, request, ctx) {
+    const { documentXml, serializer, operationSession, runtimeContext, options, author, generateRedlines, onInfo, paragraphIndexOf } = ctx;
+    const refused = error => ({ documentXml, hasChanges: false, status: 'error', error });
+    const sourceNumberingXml = runtimeContext?.numberingIdState?.sourceNumberingXml
+        || runtimeContext?.numberingXml
+        || options.numberingXml
+        || '';
+    const pendingParts = Array.isArray(operationSession?.numberingXmlParts) ? operationSession.numberingXmlParts : [];
+    const numberingXml = pendingParts.length > 0 ? mergeNumberingParts(sourceNumberingXml, pendingParts) : sourceNumberingXml;
+    const shared = {
+        author: author || getDefaultAuthor(),
+        generateRedlines,
+        runtimeContext,
+        stylesXml: runtimeContext?.stylesXml || options.stylesXml || null,
+        numberingXml,
+        paragraphIndexOf
+    };
+
+    let outcome;
+    if (request.mode === 'join') {
+        const descriptor = options.continueFromDescriptor || null;
+        const resolved = descriptor
+            ? resolveTargetParagraph(xmlDoc, descriptor.text || '', descriptor.index ?? null, 'list-format', runtimeContext, {
+                ...options,
+                targetDescriptor: descriptor,
+                _compiledSourceId: options._compiledContinueFromId || null,
+                _compiledResolvedBy: null,
+                _resolutionCapture: null
+            })
+            : null;
+        if (!resolved?.paragraph) {
+            return refused({
+                code: resolved?.error?.code || 'TARGET_NOT_FOUND',
+                message: `list.continueFrom: ${resolved?.error?.message || 'paragraph not found.'}`,
+                field: 'list.continueFrom'
+            });
+        }
+        outcome = joinListParagraphs(xmlDoc, paragraphs, resolved.paragraph, request, shared);
+    } else {
+        outcome = changeListParagraphsFormat(xmlDoc, paragraphs, request, shared);
+    }
+    if (!outcome.ok) return refused(outcome.error);
+    if (outcome.unchanged) {
+        const warning = `${LIST_FORMAT_UNCHANGED}: ${outcome.message}`;
+        ctx.onWarn?.(warning);
+        return { documentXml, hasChanges: false, status: 'ok', warnings: [warning] };
+    }
+
+    for (const item of outcome.items) {
+        ensureParagraphIdsOnImportedNode(item.paragraph, operationSession);
+        options?._mutationLiveNodes?.push(item.paragraph);
+    }
+    for (const numId of outcome.allocatedNumIds) operationSession?.receiptCollector?.recordNumbering(numId);
+    normalizeBodySectionOrder(xmlDoc);
+    const outside = outcome.items.filter(item => !item.inTarget).length;
+    onInfo(`[List] list-format ${outcome.mode} (${outcome.scope}) rebound ${outcome.items.length} paragraph(s) from numId ${outcome.sourceNumId} to numId ${outcome.numId}${outside ? ` (${outside} outside the target range)` : ''}.`);
+
+    return {
+        documentXml: completedDocumentXml(xmlDoc, serializer, documentXml, operationSession),
+        hasChanges: true,
+        status: 'ok',
+        numberingXml: outcome.numberingXml,
+        list: {
+            mode: outcome.mode,
+            scope: outcome.scope,
+            sourceNumId: outcome.sourceNumId,
+            numId: outcome.numId,
+            ...(outcome.mode === 'change-format'
+                ? { format: outcome.format, level: outcome.level, lvlText: outcome.lvlText, levelStarts: outcome.levelStarts }
+                : { continueFrom: outcome.continueFrom }),
+            items: outcome.items.map(item => ({
+                paragraphIndex: item.paragraphIndex,
+                paragraphId: getParagraphId(item.paragraph),
+                level: item.level,
+                numId: item.numId,
+                sourceNumId: item.sourceNumId,
+                inTarget: item.inTarget
+            })),
+            skipped: outcome.skipped.map(item => ({ paragraphIndex: item.paragraphIndex, reason: item.reason }))
+        }
     };
 }