@superdoc/sdk 2.25.0-next.3 → 2.25.0-next.5

package/dist/agent/actions.js

@@ -1,8 +1,9 @@
 import actionDescriptors from './action-descriptors.json' with { type: 'json' };
 import { ExecutionContext, evaluateFactChecks } from './execution-context.js';
-import { bindActionChangeMode } from './action-change-mode.js';
+import { bindActionChangeMode, withoutActionChangeMode } from './action-change-mode.js';
 import { CONTRACT } from '../generated/contract.js';
 import { SuperDocCliError } from '../runtime/errors.js';
+import { operationAcceptsTrackedMode } from '../runtime/tracked-support.js';
 import { runSuperdocListTransformWorkflow } from '../action-primitives/tools/list-transform.js';
 import { runSuperdocStructureInsertWorkflow } from '../action-primitives/tools/structure-insert.js';
 import { runSuperdocTextTransformWorkflow } from '../action-primitives/tools/text-transform.js';
@@ -13,11 +14,7 @@ function projectActionDefinitions(project) {
     return Object.fromEntries(Object.entries(ACTION_DEFINITIONS).map(([name, definition]) => [name, project(definition)]));
 }
 function contractSupportsTrackedOperation(operationId) {
-    const operation = CONTRACT.operations[`doc.${operationId}`];
-    return (operation?.trackedSupport === 'always' ||
-        operation?.trackedSupport === 'conditional' ||
-        operation?.supportsTrackedMode === true ||
-        operation?.supportsConditionalTrackedMode === true);
+    return operationAcceptsTrackedMode(CONTRACT.operations[`doc.${operationId}`]);
 }
 function deriveActionDisposition(definition) {
     if (definition.trackedOverrideReason)
@@ -172,6 +169,13 @@ function createdBlockTarget(result) {
     }
     return null;
 }
+function placementMissMessage(selector, matchCount) {
+    if (selector.kind === 'textSearch' && matchCount === 0 && (selector.occurrence ?? 1) === 1) {
+        const text = selector.terms.map((term) => `"${term}"`).join(selector.match === 'any' ? ' or ' : ' and ');
+        return `no block contains ${text}; re-inspect and quote the exact text`;
+    }
+    return 'placement selector did not resolve to a unique body block';
+}
 function resolvePlacement(placement, snapshot) {
     if (!placement || placement.at === 'document_end')
         return { kind: 'documentEnd' };
@@ -179,10 +183,7 @@ function resolvePlacement(placement, snapshot) {
         return { kind: 'documentStart' };
     const target = selectorToBlockTarget(placement.selector, snapshot);
     if (!target) {
-        throw new SuperDocCliError('placement selector did not resolve to a unique body block', {
-            code: 'INVALID_ARGUMENT',
-            details: { placement },
-        });
+        throw new SuperDocCliError(placementMissMessage(placement.selector, resolveSnapshotSelector(snapshot, placement.selector).length), { code: 'INVALID_ARGUMENT', details: { placement } });
     }
     return {
         kind: placement.at === 'before' ? 'before' : 'after',
@@ -644,14 +645,20 @@ async function executeMutations(doc, steps, changeMode, expectedRevision) {
         ...(expectedRevision ? { expectedRevision } : {}),
     });
 }
-async function previewMutations(doc, steps, changeMode, expectedRevision) {
+async function previewMutations(doc, steps, changeMode, expectedRevision, detail) {
     const fn = maybeMethod(doc, ['mutations', 'preview']);
     if (!fn) {
         throw new SuperDocCliError('doc.mutations.preview is not available on the document handle.', {
             code: 'TOOL_DISPATCH_NOT_FOUND',
         });
     }
-    const result = await fn({ atomic: true, changeMode: changeMode ?? 'direct', expectedRevision, steps });
+    const result = await fn({
+        atomic: true,
+        changeMode: changeMode ?? 'direct',
+        expectedRevision,
+        steps,
+        ...(detail ? { detail } : {}),
+    });
     return isRecord(result) ? result : {};
 }
 async function executeCreateTable(doc, args, placement) {
@@ -973,185 +980,229 @@ async function runInsertHeading(doc, args) {
         return failedReceipt('insert_heading', err, pre);
     }
 }
-async function runReplaceTextUnchecked(doc, args) {
-    const selectorDomains = args.selector ? snapshotDomainsForSelector(args.selector) : null;
-    const requiresBlockSnapshot = args.selector != null;
-    const preIdentity = requiresBlockSnapshot ? null : await readDocumentIdentity(doc);
-    const pre = requiresBlockSnapshot
-        ? await buildMutationSnapshot(doc, { includeDomains: selectorDomains ?? ['blocks'] })
-        : snapshotFromIdentity(preIdentity);
-    try {
-        assertExpectedReplacementRevision(args.expectedRevision, pre.revision);
-        assertReplacementTextPayloads(args.edits);
-        if (args.edits.length === 0) {
-            return failedReceipt('replace_text', new Error('edits must be non-empty'), pre);
-        }
-        const caseSensitive = args.caseSensitive === true;
-        const selectedTargets = [];
-        let skippedEdits = [];
-        let steps;
-        let applyExpectedRevision = args.expectedRevision != null ? pre.revision : undefined;
-        if (args.selector) {
-            const target = selectorToBlockTarget(args.selector, pre);
-            if (!target) {
-                return failedReceipt('replace_text', new Error('selector did not resolve to a unique body block'), pre);
-            }
-            let rewrittenText = target.text;
-            for (const edit of args.edits) {
-                if (!textIncludes(rewrittenText, edit.find, caseSensitive)) {
-                    return {
-                        status: 'failed',
-                        intent: 'replace_text',
-                        preSnapshot: { revision: pre.revision, counts: pre.counts },
-                        selectedTargets: [{ selector: args.selector, matched: [target.nodeId] }],
-                        executedOperations: [],
-                        verification: [],
-                        errors: [
-                            {
-                                code: 'ACTION_FAILED',
-                                message: `selected block does not contain ${JSON.stringify(edit.find)}`,
-                            },
-                        ],
-                    };
-                }
-                rewrittenText = replaceAllText(rewrittenText, edit.find, edit.replace, caseSensitive);
-            }
-            steps = [
-                {
-                    id: 'replace-text-in-block-1',
-                    op: 'text.rewrite',
-                    where: { by: 'block', nodeType: target.nodeType, nodeId: target.nodeId },
-                    args: {
-                        replacement: { text: rewrittenText },
-                        style: preserveRewriteStyle(),
-                    },
-                },
-            ];
-            applyExpectedRevision = pre.revision;
-            selectedTargets.push({ selector: args.selector, matched: [target.nodeId] });
-        }
-        else {
-            let candidates = args.edits.map((edit, editIndex) => ({
-                edit,
-                step: {
-                    id: `replace-${editIndex + 1}`,
-                    op: 'text.rewrite',
-                    where: {
-                        by: 'select',
-                        select: {
-                            type: 'text',
-                            pattern: edit.find,
-                            mode: 'contains',
-                            caseSensitive,
-                        },
-                        require: 'all',
-                    },
-                    args: {
-                        replacement: { text: edit.replace },
-                        style: preserveRewriteStyle(),
-                    },
-                },
-            }));
-            if (candidates.length > 1) {
-                applyExpectedRevision = pre.revision;
-                while (candidates.length > 0) {
-                    const preview = await previewMutations(doc, candidates.map((candidate) => candidate.step), args.changeMode, pre.revision);
-                    if (preview.valid === true)
-                        break;
-                    const failures = Array.isArray(preview.failures) ? preview.failures.filter(isRecord) : [];
-                    const absent = failures.find((failure) => failure.code === 'MATCH_NOT_FOUND' && typeof failure.stepId === 'string');
-                    if (!absent) {
-                        throw new Error(typeof failures[0]?.message === 'string' ? failures[0].message : 'replacement plan could not be prepared');
-                    }
-                    const absentIndex = candidates.findIndex((candidate) => candidate.step.id === absent.stepId);
-                    if (absentIndex < 0)
-                        throw new Error('replacement preview returned an unknown step id');
-                    skippedEdits.push({ find: candidates[absentIndex].edit.find });
-                    candidates = candidates.filter((_candidate, index) => index !== absentIndex);
-                }
-            }
-            if (candidates.length === 0) {
-                return {
-                    status: 'failed',
-                    intent: 'replace_text',
-                    preSnapshot: { revision: pre.revision, counts: pre.counts },
-                    selectedTargets: [],
-                    executedOperations: [],
-                    verification: [],
-                    errors: [
-                        { code: 'ACTION_FAILED', message: 'none of the requested text replacements matched the current document' },
-                    ],
-                };
-            }
-            steps = candidates.map((candidate) => candidate.step);
-        }
-        const result = await executeMutations(doc, steps, args.changeMode, applyExpectedRevision);
-        if (args.selector && selectedTargets[0]) {
-            const post = await buildMutationSnapshot(doc, { includeDomains: selectorDomains ?? ['blocks'] });
-            const blockId = selectedTargets[0].matched[0];
-            const postTarget = findSnapshotTextByNodeId(post, blockId);
-            const preTarget = findSnapshotTextByNodeId(pre, blockId);
-            const finalText = postTarget?.text ?? '';
-            const expectedText = args.edits.reduce((current, edit) => replaceAllText(current, edit.find, edit.replace, caseSensitive), preTarget?.text ?? '');
-            const verification = [
-                {
-                    check: { kind: 'revision-changed' },
-                    passed: pre.revision !== post.revision,
-                    detail: `pre=${pre.revision} post=${post.revision}`,
-                },
-                {
-                    check: {
-                        kind: 'block-text-contains',
-                        nodeId: blockId,
-                        text: expectedText,
-                    },
-                    passed: !!postTarget && verifyRewrittenBlockText(finalText, expectedText, args.changeMode),
+function replacementGranularityArg(granularity) {
+    return granularity === undefined ? {} : { replacementGranularity: granularity };
+}
+function globalReplaceCandidates(args) {
+    const caseSensitive = args.caseSensitive === true;
+    return args.edits.map((edit, editIndex) => ({
+        edit,
+        step: {
+            id: `replace-${editIndex + 1}`,
+            op: 'text.rewrite',
+            where: {
+                by: 'select',
+                select: {
+                    type: 'text',
+                    pattern: edit.find,
+                    mode: 'contains',
+                    caseSensitive,
                 },
-            ];
+                require: 'all',
+            },
+            args: {
+                replacement: { text: edit.replace },
+                style: preserveRewriteStyle(),
+                ...replacementGranularityArg(args.granularity),
+            },
+        },
+    }));
+}
+function previewFailuresOf(preview) {
+    return Array.isArray(preview.failures) ? preview.failures.filter(isRecord) : [];
+}
+function previewRefusal(failure, find) {
+    const code = asString(failure?.code) ?? 'ACTION_FAILED';
+    const message = asString(failure?.message) ?? 'replacement plan could not be prepared';
+    const namesFind = find !== undefined && code !== 'PLAN_LIMIT_EXCEEDED';
+    return new SuperDocCliError(namesFind ? `${JSON.stringify(find)}: ${message}` : message, { code });
+}
+const PREVIEW_DETAIL_LIMIT = 1000;
+async function completeResolutionTexts(doc, steps, changeMode, revision, firstPage) {
+    const texts = new Map();
+    const counts = new Map();
+    let page = firstPage;
+    let offset = 0;
+    while (page.valid === true) {
+        let returned = 0;
+        for (const entry of Array.isArray(page.steps) ? page.steps.filter(isRecord) : []) {
+            const stepId = asString(entry.stepId);
+            if (stepId === undefined)
+                continue;
+            const resolutions = Array.isArray(entry.resolutions) ? entry.resolutions : [];
+            texts.set(stepId, [...(texts.get(stepId) ?? []), ...resolutions.map((resolution) => asRecord(resolution)?.text)]);
+            if (typeof entry.matchCount === 'number')
+                counts.set(stepId, entry.matchCount);
+            returned = Math.max(returned, resolutions.length);
+        }
+        const missing = [...texts].some(([stepId, list]) => (counts.get(stepId) ?? list.length) > list.length);
+        if (!missing || returned === 0)
+            break;
+        offset += returned;
+        page = await previewMutations(doc, steps, changeMode, revision, { offset, limit: PREVIEW_DETAIL_LIMIT });
+    }
+    return new Map([...texts].map(([stepId, list]) => [stepId, counts.get(stepId) === list.length ? list : null]));
+}
+async function previewGlobalCandidates(doc, initial, changeMode, revision, skippedEdits) {
+    let candidates = [...initial];
+    while (candidates.length > 0) {
+        const steps = candidates.map((candidate) => candidate.step);
+        const preview = await previewMutations(doc, steps, changeMode, revision, {
+            offset: 0,
+            limit: PREVIEW_DETAIL_LIMIT,
+        });
+        const failures = previewFailuresOf(preview);
+        if (preview.valid === true) {
+            const texts = await completeResolutionTexts(doc, steps, changeMode, revision, preview);
+            const resolvedTexts = ({ step }) => texts.get(String(step.id)) ?? null;
+            const changedCount = (candidate) => (resolvedTexts(candidate) ?? []).filter((text) => text !== candidate.edit.replace).length;
+            const complete = candidates.filter((candidate) => resolvedTexts(candidate) !== null);
             return {
-                status: verification.every((v) => v.passed) ? 'ok' : 'failed',
-                intent: 'replace_text',
-                preSnapshot: { revision: pre.revision, counts: pre.counts },
-                postSnapshot: { revision: post.revision, counts: post.counts },
-                selectedTargets,
-                executedOperations: [{ operationId: 'doc.mutations.apply', result }],
-                verification,
+                candidates,
+                unchanged: complete.filter((candidate) => resolvedTexts(candidate).length > 0 && changedCount(candidate) === 0),
+                applied: complete
+                    .map((candidate) => ({ find: candidate.edit.find, occurrences: changedCount(candidate) }))
+                    .filter((edit) => edit.occurrences > 0),
+                incomplete: candidates.filter((candidate) => resolvedTexts(candidate) === null),
             };
         }
-        const postIdentity = args.changeMode === 'tracked'
-            ? await readDocumentIdentity(doc)
-            : {
-                revision: revisionAfterOperation(result, pre.revision),
-                counts: pre.counts,
-            };
-        const verification = [revisionVerification(pre.revision, postIdentity.revision, true)];
-        const skippedEditRationale = args.selector == null && args.edits.length > 1 ? summarizeSkippedReplaceEdits(skippedEdits) : undefined;
+        const absent = failures.find((failure) => failure.code === 'MATCH_NOT_FOUND' && typeof failure.stepId === 'string');
+        const failedCandidate = (failure) => candidates.find((candidate) => candidate.step.id === failure?.stepId);
+        if (!absent)
+            throw previewRefusal(failures[0], failedCandidate(failures[0])?.edit.find);
+        const absentCandidate = failedCandidate(absent);
+        if (!absentCandidate)
+            throw new Error('replacement preview returned an unknown step id');
+        skippedEdits.push({ find: absentCandidate.edit.find });
+        candidates = candidates.filter((candidate) => candidate !== absentCandidate);
+    }
+    return { candidates, unchanged: [], applied: [], incomplete: [] };
+}
+function readBackFailure(error) {
+    return { check: { kind: 'revision-changed' }, passed: false, detail: `read back failed: ${reasonOf(error)}` };
+}
+function readBackError(error) {
+    return {
+        code: 'ACTION_FAILED',
+        message: `replace_text: the edit was applied but the document could not be read back (${reasonOf(error)}). Inspect before retrying; do not repeat the edit.`,
+        recovery: { kind: 'reinspect' },
+    };
+}
+function unchangedEditsEvidence(unchanged) {
+    const finds = [...new Set(unchanged.map((span) => span.find))];
+    return finds.length > 0
+        ? { editsUnchanged: finds.map((find) => ({ find, reason: 'already reads as the replacement' })) }
+        : {};
+}
+function granularGlobalEvidence({ applied }, skippedEdits, requested) {
+    return {
+        editsApplied: applied,
+        ...(skippedEdits.length > 0
+            ? {
+                nextStep: `${skippedEdits.length} of ${requested} edits were NOT applied — the find text is not in the document. ` +
+                    'Do not stop: inspect, then call replace_text again for the remaining edits with the text as it appears.',
+                recovery: { kind: 'retry' },
+                editsSkipped: skippedEdits.map((edit) => ({ find: edit.find, reason: 'not present in the document' })),
+            }
+            : {}),
+    };
+}
+async function runGlobalReplace(doc, args, pre) {
+    assertExpectedReplacementRevision(args.expectedRevision, pre.revision);
+    assertReplacementTextPayloads(args.edits);
+    if (args.edits.length === 0) {
+        return failedReceipt('replace_text', new Error('edits must be non-empty'), pre);
+    }
+    const initial = globalReplaceCandidates(args);
+    const skippedEdits = [];
+    const granular = args.granularity !== undefined;
+    const multiple = initial.length > 1;
+    const preview = multiple || granular
+        ? await previewGlobalCandidates(doc, initial, args.changeMode, pre.revision, skippedEdits)
+        : { candidates: initial, unchanged: [], applied: [], incomplete: [] };
+    const { candidates, unchanged } = preview;
+    if (granular && preview.incomplete.length > 0) {
+        throw new SuperDocCliError(`replace_text: the engine did not list every match of ${preview.incomplete.map((candidate) => JSON.stringify(candidate.edit.find)).join(', ')}, so the granular replacement cannot be verified; nothing was written. Scope the edit with a selector or a longer find.`, { code: 'INVALID_ARGUMENT' });
+    }
+    if (candidates.length === 0) {
         return {
-            status: verification.every((v) => v.passed) ? 'ok' : 'failed',
+            status: 'failed',
             intent: 'replace_text',
             preSnapshot: { revision: pre.revision, counts: pre.counts },
-            postSnapshot: postIdentity,
-            selectedTargets,
-            executedOperations: [
-                {
-                    operationId: 'doc.mutations.apply',
-                    ...(skippedEditRationale ? { rationale: skippedEditRationale } : {}),
-                    result,
-                },
+            selectedTargets: [],
+            executedOperations: [],
+            verification: [],
+            errors: [
+                { code: 'ACTION_FAILED', message: 'none of the requested text replacements matched the current document' },
             ],
-            verification,
         };
     }
-    catch (err) {
-        return failedReceipt('replace_text', err, pre);
+    const skippedEditRationale = args.edits.length > 1 ? summarizeSkippedReplaceEdits(skippedEdits) : undefined;
+    const evidence = {
+        ...(granular ? granularGlobalEvidence(preview, skippedEdits, args.edits.length) : {}),
+        ...unchangedEditsEvidence(unchanged.map((candidate) => candidate.edit)),
+    };
+    const partial = granular && skippedEdits.length > 0;
+    if (unchanged.length === candidates.length) {
+        return {
+            status: partial ? 'partial' : 'ok',
+            intent: 'replace_text',
+            note: ['The text already reads as requested; nothing was written.', skippedEditRationale]
+                .filter(Boolean)
+                .join(' '),
+            preSnapshot: { revision: pre.revision, counts: pre.counts },
+            selectedTargets: [],
+            executedOperations: [],
+            verification: [],
+            ...evidence,
+        };
     }
+    const applyExpectedRevision = args.expectedRevision != null || multiple || granular ? pre.revision : undefined;
+    const result = await executeMutations(doc, candidates.map((candidate) => candidate.step), args.changeMode, applyExpectedRevision);
+    let postIdentity;
+    let readError;
+    try {
+        postIdentity =
+            args.changeMode === 'tracked'
+                ? await readDocumentIdentity(doc)
+                : { revision: revisionAfterOperation(result, pre.revision), counts: pre.counts };
+    }
+    catch (error) {
+        readError = error;
+    }
+    const verification = postIdentity
+        ? [revisionVerification(pre.revision, postIdentity.revision, true)]
+        : [readBackFailure(readError)];
+    const passed = verification.every((v) => v.passed);
+    return {
+        status: !passed ? 'failed' : partial ? 'partial' : 'ok',
+        intent: 'replace_text',
+        ...(readError !== undefined ? { errors: [readBackError(readError)] } : {}),
+        preSnapshot: { revision: pre.revision, counts: pre.counts },
+        ...(postIdentity ? { postSnapshot: postIdentity } : {}),
+        selectedTargets: [],
+        executedOperations: [
+            {
+                operationId: 'doc.mutations.apply',
+                ...(skippedEditRationale ? { rationale: skippedEditRationale } : {}),
+                result,
+            },
+        ],
+        verification,
+        ...evidence,
+    };
 }
 async function runReplaceText(doc, args) {
     const changeMode = args.changeMode ?? 'direct';
-    return {
-        ...(await runReplaceTextUnchecked(doc, { ...args, changeMode })),
-        changeMode,
-    };
+    const pre = snapshotFromIdentity(await readDocumentIdentity(doc));
+    let receipt;
+    try {
+        receipt = await runGlobalReplace(doc, { ...args, changeMode }, pre);
+    }
+    catch (err) {
+        receipt = failedReceipt('replace_text', err, pre);
+    }
+    return { ...receipt, changeMode };
 }
 async function runDeleteText(doc, args) {
     const caseSensitive = args.caseSensitive === true;
@@ -1973,14 +2024,14 @@ async function runAddListItems(doc, args, opts) {
                 const sibling = formattingSourceForLevel(ci.targetLevel);
                 if (!sibling?.nodeId)
                     continue;
-                const node = (await getNodeFn({ id: sibling.nodeId }));
+                const node = (await getNodeFn({ id: sibling.nodeId, story: { kind: 'story', storyType: 'body' } }));
                 const indent = paragraphIndentOf(node);
                 if (!indent)
                     continue;
                 // COMPARE rather than assume: a same-level item usually inherits the
                 // anchor's indentation on creation, but not always — one real document
                 // produced items with no `w:ind` at all beside siblings indented 851.
-                const created = paragraphIndentOf(await getNodeFn({ id: ci.nodeId }));
+                const created = paragraphIndentOf(await getNodeFn({ id: ci.nodeId, story: { kind: 'story', storyType: 'body' } }));
                 if (created && ['left', 'right', 'firstLine', 'hanging'].every((k) => created[k] === indent[k])) {
                     continue;
                 }
@@ -2028,14 +2079,13 @@ async function runAddListItems(doc, args, opts) {
         }
         // Format each new item in four layers, later layers overriding earlier on
         // overlapping keys (successive format.apply calls):
-        //   1. BASE  — the sampled look of the existing item at the same level, over
-        //      the whole item, so an item added with no explicit styling still
-        //      matches its siblings' font/size/colour (fixes the plain-insert
+        //   1. BASE  — the sampled font and size of the existing item at the same
+        //      level, over the whole item, never its emphasis or colour (fixes the plain-insert
         //      mismatch where the new item fell back to style defaults instead of
         //      the list's direct run formatting).
         //   2. LEAD  — the siblings' "bold label: plain sentence" convention over
         //      the new item's own label span, when the item requested no styling of
-        //      its own. Without it a plain add reads as the odd one out even though
+        //      its own and the sibling has a real emphasised label. Without it a plain add reads as the odd one out even though
         //      every other property matches: the agent is only told the item TEXT of
         //      its siblings, never that they open with a bold lead-in.
         //   3. ITEM  — whole-item `marks` the agent supplied (e.g. Arial 16pt on the
@@ -2056,7 +2106,7 @@ async function runAddListItems(doc, args, opts) {
             // `formattingSourceForLevel(targetLevel)` already picks the destination sibling for
             // style and indent, so the look follows the same source. Falls back to
             // the anchor only when the destination level has no sibling to sample.
-            const anchorBase = inlineLookFromRow(anchor);
+            const anchorBase = baseRunLookOf(anchor);
             const formatFn = maybeMethod(doc, ['format', 'apply']);
             if (formatFn) {
                 const applied = [];
@@ -2096,7 +2146,7 @@ async function runAddListItems(doc, args, opts) {
                     const pattern = source?.nodeId && sourceText ? await listItemRunPattern(doc, sourceText, source.nodeId) : null;
                     // 1. sampled base over the whole item (row fields first, run-level
                     //    sample second: the row read omits run styling entirely).
-                    const destinationBase = source ? inlineLookFromRow(source) : anchorBase;
+                    const destinationBase = source ? baseRunLookOf(source) : anchorBase;
                     const merged = { ...destinationBase, ...pattern?.body };
                     reportedBase = reportedBase ?? merged;
                     await applyRange(ci.nodeId, 0, len, merged);
@@ -2143,47 +2193,6 @@ async function runAddListItems(doc, args, opts) {
         catch (err) {
             formattingMatched = { skipped: reasonOf(err) };
         }
-        // Word paints the LIST NUMBER from the paragraph mark's run properties
-        // (w:pPr/w:rPr), not from the item's text runs — so an item whose text is
-        // styled correctly still shows a default-black "4." next to bold blue
-        // "1./2./3." siblings. Mirror the item's leading run onto the mark, which
-        // is the relationship those siblings already encode. Best-effort and never
-        // fatal: the item and its text styling have already landed.
-        let markStyledItems = 0;
-        const markerSkipped = await bestEffort(async () => {
-            const setMarkFn = maybeMethod(doc, ['format', 'paragraph', 'setMarkRunProps']);
-            const getNodeFn = maybeMethod(doc, ['getNodeById']);
-            if (!setMarkFn)
-                return;
-            for (const ci of createdItems) {
-                // Explicit marks describe the intent — the whole-item ones AND the
-                // leading run's, merged in that order, so a marker never loses the
-                // item's colour just because the first run also asked for bold.
-                //
-                // With no marks at all, COPY the sibling's own paragraph mark instead of
-                // deriving one from the text runs: a marker must not gain bold its
-                // siblings' markers don't have (bullet lists routinely carry a bare mark
-                // next to bold-lead-in text), and must gain it where they do. A
-                // same-level add already inherits the anchor's mark on creation; this
-                // covers the level-CHANGING add, whose inherited mark came from the
-                // wrong level. Reads nothing today: `getNodeById` reports
-                // indent/alignment/spacing but not `markRunProps`, so an unstyled
-                // promotion keeps the plain marker until that read lands.
-                let markProps = markRunPropsFromMarks({ ...ci.itemMarks, ...ci.runs[0]?.marks });
-                if (!markProps && getNodeFn) {
-                    const source = formattingSourceForLevel(ci.targetLevel);
-                    if (source?.nodeId)
-                        markProps = paragraphMarkRunPropsOf(await getNodeFn({ id: source.nodeId }));
-                }
-                if (!markProps)
-                    continue;
-                await setMarkFn({
-                    target: { kind: 'block', nodeType: 'paragraph', nodeId: ci.nodeId },
-                    markRunProps: markProps,
-                });
-                markStyledItems += 1;
-            }
-        });
         const postIdentity = await readDocumentIdentity(doc);
         const verification = [revisionVerification(pre.revision, postIdentity.revision, true)];
         return {
@@ -2193,8 +2202,6 @@ async function runAddListItems(doc, args, opts) {
             ...(styleSkipped ? { styleSkipped } : {}),
             ...(indentedItems.length ? { indentMatchedFrom: indentedItems.map((i) => i.from) } : {}),
             ...(indentSkipped ? { indentSkipped } : {}),
-            ...(markStyledItems > 0 ? { markerStyled: markStyledItems } : {}),
-            ...(markerSkipped ? { markerSkipped } : {}),
             ...(landed.length
                 ? {
                     note: `landed at ${landed
@@ -2287,9 +2294,7 @@ async function resolveFactPlacement(placement, facts) {
         return { kind: 'documentStart' };
     const target = await facts.target(placement.selector);
     if (!target)
-        throw new SuperDocCliError('placement selector did not resolve to a unique body block', {
-            code: 'INVALID_ARGUMENT',
-        });
+        throw new SuperDocCliError(placementMissMessage(placement.selector, (await facts.select(placement.selector)).length), { code: 'INVALID_ARGUMENT' });
     return { kind: placement.at, target: { kind: 'block', nodeType: target.nodeType, nodeId: target.nodeId } };
 }
 function placementSelectors(placement) {
@@ -2665,18 +2670,11 @@ async function runRewriteBlock(doc, args) {
     }
 }
 const RUN_BOOL_MARKS = ['bold', 'italic', 'underline', 'strike'];
-/**
- * The format.apply inline bag reproducing a SnapshotRun's marks. Boolean marks
- * listed in `normalize` are always emitted (true OR explicit false) so ranges
- * that were plain actively CLEAR a mark the engine smeared across the block.
- */
-function inlineFromSnapshotRun(run, normalize) {
+function inlineFromSnapshotRun(run) {
     const inline = {};
     for (const key of RUN_BOOL_MARKS) {
         if (run[key])
             inline[key] = true;
-        else if (normalize.has(key))
-            inline[key] = false;
     }
     if (run.fontFamily)
         inline.fontFamily = run.fontFamily;
@@ -2768,24 +2766,27 @@ async function runTrackedChangeDecision(doc, intentLabel, decision, exactIds, au
         const sideForType = changeType === 'delete' ? 'deleted' : changeType === 'insert' ? 'inserted' : undefined;
         const isReplacement = (item) => asString(asRecord(item)?.type) === 'replacement';
         if (changeType) {
-            scoped = scoped.filter((item) => asString(item?.type) === changeType || (sideForType != null && isReplacement(item)));
+            scoped = scoped.filter((item) => trackedChangeKindOf(asString(item?.type)) === changeType || (sideForType != null && isReplacement(item)));
         }
         const executedOperations = [];
         if (scoped.length === 0) {
             // Nothing to do is not a failure: report it honestly.
             const post = await buildDocumentSnapshot(doc);
+            const pendingByType = countTrackedChangesByKind(items);
+            const filters = [author ? `author=${author}` : '', changeType ? `changeType=${changeType}` : ''].filter(Boolean);
+            const rationale = items.length === 0
+                ? `no tracked changes${author ? ` for author=${author}` : ''}${changeType ? ` of type=${changeType}` : ''} to ${decision}`
+                : `0 of ${items.length} pending tracked changes matched ${filters.join(', ')}; nothing was ${decision}ed. Pending by type: ${Object.entries(pendingByType)
+                    .map(([kind, count]) => `${kind}: ${count}`)
+                    .join(', ')}`;
             return {
                 status: 'ok',
                 intent: intentLabel,
                 preSnapshot: { revision: pre.revision, counts: pre.counts },
                 postSnapshot: { revision: post.revision, counts: post.counts },
                 selectedTargets: [],
-                executedOperations: [
-                    {
-                        operationId: 'doc.trackChanges.list',
-                        rationale: `no tracked changes${author ? ` for author=${author}` : ''}${changeType ? ` of type=${changeType}` : ''} to ${decision}`,
-                    },
-                ],
+                executedOperations: [{ operationId: 'doc.trackChanges.list', rationale }],
+                pendingTrackedChanges: { total: items.length, byType: pendingByType },
                 verification: [{ check: { kind: 'tracked-change-count-delta', delta: 0 }, passed: true, detail: 'no-op' }],
             };
         }
@@ -3846,47 +3847,204 @@ async function runInsertToc(doc, args) {
             });
         }
         const resolvedPlacement = resolvePlacement(placement, pre);
+        const intent = `insert_toc${args.title ? `: ${args.title}` : ''}`;
+        const preTocIds = await readTocIds(doc);
+        const failure = (err, heading) => insertTocFailureReceipt({ doc, intent, err, pre, preTocIds, title: args.title, heading });
+        const createToc = async (dryRun) => {
+            const options = {
+                ...(args.changeMode ? { changeMode: args.changeMode } : {}),
+                ...(dryRun ? { dryRun: true } : {}),
+            };
+            return requireMutationSuccess(await tocFn({ at: resolvedPlacement, ...options }, Object.keys(options).length > 0 ? options : undefined));
+        };
+        const createTitle = async () => requireMutationSuccess(await executeCreateHeading(doc, args.title ?? '', 1, resolvedPlacement, args.changeMode));
         const executed = [];
-        let tocPlacement = resolvedPlacement;
-        if (args.title) {
-            const headingResult = await executeCreateHeading(doc, args.title, 1, resolvedPlacement, args.changeMode);
-            executed.push({ operationId: 'doc.create.heading', result: headingResult });
-            const headingNodeId = asString(asRecord(asRecord(headingResult)?.heading)?.nodeId);
-            if (headingNodeId) {
-                tocPlacement = {
-                    kind: 'after',
-                    target: { kind: 'block', nodeType: 'heading', nodeId: headingNodeId },
-                };
+        let headingError = null;
+        if (!args.title || resolvedPlacement.kind === 'after' || resolvedPlacement.kind === 'documentStart') {
+            try {
+                executed.push({ operationId: 'doc.create.tableOfContents', result: await createToc(false) });
+            }
+            catch (err) {
+                return failure(err);
+            }
+            if (args.title) {
+                try {
+                    executed.push({ operationId: 'doc.create.heading', result: await createTitle() });
+                }
+                catch (err) {
+                    headingError = err;
+                }
+            }
+        }
+        else {
+            let headingResult;
+            try {
+                await createToc(true);
+                headingResult = await createTitle();
+            }
+            catch (err) {
+                return failure(err);
+            }
+            try {
+                const tocResult = await createToc(false);
+                executed.push({ operationId: 'doc.create.heading', result: headingResult }, { operationId: 'doc.create.tableOfContents', result: tocResult });
+            }
+            catch (err) {
+                return failure(err, { result: headingResult, removedBy: await rollBackInsertedHeading(doc, headingResult) });
             }
         }
-        const tocParams = { at: tocPlacement };
-        if (args.changeMode)
-            tocParams.changeMode = args.changeMode;
-        // Dual dialect — see executeCreateParagraph.
-        const result = await tocFn(tocParams, args.changeMode ? { changeMode: args.changeMode } : undefined);
-        executed.push({ operationId: 'doc.create.tableOfContents', result });
         const post = await buildDocumentSnapshot(doc);
         const verification = evaluateChecks(pre, post, [{ kind: 'revision-changed' }]);
-        return {
+        const receipt = {
             status: verification.every((v) => v.passed) ? 'ok' : 'failed',
-            intent: `insert_toc${args.title ? `: ${args.title}` : ''}`,
+            intent,
             preSnapshot: { revision: pre.revision, counts: pre.counts },
             postSnapshot: { revision: post.revision, counts: post.counts },
             selectedTargets: [],
             executedOperations: executed,
             verification,
         };
+        if (!headingError)
+            return receipt;
+        return {
+            ...receipt,
+            status: 'partial',
+            errors: [{ code: asString(asRecord(headingError)?.code) ?? 'ACTION_FAILED', message: reasonOf(headingError) }],
+            note: `The table of contents was inserted without its ${JSON.stringify(args.title)} heading.`,
+            nextStep: `Add the ${JSON.stringify(args.title)} heading directly above the table of contents, or leave it untitled.`,
+        };
     }
     catch (err) {
         return failedReceipt('insert_toc', err, pre);
     }
 }
+async function rollBackInsertedHeading(doc, headingResult) {
+    const unbound = withoutActionChangeMode(doc);
+    const heading = asRecord(headingResult);
+    const trackedIds = (Array.isArray(heading?.trackedChangeRefs) ? heading.trackedChangeRefs : [])
+        .map((ref) => asString(asRecord(ref)?.entityId))
+        .filter((id) => typeof id === 'string');
+    try {
+        if (trackedIds.length > 0) {
+            const decideFn = maybeMethod(unbound, ['trackChanges', 'decide']);
+            if (!decideFn)
+                return null;
+            const target = trackedIds.length === 1 ? { kind: 'id', id: trackedIds[0] } : { kind: 'ids', ids: trackedIds };
+            requireMutationSuccess(await decideFn({ decision: 'reject', target }));
+            return 'doc.trackChanges.decide';
+        }
+        const nodeId = asString(asRecord(heading?.heading)?.nodeId);
+        const deleteFn = maybeMethod(unbound, ['blocks', 'delete']);
+        if (!nodeId || !deleteFn)
+            return null;
+        requireMutationSuccess(await deleteFn({ target: { kind: 'block', nodeType: 'heading', nodeId } }, { changeMode: 'direct' }));
+        return 'doc.blocks.delete';
+    }
+    catch {
+        return null;
+    }
+}
+async function readTocIds(doc) {
+    const listFn = maybeMethod(doc, ['toc', 'list']);
+    if (!listFn)
+        return null;
+    try {
+        const ids = new Set();
+        let offset = 0;
+        for (;;) {
+            const page = asRecord(await listFn({ offset, limit: 500 }));
+            const items = Array.isArray(page?.items) ? page.items : [];
+            for (const item of items) {
+                const id = asString(asRecord(asRecord(item)?.address)?.nodeId) ?? asString(asRecord(item)?.id);
+                if (id)
+                    ids.add(id);
+            }
+            offset += items.length;
+            if (items.length === 0 || offset >= (asNumber(page?.total) ?? 0))
+                return ids;
+        }
+    }
+    catch {
+        return null;
+    }
+}
+function requireMutationSuccess(result) {
+    const record = asRecord(result);
+    if (record?.success !== false)
+        return result;
+    const failure = asRecord(record.failure);
+    throw new SuperDocCliError(asString(failure?.message) ?? 'The operation was refused.', {
+        code: asString(failure?.code) ?? 'COMMAND_FAILED',
+    });
+}
+async function insertTocFailureReceipt(input) {
+    const { pre, heading } = input;
+    const failed = failedReceipt(input.intent, input.err, pre);
+    const post = await buildDocumentSnapshot(input.doc).catch(() => null);
+    const postTocIds = await readTocIds(input.doc);
+    const preTocIds = input.preTocIds;
+    const survivingTocs = postTocIds && preTocIds ? [...postTocIds].filter((id) => !preTocIds.has(id)) : null;
+    const headingLeft = heading !== undefined && heading.removedBy === null;
+    const title = JSON.stringify(input.title ?? '');
+    const executed = [];
+    const notes = [];
+    if (heading) {
+        executed.push({ operationId: 'doc.create.heading', result: heading.result });
+        if (heading.removedBy) {
+            executed.push({
+                operationId: heading.removedBy,
+                rationale: 'remove the heading written for the refused table of contents',
+            });
+            notes.push(`The ${title} heading was written and removed again.`);
+        }
+        else {
+            notes.push(`The ${title} heading is still in the document; remove it or add the table of contents below it.`);
+        }
+    }
+    if (survivingTocs && survivingTocs.length > 0) {
+        executed.push({
+            operationId: 'doc.create.tableOfContents',
+            rationale: 'reported a failure after committing',
+            result: { tocs: survivingTocs },
+        });
+        notes.push(`A table of contents is in the document despite the failure (${survivingTocs.join(', ')}); do not retry without removing it.`);
+    }
+    const partial = headingLeft || (survivingTocs?.length ?? 0) > 0;
+    const revisionsKnown = post !== null && pre.revision !== 'unknown' && post.revision !== 'unknown';
+    const unchanged = !partial && revisionsKnown && post.revision === pre.revision;
+    const nothingAdded = !partial && survivingTocs !== null && post !== null && insertTocCountsMatch(pre.counts, post.counts);
+    if (unchanged)
+        notes.push('Nothing was inserted: the request was refused and the document is unchanged.');
+    else if (nothingAdded) {
+        notes.push('No content was added: no new table of contents remains and block counts match the pre-action snapshot.');
+    }
+    else if (post === null || survivingTocs === null) {
+        notes.push('What survived could not be confirmed; re-inspect before retrying.');
+    }
+    else if (!partial) {
+        notes.push('The document changed during the failed request; re-inspect before retrying.');
+    }
+    return {
+        ...failed,
+        status: partial ? 'partial' : 'failed',
+        executedOperations: executed,
+        ...(post ? { postSnapshot: { revision: post.revision, counts: post.counts } } : {}),
+        ...(revisionsKnown ? { verification: [revisionVerification(pre.revision, post.revision, false)] } : {}),
+        ...(unchanged || nothingAdded ? {} : { recovery: { kind: 'reinspect' } }),
+        note: notes.join(' '),
+    };
+}
+function insertTocCountsMatch(before, after) {
+    return ['blocks', 'paragraphs', 'headings', 'tables'].every((key) => before[key] === after[key]);
+}
 /**
  * style_table — make a table look professional in one call: a filled accent
- * header row (navy by default) with white bold header text, bold first-column
- * labels, banded rows, and clean borders. Composes tables.applyPreset("accent")
- * for the header fill + borders, then formats the header row (white + bold) and
- * the first column (bold + accent) via cell formatting.
+ * header row (navy by default) with contrasting bold header text, bold
+ * first-column labels and accent top/bottom borders. tables.applyPreset("accent")
+ * paints the header fill and header text atomically; the first column (body
+ * rows) is then formatted bold + accent through paragraph-targeted
+ * format.apply steps. The receipt reads the header back and reports any step
+ * that did not land, so a half-styled table never reports ok.
  */
 async function runStyleTable(doc, args) {
     const preIdentity = await readDocumentIdentity(doc);
@@ -3900,61 +4058,61 @@ async function runStyleTable(doc, args) {
         const accent = normalizeTableColor(args.accentColor ?? '#1F3864') ?? '#1F3864';
         const target = { kind: 'block', nodeType: 'table', nodeId: table.nodeId };
         const executed = [];
-        // 1. Accent preset: filled header row + accent borders, in one call.
+        const errors = [];
         const presetFn = maybeMethod(doc, ['tables', 'applyPreset']);
         if (!presetFn) {
             throw new SuperDocCliError('doc.tables.applyPreset is not available on the document handle.', {
                 code: 'TOOL_DISPATCH_NOT_FOUND',
             });
         }
-        const presetResult = await presetFn({ target, preset: 'accent', accentColor: accent });
+        const presetResult = requireMutationSuccess(await presetFn({ target, preset: 'accent', accentColor: accent }));
         executed.push({ operationId: 'doc.tables.applyPreset', result: compactOpResult(presetResult) });
-        // 2. Header row → white + bold; first column (body rows) → bold + accent.
-        //    Best-effort: a failure to read/format cells must not fail the action,
-        //    the header fill + borders already landed.
+        let cellParagraphs = [];
         try {
-            const getCellsFn = maybeMethod(doc, ['tables', 'getCells']);
-            if (getCellsFn) {
-                const cellsRes = asRecord(await getCellsFn({ target }));
-                const cells = Array.isArray(cellsRes?.cells) ? cellsRes.cells : [];
-                const steps = [];
-                for (const cell of cells) {
-                    const nodeId = asString(cell.nodeId);
-                    const rowIndex = asNumber(cell.rowIndex);
-                    const columnIndex = asNumber(cell.columnIndex);
-                    if (!nodeId || rowIndex == null)
-                        continue;
-                    const where = { by: 'block', nodeType: 'tableCell', nodeId };
-                    if (rowIndex === 0) {
-                        steps.push({
-                            id: `hdr-${nodeId}`,
-                            op: 'format.apply',
-                            where,
-                            args: { inline: { bold: true, color: '#FFFFFF' }, scope: 'block' },
-                        });
-                    }
-                    else if (columnIndex === 0) {
-                        steps.push({
-                            id: `col-${nodeId}`,
-                            op: 'format.apply',
-                            where,
-                            args: { inline: { bold: true, color: accent }, scope: 'block' },
-                        });
-                    }
-                }
-                if (steps.length > 0) {
-                    const fmtResult = await executeMutations(doc, steps, 'direct');
-                    executed.push({ operationId: 'doc.mutations.apply', result: compactOpResult(fmtResult) });
-                }
-            }
+            cellParagraphs = await readStyleTableParagraphs(doc, target);
         }
-        catch {
-            // header/first-column emphasis is cosmetic polish on top of the preset.
+        catch (err) {
+            errors.push({ code: 'TABLE_READBACK_FAILED', message: `could not read the styled table back: ${reasonOf(err)}` });
+        }
+        const labelParagraphs = cellParagraphs.filter((paragraph) => paragraph.rowIndex > 0 && paragraph.columnIndex === 0 && paragraph.text.trim().length > 0);
+        const firstColumnSteps = [];
+        for (const paragraph of labelParagraphs) {
+            const color = (await accentReadsOnLabel(doc, paragraph, accent)) ? { color: accent } : {};
+            firstColumnSteps.push({
+                id: `col-${paragraph.nodeId}`,
+                op: 'format.apply',
+                where: { by: 'block', nodeType: 'paragraph', nodeId: paragraph.nodeId },
+                args: { inline: { bold: true, ...color }, scope: 'block' },
+            });
+        }
+        if (firstColumnSteps.length > 0) {
+            try {
+                const fmtResult = await executeMutations(doc, firstColumnSteps, args.changeMode);
+                executed.push({ operationId: 'doc.mutations.apply', result: compactOpResult(fmtResult) });
+            }
+            catch (err) {
+                errors.push({
+                    code: 'FIRST_COLUMN_FORMAT_FAILED',
+                    message: `first-column formatting did not apply: ${reasonOf(err)}`,
+                });
+            }
         }
         const postIdentity = await readDocumentIdentity(doc);
-        const verification = [revisionVerification(preIdentity.revision, postIdentity.revision, true)];
+        const headerParagraphs = cellParagraphs.filter((paragraph) => paragraph.rowIndex === 0);
+        let headerVerification;
+        try {
+            headerVerification = await verifyStyledTableHeader(doc, headerParagraphs, accent);
+        }
+        catch (err) {
+            const message = `could not read the header back: ${reasonOf(err)}`;
+            errors.push({ code: 'HEADER_VERIFICATION_FAILED', message });
+            headerVerification = { check: { kind: 'table-header-styled', fill: accent }, passed: false, detail: message };
+        }
+        const verification = [revisionVerification(preIdentity.revision, postIdentity.revision, true), headerVerification];
+        const allPassed = verification.every((entry) => entry.passed) && errors.length === 0;
+        const anyApplied = preIdentity.revision !== postIdentity.revision;
         return {
-            status: verification.every((entry) => entry.passed) ? 'ok' : 'failed',
+            status: allPassed ? 'ok' : anyApplied ? 'partial' : 'failed',
             intent: `style_table: accent ${accent}`,
             preSnapshot: preIdentity,
             postSnapshot: postIdentity,
@@ -3963,12 +4121,121 @@ async function runStyleTable(doc, args) {
             ],
             executedOperations: executed,
             verification,
+            ...(errors.length > 0 ? { errors } : {}),
         };
     }
     catch (err) {
         return failedReceipt('style_table', err, pre);
     }
 }
+async function readStyleTableParagraphs(doc, target) {
+    const extractFn = maybeMethod(doc, ['extract']);
+    const getCellsFn = maybeMethod(doc, ['tables', 'getCells']);
+    if (!extractFn || !getCellsFn)
+        return [];
+    const cellsResult = asRecord(await getCellsFn({ target }));
+    const cells = Array.isArray(cellsResult?.cells) ? cellsResult.cells : [];
+    const ownParagraphIds = new Map(cells.flatMap((cell) => {
+        const record = asRecord(cell);
+        const id = asString(record?.firstParagraphNodeId);
+        return id ? [[id, `${asNumber(record?.rowIndex)}:${asNumber(record?.columnIndex)}`]] : [];
+    }));
+    const extracted = asRecord(await extractFn({}));
+    const tableBlocks = (Array.isArray(extracted?.blocks) ? extracted.blocks : []).flatMap((entry) => {
+        const block = asRecord(entry);
+        const context = asRecord(block?.tableContext);
+        const nodeId = asString(block?.nodeId);
+        const extractOrdinal = asNumber(context?.tableOrdinal);
+        if (!nodeId || extractOrdinal == null)
+            return [];
+        return [
+            {
+                extractOrdinal,
+                paragraph: {
+                    nodeId,
+                    text: asString(block?.text) ?? '',
+                    rowIndex: asNumber(context?.rowIndex) ?? -1,
+                    columnIndex: asNumber(context?.columnIndex) ?? -1,
+                },
+            },
+        ];
+    });
+    const ownOrdinal = tableBlocks.find((entry) => ownParagraphIds.get(entry.paragraph.nodeId) === `${entry.paragraph.rowIndex}:${entry.paragraph.columnIndex}`)?.extractOrdinal;
+    if (ownOrdinal == null)
+        return [];
+    return tableBlocks.filter((entry) => entry.extractOrdinal === ownOrdinal).map((entry) => entry.paragraph);
+}
+async function verifyStyledTableHeader(doc, headerParagraphs, accent) {
+    const check = { kind: 'table-header-styled', fill: accent };
+    const withText = headerParagraphs.filter((paragraph) => paragraph.text.trim().length > 0);
+    if (withText.length === 0) {
+        return { check, passed: headerParagraphs.length > 0, detail: 'header row has no text to read back' };
+    }
+    const queryFn = maybeMethod(doc, ['query', 'match']);
+    if (!queryFn)
+        return { check, passed: false, detail: 'doc.query.match is unavailable; header styling unverified' };
+    const unreadable = [];
+    for (const paragraph of withText) {
+        const runs = await readParagraphRunStyles(queryFn, paragraph);
+        const readable = runs.length > 0 && runs.every((run) => run.bold && !!run.color && contrastRatio(run.color, accent) >= 4.5);
+        if (!readable)
+            unreadable.push(paragraph.text.trim());
+    }
+    return {
+        check,
+        passed: unreadable.length === 0,
+        detail: unreadable.length === 0
+            ? `${withText.length} header cell(s) bold with text contrasting ${accent}`
+            : `header text not bold or not contrasting ${accent}: ${unreadable.join(', ')}`,
+    };
+}
+async function readParagraphRunStyles(queryFn, paragraph) {
+    const result = asRecord(await queryFn({ select: { type: 'text', pattern: paragraph.text.trim() } }));
+    const items = Array.isArray(result?.items) ? result.items : [];
+    return items.flatMap((item) => {
+        const blocks = Array.isArray(asRecord(item)?.blocks) ? asRecord(item).blocks : [];
+        const block = blocks.map((entry) => asRecord(entry)).find((entry) => asString(entry?.blockId) === paragraph.nodeId);
+        const runs = Array.isArray(block?.runs) ? block.runs : [];
+        return runs.map((run) => {
+            const styles = asRecord(asRecord(run)?.styles);
+            const effective = asRecord(styles?.effective);
+            return { bold: effective?.bold === true, color: asString(effective?.color) ?? asString(styles?.color) };
+        });
+    });
+}
+const PAGE_WHITE = '#FFFFFF';
+const READABLE_CONTRAST = 4.5;
+async function accentReadsOnLabel(doc, paragraph, accent) {
+    if (contrastRatio(accent, PAGE_WHITE) < READABLE_CONTRAST)
+        return false;
+    const queryFn = maybeMethod(doc, ['query', 'match']);
+    if (!queryFn)
+        return false;
+    try {
+        const runs = await readParagraphRunStyles(queryFn, paragraph);
+        return runs.every((run) => !run.color || contrastRatio(run.color, PAGE_WHITE) >= READABLE_CONTRAST);
+    }
+    catch {
+        return false;
+    }
+}
+function contrastRatio(first, second) {
+    const luminance = (hex) => {
+        const raw = hex.replace(/^#/, '');
+        if (!/^[0-9a-f]{6}$/i.test(raw))
+            return null;
+        const [red, green, blue] = [0, 2, 4].map((offset) => {
+            const channel = Number.parseInt(raw.slice(offset, offset + 2), 16) / 255;
+            return channel <= 0.03928 ? channel / 12.92 : ((channel + 0.055) / 1.055) ** 2.4;
+        });
+        return 0.2126 * red + 0.7152 * green + 0.0722 * blue;
+    };
+    const left = luminance(first);
+    const right = luminance(second);
+    if (left == null || right == null)
+        return 0;
+    return (Math.max(left, right) + 0.05) / (Math.min(left, right) + 0.05);
+}
 /**
  * move_table — relocate a WHOLE table (with all its content) in ONE call.
  * Wraps doc.tables.move; `resolvePlacement` returns exactly the destination
@@ -4485,7 +4752,7 @@ function trackedChangeRefIds(result) {
         return entityId ? [entityId] : [];
     }));
 }
-function parseScopedReplaceArgs(args, edits, changeMode, expectedRevision) {
+function parseScopedReplaceArgs(args, edits, changeMode, expectedRevision, granularity) {
     if (!isRecord(args.selector))
         return null;
     return {
@@ -4494,8 +4761,21 @@ function parseScopedReplaceArgs(args, edits, changeMode, expectedRevision) {
         caseSensitive: args.caseSensitive === true,
         expectedRevision,
         changeMode,
+        ...(granularity !== undefined ? { granularity } : {}),
     };
 }
+const REPLACEMENT_GRANULARITIES = ['word', 'phrase', 'range'];
+function parseReplacementGranularity(value) {
+    if (value === undefined)
+        return undefined;
+    const granularity = REPLACEMENT_GRANULARITIES.find((candidate) => candidate === value);
+    if (granularity === undefined) {
+        throw new SuperDocCliError('replace_text: granularity must be "word", "phrase" or "range"', {
+            code: 'INVALID_ARGUMENT',
+        });
+    }
+    return granularity;
+}
 function assertExpectedReplacementRevision(expected, actual) {
     if (expected != null && expected !== actual) {
         throw new SuperDocCliError('replace_text: expectedRevision is stale. Inspect this live document again before editing.', {
@@ -4539,7 +4819,7 @@ async function fieldResultRanges(doc, nodeId, blockText) {
     }
     return ranges;
 }
-async function runScopedReplaceUnchecked(doc, args) {
+async function resolveScopedReplaceTarget(doc, args) {
     assertReplacementTextPayloads(args.edits);
     const pre = await buildMutationSnapshot(doc, { includeDomains: ['blocks', 'tables'] });
     assertExpectedReplacementRevision(args.expectedRevision, pre.revision);
@@ -4547,20 +4827,28 @@ async function runScopedReplaceUnchecked(doc, args) {
     if (matched.length !== 1) {
         const failure = describeSelectorFailure(args.selector, matched, pre, args.edits.map((e) => e.find));
         return {
-            status: 'failed',
-            intent: 'replace_text',
-            errors: [{ code: 'SELECTOR_NOT_UNIQUE', message: failure.message, recovery: failure.recovery }],
+            receipt: {
+                status: 'failed',
+                intent: 'replace_text',
+                errors: [{ code: 'SELECTOR_NOT_UNIQUE', message: failure.message, recovery: failure.recovery }],
+            },
         };
     }
     const nodeId = matched[0];
     const block = findTextTarget(pre, nodeId);
     if (!block) {
         return {
-            status: 'failed',
-            intent: 'replace_text',
-            errors: [{ code: 'TARGET_NOT_FOUND', message: `resolved block ${nodeId} missing from snapshot` }],
+            receipt: {
+                status: 'failed',
+                intent: 'replace_text',
+                errors: [{ code: 'TARGET_NOT_FOUND', message: `resolved block ${nodeId} missing from snapshot` }],
+            },
         };
     }
+    return { pre, nodeId, block };
+}
+const ENGINE_MAX_PLAN_STEPS = 200;
+function planScopedReplaceSpans(args, { pre, nodeId, block }) {
     const caseSensitive = args.caseSensitive === true;
     const hasExplicitOccurrence = args.edits.some((edit) => edit.occurrence != null);
     const perEdit = [];
@@ -4569,9 +4857,11 @@ async function runScopedReplaceUnchecked(doc, args) {
         const matches = findRanges(block.text, edit.find, caseSensitive);
         const spans = edit.occurrence == null ? matches : matches.slice(edit.occurrence - 1, edit.occurrence);
         if (hasExplicitOccurrence && spans.length === 0) {
-            return failedReceipt('replace_text', new SuperDocCliError(edit.occurrence == null
-                ? `replace_text: ${JSON.stringify(edit.find)} not found in the selected block. Inspect and choose a valid target.`
-                : `replace_text: ${JSON.stringify(edit.find)} occurrence ${edit.occurrence} not found in the selected block (${matches.length} matches). Inspect and choose a valid target.`, { code: 'MATCH_NOT_FOUND' }), pre);
+            return {
+                receipt: failedReceipt('replace_text', new SuperDocCliError(edit.occurrence == null
+                    ? `replace_text: ${JSON.stringify(edit.find)} not found in the selected block. Inspect and choose a valid target.`
+                    : `replace_text: ${JSON.stringify(edit.find)} occurrence ${edit.occurrence} not found in the selected block (${matches.length} matches). Inspect and choose a valid target.`, { code: 'MATCH_NOT_FOUND' }), pre),
+            };
         }
         perEdit.push({
             find: edit.find,
@@ -4582,22 +4872,23 @@ async function runScopedReplaceUnchecked(doc, args) {
             allSpans.push({ ...span, replace: edit.replace, find: edit.find, editIndex: perEdit.length - 1 });
         }
     }
-    const appliedEdits = perEdit.filter((e) => e.occurrences > 0);
     const skippedEdits = perEdit.filter((e) => e.occurrences === 0);
     if (allSpans.length === 0) {
         const cellHint = suggestTableCell(pre, args.edits.map((e) => e.find));
         return {
-            status: 'failed',
-            intent: 'replace_text',
-            selectedBlock: { nodeId, nodeType: block.nodeType, text: snippetAround(block.text) },
-            errors: [
-                {
-                    code: 'MATCH_NOT_FOUND',
-                    message: `none of the finds occur in the selected block. Block text: ${JSON.stringify(snippetAround(block.text, 160))}` +
-                        (cellHint != null ? ` ${cellHint.message}` : ''),
-                    ...(cellHint != null ? { recovery: { kind: 'retry', selector: cellHint.selector } } : {}),
-                },
-            ],
+            receipt: {
+                status: 'failed',
+                intent: 'replace_text',
+                selectedBlock: { nodeId, nodeType: block.nodeType, text: snippetAround(block.text) },
+                errors: [
+                    {
+                        code: 'MATCH_NOT_FOUND',
+                        message: `none of the finds occur in the selected block. Block text: ${JSON.stringify(snippetAround(block.text, 160))}` +
+                            (cellHint != null ? ` ${cellHint.message}` : ''),
+                        ...(cellHint != null ? { recovery: { kind: 'retry', selector: cellHint.selector } } : {}),
+                    },
+                ],
+            },
         };
     }
     // Overlapping spans (e.g. finds that contain each other) cannot be applied
@@ -4608,8 +4899,16 @@ async function runScopedReplaceUnchecked(doc, args) {
     let lastEnd = -1;
     for (const span of allSpans) {
         if (span.start < lastEnd) {
+            const covering = planned[planned.length - 1];
+            if (args.granularity !== undefined && !hasExplicitOccurrence && covering) {
+                return {
+                    receipt: failedReceipt('replace_text', new SuperDocCliError(`replace_text: the finds ${JSON.stringify(covering.find)} and ${JSON.stringify(span.find)} overlap in the same block; nothing was changed. Send non-overlapping finds, or one find covering both.`, { code: 'INVALID_ARGUMENT' }), pre),
+                };
+            }
             if (hasExplicitOccurrence) {
-                return failedReceipt('replace_text', new SuperDocCliError('replace_text: explicit occurrence targets overlap. Choose non-overlapping edits in the pre-edit block.', { code: 'INVALID_ARGUMENT' }), pre);
+                return {
+                    receipt: failedReceipt('replace_text', new SuperDocCliError('replace_text: explicit occurrence targets overlap. Choose non-overlapping edits in the pre-edit block.', { code: 'INVALID_ARGUMENT' }), pre),
+                };
             }
             droppedOverlaps.push(span);
             continue;
@@ -4634,10 +4933,27 @@ async function runScopedReplaceUnchecked(doc, args) {
         span.end += 1;
         perEdit[span.editIndex].collapsedSpace = true;
     });
+    const replacements = planned.filter((span) => block.text.slice(span.start, span.end) !== span.replace).length;
+    if (args.granularity !== undefined && !hasExplicitOccurrence && replacements > ENGINE_MAX_PLAN_STEPS) {
+        return {
+            receipt: failedReceipt('replace_text', new SuperDocCliError(`replace_text: ${replacements} granular replacements in one block exceed the ${ENGINE_MAX_PLAN_STEPS}-step plan limit; nothing was changed. Narrow the selector, or run the edit in parts, giving each part's edits explicit occurrence numbers.`, { code: 'INVALID_ARGUMENT' }), pre),
+        };
+    }
     // The block text once every planned span is replaced: the whole-block
     // rewrite writes it, and exact-target writes must produce it.
     const expected = planned.reduceRight((text, span) => text.slice(0, span.start) + span.replace + text.slice(span.end), block.text);
-    const tracked = (args.changeMode ?? 'direct') === 'tracked';
+    return {
+        perEdit,
+        skippedEdits,
+        planned,
+        droppedOverlaps,
+        expected,
+        hasExplicitOccurrence,
+        caseSensitive,
+    };
+}
+async function writesExactScopedTargets(doc, { nodeId, block }, plan, tracked, granular) {
+    const { planned, caseSensitive, hasExplicitOccurrence } = plan;
     // Unique tracked finds can be resolved within the block. Repeated finds
     // use one whole-block rewrite, whose engine diff preserves unchanged runs.
     // Dedupe on the same basis the planner matched on: under a case-sensitive
@@ -4656,66 +4972,96 @@ async function runScopedReplaceUnchecked(doc, args) {
     const fieldRanges = deletions.length > 0 ? await fieldResultRanges(doc, nodeId, block.text) : [];
     const fieldDeletionRisk = fieldRanges == null ||
         deletions.some((span) => fieldRanges.some((range) => span.start < range.end && span.end > range.start));
-    const exactTargets = !fieldDeletionRisk && (hasExplicitOccurrence || (tracked && uniqueFinds.size === planned.length));
-    let result = null;
-    let wroteExactTargets = false;
-    if (exactTargets) {
-        // A span already equal to its replacement has nothing to write, and the
-        // engine refuses a no-op target, which would sink its sibling edits.
-        const targetedSpans = [...planned]
-            .reverse()
-            .filter((span) => block.text.slice(span.start, span.end) !== span.replace);
-        const steps = targetedSpans.map((span, index) => ({
-            id: `scoped-replace-${index + 1}`,
-            op: 'text.rewrite',
-            where: {
-                by: 'target',
-                target: {
-                    kind: 'selection',
-                    start: { kind: 'text', blockId: nodeId, offset: span.start },
-                    end: { kind: 'text', blockId: nodeId, offset: span.end },
-                },
+    return !fieldDeletionRisk && (hasExplicitOccurrence || granular || (tracked && uniqueFinds.size === planned.length));
+}
+async function executeExactScopedTargets(doc, target, plan, { changeMode, granularity }) {
+    const { pre, nodeId, block } = target;
+    const targetedSpans = [...plan.planned]
+        .reverse()
+        .filter((span) => block.text.slice(span.start, span.end) !== span.replace);
+    const steps = targetedSpans.map((span, index) => ({
+        id: `scoped-replace-${index + 1}`,
+        op: 'text.rewrite',
+        where: {
+            by: 'target',
+            target: {
+                kind: 'selection',
+                start: { kind: 'text', blockId: nodeId, offset: span.start },
+                end: { kind: 'text', blockId: nodeId, offset: span.end },
             },
-            args: { replacement: { text: span.replace }, style: preserveRewriteStyle() },
-        }));
-        if (steps.length === 0) {
-            result = { noop: true };
-        }
-        else {
-            // The engine resolves these offsets against its own paragraph text. Check
-            // that each one still covers the text matched in the snapshot, so a
-            // projection mismatch never rewrites other text.
-            const preview = await previewMutations(doc, steps, args.changeMode, pre.revision);
-            const previewSteps = Array.isArray(preview.steps) ? preview.steps.filter(isRecord) : [];
-            const aligned = preview.valid === true &&
-                steps.every((step, index) => {
-                    const resolutions = previewSteps.find((candidate) => candidate.stepId === step.id)?.resolutions;
-                    const resolved = Array.isArray(resolutions) && isRecord(resolutions[0]) ? resolutions[0].text : undefined;
-                    const span = targetedSpans[index];
-                    return resolved === block.text.slice(span.start, span.end);
-                });
-            if (aligned) {
-                result = await executeMutations(doc, steps, args.changeMode, pre.revision);
-                wroteExactTargets = true;
-            }
-            else if (hasExplicitOccurrence) {
-                return failedReceipt('replace_text', new SuperDocCliError('replace_text: the chosen occurrence does not resolve to the same text in the document. Inspect again before editing.', { code: 'TARGET_NOT_FOUND' }), pre);
-            }
-        }
+        },
+        args: {
+            replacement: { text: span.replace },
+            style: preserveRewriteStyle(),
+            ...replacementGranularityArg(granularity),
+        },
+    }));
+    if (steps.length === 0)
+        return { result: { noop: true }, wroteExactTargets: false };
+    const preview = await previewMutations(doc, steps, changeMode, pre.revision);
+    const previewSteps = Array.isArray(preview.steps) ? preview.steps.filter(isRecord) : [];
+    const aligned = preview.valid === true &&
+        steps.every((step, index) => {
+            const resolutions = previewSteps.find((candidate) => candidate.stepId === step.id)?.resolutions;
+            const resolved = Array.isArray(resolutions) && isRecord(resolutions[0]) ? resolutions[0].text : undefined;
+            const span = targetedSpans[index];
+            return resolved === block.text.slice(span.start, span.end);
+        });
+    if (aligned) {
+        return { result: await executeMutations(doc, steps, changeMode, pre.revision), wroteExactTargets: true };
     }
-    if (result == null) {
-        // The engine preserves runs while applying the text diff. A separate
-        // formatting pass would restyle unchanged text and split the undo unit.
-        const steps = [
-            {
-                id: 'scoped-replace-1',
-                op: 'text.rewrite',
-                where: { by: 'block', nodeType: block.nodeType, nodeId },
-                args: { replacement: { text: expected }, style: preserveRewriteStyle() },
-            },
-        ];
-        result = await executeMutations(doc, steps, args.changeMode, pre.revision);
+    const planLimit = previewFailuresOf(preview).find((failure) => failure.code === 'PLAN_LIMIT_EXCEEDED');
+    if (planLimit && (plan.hasExplicitOccurrence || granularity !== undefined)) {
+        return { receipt: failedReceipt('replace_text', previewRefusal(planLimit), pre) };
+    }
+    if (plan.hasExplicitOccurrence) {
+        return {
+            receipt: failedReceipt('replace_text', new SuperDocCliError('replace_text: the chosen occurrence does not resolve to the same text in the document. Inspect again before editing.', { code: 'TARGET_NOT_FOUND' }), pre),
+        };
+    }
+    if (granularity !== undefined) {
+        const refusal = paragraphCrossingError(target, plan) ??
+            (preview.valid !== true
+                ? previewRefusal(previewFailuresOf(preview)[0])
+                : new SuperDocCliError('replace_text: a find does not resolve to the same text in the document, so nothing was written. Inspect again before editing.', { code: 'TARGET_NOT_FOUND' }));
+        return { receipt: failedReceipt('replace_text', refusal, pre) };
+    }
+    return { result: null, wroteExactTargets: false };
+}
+function paragraphCrossingError({ pre, nodeId }, plan) {
+    const cell = (pre.tables ?? []).flatMap((table) => table.cells).find((candidate) => candidate.nodeId === nodeId);
+    const firstParagraphEnd = cell ? cell.text.indexOf('\n') : -1;
+    if (firstParagraphEnd < 0 || plan.planned.every((span) => span.end <= firstParagraphEnd))
+        return null;
+    return new SuperDocCliError('replace_text: granularity writes inside one paragraph, and the selected table cell holds several. Call replace_text without a selector so each find resolves to its own paragraph.', { code: 'INVALID_ARGUMENT' });
+}
+async function executeScopedRewrite(doc, target, plan, args, tracked) {
+    if (await writesExactScopedTargets(doc, target, plan, tracked, args.granularity !== undefined)) {
+        const exact = await executeExactScopedTargets(doc, target, plan, args);
+        if ('receipt' in exact)
+            return exact;
+        if (exact.result != null)
+            return { result: exact.result, wroteExactTargets: exact.wroteExactTargets };
+    }
+    const steps = [
+        {
+            id: 'scoped-replace-1',
+            op: 'text.rewrite',
+            where: { by: 'block', nodeType: target.block.nodeType, nodeId: target.nodeId },
+            args: { replacement: { text: plan.expected }, style: preserveRewriteStyle() },
+        },
+    ];
+    return { result: await executeMutations(doc, steps, args.changeMode, target.pre.revision), wroteExactTargets: false };
+}
+async function readScopedReplaceBack(doc, target, plan, execution) {
+    try {
+        return await readScopedReplaceBackUnchecked(doc, target, plan, execution);
     }
+    catch (readError) {
+        return { post: null, postBlock: null, rolledBack: false, readError };
+    }
+}
+async function readScopedReplaceBackUnchecked(doc, { nodeId, block }, plan, execution) {
     let post = await buildMutationSnapshot(doc, { includeDomains: ['blocks', 'tables'] });
     let postBlock = findTextTarget(post, nodeId);
     // Exact-target edits must leave exactly the planned visible text. If the
@@ -4723,10 +5069,11 @@ async function runScopedReplaceUnchecked(doc, args) {
     // atomic history step. Only do so while the document is still at the
     // revision this plan produced, so the undo cannot reach any other change.
     let rolledBack = false;
+    const { result } = execution;
     const appliedRevision = isRecord(result) && isRecord(result.revision) ? result.revision.after : undefined;
-    if (wroteExactTargets &&
+    if (execution.wroteExactTargets &&
         postBlock != null &&
-        postBlock.text !== expected &&
+        postBlock.text !== plan.expected &&
         postBlock.text !== block.text &&
         typeof appliedRevision === 'string' &&
         appliedRevision === post.revision) {
@@ -4738,14 +5085,23 @@ async function runScopedReplaceUnchecked(doc, args) {
             rolledBack = postBlock?.text === block.text;
         }
     }
+    return { post, postBlock, rolledBack };
+}
+function buildScopedReplaceReceipt({ pre, nodeId, block }, plan, execution, { post, postBlock, rolledBack, readError }, tracked) {
+    const { perEdit, skippedEdits, planned, droppedOverlaps, expected, hasExplicitOccurrence } = plan;
     // Block text is the visible (final) text. Exact-offset edits must produce
     // exactly the planned text; tracked edits that fell back to a whole-block
     // rewrite only need each inserted text to be visible.
     const passed = postBlock != null &&
         !rolledBack &&
-        (tracked && !hasExplicitOccurrence && !wroteExactTargets
+        (tracked && !hasExplicitOccurrence && !execution.wroteExactTargets
             ? planned.every((span) => span.replace.length === 0 || postBlock.text.includes(span.replace))
             : postBlock.text === expected);
+    const readsAsReplacement = (span) => block.text.slice(span.start, span.end) === span.replace;
+    const replaced = planned.filter((span) => !readsAsReplacement(span));
+    const editsApplied = perEdit
+        .map((edit, index) => ({ ...edit, occurrences: replaced.filter((span) => span.editIndex === index).length }))
+        .filter((edit) => edit.occurrences > 0);
     // Partially-applied requests must NOT read as success: a model that asked
     // for two edits and got one will stop if the receipt says "ok".
     const status = !passed ? 'failed' : skippedEdits.length > 0 ? 'partial' : 'ok';
@@ -4769,24 +5125,42 @@ async function runScopedReplaceUnchecked(doc, args) {
                 ],
             }
             : {}),
+        ...(post === null ? { errors: [readBackError(readError)] } : {}),
         preSnapshot: { revision: pre.revision },
-        postSnapshot: { revision: post.revision },
+        ...(post ? { postSnapshot: { revision: post.revision } } : {}),
         selectedBlock: { nodeId, nodeType: block.nodeType },
         editsRequested: perEdit.length,
-        editsApplied: appliedEdits,
+        editsApplied,
+        ...unchangedEditsEvidence(planned.filter(readsAsReplacement)),
         ...(skippedEdits.length > 0
             ? { editsSkipped: skippedEdits.map((e) => ({ find: e.find, reason: 'not present in selected block' })) }
             : {}),
         ...(droppedOverlaps.length > 0 ? { overlapsDropped: droppedOverlaps.map((s) => s.find) } : {}),
-        replacedSpans: planned.length,
+        replacedSpans: replaced.length,
         postText: snippetAround(postBlock?.text ?? ''),
-        executedOperations: [{ operationId: 'doc.mutations.apply', result: compactOpResult(result) }],
+        executedOperations: [{ operationId: 'doc.mutations.apply', result: compactOpResult(execution.result) }],
         verification: [
             { check: { kind: 'block-text-matches-expectation' }, passed },
-            { check: { kind: 'revision-changed' }, passed: pre.revision !== post.revision },
+            post
+                ? { check: { kind: 'revision-changed' }, passed: pre.revision !== post.revision }
+                : readBackFailure(readError),
         ],
     };
 }
+async function runScopedReplaceUnchecked(doc, args) {
+    const target = await resolveScopedReplaceTarget(doc, args);
+    if ('receipt' in target)
+        return target.receipt;
+    const plan = planScopedReplaceSpans(args, target);
+    if ('receipt' in plan)
+        return plan.receipt;
+    const tracked = (args.changeMode ?? 'direct') === 'tracked';
+    const execution = await executeScopedRewrite(doc, target, plan, args, tracked);
+    if ('receipt' in execution)
+        return execution.receipt;
+    const readBack = await readScopedReplaceBack(doc, target, plan, execution);
+    return buildScopedReplaceReceipt(target, plan, execution, readBack, tracked);
+}
 async function runScopedReplace(doc, args) {
     const changeMode = args.changeMode ?? 'direct';
     try {
@@ -4807,48 +5181,6 @@ async function runScopedReplace(doc, args) {
  */
 /** Points → twips: the node read side reports points, mutations take twips. */
 const TWIPS_PER_POINT = 20;
-/**
- * Build `format.paragraph.setMarkRunProps` input from agent run marks.
- *
- * The mark's colour is a discriminated model object, not the plain hex string
- * `format.apply` takes, and the hex is stored without the leading `#`.
- * Returns null when the marks say nothing about the mark's appearance.
- */
-function markRunPropsFromMarks(marks) {
-    if (!marks)
-        return null;
-    const props = {};
-    if (typeof marks.bold === 'boolean')
-        props.bold = marks.bold;
-    if (typeof marks.italic === 'boolean')
-        props.italic = marks.italic;
-    if (typeof marks.fontFamily === 'string' && marks.fontFamily)
-        props.fontFamily = marks.fontFamily;
-    if (typeof marks.fontSize === 'number' && Number.isFinite(marks.fontSize))
-        props.fontSize = marks.fontSize;
-    if (typeof marks.color === 'string' && marks.color) {
-        props.color = { model: 'rgb', value: marks.color.replace(/^#/, '') };
-    }
-    return Object.keys(props).length > 0 ? props : null;
-}
-/**
- * Pull a paragraph's MARK run properties (`w:pPr/w:rPr`) out of a `getNodeById`
- * payload, ready to hand straight back to `format.paragraph.setMarkRunProps`
- * (same internal shape, so the values round-trip). Node-shape tolerant like
- * paragraphIndentOf. Returns null when the paragraph mark carries nothing.
- */
-function paragraphMarkRunPropsOf(payload) {
-    const node = isRecord(payload) ? payload.node : null;
-    if (!isRecord(node))
-        return null;
-    const candidates = [isRecord(node.paragraph) ? node.paragraph.props : null, node.props];
-    for (const props of candidates) {
-        const mark = isRecord(props) ? props.markRunProps : null;
-        if (isRecord(mark) && Object.keys(mark).length > 0)
-            return mark;
-    }
-    return null;
-}
 /**
  * Delimiters that separate a list item's lead-in label from its body text.
  * Spaced dashes are listed separately from bare ones because the label run
@@ -5052,6 +5384,7 @@ function matchRunStyle(run) {
     return {
         bold: effective?.bold === true,
         italic: effective?.italic === true,
+        underline: effective?.underline === true,
         ...(sizePt != null && Number.isFinite(sizePt) ? { fontSize: sizePt } : {}),
         ...(fontFamily ? { fontFamily } : {}),
         ...(color ? { color } : {}),
@@ -5063,15 +5396,15 @@ function matchRunStyle(run) {
  * A toggle that is OFF is dropped rather than sent as an explicit `false`: new
  * text starts unformatted, so "not bold" needs no write — and writing it would
  * stamp an explicit `w:b w:val="0"` the sampled siblings themselves don't carry.
- * The exception is a toggle that must be CLEARED because an earlier layer
- * (`against`) turned it on.
  */
-function inlineFromMatchStyle(style, against) {
+function inlineFromMatchStyle(style) {
     const inline = {};
-    if (style.bold || against?.bold === true)
-        inline.bold = style.bold;
-    if (style.italic || against?.italic === true)
-        inline.italic = style.italic;
+    if (style.bold)
+        inline.bold = true;
+    if (style.italic)
+        inline.italic = true;
+    if (style.underline)
+        inline.underline = true;
     if (style.fontSize != null)
         inline.fontSize = style.fontSize;
     if (style.fontFamily)
@@ -5080,6 +5413,10 @@ function inlineFromMatchStyle(style, against) {
         inline.color = style.color;
     return inline;
 }
+function runPatternOf(bodyStyle, label) {
+    const look = label ? emphasisedLookOf(inlineFromMatchStyle(label.style)) : null;
+    return { body: baseRunLookOf(bodyStyle), ...(label && look ? { lead: { look, shape: label.shape } } : {}) };
+}
 /**
  * Read an existing list item's RUN PATTERN — the body look plus the "bold
  * label: plain sentence" lead-in convention its siblings share — through
@@ -5137,27 +5474,16 @@ async function listItemRunPattern(doc, text, blockId) {
             const label = runs[labelIndex];
             const labelText = runTextOf(label);
             const leadStyle = matchRunStyle(label);
-            // A source block that is ONLY a short emphasised label (a heading-ish "LLM
-            // Integration", a signature-block name) has no body look to copy — and
-            // copying its label look over a whole new block would emphasise the
-            // entire thing. Treat it as a lead-in whose span the new text decides.
-            if (runs.length === 1) {
-                const labelOnly = labelText.length <= LEAD_IN_MAX_CHARS && (leadStyle.bold || leadStyle.italic);
-                return labelOnly
-                    ? { body: {}, lead: { look: inlineFromMatchStyle(leadStyle), shape: { kind: 'before', delimiter: null } } }
-                    : { body: inlineFromMatchStyle(leadStyle) };
-            }
+            if (runs.length === 1)
+                return runPatternOf(leadStyle);
             // The body is the run the label INTRODUCES, not the longest run in the
             // block: a later emphasised phrase is part of the prose, and sampling it
             // would stamp its emphasis across the whole new block.
             const bodyStyle = matchRunStyle(runs[labelIndex + 1]);
-            const differs = ['bold', 'italic', 'fontSize', 'fontFamily', 'color'].some((k) => leadStyle[k] !== bodyStyle[k]);
+            const differs = ['bold', 'italic', 'underline', 'fontSize', 'fontFamily', 'color'].some((k) => leadStyle[k] !== bodyStyle[k]);
             const shape = leadInShapeOf(blockText, labelText, labelIndex > 0 ? quote : undefined);
             const isLabel = differs && shape != null && labelText.length > 0 && labelText.length <= LEAD_IN_MAX_CHARS;
-            return {
-                body: inlineFromMatchStyle(bodyStyle),
-                ...(isLabel ? { lead: { look: inlineFromMatchStyle(leadStyle, bodyStyle), shape: shape } } : {}),
-            };
+            return runPatternOf(bodyStyle, isLabel && shape ? { style: leadStyle, shape } : undefined);
         }
     }
     return null;
@@ -5175,10 +5501,9 @@ function typedPrefixLabelOf(runs, runTextOf) {
     }
     if (covered < markerEnd || labelIndex + 1 >= runs.length)
         return null;
-    const underlined = (run) => asRecord(asRecord(asRecord(run)?.styles)?.effective)?.underline === true;
     const emphasisOf = (run) => {
         const style = matchRunStyle(run);
-        return `${style.bold}/${style.italic}/${underlined(run)}`;
+        return `${style.bold}/${style.italic}/${style.underline}`;
     };
     const label = runs[labelIndex];
     if (emphasisOf(label) === 'false/false/false')
@@ -5205,15 +5530,10 @@ function typedPrefixLabelOf(runs, runTextOf) {
     const delimiter = ['.', ...LEAD_IN_DELIMITERS.map((d) => d.trim())].find((d) => labelText.endsWith(d) && labelText.length > d.length);
     if (!delimiter)
         return null;
-    const body = runs[bodyIndex];
-    const leadStyle = matchRunStyle(label);
-    const bodyStyle = matchRunStyle(body);
-    const leadUnderline = underlined(label);
-    const bodyUnderline = underlined(body);
-    const look = inlineFromMatchStyle(leadStyle, bodyStyle);
-    if (leadUnderline || bodyUnderline)
-        look.underline = leadUnderline;
-    return { body: inlineFromMatchStyle(bodyStyle), lead: { look, shape: { kind: 'typed', delimiter } } };
+    return runPatternOf(matchRunStyle(runs[bodyIndex]), {
+        style: matchRunStyle(label),
+        shape: { kind: 'typed', delimiter },
+    });
 }
 /**
  * Pull a paragraph's direct indentation out of a `getNodeById` payload and
@@ -5244,12 +5564,32 @@ function paragraphIndentOf(payload) {
     }
     return null;
 }
-function inlineLookFromRow(row) {
+function emphasisedLookOf(look) {
+    return RUN_BOOL_MARKS.some((key) => look[key] === true) ? look : null;
+}
+async function effectiveBaseLookOf(doc, text, block) {
+    const queryFn = maybeMethod(doc, ['query', 'match']);
+    if (!queryFn || !text.trim())
+        return null;
+    const runs = await matchRunsForBlock(queryFn, text, block.nodeId, { nodeType: block.nodeType, fonts: 'effective' });
+    const looks = runs.filter((run) => run.text).map(baseRunLookOf);
+    if (looks.length === 0)
+        return null;
+    const [first, ...rest] = looks;
+    return rest.every((look) => look.fontFamily === first.fontFamily && look.fontSize === first.fontSize)
+        ? first
+        : 'mixed';
+}
+function baseRunLookOf(look) {
     const inline = {};
-    if (row.fontFamily)
-        inline.fontFamily = row.fontFamily;
-    if (typeof row.fontSize === 'number')
-        inline.fontSize = row.fontSize;
+    if (typeof look.fontFamily === 'string' && look.fontFamily)
+        inline.fontFamily = look.fontFamily;
+    if (typeof look.fontSize === 'number' && Number.isFinite(look.fontSize))
+        inline.fontSize = look.fontSize;
+    return inline;
+}
+function inlineLookFromRow(row) {
+    const inline = baseRunLookOf(row);
     if (row.color)
         inline.color = row.color;
     if (row.bold === true)
@@ -6144,17 +6484,11 @@ async function matchOneBlock(doc, postBlocks, preIds, created, createdIndex, anc
                 }
             }
         }
-        // Same "inline look" the style-copy paths use, minus properties the
-        // create already produced — contextual matching only applies the DELTA.
-        const inline = inlineLookFromRow(reference);
+        const inline = baseRunLookOf(reference);
         if (inline.fontFamily === created.fontFamily)
             delete inline.fontFamily;
         if (inline.fontSize === created.fontSize)
             delete inline.fontSize;
-        if (inline.color === created.color)
-            delete inline.color;
-        if (created.bold === true)
-            delete inline.bold;
         if (Object.keys(inline).length > 0) {
             const formatApplyFn = maybeMethod(doc, ['format', 'apply']);
             if (formatApplyFn) {
@@ -6195,15 +6529,14 @@ async function matchOneBlock(doc, postBlocks, preIds, created, createdIndex, anc
         // created block. Skipped when the caller supplied explicit runs/marks.
         if (allowLeadPattern) {
             const lead = await matchLeadMarkerPattern(doc, reference, created, createdText);
-            if (lead)
+            if (lead?.changed)
                 applied.leadMarker = lead;
             // matchLeadMarkerPattern only knows a shared literal lead ("WHEREAS") and
             // numbered tokens ("1.", "(m)"), and it needs the reference split across
             // two runs. Sample the reference's RUNS for everything else: a quoted
             // defined term (`"Deliverables" means …`), a "1.7. Records. " clause whose
-            // marker and label share a run, and — the case nothing covered — a
-            // UNIFORM reference, where the whole look transfers (a bold signature-block
-            // name beside which the new one landed plain).
+            // marker and label share a run. A UNIFORM reference is not a split, so
+            // its emphasis never transfers.
             else {
                 const runPattern = await matchBlockRunPattern(doc, reference, created, createdText);
                 // Assigning `undefined` would still create the key, and an `applied` with
@@ -6268,10 +6601,9 @@ const LEAD_MARKER_PATTERN = /^\(?(?:[a-zA-Z]{1,3}|\d{1,3})[).:\]]/;
  *    created text starts with the reference's exact lead text;
  *  - marker tokens ("(m)", "1.", "a)"): the token text differs per clause, so
  *    the created lead is its OWN token matched by shape.
- * Applies the reference lead's marks to the created lead span and the
- * reference body's marks to the rest — with explicit false for boolean marks
- * only one side has, so formatting inherited from a mis-styled anchor is
- * corrected, not compounded.
+ * Applies the reference lead's marks to the created lead span and only the
+ * reference body's font and size to the rest: the body never gains emphasis or
+ * an explicit mark-off it did not already carry.
  */
 async function matchLeadMarkerPattern(doc, reference, created, createdText) {
     const createdPreview = created.textPreview ?? '';
@@ -6331,21 +6663,16 @@ async function matchLeadMarkerPattern(doc, reference, created, createdText) {
     }
     if (createdLeadLen === 0)
         return null;
-    const normalize = new Set(RUN_BOOL_MARKS.filter((key) => leadRun[key] !== bodyRun[key]));
-    const markerInline = inlineFromSnapshotRun(leadRun, normalize);
-    const bodyInline = inlineFromSnapshotRun(bodyRun, normalize);
-    if (Object.keys(markerInline).length === 0 && Object.keys(bodyInline).length === 0)
+    const markerInline = emphasisedLookOf(inlineFromSnapshotRun(leadRun));
+    if (!markerInline)
         return null;
-    let changed = false;
-    if (Object.keys(markerInline).length > 0) {
-        changed =
-            (await applyInlineQuiet(formatFn, {
-                blockId: created.nodeId,
-                start: 0,
-                end: createdLeadLen,
-                inline: markerInline,
-            })) || changed;
-    }
+    const bodyInline = baseRunLookOf(bodyRun);
+    let changed = await applyInlineQuiet(formatFn, {
+        blockId: created.nodeId,
+        start: 0,
+        end: createdLeadLen,
+        inline: markerInline,
+    });
     if (Object.keys(bodyInline).length > 0 && fullText.length > createdLeadLen) {
         changed =
             (await applyInlineQuiet(formatFn, {
@@ -6358,14 +6685,15 @@ async function matchLeadMarkerPattern(doc, reference, created, createdText) {
     return { marker: fullText.slice(0, createdLeadLen), markerInline, bodyInline, changed };
 }
 /**
- * Copy a reference block's RUN pattern onto a created block: the body look over
- * the whole block, then the label look over the new block's own label span.
+ * Copy a reference block's RUN pattern onto a created block: the body's font
+ * and size over the whole block, then the label look over the new block's own
+ * label span.
  *
  * Complements matchLeadMarkerPattern, which requires either a shared literal
  * lead word or a marker token AND a two-run reference. This one reads the
  * reference's runs (`query.match`, the only read that reports run styling) and
- * handles the shapes that leaves out — including a reference with a single
- * uniform run, whose look simply transfers.
+ * handles the shapes that leaves out. A single uniform run has no label, so
+ * nothing but its font transfers.
  */
 async function matchBlockRunPattern(doc, reference, created, createdText) {
     const formatFn = maybeMethod(doc, ['format', 'apply']);
@@ -6378,19 +6706,25 @@ async function matchBlockRunPattern(doc, reference, created, createdText) {
         return null;
     const end = Math.max(fullText.length, 1);
     const applied = {};
-    if (Object.keys(pattern.body).length > 0) {
-        if (await applyInlineQuiet(formatFn, { blockId: created.nodeId, start: 0, end, inline: pattern.body })) {
-            applied.body = pattern.body;
+    const sampled = pattern.body;
+    const own = Object.keys(sampled).length > 0
+        ? await effectiveBaseLookOf(doc, fullText, { nodeId: created.nodeId, nodeType: created.nodeType })
+        : null;
+    const body = own === 'mixed'
+        ? {}
+        : own
+            ? Object.fromEntries(Object.entries(sampled).filter(([key, value]) => own[key] !== value))
+            : sampled;
+    if (Object.keys(body).length > 0) {
+        if (await applyInlineQuiet(formatFn, { blockId: created.nodeId, start: 0, end, inline: body })) {
+            applied.body = body;
         }
     }
     if (pattern.lead) {
-        const span = leadInSpanOf(fullText, pattern.lead.shape);
-        // A uniform reference has no body look and no delimiter of its own: its look
-        // belongs to the whole created block, not to a label span inside it.
-        const range = span ??
-            (Object.keys(pattern.body).length === 0 && pattern.lead.shape.kind !== 'typed' ? { start: 0, end } : null);
-        if (range && (await applyInlineQuiet(formatFn, { blockId: created.nodeId, ...range, inline: pattern.lead.look }))) {
-            applied.lead = { ...pattern.lead.look, range: [range.start, range.end] };
+        const { look, shape } = pattern.lead;
+        const span = leadInSpanOf(fullText, shape);
+        if (span && (await applyInlineQuiet(formatFn, { blockId: created.nodeId, ...span, inline: look }))) {
+            applied.lead = { ...look, range: [span.start, span.end] };
         }
     }
     return Object.keys(applied).length > 0 ? { matchedSibling: reference.nodeId, ...applied } : null;
@@ -6745,25 +7079,26 @@ async function dispatchSuperdocPerformAction(doc, args) {
                 });
             }
             const changeMode = parseReplaceTextChangeMode(args.changeMode);
+            const parsedGranularity = parseReplacementGranularity(args.granularity);
+            const granularity = changeMode === 'tracked' ? parsedGranularity : undefined;
             // Selector-scoped replaces take the span-targeted path: per-find
             // text.rewrite spans inside the one selected block, so tabs/breaks/
             // images outside the spans survive and the receipt reports per-edit
             // applied/skipped truth.
-            const scoped = parseScopedReplaceArgs(args, edits, changeMode, expectedRevision);
+            const scoped = parseScopedReplaceArgs(args, edits, changeMode, expectedRevision, granularity);
             if (scoped) {
                 return runScopedReplace(doc, scoped);
             }
-            const selector = args.selector != null ? parseSelector(args.selector) : undefined;
-            if (args.selector != null && selector == null) {
+            if (args.selector != null) {
                 throw new SuperDocCliError('replace_text: invalid "selector"', { code: 'INVALID_ARGUMENT' });
             }
             return runReplaceText(doc, {
                 action,
                 edits,
-                selector,
                 caseSensitive: args.caseSensitive === true,
                 expectedRevision,
                 changeMode,
+                ...(granularity !== undefined ? { granularity } : {}),
             });
         }
         case 'delete_text': {
@@ -7407,9 +7742,30 @@ function parseReplaceTextChangeMode(value) {
     });
 }
 function parseTrackedChangeKind(value) {
-    if (value === 'insert' || value === 'delete' || value === 'replacement' || value === 'format')
-        return value;
-    return undefined;
+    return typeof value === 'string' ? trackedChangeKindOf(value) : undefined;
+}
+const TRACKED_CHANGE_KIND_BY_LIST_TYPE = {
+    insert: 'insert',
+    insertion: 'insert',
+    delete: 'delete',
+    deletion: 'delete',
+    replacement: 'replacement',
+    format: 'format',
+    formatting: 'format',
+};
+function trackedChangeKindOf(type) {
+    return type !== undefined && Object.hasOwn(TRACKED_CHANGE_KIND_BY_LIST_TYPE, type)
+        ? TRACKED_CHANGE_KIND_BY_LIST_TYPE[type]
+        : undefined;
+}
+function countTrackedChangesByKind(items) {
+    const counts = {};
+    for (const item of items) {
+        const type = asString(item?.type);
+        const kind = trackedChangeKindOf(type) ?? (type || 'unknown');
+        counts[kind] = (counts[kind] ?? 0) + 1;
+    }
+    return counts;
 }
 function parseStringArray(value) {
     if (!Array.isArray(value))