@superdoc/sdk 2.9.1-next.2 → 2.10.0-next.10

package/dist/agent/actions.cjs

@@ -1,5 +1,6 @@
 'use strict';
 
+var executionContext = require('./execution-context.cjs');
 var errors = require('../runtime/errors.cjs');
 var listTransform = require('../action-primitives/tools/list-transform.cjs');
 var structureInsert = require('../action-primitives/tools/structure-insert.cjs');
@@ -170,18 +171,18 @@ const ACTION_GROUPS = [
  * action at compile time.
  */
 const ACTION_ARGS = {
-    insert_paragraphs: ['text', 'texts', 'headingLevel', 'placement', 'changeMode'],
+    insert_paragraphs: ['text', 'texts', 'headingLevel', 'placement', 'changeMode', 'evidence'],
     insert_heading: ['text', 'level', 'placement', 'changeMode'],
     replace_text: ['edits', 'selector', 'caseSensitive', 'changeMode'],
     delete_text: ['finds', 'selector', 'caseSensitive', 'changeMode'],
     delete_blocks: ['selectors', 'selector', 'changeMode'],
     append_list: ['items', 'kind', 'headingText', 'headingLevel', 'placement', 'changeMode'],
-    create_table: ['rows', 'columns', 'cellTexts', 'placement', 'changeMode'],
+    create_table: ['rows', 'columns', 'cellTexts', 'placement', 'changeMode', 'evidence'],
     comment_paragraphs: ['commentText', 'scope', 'excludeBlockQuotes'],
     add_comments: ['commentText', 'selector', 'selectors'],
     resolve_comments: ['anchorText', 'reopen'],
     reply_to_comment: ['commentText', 'anchorText', 'commentId'],
-    rewrite_block: ['text', 'selector', 'changeMode'],
+    rewrite_block: ['text', 'selector', 'changeMode', 'evidence'],
     accept_tracked_changes: ['author', 'changeType'],
     reject_tracked_changes: ['author', 'changeType'],
     normalize_body_font_size: ['fontSize', 'changeMode'],
@@ -216,7 +217,7 @@ const ACTION_ARGS = {
         'changeMode',
     ],
     apply_style: ['selector', 'styleId', 'headingLevel', 'likeText'],
-    format_paragraph: ['selector', 'alignment', 'changeMode'],
+    format_paragraph: ['selector', 'alignment', 'changeMode', 'evidence'],
     move_text: ['text', 'afterText', 'changeMode'],
     style_table: ['tableOrdinal', 'accentColor'],
     move_table: ['tableOrdinal', 'placement'],
@@ -319,10 +320,6 @@ function findSnapshotTextByNodeId(snapshot, nodeId) {
     }
     return null;
 }
-function lastBlock(snapshot) {
-    const block = snapshot.blocks[snapshot.blocks.length - 1];
-    return block ? { nodeId: block.nodeId, nodeType: block.nodeType } : null;
-}
 function createdBlockTarget(result) {
     const rec = asRecord(result);
     const paragraph = asRecord(rec?.paragraph);
@@ -514,6 +511,8 @@ function revisionVerification(preRevision, postRevision, expectChanged) {
 }
 function failedReceipt(intent, err, preSnapshot) {
     const message = reasonOf(err);
+    const snapshotError = err instanceof docSnapshot.MutationSnapshotError ? err : null;
+    const errorCode = snapshotError?.code ?? asString(asRecord(err)?.code) ?? 'ACTION_FAILED';
     return {
         status: 'failed',
         intent,
@@ -523,7 +522,13 @@ function failedReceipt(intent, err, preSnapshot) {
         selectedTargets: [],
         executedOperations: [],
         verification: [],
-        errors: [{ code: 'ACTION_FAILED', message }],
+        errors: [
+            {
+                code: errorCode,
+                message,
+                ...(snapshotError || errorCode === 'REVISION_CONFLICT' ? { recovery: { kind: 'reinspect' } } : {}),
+            },
+        ],
     };
 }
 async function receiptFromWorkflowResult(doc, intent, pre, workflowResult, selectedTargets = [], checks = [{ kind: 'revision-changed' }]) {
@@ -567,14 +572,16 @@ async function receiptFromWorkflowResult(doc, intent, pre, workflowResult, selec
 }
 function buildFullBlockTextTarget(snapshot, blockId) {
     const block = snapshot.blocks.find((entry) => entry.nodeId === blockId);
-    if (!block)
+    const cell = block ? null : snapshot.tables.flatMap((table) => table.cells).find((entry) => entry.nodeId === blockId);
+    const text = block?.text ?? cell?.text;
+    if (text == null)
         return null;
     return {
         kind: 'text',
         blockId,
         range: {
             start: 0,
-            end: block.text.length,
+            end: text.length,
         },
     };
 }
@@ -627,8 +634,8 @@ function evaluateChecks(pre, post, checks) {
         else if (check.kind === 'comment-count-delta') {
             results.push({
                 check,
-                passed: post.comments.length - pre.comments.length === check.delta,
-                detail: `pre=${pre.comments.length} post=${post.comments.length}`,
+                passed: post.counts.comments - pre.counts.comments === check.delta,
+                detail: `pre=${pre.counts.comments} post=${post.counts.comments}`,
             });
         }
         else if (check.kind === 'tracked-change-count-delta') {
@@ -775,13 +782,28 @@ async function executeCreateHeading(doc, text, level, placement, changeMode) {
     // Dual dialect — see executeCreateParagraph.
     return fn(params, changeMode ? { changeMode } : undefined);
 }
-async function executeMutations(doc, steps, changeMode) {
+async function executeMutations(doc, steps, changeMode, expectedRevision) {
     const fn = maybeMethod(doc, ['mutations', 'apply']);
     if (!fn)
         throw new errors.SuperDocCliError('doc.mutations.apply is not available on the document handle.', {
             code: 'TOOL_DISPATCH_NOT_FOUND',
         });
-    return fn({ atomic: true, changeMode: changeMode ?? 'direct', steps });
+    return fn({
+        atomic: true,
+        changeMode: changeMode ?? 'direct',
+        steps,
+        ...(expectedRevision ? { expectedRevision } : {}),
+    });
+}
+async function previewMutations(doc, steps, changeMode, expectedRevision) {
+    const fn = maybeMethod(doc, ['mutations', 'preview']);
+    if (!fn) {
+        throw new errors.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 });
+    return isRecord(result) ? result : {};
 }
 async function executeCreateTable(doc, args, placement) {
     const fn = maybeMethod(doc, ['create', 'table']);
@@ -835,7 +857,7 @@ forceDirectFill = false) {
         });
     }
     const extracted = asRecord(await extractFn({}));
-    const blocks = (Array.isArray(extracted?.blocks) ? extracted?.blocks : [])
+    const blocks = (Array.isArray(extracted?.blocks) ? extracted.blocks : [])
         .map((block) => asRecord(block))
         .filter((block) => block != null)
         .flatMap((block) => {
@@ -1024,97 +1046,74 @@ async function styleTableCells(doc, cells, changeMode) {
     await applyItemStyling(doc, nodeIds, specs, changeMode);
     return styled.length;
 }
-async function runInsertParagraphs(doc, args) {
-    const pre = await docSnapshot.buildDocumentSnapshot(doc, { includeDomains: ['blocks'] });
+async function runInsertParagraphs(doc, args, formatArgs) {
+    const context = new executionContext.ExecutionContext(doc, { evidence: args.evidence, selectors: placementSelectors(args.placement) });
     try {
-        // `texts` is the canonical input; a single `text` is normalized to one item
-        // upstream in the dispatcher, but tolerate it here too.
-        const texts = args.texts ?? (args.text ? [args.text] : []);
-        const placement = resolvePlacement(args.placement, pre);
-        const executedOperations = [];
-        // Blank-line spacing between drafted paragraphs is only desirable when
-        // creating a NEW document (a blank doc has ~one empty block). Inserting into
-        // an existing doc must NOT scatter blank paragraphs through it.
-        const isNewDocument = (pre.counts?.blocks ?? 0) <= 1;
-        // For the first item: respect the requested placement and headingLevel.
-        // For subsequent items: append after the previously inserted block by
-        // using `documentEnd` (the SDK keeps blocks contiguous) so order is
-        // preserved.
+        const pre = await context.start();
+        const placement = await resolveFactPlacement(args.placement, pre);
+        const isNewDocument = (await pre.count()) <= 1;
+        const anchor = placement.kind === 'before' || placement.kind === 'after'
+            ? await pre.block(placement.target.nodeId)
+            : await pre.target({
+                kind: 'placement',
+                at: placement.kind === 'documentStart' ? 'document_start' : 'document_end',
+            });
+        const preRows = pre.complete ? await listBlockRows(doc) : anchor ? [anchor] : [];
         let currentPlacement = placement;
-        let headingFirst = false;
-        if (typeof args.headingLevel === 'number' && args.headingLevel >= 1 && args.headingLevel <= 6) {
-            headingFirst = true;
-        }
-        // Advance the insertion point to sit right after the block just created
-        // (prefer the receipt's created id; fall back to the document's last block).
-        const advanceAfter = async (result) => {
-            const created = createdBlockTarget(result);
-            if (created) {
-                return { kind: 'after', target: { kind: 'block', nodeType: created.nodeType, nodeId: created.nodeId } };
+        const nodeIds = [];
+        const specs = [];
+        const advance = async (result) => {
+            const target = createdBlockTarget(result);
+            if (target) {
+                currentPlacement = {
+                    kind: 'after',
+                    target: { kind: 'block', nodeType: target.nodeType, nodeId: target.nodeId },
+                };
+                return target.nodeId;
             }
-            const mid = await docSnapshot.buildDocumentSnapshot(doc, { includeDomains: ['blocks'] });
-            const last = lastBlock(mid);
-            return last
-                ? { kind: 'after', target: { kind: 'block', nodeType: last.nodeType, nodeId: last.nodeId } }
-                : { kind: 'documentEnd' };
+            const current = await context.finishRevision();
+            const last = await current.target({ kind: 'placement', at: 'document_end' });
+            if (!last)
+                throw new Error('Created paragraph identity is unavailable.');
+            currentPlacement = { kind: 'after', target: { kind: 'block', nodeType: last.nodeType, nodeId: last.nodeId } };
+            return last.nodeId;
         };
-        const styledNodeIds = [];
-        const styledSpecs = [];
-        for (let i = 0; i < texts.length; i += 1) {
-            const text = texts[i];
-            const isFirst = i === 0;
-            const result = isFirst && headingFirst
-                ? await executeCreateHeading(doc, text, args.headingLevel, currentPlacement, args.changeMode)
-                : await executeCreateParagraph(doc, text, currentPlacement, args.changeMode);
-            executedOperations.push({
-                operationId: isFirst && headingFirst ? 'doc.create.heading' : 'doc.create.paragraph',
-                result,
-            });
-            // Remember the created block for the post-insert styling pass when this
-            // paragraph carries a runs/marks spec.
-            const spec = args.textSpecs?.[i];
-            if (spec && ((spec.runs && spec.runs.length > 0) || spec.marks != null)) {
-                const created = createdBlockTarget(result);
-                if (created?.nodeId) {
-                    styledNodeIds.push(created.nodeId);
-                    styledSpecs.push({ ...spec, text });
-                }
-            }
-            currentPlacement = await advanceAfter(result);
-            // New-document drafts get a blank paragraph after each item for spacing;
-            // inserts into an existing document do not (would scatter blank lines).
-            if (isNewDocument) {
-                const spacer = await executeCreateParagraph(doc, '', currentPlacement, args.changeMode);
-                executedOperations.push({ operationId: 'doc.create.paragraph', result: spacer, rationale: 'spacing' });
-                currentPlacement = await advanceAfter(spacer);
+        const texts = args.texts ?? (args.text ? [args.text] : []);
+        for (let i = 0; i < texts.length; i++) {
+            const result = i === 0 && args.headingLevel
+                ? await executeCreateHeading(context.document, texts[i], args.headingLevel, currentPlacement, args.changeMode)
+                : await executeCreateParagraph(context.document, texts[i], currentPlacement, args.changeMode);
+            const id = await advance(result);
+            nodeIds.push(id);
+            specs.push({ ...args.textSpecs?.[i], text: texts[i] });
+            if (isNewDocument)
+                await advance(await executeCreateParagraph(context.document, '', currentPlacement, args.changeMode));
+        }
+        if (specs.some((spec) => spec.runs?.length || spec.marks))
+            await applyItemStyling(context.document, nodeIds, specs, args.changeMode);
+        let post = await context.finishRevision();
+        let formatted;
+        if (formatArgs) {
+            let localRows;
+            if (!pre.complete) {
+                const created = await post.page({ nodeIds, limit: Math.max(nodeIds.length, 1) });
+                localRows = [...(anchor ? [anchor] : []), ...created].sort((a, b) => a.ordinal - b.ordinal);
             }
+            const count = context.executedOperations.length;
+            formatted = await matchInsertedBlockFormatting(context.document, preRows, context.receipt('insert_paragraphs', []), formatArgs, localRows);
+            if (context.executedOperations.length !== count)
+                post = await context.finishRevision();
         }
-        if (styledNodeIds.length > 0) {
-            const styling = await applyItemStyling(doc, styledNodeIds, styledSpecs, args.changeMode);
-            executedOperations.push({
-                operationId: 'doc.format.apply',
-                result: styling,
-                rationale: `Styled ${styledNodeIds.length} inserted paragraph(s)`,
-            });
-        }
-        const postIdentity = await readDocumentIdentity(doc);
-        const verification = [revisionVerification(pre.revision, postIdentity.revision, true)];
-        return {
-            status: verification.every((v) => v.passed) ? 'ok' : 'failed',
-            intent: 'insert_paragraphs',
-            preSnapshot: { revision: pre.revision, counts: pre.counts },
-            postSnapshot: postIdentity,
-            selectedTargets: [],
-            executedOperations,
-            verification,
-        };
+        return context.receipt('insert_paragraphs', await executionContext.evaluateFactChecks(pre, post, [{ kind: 'revision-changed' }]), formatted?.contextualFormatting ? { contextualFormatting: formatted.contextualFormatting } : {});
     }
-    catch (err) {
-        return failedReceipt('insert_paragraphs', err, pre);
+    catch (error) {
+        return context.failure('insert_paragraphs', error);
     }
 }
 async function runInsertHeading(doc, args) {
-    const pre = await docSnapshot.buildDocumentSnapshot(doc, { includeDomains: ['blocks'] });
+    const pre = args.placement?.at === 'before' || args.placement?.at === 'after'
+        ? await docSnapshot.buildMutationSnapshot(doc, { includeDomains: ['blocks'] })
+        : await docSnapshot.buildDocumentSnapshot(doc, { includeDomains: ['blocks'] });
     try {
         const placement = resolvePlacement(args.placement, pre);
         const result = await executeCreateHeading(doc, args.text, args.level, placement, args.changeMode);
@@ -1136,10 +1135,10 @@ async function runInsertHeading(doc, args) {
 }
 async function runReplaceText(doc, args) {
     const selectorDomains = args.selector ? snapshotDomainsForSelector(args.selector) : null;
-    const requiresBlockSnapshot = args.selector != null || args.edits.length > 1;
+    const requiresBlockSnapshot = args.selector != null;
     const preIdentity = requiresBlockSnapshot ? null : await readDocumentIdentity(doc);
     const pre = requiresBlockSnapshot
-        ? await docSnapshot.buildDocumentSnapshot(doc, { includeDomains: selectorDomains ?? ['blocks'] })
+        ? await docSnapshot.buildMutationSnapshot(doc, { includeDomains: selectorDomains ?? ['blocks'] })
         : snapshotFromIdentity(preIdentity);
     try {
         if (args.edits.length === 0) {
@@ -1149,6 +1148,7 @@ async function runReplaceText(doc, args) {
         const selectedTargets = [];
         let skippedEdits = [];
         let steps;
+        let applyExpectedRevision;
         // Blocks whose text this call rewrites, with their pre-mutation run layout:
         // the engine replace lane renders the replaced range as uniform runs, so a
         // whole-paragraph find/replace flattens intra-paragraph formatting (bold
@@ -1190,6 +1190,7 @@ async function runReplaceText(doc, args) {
                     },
                 },
             ];
+            applyExpectedRevision = pre.revision;
             selectedTargets.push({ selector: args.selector, matched: [target.nodeId] });
             preserveTargets.push({
                 nodeId: target.nodeId,
@@ -1200,98 +1201,9 @@ async function runReplaceText(doc, args) {
             });
         }
         else {
-            const matchingEdits = args.edits.length === 1
-                ? args.edits
-                : args.edits.filter((edit) => pre.blocks.some((block) => textIncludes(block.text, edit.find, caseSensitive)));
-            skippedEdits = args.edits.filter((edit) => !matchingEdits.includes(edit));
-            if (matchingEdits.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',
-                        },
-                    ],
-                };
-            }
-            // Rewrite affected BODY blocks with block-targeted rewrites. The select
-            // (matched-range) rewrite lane flattens the WHOLE paragraph's runs in
-            // collaborative sessions and leaves format.apply inert on the block
-            // afterwards, so per-block rewrites + the preserve pass below are the
-            // only path that keeps intra-paragraph formatting alive. Bounded; edits
-            // that touch no scanned body block (e.g. header/footer text) fall back
-            // to a select-rewrite step.
-            // Tracked mode keeps the matched-range lane. A block rewrite asks the
-            // engine to delete and re-insert the WHOLE paragraph, so a reviewer sees
-            // the entire block struck and re-added instead of the words that changed,
-            // and each block contributes its own replacement/deletion pair. The
-            // per-block lane exists to keep intra-paragraph formatting alive, which
-            // is a direct-mode concern; under tracked mode the revision itself is the
-            // reviewable unit and must stay scoped to the edit.
-            const scanBlocks = args.changeMode === 'tracked'
-                ? []
-                : pre.blocks.length > 0
-                    ? pre.blocks
-                    : (await docSnapshot.buildDocumentSnapshot(doc, { includeDomains: ['blocks'] })).blocks;
-            // An edit counts as covered only when EVERY block holding it got a
-            // rewrite target. The per-block lane is bounded (run capture costs a read
-            // each), so a find present in more blocks than the cap must fall through
-            // to the select lane below, which carries `require: 'all'`. Marking such
-            // an edit covered after its first match would replace only the first
-            // PRESERVE_TARGET_CAP blocks and still report success.
-            const blocksHoldingEdit = matchingEdits.map((edit) => scanBlocks.filter((block) => block.nodeId && block.text && textIncludes(block.text, edit.find, caseSensitive))
-                .length);
-            const blocksCoveredForEdit = Array.from({ length: matchingEdits.length }, () => 0);
-            for (const block of scanBlocks) {
-                if (preserveTargets.length >= PRESERVE_TARGET_CAP)
-                    break;
-                if (!block.nodeId || !block.text)
-                    continue;
-                let newText = block.text;
-                const touched = [];
-                matchingEdits.forEach((edit, editIndex) => {
-                    if (textIncludes(newText, edit.find, caseSensitive)) {
-                        newText = replaceAllText(newText, edit.find, edit.replace, caseSensitive);
-                        touched.push(editIndex);
-                    }
-                });
-                if (newText === block.text)
-                    continue;
-                preserveTargets.push({
-                    nodeId: block.nodeId,
-                    nodeType: block.nodeType ?? 'paragraph',
-                    oldText: block.text,
-                    newText,
-                    runs: await captureBlockRuns(doc, block.nodeId, block.text),
-                });
-                for (const editIndex of touched)
-                    blocksCoveredForEdit[editIndex] += 1;
-            }
-            const coveredEdits = new Set(matchingEdits
-                .map((_edit, editIndex) => editIndex)
-                .filter((editIndex) => blocksHoldingEdit[editIndex] > 0 && blocksCoveredForEdit[editIndex] >= blocksHoldingEdit[editIndex]));
-            steps = [
-                ...preserveTargets.map((entry, index) => ({
-                    id: `replace-block-${index + 1}`,
-                    op: 'text.rewrite',
-                    where: { by: 'block', nodeType: entry.nodeType, nodeId: entry.nodeId },
-                    args: {
-                        replacement: { text: entry.newText },
-                        style: preserveRewriteStyle(),
-                    },
-                })),
-                // Edits that touched no scanned body block (header/footer text, or a
-                // doc larger than the scan window) keep the original select-rewrite.
-                ...matchingEdits
-                    .map((edit, editIndex) => ({ edit, editIndex }))
-                    .filter(({ editIndex }) => !coveredEdits.has(editIndex))
-                    .map(({ edit, editIndex }) => ({
+            let candidates = args.edits.map((edit, editIndex) => ({
+                edit,
+                step: {
                     id: `replace-${editIndex + 1}`,
                     op: 'text.rewrite',
                     where: {
@@ -1308,10 +1220,42 @@ async function runReplaceText(doc, 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);
+        const result = await executeMutations(doc, steps, args.changeMode, applyExpectedRevision);
         const preserved = [];
         for (const entry of preserveTargets) {
             const restored = await preserveRunPatternAfterRewrite(doc, entry.nodeId, entry.oldText, entry.runs, entry.newText);
@@ -1319,7 +1263,7 @@ async function runReplaceText(doc, args) {
                 preserved.push({ nodeId: entry.nodeId, ...restored });
         }
         if (args.selector && selectedTargets[0]) {
-            const post = await docSnapshot.buildDocumentSnapshot(doc, { includeDomains: selectorDomains ?? ['blocks'] });
+            const post = await docSnapshot.buildMutationSnapshot(doc, { includeDomains: selectorDomains ?? ['blocks'] });
             const blockId = selectedTargets[0].matched[0];
             const postTarget = findSnapshotTextByNodeId(post, blockId);
             const preTarget = findSnapshotTextByNodeId(pre, blockId);
@@ -1388,7 +1332,7 @@ async function runDeleteText(doc, args) {
     // path). Rewriting the block minus the finds keeps the deletion local — without
     // this a short/whitespace find matches document-wide and blows the target cap.
     if (args.selector) {
-        const scopedPre = await docSnapshot.buildDocumentSnapshot(doc, { includeDomains: snapshotDomainsForSelector(args.selector) });
+        const scopedPre = await docSnapshot.buildMutationSnapshot(doc, { includeDomains: snapshotDomainsForSelector(args.selector) });
         try {
             if (args.finds.length === 0) {
                 return failedReceipt('delete_text', new Error('finds must be non-empty'), scopedPre);
@@ -1431,7 +1375,7 @@ async function runDeleteText(doc, args) {
                     args: { replacement: { text: rewritten }, style: preserveRewriteStyle() },
                 },
             ];
-            const scopedResult = await executeMutations(doc, scopedSteps, args.changeMode);
+            const scopedResult = await executeMutations(doc, scopedSteps, args.changeMode, scopedPre.revision);
             const scopedPost = await docSnapshot.buildDocumentSnapshot(doc, { includeDomains: ['blocks'] });
             const verification = evaluateChecks(scopedPre, scopedPost, [{ kind: 'revision-changed' }]);
             return {
@@ -1493,7 +1437,7 @@ async function runDeleteText(doc, args) {
             },
             args: {},
         }));
-        const result = await executeMutations(doc, steps, args.changeMode);
+        const result = await executeMutations(doc, steps, args.changeMode, pre.revision);
         const revision = asRecord(asRecord(result)?.revision);
         const postIdentity = args.changeMode === 'tracked'
             ? await readDocumentIdentity(doc)
@@ -1536,7 +1480,7 @@ async function runDeleteBlocks(doc, args) {
         for (const domain of snapshotDomainsForSelector(selector))
             domains.add(domain);
     }
-    const pre = await docSnapshot.buildDocumentSnapshot(doc, { includeDomains: [...domains] });
+    const pre = await docSnapshot.buildMutationSnapshot(doc, { includeDomains: [...domains] });
     try {
         if (args.selectors.length === 0) {
             return failedReceipt('delete_blocks', new Error('selectors must be non-empty'), pre);
@@ -1629,7 +1573,7 @@ async function runDeleteBlocks(doc, args) {
                 });
             }
         }
-        const post = await docSnapshot.buildDocumentSnapshot(doc, { includeDomains: [...domains] });
+        const post = await docSnapshot.buildMutationSnapshot(doc, { includeDomains: [...domains] });
         // Tracked deletions leave the block in place until the revision is decided,
         // so the block count cannot move — count the structural revisions instead.
         // Direct deletions must show one fewer block of each deleted node type.
@@ -1747,7 +1691,7 @@ async function runInsertListItems(doc, args) {
     }
 }
 async function runAddListItems(doc, args, opts) {
-    const pre = await docSnapshot.buildDocumentSnapshot(doc, { includeDomains: ['blocks'] });
+    const pre = await docSnapshot.buildMutationSnapshot(doc, { includeDomains: ['blocks'] });
     try {
         const needle = args.anchorText?.trim();
         const anchorNodeId = args.anchorNodeId?.trim();
@@ -2280,56 +2224,79 @@ async function runSplitList(doc, args) {
         return failedReceipt('split_list', err, pre);
     }
 }
+async function resolveFactPlacement(placement, facts) {
+    if (!placement || placement.at === 'document_end')
+        return { kind: 'documentEnd' };
+    if (placement.at === 'document_start')
+        return { kind: 'documentStart' };
+    const target = await facts.target(placement.selector);
+    if (!target)
+        throw new errors.SuperDocCliError('placement selector did not resolve to a unique body block', {
+            code: 'INVALID_ARGUMENT',
+        });
+    return { kind: placement.at, target: { kind: 'block', nodeType: target.nodeType, nodeId: target.nodeId } };
+}
+function placementSelectors(placement) {
+    return placement?.at === 'before' || placement?.at === 'after' ? [placement.selector] : [];
+}
 async function runCreateTable(doc, args) {
-    const pre = await docSnapshot.buildDocumentSnapshot(doc);
+    const checks = [
+        { kind: 'revision-changed' },
+        { kind: 'block-count-delta', nodeType: 'table', delta: 1 },
+    ];
+    const context = new executionContext.ExecutionContext(doc, {
+        evidence: args.evidence,
+        selectors: placementSelectors(args.placement),
+        checks,
+    });
     try {
-        if (!Number.isInteger(args.rows) || args.rows < 1 || !Number.isInteger(args.columns) || args.columns < 1) {
-            return failedReceipt('create_table', new Error('rows and columns must be positive integers'), pre);
-        }
-        const placement = resolvePlacement(args.placement, pre);
-        const insertedTableOrdinal = estimateInsertedTableOrdinal(pre, placement);
-        const result = await executeCreateTable(doc, args, placement);
-        const executedOperations = [
-            { operationId: 'doc.create.table', result },
-        ];
-        const createdTableNodeId = asString(asRecord(asRecord(result)?.table)?.nodeId);
-        if (createdTableNodeId && args.cellTexts) {
-            const appliedCells = await applyTableCellTexts(doc, createdTableNodeId, insertedTableOrdinal, flattenCellTexts(args.cellTexts), args.changeMode);
-            if (appliedCells.length > 0) {
-                executedOperations.push({
-                    operationId: 'doc.mutations.apply',
-                    rationale: `Populated ${appliedCells.length} table cells.`,
-                });
+        if (!Number.isInteger(args.rows) || args.rows < 1 || !Number.isInteger(args.columns) || args.columns < 1)
+            throw new Error('rows and columns must be positive integers');
+        const pre = await context.start();
+        const placement = await resolveFactPlacement(args.placement, pre);
+        const result = await executeCreateTable(context.document, args, placement);
+        const tableNodeId = asString(asRecord(asRecord(result)?.table)?.nodeId);
+        if (args.cellTexts && tableNodeId) {
+            const cells = flattenCellTexts(args.cellTexts).filter((cell) => cell.text.trim());
+            if (pre.complete) {
+                const applied = await applyTableCellTexts(context.document, tableNodeId, estimateInsertedTableOrdinal(pre.complete, placement), cells, args.changeMode);
+                await styleTableCells(context.document, applied, args.changeMode);
             }
-            const styledCount = await styleTableCells(doc, appliedCells, args.changeMode);
-            if (styledCount > 0) {
-                executedOperations.push({
-                    operationId: 'doc.format.apply',
-                    rationale: `Styled ${styledCount} table cell(s).`,
-                });
+            else {
+                for (const cell of cells)
+                    await context.document.tables.setCellText({
+                        target: { kind: 'block', nodeType: 'table', nodeId: tableNodeId },
+                        rowIndex: cell.rowIndex,
+                        columnIndex: cell.columnIndex,
+                        text: cell.text,
+                        changeMode: args.changeMode,
+                    });
+                const styled = cells.filter((cell) => cell.runs?.length || cell.marks);
+                if (styled.length) {
+                    const identities = await doc.tables.getCells({ nodeId: tableNodeId });
+                    const resolved = styled.map((cell) => {
+                        const identity = identities.cells.find((item) => item.rowIndex === cell.rowIndex &&
+                            item.columnIndex <= cell.columnIndex &&
+                            item.columnIndex + item.colspan > cell.columnIndex);
+                        if (!identity?.firstParagraphNodeId)
+                            throw new Error('Required cell paragraph identity is unavailable.');
+                        return { ...cell, nodeId: identity.firstParagraphNodeId };
+                    });
+                    const styling = await applyItemStyling(context.document, resolved.map((cell) => cell.nodeId), resolved, args.changeMode);
+                    if (styling.skipped)
+                        throw new Error(`Requested cell styling failed: ${styling.skipped}`);
+                }
             }
         }
-        const post = await docSnapshot.buildDocumentSnapshot(doc);
-        const verification = evaluateChecks(pre, post, [
-            { kind: 'revision-changed' },
-            { kind: 'block-count-delta', nodeType: 'table', delta: 1 },
-        ]);
-        return {
-            status: verification.every((v) => v.passed) ? 'ok' : 'failed',
-            intent: 'create_table',
-            preSnapshot: { revision: pre.revision, counts: pre.counts },
-            postSnapshot: { revision: post.revision, counts: post.counts },
-            selectedTargets: [],
-            executedOperations,
-            verification,
-        };
+        const post = await context.finish();
+        return context.receipt('create_table', await executionContext.evaluateFactChecks(pre, post, checks));
     }
-    catch (err) {
-        return failedReceipt('create_table', err, pre);
+    catch (error) {
+        return context.failure('create_table', error);
     }
 }
 async function runCommentParagraphs(doc, args) {
-    const pre = await docSnapshot.buildDocumentSnapshot(doc);
+    const pre = await docSnapshot.buildMutationSnapshot(doc, { includeDomains: ['blocks'] });
     try {
         const blocks = pre.blocks.filter((b) => {
             if (args.scope === 'all') {
@@ -2371,13 +2338,18 @@ async function runCommentParagraphs(doc, args) {
     }
 }
 async function runAddComments(doc, args) {
-    const pre = await docSnapshot.buildDocumentSnapshot(doc);
+    const selectorList = args.selectors?.length ? args.selectors : args.selector ? [args.selector] : [];
+    const domains = new Set(['blocks']);
+    for (const selector of selectorList) {
+        for (const domain of snapshotDomainsForSelector(selector))
+            domains.add(domain);
+    }
+    const pre = await docSnapshot.buildMutationSnapshot(doc, { includeDomains: [...domains] });
     try {
         // Batch form: `selectors` comments many blocks in ONE action call so the
         // model never fans out N concurrent add_comments tool calls (which race the
         // shared document and the comment-count verification). A single `selector`
         // is the one-target shorthand. Comments are applied sequentially.
-        const selectorList = args.selectors?.length ? args.selectors : args.selector ? [args.selector] : [];
         if (!selectorList.length) {
             return failedReceipt('add_comments', new Error('add_comments requires a "selector" or a non-empty "selectors" array'), pre);
         }
@@ -2391,7 +2363,21 @@ async function runAddComments(doc, args) {
                 unresolved.push(sel);
         }
         if (!resolved.length) {
-            return failedReceipt('add_comments', new Error('no selector resolved to a body block'), pre);
+            return {
+                status: 'failed',
+                intent: 'add_comments',
+                preSnapshot: { revision: pre.revision, counts: pre.counts },
+                selectedTargets: unresolved.map((selector) => ({ selector, matched: [] })),
+                executedOperations: [],
+                verification: [],
+                errors: [
+                    {
+                        code: 'TARGET_NOT_FOUND',
+                        message: 'none of the requested comment selectors resolved to a block',
+                        recovery: { kind: 'reinspect' },
+                    },
+                ],
+            };
         }
         const executed = [];
         for (const { commentText, nodeId } of resolved.map((r) => ({ commentText: args.commentText, nodeId: r.nodeId }))) {
@@ -2400,15 +2386,20 @@ async function runAddComments(doc, args) {
         }
         const post = await docSnapshot.buildDocumentSnapshot(doc);
         const verification = evaluateChecks(pre, post, [{ kind: 'comment-count-delta', delta: resolved.length }]);
+        const verified = verification.every((v) => v.passed);
+        const status = !verified ? 'failed' : unresolved.length > 0 ? 'partial' : 'ok';
         return {
-            status: verification.every((v) => v.passed) ? 'ok' : 'failed',
+            status,
             intent: 'add_comments',
             ...(unresolved.length
                 ? { note: `${unresolved.length} selector(s) did not resolve to a block and were skipped` }
                 : {}),
             preSnapshot: { revision: pre.revision, counts: pre.counts },
             postSnapshot: { revision: post.revision, counts: post.counts },
-            selectedTargets: resolved.map((r) => ({ selector: r.selector, matched: [r.nodeId] })),
+            selectedTargets: [
+                ...resolved.map((r) => ({ selector: r.selector, matched: [r.nodeId] })),
+                ...unresolved.map((selector) => ({ selector, matched: [] })),
+            ],
             executedOperations: executed,
             verification,
         };
@@ -2584,67 +2575,39 @@ async function runReplyToComment(doc, args) {
     }
 }
 async function runRewriteBlock(doc, args) {
-    const pre = await docSnapshot.buildDocumentSnapshot(doc);
+    const context = new executionContext.ExecutionContext(doc, { evidence: args.evidence, selectors: [args.selector] });
     try {
-        const target = selectorToBlockTarget(args.selector, pre);
-        if (!target) {
-            return failedReceipt('rewrite_block', new Error('selector did not resolve to a body block'), pre);
-        }
-        const normalizedText = normalizeTitleLikeRewriteText(target.text, args.text);
-        // The engine rewrites the whole block as ONE uniform run — losing an
-        // intra-paragraph pattern (bold "(n)" lead-in), or smearing the first
-        // run's marks across the entire text. Capture the current run layout so
-        // it can be re-applied over the unchanged prefix/suffix afterward.
-        const preRuns = await captureBlockRuns(doc, target.nodeId, target.text);
-        const steps = [
+        const pre = await context.start();
+        const target = await pre.target(args.selector);
+        if (!target)
+            throw new Error('selector did not resolve to a body block');
+        context.selectedTargets.push({ selector: args.selector, matched: [target.nodeId] });
+        const text = normalizeTitleLikeRewriteText(target.text, args.text);
+        const runs = await captureBlockRuns(doc, target.nodeId, target.text);
+        await executeMutations(context.document, [
             {
                 id: 'rewrite-block-1',
                 op: 'text.rewrite',
                 where: { by: 'block', nodeType: target.nodeType, nodeId: target.nodeId },
-                args: {
-                    replacement: { text: normalizedText },
-                    style: preserveRewriteStyle(),
-                },
+                args: { replacement: { text }, style: preserveRewriteStyle() },
             },
-        ];
-        const result = await executeMutations(doc, steps, args.changeMode);
-        const preservation = await preserveRunPatternAfterRewrite(doc, target.nodeId, target.text, preRuns, normalizedText);
-        const post = await docSnapshot.buildDocumentSnapshot(doc);
-        const rewrittenBlock = findSnapshotTextByNodeId(post, target.nodeId);
+        ], args.changeMode, pre.revision);
+        await preserveRunPatternAfterRewrite(context.document, target.nodeId, target.text, runs, text);
+        const post = await context.finish();
+        const rewritten = await post.block(target.nodeId);
         const verification = [
             revisionVerification(pre.revision, post.revision, true),
             {
-                check: { kind: 'block-text-contains', nodeId: target.nodeId, text: normalizedText },
-                passed: !!rewrittenBlock && verifyRewrittenBlockText(rewrittenBlock.text, normalizedText, args.changeMode),
+                check: { kind: 'block-text-contains', nodeId: target.nodeId, text },
+                passed: !!rewritten && verifyRewrittenBlockText(rewritten.text, text, args.changeMode),
             },
         ];
-        const changed = pre.revision !== post.revision;
-        const rewritten = !!rewrittenBlock && verifyRewrittenBlockText(rewrittenBlock.text, args.text, args.changeMode);
-        return {
-            status: changed && rewritten ? 'ok' : 'failed',
-            intent: 'rewrite_block',
-            preSnapshot: { revision: pre.revision, counts: pre.counts },
-            postSnapshot: { revision: post.revision, counts: post.counts },
-            selectedTargets: [{ selector: args.selector, matched: [target.nodeId] }],
-            executedOperations: [
-                { operationId: 'doc.mutations.apply', result },
-                ...(preservation ? [{ operationId: 'doc.format.apply', result: preservation }] : []),
-            ],
-            verification,
-            errors: changed && rewritten
-                ? undefined
-                : [
-                    {
-                        code: 'ACTION_FAILED',
-                        message: changed
-                            ? 'rewrite_block did not produce the requested rewritten text for the selected block'
-                            : 'rewrite_block produced no change for the selected block; keep the same target and provide a changed rewrite',
-                    },
-                ],
-        };
+        return context.receipt('rewrite_block', verification, verification.every((check) => check.passed)
+            ? {}
+            : { errors: [{ code: 'ACTION_FAILED', message: 'rewrite_block did not produce the requested changed text' }] });
     }
-    catch (err) {
-        return failedReceipt('rewrite_block', err, pre);
+    catch (error) {
+        return context.failure('rewrite_block', error);
     }
 }
 const RUN_BOOL_MARKS = ['bold', 'italic', 'underline', 'strike'];
@@ -3018,7 +2981,7 @@ async function listAllTrackedChanges(listFn) {
     }
 }
 async function runNormalizeBodyFontSize(doc, args) {
-    const pre = await docSnapshot.buildDocumentSnapshot(doc);
+    const pre = await docSnapshot.buildMutationSnapshot(doc, { includeDomains: ['blocks'] });
     try {
         if (!Number.isFinite(args.fontSize) || args.fontSize <= 0) {
             return failedReceipt('normalize_body_font_size', new Error('fontSize must be a positive number'), pre);
@@ -3035,7 +2998,7 @@ async function runNormalizeBodyFontSize(doc, args) {
             where: { by: 'block', nodeType: block.nodeType, nodeId: block.nodeId },
             args: { inline: { fontSize: args.fontSize }, scope: 'block' },
         }));
-        const result = await executeMutations(doc, steps, args.changeMode);
+        const result = await executeMutations(doc, steps, args.changeMode, pre.revision);
         const post = await docSnapshot.buildDocumentSnapshot(doc);
         const verification = evaluateChecks(pre, post, [{ kind: 'revision-changed' }]);
         return {
@@ -3066,7 +3029,7 @@ async function runNormalizeBodyFontSize(doc, args) {
  * tracked-safe (changeMode).
  */
 async function runSetFontFamily(doc, args) {
-    const pre = await docSnapshot.buildDocumentSnapshot(doc);
+    const pre = await docSnapshot.buildMutationSnapshot(doc, { includeDomains: ['blocks', 'tables'] });
     try {
         const fontFamily = args.fontFamily.trim();
         if (fontFamily.length === 0) {
@@ -3193,7 +3156,7 @@ async function runSetFontFamily(doc, args) {
  * the recreated block inside an adjacent table cell.
  */
 async function runApplyStyle(doc, args) {
-    const pre = await docSnapshot.buildDocumentSnapshot(doc);
+    const pre = await docSnapshot.buildMutationSnapshot(doc, { includeDomains: ['blocks'] });
     try {
         const target = selectorToBlockTarget(args.selector, pre);
         if (!target) {
@@ -3295,43 +3258,30 @@ async function runApplyStyle(doc, args) {
  * escape to superdoc_execute_code and apply the alignment untracked (no pPrChange).
  */
 async function runFormatParagraph(doc, args) {
-    const pre = await docSnapshot.buildDocumentSnapshot(doc);
+    const context = new executionContext.ExecutionContext(doc, { evidence: args.evidence, selectors: [args.selector] });
     try {
-        const target = selectorToBlockTarget(args.selector, pre);
-        if (!target) {
-            return failedReceipt('format_paragraph', new Error('selector did not resolve to a unique body block'), pre);
-        }
         const alignment = typeof args.alignment === 'string' ? args.alignment.trim().toLowerCase() : '';
-        const normalizedAlignment = alignment === 'both' ? 'justify' : alignment;
-        if (!['left', 'center', 'right', 'justify'].includes(normalizedAlignment)) {
-            return failedReceipt('format_paragraph', new Error('format_paragraph requires alignment: left | center | right | justify'), pre);
-        }
-        const steps = [
+        const normalized = alignment === 'both' ? 'justify' : alignment;
+        if (!['left', 'center', 'right', 'justify'].includes(normalized))
+            throw new Error('format_paragraph requires alignment: left | center | right | justify');
+        const pre = await context.start();
+        const target = await pre.target(args.selector);
+        if (!target)
+            throw new Error('selector did not resolve to a unique body block');
+        context.selectedTargets.push({ selector: args.selector, matched: [target.nodeId] });
+        await executeMutations(context.document, [
             {
                 id: 'format-paragraph-1',
                 op: 'format.apply',
                 where: { by: 'block', nodeType: target.nodeType, nodeId: target.nodeId },
-                args: { alignment: normalizedAlignment, scope: 'block' },
+                args: { alignment: normalized, scope: 'block' },
             },
-        ];
-        const result = await executeMutations(doc, steps, args.changeMode);
-        const post = await docSnapshot.buildDocumentSnapshot(doc);
-        const verification = evaluateChecks(pre, post, [{ kind: 'revision-changed' }]);
-        return {
-            status: verification.every((v) => v.passed) ? 'ok' : 'failed',
-            intent: `format_paragraph: ${normalizedAlignment}`,
-            preSnapshot: { revision: pre.revision, counts: pre.counts },
-            postSnapshot: { revision: post.revision, counts: post.counts },
-            selectedTargets: [{ selector: args.selector, matched: [target.nodeId] }],
-            applied: { alignment: normalizedAlignment },
-            executedOperations: [
-                { operationId: 'doc.mutations.apply', result: compactOpResult(result), rationale: `align ${target.nodeId}` },
-            ],
-            verification,
-        };
+        ], args.changeMode, pre.revision);
+        const post = await context.finish();
+        return context.receipt(`format_paragraph: ${normalized}`, await executionContext.evaluateFactChecks(pre, post, [{ kind: 'revision-changed' }]), { applied: { alignment: normalized } });
     }
-    catch (err) {
-        return failedReceipt('format_paragraph', err, pre);
+    catch (error) {
+        return context.failure('format_paragraph', error);
     }
 }
 /**
@@ -3349,7 +3299,7 @@ async function runFormatParagraph(doc, args) {
  * still anchor on the (now tracked-deleted) source span and land right after it.
  */
 async function runMoveText(doc, args) {
-    const pre = await docSnapshot.buildDocumentSnapshot(doc);
+    const pre = await docSnapshot.buildMutationSnapshot(doc, { includeDomains: ['blocks', 'tables'] });
     try {
         if (!args.text || args.text.length === 0) {
             return failedReceipt('move_text', new Error('text (the exact source span to move) is required'), pre);
@@ -3466,7 +3416,7 @@ async function runMoveText(doc, args) {
  * instead of inserting blank paragraphs.
  */
 async function runSetParagraphSpacing(doc, args) {
-    const pre = await docSnapshot.buildDocumentSnapshot(doc, { includeDomains: ['blocks'] });
+    const pre = await docSnapshot.buildMutationSnapshot(doc, { includeDomains: ['blocks'] });
     try {
         const target = selectorToBlockTarget(args.selector, pre);
         if (!target) {
@@ -3523,7 +3473,7 @@ async function runSetParagraphSpacing(doc, args) {
  * THE way to "start X on a new page" instead of padding with empty paragraphs.
  */
 async function runInsertPageBreak(doc, args) {
-    const pre = await docSnapshot.buildDocumentSnapshot(doc, { includeDomains: ['blocks'] });
+    const pre = await docSnapshot.buildMutationSnapshot(doc, { includeDomains: ['blocks'] });
     try {
         const target = selectorToBlockTarget(args.selector, pre);
         if (!target) {
@@ -3560,7 +3510,7 @@ async function runInsertPageBreak(doc, args) {
  * Finds the text in the body and applies a link over its range.
  */
 async function runAddHyperlink(doc, args) {
-    const pre = await docSnapshot.buildDocumentSnapshot(doc, { includeDomains: ['blocks'] });
+    const pre = await docSnapshot.buildMutationSnapshot(doc, { includeDomains: ['blocks'] });
     try {
         const needle = args.text;
         const url = args.url;
@@ -3618,7 +3568,7 @@ async function runAddHyperlink(doc, args) {
  * dialect, and silently apply the formatting untracked.
  */
 async function runFormatText(doc, args) {
-    const pre = await docSnapshot.buildDocumentSnapshot(doc);
+    const pre = await docSnapshot.buildMutationSnapshot(doc, { includeDomains: ['blocks', 'tables'] });
     try {
         const inline = {};
         if (args.bold === true)
@@ -3779,7 +3729,7 @@ function findRanges(haystack, needle, caseSensitive) {
     return ranges;
 }
 async function runApplyLetterSpacing(doc, args) {
-    const pre = await docSnapshot.buildDocumentSnapshot(doc);
+    const pre = await docSnapshot.buildMutationSnapshot(doc, { includeDomains: ['blocks'] });
     try {
         if (!Number.isFinite(args.letterSpacing)) {
             return failedReceipt('apply_letter_spacing', new Error('letterSpacing must be a finite number'), pre);
@@ -3799,7 +3749,7 @@ async function runApplyLetterSpacing(doc, args) {
                 args: { inline: { letterSpacing: args.letterSpacing }, scope: 'block' },
             },
         ];
-        const result = await executeMutations(doc, steps, args.changeMode);
+        const result = await executeMutations(doc, steps, args.changeMode, pre.revision);
         const post = await docSnapshot.buildDocumentSnapshot(doc);
         const verification = evaluateChecks(pre, post, [{ kind: 'revision-changed' }]);
         return {
@@ -3957,7 +3907,10 @@ async function runMoveRange(doc, args) {
     }
 }
 async function runInsertToc(doc, args) {
-    const pre = await docSnapshot.buildDocumentSnapshot(doc);
+    const placement = args.placement ?? { at: 'document_start' };
+    const pre = placement.at === 'before' || placement.at === 'after'
+        ? await docSnapshot.buildMutationSnapshot(doc)
+        : await docSnapshot.buildDocumentSnapshot(doc);
     try {
         const tocFn = maybeMethod(doc, ['create', 'tableOfContents']);
         if (!tocFn) {
@@ -3965,11 +3918,11 @@ async function runInsertToc(doc, args) {
                 code: 'TOOL_DISPATCH_NOT_FOUND',
             });
         }
-        const placement = resolvePlacement(args.placement ?? { at: 'document_start' }, pre);
+        const resolvedPlacement = resolvePlacement(placement, pre);
         const executed = [];
-        let tocPlacement = placement;
+        let tocPlacement = resolvedPlacement;
         if (args.title) {
-            const headingResult = await executeCreateHeading(doc, args.title, 1, placement, args.changeMode);
+            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) {
@@ -4096,7 +4049,7 @@ async function runStyleTable(doc, args) {
  * should reach for instead of delete-and-recreate or insert/undo churn.
  */
 async function runMoveTable(doc, args) {
-    const pre = await docSnapshot.buildDocumentSnapshot(doc);
+    const pre = await docSnapshot.buildMutationSnapshot(doc);
     try {
         const tableOrdinal = args.tableOrdinal ?? 1;
         const table = await resolveTableContextQuick(doc, tableOrdinal);
@@ -4622,8 +4575,8 @@ function parseScopedReplaceArgs(args) {
         changeMode: args.changeMode === 'tracked' ? 'tracked' : 'direct',
     };
 }
-async function runScopedReplace(doc, args) {
-    const pre = await docSnapshot.buildDocumentSnapshot(doc, { includeDomains: ['blocks', 'tables'] });
+async function runScopedReplaceUnchecked(doc, args) {
+    const pre = await docSnapshot.buildMutationSnapshot(doc, { includeDomains: ['blocks', 'tables'] });
     const matched = docSnapshot.resolveSnapshotSelector(pre, args.selector);
     if (matched.length !== 1) {
         const failure = describeSelectorFailure(args.selector, matched, pre, args.edits.map((e) => e.find));
@@ -4720,7 +4673,7 @@ async function runScopedReplace(doc, args) {
         // applies directly, so restoring marks adds no second reviewable change.
         const trackedPreRuns = await captureBlockRuns(doc, nodeId, block.text);
         try {
-            result = await executeMutations(doc, spanSteps, args.changeMode);
+            result = await executeMutations(doc, spanSteps, args.changeMode, pre.revision);
             if (result != null)
                 await preserveScopedRunPattern(doc, nodeId, block.text, trackedPreRuns, planned);
         }
@@ -4742,10 +4695,10 @@ async function runScopedReplace(doc, args) {
                 args: { replacement: { text: expected }, style: preserveRewriteStyle() },
             },
         ];
-        result = await executeMutations(doc, steps, args.changeMode);
+        result = await executeMutations(doc, steps, args.changeMode, pre.revision);
         await preserveScopedRunPattern(doc, nodeId, block.text, preRuns, planned);
     }
-    const post = await docSnapshot.buildDocumentSnapshot(doc, { includeDomains: ['blocks', 'tables'] });
+    const post = await docSnapshot.buildMutationSnapshot(doc, { includeDomains: ['blocks', 'tables'] });
     const postBlock = findTextTarget(post, nodeId);
     // In tracked mode the deleted text is still present in the block, so only
     // require the inserted text to be visible.
@@ -4784,6 +4737,14 @@ async function runScopedReplace(doc, args) {
         ],
     };
 }
+async function runScopedReplace(doc, args) {
+    try {
+        return await runScopedReplaceUnchecked(doc, args);
+    }
+    catch (error) {
+        return failedReceipt('replace_text', error);
+    }
+}
 /**
  * Build a `doc.format.apply` `inline` payload from a block row's sampled look.
  * Shared by apply_style (likeText copy) and add_list_items (anchor auto-match)
@@ -4839,12 +4800,6 @@ function paragraphMarkRunPropsOf(payload) {
  * Spaced dashes are listed separately from bare ones because the label run
  * usually stops BEFORE the space ("JavaScript / TypeScript" + " — SuperDoc…").
  */
-/**
- * How many blocks the per-block replace lane will capture runs for. Each target
- * costs a `query.match` read, so the lane is bounded; edits reaching past it
- * fall through to the select lane rather than being silently truncated.
- */
-const PRESERVE_TARGET_CAP = 20;
 const LEAD_IN_DELIMITERS = [':', ' — ', ' – ', ' - ', '—', '–'];
 /** A lead-in is a LABEL, not a sentence — longer spans are prose, not a pattern. */
 const LEAD_IN_MAX_CHARS = 90;
@@ -5327,8 +5282,18 @@ async function listBlockRows(doc) {
     const fn = maybeMethod(doc, ['blocks', 'list']);
     if (!fn)
         return [];
-    const raw = (await fn({}));
-    return Array.isArray(raw?.blocks) ? raw.blocks : [];
+    const rows = [];
+    const pageSize = 250;
+    let offset = 0;
+    while (true) {
+        const raw = (await fn({ offset, limit: pageSize }));
+        const page = Array.isArray(raw?.blocks) ? raw.blocks : [];
+        rows.push(...page);
+        offset += page.length;
+        const total = typeof raw?.total === 'number' && Number.isFinite(raw.total) ? raw.total : rows.length;
+        if (page.length === 0 || offset >= total)
+            return rows;
+    }
 }
 function blockNumbering(row) {
     const numbering = row?.numbering;
@@ -5494,7 +5459,7 @@ async function convertNumberedRange(doc, fromMarker, toMarker, kind, tracked) {
     };
 }
 async function convertParagraphRange(doc, fromText, toText, kind, tracked) {
-    const pre = await docSnapshot.buildDocumentSnapshot(doc, { includeDomains: ['blocks'] });
+    const pre = await docSnapshot.buildMutationSnapshot(doc, { includeDomains: ['blocks'] });
     const blocks = pre.blocks ?? [];
     const findBlock = (needle) => blocks.findIndex((b) => b.nodeType === 'paragraph' && (b.text ?? '').toLowerCase().includes(needle.toLowerCase()));
     const fromIdx = findBlock(fromText);
@@ -5538,7 +5503,7 @@ async function convertParagraphRange(doc, fromText, toText, kind, tracked) {
         };
     }
     await createListFromParagraphRange(createFn, kind, range[0].nodeId, range[range.length - 1].nodeId, tracked ? 'tracked' : undefined);
-    const post = await docSnapshot.buildDocumentSnapshot(doc, { includeDomains: ['blocks', 'lists'] });
+    const post = await docSnapshot.buildMutationSnapshot(doc, { includeDomains: ['blocks', 'lists'] });
     const postList = (post.lists ?? []).find((l) => l.items.some((it) => it.nodeId === range[0].nodeId));
     const allInOneList = postList != null && range.every((b) => postList.items.some((it) => it.nodeId === b.nodeId));
     return {
@@ -5807,7 +5772,7 @@ async function appendListAtPlacement(doc, args) {
     const selector = placement && isRecord(placement.selector) ? placement.selector : null;
     if (items.length === 0 || !placement || (at !== 'after' && at !== 'before') || !selector)
         return null;
-    const pre = await docSnapshot.buildDocumentSnapshot(doc, { includeDomains: ['blocks'] });
+    const pre = await docSnapshot.buildMutationSnapshot(doc, { includeDomains: ['blocks'] });
     const blocks = pre.blocks ?? [];
     // Resolve through the SHARED selector resolver so the full selector
     // vocabulary works (nodeId / textSearch / ordinal / relative / ref) and
@@ -5868,7 +5833,7 @@ async function appendListAtPlacement(doc, args) {
     const listIds = typeof args.headingText === 'string' && args.headingText.length > 0 ? createdIds.slice(1) : createdIds;
     await createListFromParagraphRange(listsCreateFn, kind, listIds[0], listIds[listIds.length - 1], parseChangeMode(args.changeMode));
     // Verify both promises: the items form one list AND it sits at the anchor.
-    const post = await docSnapshot.buildDocumentSnapshot(doc, { includeDomains: ['blocks', 'lists'] });
+    const post = await docSnapshot.buildMutationSnapshot(doc, { includeDomains: ['blocks', 'lists'] });
     const postBlocks = post.blocks ?? [];
     const postList = (post.lists ?? []).find((l) => l.items.some((it) => it.nodeId === listIds[0]));
     const listOk = postList != null && listIds.every((id) => postList.items.some((it) => it.nodeId === id));
@@ -5972,8 +5937,9 @@ async function matchOneBlock(doc, postBlocks, preIds, created, createdIndex, anc
             const formatApplyFn = maybeMethod(doc, ['format', 'apply']);
             if (formatApplyFn) {
                 const textLength = (created.textPreview ?? '').length;
-                const post = await docSnapshot.buildDocumentSnapshot(doc, { includeDomains: ['blocks'] });
-                const full = post.blocks.find((b) => b.nodeId === created.nodeId)?.text ?? '';
+                const full = createdText ||
+                    (await doc.blocks.list({ nodeIds: [created.nodeId], limit: 1, includeText: true })).blocks.find((block) => block.nodeId === created.nodeId)?.text ||
+                    '';
                 await formatApplyFn({
                     blockId: created.nodeId,
                     start: 0,
@@ -6170,11 +6136,11 @@ async function matchBlockRunPattern(doc, reference, created, createdText) {
     }
     return Object.keys(applied).length > 0 ? { matchedSibling: reference.nodeId, ...applied } : null;
 }
-async function matchInsertedBlockFormatting(doc, preBlocks, receipt, args) {
+async function matchInsertedBlockFormatting(doc, preBlocks, receipt, args, availableRows) {
     if (receipt.status !== 'ok')
         return receipt;
     try {
-        const postBlocks = await listBlockRows(doc);
+        const postBlocks = availableRows ?? (await listBlockRows(doc));
         const preIds = new Set(preBlocks.map((b) => b.nodeId));
         const createdRows = postBlocks
             .map((b, i) => ({ row: b, index: i }))
@@ -6431,7 +6397,7 @@ async function runAttachNumbering(doc, args) {
         verification: [{ check: { kind: 'marker-rendered' }, passed: !!newMarker }],
     };
 }
-async function superdocPerformAction(doc, args) {
+async function dispatchSuperdocPerformAction(doc, args) {
     if (!isRecord(args)) {
         throw new errors.SuperDocCliError('superdoc_perform_action arguments must be an object', {
             code: 'INVALID_ARGUMENT',
@@ -6465,9 +6431,9 @@ async function superdocPerformAction(doc, args) {
                 });
             }
             const headingLevel = asNumber(args.headingLevel);
-            const preRows = await listBlockRows(doc);
-            const receipt = await runInsertParagraphs(doc, {
+            return runInsertParagraphs(doc, {
                 action,
+                evidence: args.evidence,
                 texts,
                 textSpecs,
                 placement: parsePlacement(args.placement),
@@ -6475,8 +6441,7 @@ async function superdocPerformAction(doc, args) {
                 headingLevel: headingLevel != null && Number.isInteger(headingLevel) && headingLevel >= 1 && headingLevel <= 6
                     ? headingLevel
                     : undefined,
-            });
-            return matchInsertedBlockFormatting(doc, preRows, receipt, args);
+            }, args);
         }
         case 'insert_heading': {
             const text = asString(args.text);
@@ -6600,6 +6565,7 @@ async function superdocPerformAction(doc, args) {
             }
             return runCreateTable(doc, {
                 action,
+                evidence: args.evidence,
                 rows,
                 columns,
                 cellTexts: parseCellTexts(args.cellTexts),
@@ -6623,16 +6589,41 @@ async function superdocPerformAction(doc, args) {
         }
         case 'add_comments': {
             const commentText = asString(args.commentText);
-            const selector = parseSelector(args.selector);
-            const selectors = Array.isArray(args.selectors)
-                ? args.selectors.map((s) => parseSelector(s)).filter((s) => Boolean(s))
-                : undefined;
-            if (!commentText || (!selector && !(selectors && selectors.length))) {
+            if (!commentText) {
                 throw new errors.SuperDocCliError('add_comments requires "commentText" and a "selector" or non-empty "selectors" array', {
                     code: 'INVALID_ARGUMENT',
                 });
             }
-            return runAddComments(doc, { action, commentText, selector: selector ?? undefined, selectors });
+            const hasSelector = args.selector != null;
+            const hasSelectors = args.selectors != null;
+            if (hasSelector && hasSelectors) {
+                throw new errors.SuperDocCliError('add_comments requires either "selector" or "selectors", not both', {
+                    code: 'INVALID_ARGUMENT',
+                });
+            }
+            if (hasSelectors) {
+                if (!Array.isArray(args.selectors) || args.selectors.length === 0) {
+                    throw new errors.SuperDocCliError('add_comments requires "selectors" to be a non-empty array', {
+                        code: 'INVALID_ARGUMENT',
+                    });
+                }
+                // Parse the complete batch before mutation. Filtering an invalid entry
+                // would make the receipt report success for only part of the request.
+                const selectors = [];
+                for (const [index, raw] of args.selectors.entries()) {
+                    const parsed = parseSelector(raw);
+                    if (!parsed) {
+                        throw new errors.SuperDocCliError(`add_comments selectors[${index}] is not a valid selector; no comments were added`, { code: 'INVALID_ARGUMENT' });
+                    }
+                    selectors.push(parsed);
+                }
+                return runAddComments(doc, { action, commentText, selectors });
+            }
+            const selector = parseSelector(args.selector);
+            if (!selector) {
+                throw new errors.SuperDocCliError('add_comments requires "selector" to be valid or "selectors" to be a non-empty array', { code: 'INVALID_ARGUMENT' });
+            }
+            return runAddComments(doc, { action, commentText, selector });
         }
         case 'resolve_comments':
             return runResolveComments(doc, {
@@ -6661,6 +6652,7 @@ async function superdocPerformAction(doc, args) {
             }
             return runRewriteBlock(doc, {
                 action,
+                evidence: args.evidence,
                 text,
                 selector,
                 changeMode: parseChangeMode(args.changeMode),
@@ -6912,6 +6904,7 @@ async function superdocPerformAction(doc, args) {
             }
             return runFormatParagraph(doc, {
                 action,
+                evidence: args.evidence,
                 selector,
                 alignment: asString(args.alignment) ?? '',
                 changeMode: parseChangeMode(args.changeMode),
@@ -7043,6 +7036,24 @@ async function superdocPerformAction(doc, args) {
         }
     }
 }
+async function superdocPerformAction(doc, args) {
+    try {
+        return await dispatchSuperdocPerformAction(doc, args);
+    }
+    catch (error) {
+        if (!(error instanceof docSnapshot.MutationSnapshotError))
+            throw error;
+        const action = isRecord(args) && isActionName(args.action) ? args.action : 'superdoc_perform_action';
+        return {
+            status: 'failed',
+            intent: action,
+            selectedTargets: [],
+            executedOperations: [],
+            verification: [],
+            errors: [{ code: error.code, message: error.message, recovery: { kind: 'reinspect' } }],
+        };
+    }
+}
 function parseChangeMode(value) {
     if (value === 'direct' || value === 'tracked')
         return value;