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

package/dist/agent/doc-snapshot.cjs

@@ -99,6 +99,48 @@ function includesDomain(requested, domain) {
 function truncateBlockText(value, limit) {
     return limit == null ? value : value.slice(0, limit);
 }
+function populateTableCellsFromExtract(tables, extractRaw, tableOrdinalBase = 0) {
+    const extractRec = asRecord(extractRaw);
+    const extractBlocks = Array.isArray(extractRec?.blocks) ? extractRec.blocks : [];
+    const cellsByTableNodeId = new Map();
+    for (const block of extractBlocks) {
+        const rec = asRecord(block);
+        const tableContext = asRecord(rec?.tableContext);
+        if (!rec || !tableContext)
+            continue;
+        const tableOrdinal = asNumber(tableContext.tableOrdinal, -1);
+        const rowIndex = asNumber(tableContext.rowIndex, -1);
+        const columnIndex = asNumber(tableContext.columnIndex, -1);
+        if (tableOrdinal < 0 || rowIndex < 0 || columnIndex < 0)
+            continue;
+        const table = tables[tableOrdinal - tableOrdinalBase];
+        if (!table)
+            continue;
+        const key = `${rowIndex}:${columnIndex}`;
+        const text = asString(rec.text);
+        const nodeId = asString(rec.nodeId) || undefined;
+        const cellMap = cellsByTableNodeId.get(table.nodeId) ??
+            new Map();
+        const existing = cellMap.get(key);
+        cellMap.set(key, {
+            rowIndex,
+            columnIndex,
+            text: existing == null || text.length === 0
+                ? (existing?.text ?? text)
+                : existing.text.length === 0
+                    ? text
+                    : `${existing.text}\n${text}`,
+            nodeId: existing?.nodeId ?? nodeId,
+        });
+        cellsByTableNodeId.set(table.nodeId, cellMap);
+    }
+    for (const table of tables) {
+        const cellMap = cellsByTableNodeId.get(table.nodeId);
+        if (!cellMap)
+            continue;
+        table.cells = [...cellMap.values()].sort((left, right) => left.rowIndex - right.rowIndex || left.columnIndex - right.columnIndex);
+    }
+}
 /**
  * Build a deterministic snapshot of a document. The snapshot uses only
  * read-mode operations from the generated contract — it never mutates state,
@@ -404,46 +446,7 @@ async function buildDocumentSnapshot(doc, options = {}) {
     const extractFn = maybeMethod(doc, ['extract']);
     if (tables.length > 0 && extractFn) {
         const extractRaw = await safeCall(() => extractFn({}), null, recordError('extract'));
-        const extractRec = asRecord(extractRaw);
-        const extractBlocks = Array.isArray(extractRec?.blocks) ? extractRec.blocks : [];
-        const cellsByTableNodeId = new Map();
-        for (const block of extractBlocks) {
-            const rec = asRecord(block);
-            const tableContext = asRecord(rec?.tableContext);
-            if (!rec || !tableContext)
-                continue;
-            const tableOrdinal = asNumber(tableContext.tableOrdinal, -1);
-            const rowIndex = asNumber(tableContext.rowIndex, -1);
-            const columnIndex = asNumber(tableContext.columnIndex, -1);
-            if (tableOrdinal < 0 || rowIndex < 0 || columnIndex < 0)
-                continue;
-            const table = tables[tableOrdinal - precedingTableCount];
-            if (!table)
-                continue;
-            const key = `${rowIndex}:${columnIndex}`;
-            const text = asString(rec.text);
-            const nodeId = asString(rec.nodeId) || undefined;
-            const cellMap = cellsByTableNodeId.get(table.nodeId) ??
-                new Map();
-            const existing = cellMap.get(key);
-            cellMap.set(key, {
-                rowIndex,
-                columnIndex,
-                text: existing == null || text.length === 0
-                    ? (existing?.text ?? text)
-                    : existing.text.length === 0
-                        ? text
-                        : `${existing.text}\n${text}`,
-                nodeId: existing?.nodeId ?? nodeId,
-            });
-            cellsByTableNodeId.set(table.nodeId, cellMap);
-        }
-        for (const table of tables) {
-            const cellMap = cellsByTableNodeId.get(table.nodeId);
-            if (!cellMap)
-                continue;
-            table.cells = [...cellMap.values()].sort((left, right) => left.rowIndex - right.rowIndex || left.columnIndex - right.columnIndex);
-        }
+        populateTableCellsFromExtract(tables, extractRaw, precedingTableCount);
     }
     // Optionally enrich table cells with per-run formatting (opt-in; one
     // query.match per cell, bounded) so a reader can match a cell's pattern.
@@ -748,6 +751,144 @@ async function buildDocumentSnapshot(doc, options = {}) {
         ...(finds ? { finds } : {}),
     };
 }
+class MutationSnapshotError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.code = code;
+        this.name = 'MutationSnapshotError';
+    }
+}
+const MUTATION_BLOCK_PAGE_SIZE = 1000;
+const MUTATION_BLOCK_PAGE_CONCURRENCY = 4;
+const MUTATION_NON_TABLE_DOMAINS = [
+    'blocks',
+    'lists',
+    'comments',
+    'trackedChanges',
+    'sections',
+    'headerFooters',
+    'styles',
+    'contentControls',
+    'fields',
+    'hyperlinks',
+    'bookmarks',
+    'permissionRanges',
+    'images',
+];
+/**
+ * Build the complete block index used to authorize mutations. Inspection
+ * snapshots stay windowed; mutation selectors must not treat that presentation
+ * window as the end of the document. Reads remain bounded and the revision is
+ * checked before the combined snapshot is returned.
+ */
+async function buildMutationSnapshot(doc, options = {}) {
+    const requestedDomains = options.includeDomains == null || options.includeDomains.length === 0 ? null : new Set(options.includeDomains);
+    const includeTables = requestedDomains == null || requestedDomains.has('tables');
+    const firstDomains = requestedDomains == null
+        ? MUTATION_NON_TABLE_DOMAINS
+        : [...requestedDomains].filter((domain) => domain !== 'tables').concat('blocks');
+    const first = await buildDocumentSnapshot(doc, {
+        includeDomains: firstDomains,
+        blockOffset: 0,
+        blockLimit: MUTATION_BLOCK_PAGE_SIZE,
+    });
+    assertMutationBlockRead(first, 0);
+    const total = first.counts.blocks;
+    if (first.blocks.length > total) {
+        throw new MutationSnapshotError('SNAPSHOT_INCOMPLETE', `cannot build complete mutation snapshot: document reports ${total} blocks but returned ${first.blocks.length}`);
+    }
+    if (first.blocks.length === 0 && total > 0) {
+        throw new MutationSnapshotError('SNAPSHOT_INCOMPLETE', `cannot build complete mutation snapshot: document reports ${total} blocks but returned none`);
+    }
+    const blocks = [...first.blocks];
+    const diagnostics = [...first.diagnostics];
+    const pageStride = first.blocks.length || MUTATION_BLOCK_PAGE_SIZE;
+    const offsets = first.blocks.length === total
+        ? []
+        : Array.from({ length: Math.ceil((total - pageStride) / pageStride) }, (_, index) => pageStride * (index + 1));
+    for (let index = 0; index < offsets.length; index += MUTATION_BLOCK_PAGE_CONCURRENCY) {
+        const batchOffsets = offsets.slice(index, index + MUTATION_BLOCK_PAGE_CONCURRENCY);
+        const pages = await Promise.all(batchOffsets.map((blockOffset) => buildDocumentSnapshot(doc, {
+            includeDomains: ['blocks'],
+            blockOffset,
+            blockLimit: pageStride,
+        })));
+        for (let pageIndex = 0; pageIndex < pages.length; pageIndex += 1) {
+            const page = pages[pageIndex];
+            const blockOffset = batchOffsets[pageIndex];
+            assertMutationBlockRead(page, blockOffset);
+            assertMutationSnapshotRevision(first.revision, page.revision);
+            if (page.blocks.length === 0) {
+                throw new MutationSnapshotError('SNAPSHOT_INCOMPLETE', `cannot build complete mutation snapshot: block pagination stopped at ${blockOffset} of ${total} blocks`);
+            }
+            blocks.push(...page.blocks);
+            diagnostics.push(...page.diagnostics);
+        }
+    }
+    if (blocks.length !== total) {
+        throw new MutationSnapshotError('SNAPSHOT_INCOMPLETE', `cannot build complete mutation snapshot: expected ${total} blocks but materialized ${blocks.length}`);
+    }
+    const tables = includeTables ? await buildMutationTables(doc, blocks, diagnostics) : [];
+    const finalIdentity = await buildDocumentSnapshot(doc, { countsOnly: true });
+    assertMutationSnapshotRevision(first.revision, finalIdentity.revision);
+    return {
+        ...first,
+        blocks,
+        tables,
+        diagnostics,
+    };
+}
+async function buildMutationTables(doc, blocks, diagnostics) {
+    const tableBlocks = blocks.filter((block) => block.nodeType === 'table');
+    const tables = tableBlocks.map((block, index) => ({
+        nodeId: block.nodeId,
+        ordinal: index + 1,
+        rows: 0,
+        columns: 0,
+        cells: [],
+    }));
+    const getTable = maybeMethod(doc, ['tables', 'get']);
+    if (getTable) {
+        for (let index = 0; index < tables.length; index += MUTATION_BLOCK_PAGE_CONCURRENCY) {
+            const batch = tables.slice(index, index + MUTATION_BLOCK_PAGE_CONCURRENCY);
+            await Promise.all(batch.map(async (table) => {
+                try {
+                    const raw = asRecord(await getTable({ nodeId: table.nodeId }));
+                    table.rows = asNumber(raw?.rows);
+                    table.columns = asNumber(raw?.columns);
+                }
+                catch (error) {
+                    diagnostics.push({
+                        section: `tables.get:${table.nodeId}`,
+                        message: error instanceof Error ? error.message : String(error),
+                    });
+                }
+            }));
+        }
+    }
+    const extract = maybeMethod(doc, ['extract']);
+    if (tables.length > 0 && extract) {
+        try {
+            populateTableCellsFromExtract(tables, await extract({}));
+        }
+        catch (error) {
+            diagnostics.push({ section: 'extract', message: error instanceof Error ? error.message : String(error) });
+        }
+    }
+    return tables;
+}
+function assertMutationBlockRead(snapshot, blockOffset) {
+    const failure = snapshot.diagnostics.find((diagnostic) => diagnostic.section === 'blocks.list');
+    if (!failure)
+        return;
+    throw new MutationSnapshotError('SNAPSHOT_INCOMPLETE', `cannot build complete mutation snapshot: block page at offset ${blockOffset} failed: ${failure.message}`);
+}
+function assertMutationSnapshotRevision(expected, actual) {
+    if (expected === 'unknown' || actual === 'unknown' || expected === actual)
+        return;
+    throw new MutationSnapshotError('REVISION_CONFLICT', `document changed while resolving mutation selectors (${expected} -> ${actual}); retry the action`);
+}
 /**
  * Structured ambiguity error returned when multiple candidates match a
  * selector and the plan required uniqueness.
@@ -882,6 +1023,8 @@ function resolveSnapshotSelector(snapshot, selector) {
 }
 
 exports.AmbiguousSelectorError = AmbiguousSelectorError;
+exports.MutationSnapshotError = MutationSnapshotError;
 exports.buildDocumentSnapshot = buildDocumentSnapshot;
+exports.buildMutationSnapshot = buildMutationSnapshot;
 exports.matchRunsForBlock = matchRunsForBlock;
 exports.resolveSnapshotSelector = resolveSnapshotSelector;

package/dist/agent/doc-snapshot.d.ts

@@ -313,6 +313,17 @@ type SnapshotOptions = {
  * rest of the snapshot remains usable.
  */
 export declare function buildDocumentSnapshot(doc: BoundDocApi, options?: SnapshotOptions): Promise<DocumentSnapshot>;
+export declare class MutationSnapshotError extends Error {
+    readonly code: 'SNAPSHOT_INCOMPLETE' | 'REVISION_CONFLICT';
+    constructor(code: 'SNAPSHOT_INCOMPLETE' | 'REVISION_CONFLICT', message: string);
+}
+/**
+ * Build the complete block index used to authorize mutations. Inspection
+ * snapshots stay windowed; mutation selectors must not treat that presentation
+ * window as the end of the document. Reads remain bounded and the revision is
+ * checked before the combined snapshot is returned.
+ */
+export declare function buildMutationSnapshot(doc: BoundDocApi, options?: Pick<SnapshotOptions, 'includeDomains'>): Promise<DocumentSnapshot>;
 /**
  * Structured ambiguity error returned when multiple candidates match a
  * selector and the plan required uniqueness.

package/dist/agent/doc-snapshot.js

@@ -97,6 +97,48 @@ function includesDomain(requested, domain) {
 function truncateBlockText(value, limit) {
     return limit == null ? value : value.slice(0, limit);
 }
+function populateTableCellsFromExtract(tables, extractRaw, tableOrdinalBase = 0) {
+    const extractRec = asRecord(extractRaw);
+    const extractBlocks = Array.isArray(extractRec?.blocks) ? extractRec.blocks : [];
+    const cellsByTableNodeId = new Map();
+    for (const block of extractBlocks) {
+        const rec = asRecord(block);
+        const tableContext = asRecord(rec?.tableContext);
+        if (!rec || !tableContext)
+            continue;
+        const tableOrdinal = asNumber(tableContext.tableOrdinal, -1);
+        const rowIndex = asNumber(tableContext.rowIndex, -1);
+        const columnIndex = asNumber(tableContext.columnIndex, -1);
+        if (tableOrdinal < 0 || rowIndex < 0 || columnIndex < 0)
+            continue;
+        const table = tables[tableOrdinal - tableOrdinalBase];
+        if (!table)
+            continue;
+        const key = `${rowIndex}:${columnIndex}`;
+        const text = asString(rec.text);
+        const nodeId = asString(rec.nodeId) || undefined;
+        const cellMap = cellsByTableNodeId.get(table.nodeId) ??
+            new Map();
+        const existing = cellMap.get(key);
+        cellMap.set(key, {
+            rowIndex,
+            columnIndex,
+            text: existing == null || text.length === 0
+                ? (existing?.text ?? text)
+                : existing.text.length === 0
+                    ? text
+                    : `${existing.text}\n${text}`,
+            nodeId: existing?.nodeId ?? nodeId,
+        });
+        cellsByTableNodeId.set(table.nodeId, cellMap);
+    }
+    for (const table of tables) {
+        const cellMap = cellsByTableNodeId.get(table.nodeId);
+        if (!cellMap)
+            continue;
+        table.cells = [...cellMap.values()].sort((left, right) => left.rowIndex - right.rowIndex || left.columnIndex - right.columnIndex);
+    }
+}
 /**
  * Build a deterministic snapshot of a document. The snapshot uses only
  * read-mode operations from the generated contract — it never mutates state,
@@ -402,46 +444,7 @@ export async function buildDocumentSnapshot(doc, options = {}) {
     const extractFn = maybeMethod(doc, ['extract']);
     if (tables.length > 0 && extractFn) {
         const extractRaw = await safeCall(() => extractFn({}), null, recordError('extract'));
-        const extractRec = asRecord(extractRaw);
-        const extractBlocks = Array.isArray(extractRec?.blocks) ? extractRec.blocks : [];
-        const cellsByTableNodeId = new Map();
-        for (const block of extractBlocks) {
-            const rec = asRecord(block);
-            const tableContext = asRecord(rec?.tableContext);
-            if (!rec || !tableContext)
-                continue;
-            const tableOrdinal = asNumber(tableContext.tableOrdinal, -1);
-            const rowIndex = asNumber(tableContext.rowIndex, -1);
-            const columnIndex = asNumber(tableContext.columnIndex, -1);
-            if (tableOrdinal < 0 || rowIndex < 0 || columnIndex < 0)
-                continue;
-            const table = tables[tableOrdinal - precedingTableCount];
-            if (!table)
-                continue;
-            const key = `${rowIndex}:${columnIndex}`;
-            const text = asString(rec.text);
-            const nodeId = asString(rec.nodeId) || undefined;
-            const cellMap = cellsByTableNodeId.get(table.nodeId) ??
-                new Map();
-            const existing = cellMap.get(key);
-            cellMap.set(key, {
-                rowIndex,
-                columnIndex,
-                text: existing == null || text.length === 0
-                    ? (existing?.text ?? text)
-                    : existing.text.length === 0
-                        ? text
-                        : `${existing.text}\n${text}`,
-                nodeId: existing?.nodeId ?? nodeId,
-            });
-            cellsByTableNodeId.set(table.nodeId, cellMap);
-        }
-        for (const table of tables) {
-            const cellMap = cellsByTableNodeId.get(table.nodeId);
-            if (!cellMap)
-                continue;
-            table.cells = [...cellMap.values()].sort((left, right) => left.rowIndex - right.rowIndex || left.columnIndex - right.columnIndex);
-        }
+        populateTableCellsFromExtract(tables, extractRaw, precedingTableCount);
     }
     // Optionally enrich table cells with per-run formatting (opt-in; one
     // query.match per cell, bounded) so a reader can match a cell's pattern.
@@ -746,6 +749,144 @@ export async function buildDocumentSnapshot(doc, options = {}) {
         ...(finds ? { finds } : {}),
     };
 }
+export class MutationSnapshotError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.code = code;
+        this.name = 'MutationSnapshotError';
+    }
+}
+const MUTATION_BLOCK_PAGE_SIZE = 1000;
+const MUTATION_BLOCK_PAGE_CONCURRENCY = 4;
+const MUTATION_NON_TABLE_DOMAINS = [
+    'blocks',
+    'lists',
+    'comments',
+    'trackedChanges',
+    'sections',
+    'headerFooters',
+    'styles',
+    'contentControls',
+    'fields',
+    'hyperlinks',
+    'bookmarks',
+    'permissionRanges',
+    'images',
+];
+/**
+ * Build the complete block index used to authorize mutations. Inspection
+ * snapshots stay windowed; mutation selectors must not treat that presentation
+ * window as the end of the document. Reads remain bounded and the revision is
+ * checked before the combined snapshot is returned.
+ */
+export async function buildMutationSnapshot(doc, options = {}) {
+    const requestedDomains = options.includeDomains == null || options.includeDomains.length === 0 ? null : new Set(options.includeDomains);
+    const includeTables = requestedDomains == null || requestedDomains.has('tables');
+    const firstDomains = requestedDomains == null
+        ? MUTATION_NON_TABLE_DOMAINS
+        : [...requestedDomains].filter((domain) => domain !== 'tables').concat('blocks');
+    const first = await buildDocumentSnapshot(doc, {
+        includeDomains: firstDomains,
+        blockOffset: 0,
+        blockLimit: MUTATION_BLOCK_PAGE_SIZE,
+    });
+    assertMutationBlockRead(first, 0);
+    const total = first.counts.blocks;
+    if (first.blocks.length > total) {
+        throw new MutationSnapshotError('SNAPSHOT_INCOMPLETE', `cannot build complete mutation snapshot: document reports ${total} blocks but returned ${first.blocks.length}`);
+    }
+    if (first.blocks.length === 0 && total > 0) {
+        throw new MutationSnapshotError('SNAPSHOT_INCOMPLETE', `cannot build complete mutation snapshot: document reports ${total} blocks but returned none`);
+    }
+    const blocks = [...first.blocks];
+    const diagnostics = [...first.diagnostics];
+    const pageStride = first.blocks.length || MUTATION_BLOCK_PAGE_SIZE;
+    const offsets = first.blocks.length === total
+        ? []
+        : Array.from({ length: Math.ceil((total - pageStride) / pageStride) }, (_, index) => pageStride * (index + 1));
+    for (let index = 0; index < offsets.length; index += MUTATION_BLOCK_PAGE_CONCURRENCY) {
+        const batchOffsets = offsets.slice(index, index + MUTATION_BLOCK_PAGE_CONCURRENCY);
+        const pages = await Promise.all(batchOffsets.map((blockOffset) => buildDocumentSnapshot(doc, {
+            includeDomains: ['blocks'],
+            blockOffset,
+            blockLimit: pageStride,
+        })));
+        for (let pageIndex = 0; pageIndex < pages.length; pageIndex += 1) {
+            const page = pages[pageIndex];
+            const blockOffset = batchOffsets[pageIndex];
+            assertMutationBlockRead(page, blockOffset);
+            assertMutationSnapshotRevision(first.revision, page.revision);
+            if (page.blocks.length === 0) {
+                throw new MutationSnapshotError('SNAPSHOT_INCOMPLETE', `cannot build complete mutation snapshot: block pagination stopped at ${blockOffset} of ${total} blocks`);
+            }
+            blocks.push(...page.blocks);
+            diagnostics.push(...page.diagnostics);
+        }
+    }
+    if (blocks.length !== total) {
+        throw new MutationSnapshotError('SNAPSHOT_INCOMPLETE', `cannot build complete mutation snapshot: expected ${total} blocks but materialized ${blocks.length}`);
+    }
+    const tables = includeTables ? await buildMutationTables(doc, blocks, diagnostics) : [];
+    const finalIdentity = await buildDocumentSnapshot(doc, { countsOnly: true });
+    assertMutationSnapshotRevision(first.revision, finalIdentity.revision);
+    return {
+        ...first,
+        blocks,
+        tables,
+        diagnostics,
+    };
+}
+async function buildMutationTables(doc, blocks, diagnostics) {
+    const tableBlocks = blocks.filter((block) => block.nodeType === 'table');
+    const tables = tableBlocks.map((block, index) => ({
+        nodeId: block.nodeId,
+        ordinal: index + 1,
+        rows: 0,
+        columns: 0,
+        cells: [],
+    }));
+    const getTable = maybeMethod(doc, ['tables', 'get']);
+    if (getTable) {
+        for (let index = 0; index < tables.length; index += MUTATION_BLOCK_PAGE_CONCURRENCY) {
+            const batch = tables.slice(index, index + MUTATION_BLOCK_PAGE_CONCURRENCY);
+            await Promise.all(batch.map(async (table) => {
+                try {
+                    const raw = asRecord(await getTable({ nodeId: table.nodeId }));
+                    table.rows = asNumber(raw?.rows);
+                    table.columns = asNumber(raw?.columns);
+                }
+                catch (error) {
+                    diagnostics.push({
+                        section: `tables.get:${table.nodeId}`,
+                        message: error instanceof Error ? error.message : String(error),
+                    });
+                }
+            }));
+        }
+    }
+    const extract = maybeMethod(doc, ['extract']);
+    if (tables.length > 0 && extract) {
+        try {
+            populateTableCellsFromExtract(tables, await extract({}));
+        }
+        catch (error) {
+            diagnostics.push({ section: 'extract', message: error instanceof Error ? error.message : String(error) });
+        }
+    }
+    return tables;
+}
+function assertMutationBlockRead(snapshot, blockOffset) {
+    const failure = snapshot.diagnostics.find((diagnostic) => diagnostic.section === 'blocks.list');
+    if (!failure)
+        return;
+    throw new MutationSnapshotError('SNAPSHOT_INCOMPLETE', `cannot build complete mutation snapshot: block page at offset ${blockOffset} failed: ${failure.message}`);
+}
+function assertMutationSnapshotRevision(expected, actual) {
+    if (expected === 'unknown' || actual === 'unknown' || expected === actual)
+        return;
+    throw new MutationSnapshotError('REVISION_CONFLICT', `document changed while resolving mutation selectors (${expected} -> ${actual}); retry the action`);
+}
 /**
  * Structured ambiguity error returned when multiple candidates match a
  * selector and the plan required uniqueness.

package/dist/agent/runtime.cjs

@@ -227,8 +227,8 @@ function computeDeltaChecks(pre, post, checks, saveReopen) {
         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') {
@@ -313,7 +313,7 @@ async function trySaveReopen(doc, checks) {
         await saveAny.call(doc, {});
         // Rebuild a fresh snapshot after save. Host-level true reopen still needs
         // a new document handle, which this runtime cannot force on its own.
-        const fresh = await docSnapshot.buildDocumentSnapshot(doc);
+        const fresh = await docSnapshot.buildMutationSnapshot(doc);
         for (const check of checks) {
             if (check.kind === 'save-reopen-text-contains') {
                 const found = fresh.blocks.some((b) => b.text.includes(check.text));
@@ -350,7 +350,23 @@ async function agentApply(doc, args) {
             errors: validation.errors.map((e) => ({ code: e.code, message: e.message })),
         };
     }
-    const preSnapshot = await docSnapshot.buildDocumentSnapshot(doc);
+    let preSnapshot;
+    try {
+        preSnapshot = await docSnapshot.buildMutationSnapshot(doc);
+    }
+    catch (error) {
+        if (!(error instanceof docSnapshot.MutationSnapshotError))
+            throw error;
+        return {
+            status: 'failed',
+            intent: plan.intent,
+            preSnapshot: { revision: 'unknown', counts: emptyCounts() },
+            selectedTargets: [],
+            executedOperations: [],
+            verification: [],
+            errors: [{ code: error.code, message: error.message, recovery: { kind: 'retry' } }],
+        };
+    }
     const selectedTargets = [];
     const executedOperations = [];
     const bindings = new Map();
@@ -415,7 +431,23 @@ async function agentApply(doc, args) {
             errors: [{ code: 'APPLY_FAILED', message }],
         };
     }
-    const postSnapshot = await docSnapshot.buildDocumentSnapshot(doc);
+    let postSnapshot;
+    try {
+        postSnapshot = await docSnapshot.buildMutationSnapshot(doc);
+    }
+    catch (error) {
+        if (!(error instanceof docSnapshot.MutationSnapshotError))
+            throw error;
+        return {
+            status: 'failed',
+            intent: plan.intent,
+            preSnapshot: { revision: preSnapshot.revision, counts: preSnapshot.counts },
+            selectedTargets,
+            executedOperations,
+            verification: [],
+            errors: [{ code: error.code, message: error.message, recovery: { kind: 'reinspect' } }],
+        };
+    }
     const verifyStep = plan.steps.find((s) => s.kind === 'verify');
     let saveReopen;
     const shouldSaveReopen = (verifyStep?.kind === 'verify' && (verifyStep.saveReopen || verificationNeedsSaveReopen(verifyStep.checks))) ||
@@ -437,7 +469,23 @@ async function agentApply(doc, args) {
     };
 }
 async function agentVerify(doc, args) {
-    const snapshot = await docSnapshot.buildDocumentSnapshot(doc);
+    let snapshot;
+    try {
+        snapshot = await docSnapshot.buildMutationSnapshot(doc);
+    }
+    catch (error) {
+        if (!(error instanceof docSnapshot.MutationSnapshotError))
+            throw error;
+        return {
+            status: 'failed',
+            intent: 'verify',
+            preSnapshot: { revision: 'unknown', counts: emptyCounts() },
+            selectedTargets: [],
+            executedOperations: [],
+            verification: [],
+            errors: [{ code: error.code, message: error.message, recovery: { kind: 'retry' } }],
+        };
+    }
     let saveReopen;
     if (args.saveReopen || verificationNeedsSaveReopen(args.checks)) {
         saveReopen = await trySaveReopen(doc, args.checks);