@superdoc/sdk 2.10.0-next.4 → 2.10.0-next.6

package/dist/agent/actions.cjs

@@ -514,6 +514,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 +525,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 +575,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 +637,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') {
@@ -1040,7 +1050,9 @@ async function styleTableCells(doc, cells, changeMode) {
     return styled.length;
 }
 async function runInsertParagraphs(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 {
         // `texts` is the canonical input; a single `text` is normalized to one item
         // upstream in the dispatcher, but tolerate it here too.
@@ -1067,7 +1079,7 @@ async function runInsertParagraphs(doc, args) {
             if (created) {
                 return { kind: 'after', target: { kind: 'block', nodeType: created.nodeType, nodeId: created.nodeId } };
             }
-            const mid = await docSnapshot.buildDocumentSnapshot(doc, { includeDomains: ['blocks'] });
+            const mid = await docSnapshot.buildMutationSnapshot(doc, { includeDomains: ['blocks'] });
             const last = lastBlock(mid);
             return last
                 ? { kind: 'after', target: { kind: 'block', nodeType: last.nodeType, nodeId: last.nodeId } }
@@ -1129,7 +1141,9 @@ async function runInsertParagraphs(doc, args) {
     }
 }
 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);
@@ -1154,7 +1168,7 @@ async function runReplaceText(doc, args) {
     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) {
@@ -1206,6 +1220,7 @@ async function runReplaceText(doc, args) {
                     },
                 },
             ];
+            applyExpectedRevision = pre.revision;
             selectedTargets.push({ selector: args.selector, matched: [target.nodeId] });
             preserveTargets.push({
                 nodeId: target.nodeId,
@@ -1278,7 +1293,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);
@@ -1347,7 +1362,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);
@@ -1390,7 +1405,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 {
@@ -1452,7 +1467,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)
@@ -1495,7 +1510,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);
@@ -1588,7 +1603,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.
@@ -1706,7 +1721,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();
@@ -2240,7 +2255,7 @@ async function runSplitList(doc, args) {
     }
 }
 async function runCreateTable(doc, args) {
-    const pre = await docSnapshot.buildDocumentSnapshot(doc);
+    const pre = await docSnapshot.buildMutationSnapshot(doc, { includeDomains: ['blocks', 'tables'] });
     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);
@@ -2268,7 +2283,7 @@ async function runCreateTable(doc, args) {
                 });
             }
         }
-        const post = await docSnapshot.buildDocumentSnapshot(doc);
+        const post = await docSnapshot.buildMutationSnapshot(doc, { includeDomains: ['blocks', 'tables'] });
         const verification = evaluateChecks(pre, post, [
             { kind: 'revision-changed' },
             { kind: 'block-count-delta', nodeType: 'table', delta: 1 },
@@ -2288,7 +2303,7 @@ async function runCreateTable(doc, args) {
     }
 }
 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') {
@@ -2330,13 +2345,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);
         }
@@ -2350,7 +2370,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 }))) {
@@ -2359,15 +2393,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,
         };
@@ -2543,7 +2582,7 @@ async function runReplyToComment(doc, args) {
     }
 }
 async function runRewriteBlock(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) {
@@ -2566,9 +2605,9 @@ async function runRewriteBlock(doc, args) {
                 },
             },
         ];
-        const result = await executeMutations(doc, steps, args.changeMode);
+        const result = await executeMutations(doc, steps, args.changeMode, pre.revision);
         const preservation = await preserveRunPatternAfterRewrite(doc, target.nodeId, target.text, preRuns, normalizedText);
-        const post = await docSnapshot.buildDocumentSnapshot(doc);
+        const post = await docSnapshot.buildMutationSnapshot(doc, { includeDomains: ['blocks'] });
         const rewrittenBlock = findSnapshotTextByNodeId(post, target.nodeId);
         const verification = [
             revisionVerification(pre.revision, post.revision, true),
@@ -2977,7 +3016,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);
@@ -2994,7 +3033,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 {
@@ -3025,7 +3064,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) {
@@ -3152,7 +3191,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) {
@@ -3254,7 +3293,7 @@ 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 pre = await docSnapshot.buildMutationSnapshot(doc, { includeDomains: ['blocks'] });
     try {
         const target = selectorToBlockTarget(args.selector, pre);
         if (!target) {
@@ -3273,7 +3312,7 @@ async function runFormatParagraph(doc, args) {
                 args: { alignment: normalizedAlignment, 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 {
@@ -3308,7 +3347,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);
@@ -3425,7 +3464,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) {
@@ -3482,7 +3521,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) {
@@ -3519,7 +3558,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;
@@ -3577,7 +3616,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)
@@ -3738,7 +3777,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);
@@ -3758,7 +3797,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 {
@@ -3916,7 +3955,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) {
@@ -3924,11 +3966,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) {
@@ -4055,7 +4097,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);
@@ -4581,8 +4623,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));
@@ -4679,7 +4721,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);
         }
@@ -4701,10 +4743,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.
@@ -4743,6 +4785,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)
@@ -5280,8 +5330,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;
@@ -5447,7 +5507,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);
@@ -5491,7 +5551,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 {
@@ -5760,7 +5820,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
@@ -5821,7 +5881,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));
@@ -6384,7 +6444,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',
@@ -6996,6 +7056,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;