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

package/dist/agent/catalog.cjs

@@ -146,6 +146,11 @@ const ACTION_ARG_SCHEMA = {
     },
     finds: { type: 'array', items: { type: 'string' } },
     caseSensitive: { type: 'boolean' },
+    evidence: {
+        type: 'string',
+        enum: ['required', 'full'],
+        description: 'Required evidence by default; full includes complete count summaries.',
+    },
     changeMode: { type: 'string', enum: ['direct', 'tracked'] },
     placement: { type: 'object', additionalProperties: true, properties: {} },
     selector: SELECTOR_SCHEMA,
@@ -390,6 +395,11 @@ const AGENT_TOOL_DEFINITIONS = [
             additionalProperties: false,
             required: ['plan'],
             properties: {
+                evidence: {
+                    type: 'string',
+                    enum: ['required', 'full'],
+                    description: 'Required evidence by default; full includes complete count summaries.',
+                },
                 plan: {
                     type: 'object',
                     additionalProperties: false,
@@ -428,6 +438,11 @@ const AGENT_TOOL_DEFINITIONS = [
             additionalProperties: false,
             required: ['checks'],
             properties: {
+                evidence: {
+                    type: 'string',
+                    enum: ['required', 'full'],
+                    description: 'Required evidence by default; full includes complete count summaries.',
+                },
                 checks: {
                     type: 'array',
                     minItems: 1,

package/dist/agent/catalog.js

@@ -143,6 +143,11 @@ export const ACTION_ARG_SCHEMA = {
     },
     finds: { type: 'array', items: { type: 'string' } },
     caseSensitive: { type: 'boolean' },
+    evidence: {
+        type: 'string',
+        enum: ['required', 'full'],
+        description: 'Required evidence by default; full includes complete count summaries.',
+    },
     changeMode: { type: 'string', enum: ['direct', 'tracked'] },
     placement: { type: 'object', additionalProperties: true, properties: {} },
     selector: SELECTOR_SCHEMA,
@@ -387,6 +392,11 @@ export const AGENT_TOOL_DEFINITIONS = [
             additionalProperties: false,
             required: ['plan'],
             properties: {
+                evidence: {
+                    type: 'string',
+                    enum: ['required', 'full'],
+                    description: 'Required evidence by default; full includes complete count summaries.',
+                },
                 plan: {
                     type: 'object',
                     additionalProperties: false,
@@ -425,6 +435,11 @@ export const AGENT_TOOL_DEFINITIONS = [
             additionalProperties: false,
             required: ['checks'],
             properties: {
+                evidence: {
+                    type: 'string',
+                    enum: ['required', 'full'],
+                    description: 'Required evidence by default; full includes complete count summaries.',
+                },
                 checks: {
                     type: 'array',
                     minItems: 1,

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,
@@ -117,57 +159,33 @@ async function buildDocumentSnapshot(doc, options = {}) {
     // first match so one call both LOCATES and READS the target section.
     let finds;
     if (typeof options.findText === 'string' && options.findText.trim().length > 0) {
-        const scanFn = maybeMethod(doc, ['blocks', 'list']);
+        const scanFn = maybeMethod(doc, ['blocks', 'findText']);
         if (scanFn) {
-            // Paginated scan with a hard cap: bounded bridge payloads per page, and
-            // an explicit truncated flag instead of a silently-partial `total`.
-            const SCAN_PAGE = 2000;
-            const SCAN_CAP = 20000;
-            const needle = options.findText.toLowerCase();
             const findLimit = options.findLimit != null && options.findLimit > 0 ? options.findLimit : 8;
-            const matches = [];
-            let scanned = 0;
-            let truncated = false;
-            for (let pageOffset = 0; pageOffset < SCAN_CAP; pageOffset += SCAN_PAGE) {
-                const scanRaw = await safeCall(() => scanFn({ offset: pageOffset, limit: SCAN_PAGE, includeText: true }), null, recordError('blocks.findText'));
-                const scanRec = asRecord(scanRaw);
-                const scanBlocks = Array.isArray(scanRec?.blocks) ? scanRec.blocks : [];
-                scanBlocks.forEach((b, i) => {
-                    const rec = asRecord(b) ?? {};
-                    const text = asString(rec.text);
-                    if (!text || !text.toLowerCase().includes(needle))
-                        return;
-                    matches.push({
-                        ordinal: asNumber(rec.ordinal, pageOffset + i) + 1,
-                        nodeId: asString(rec.nodeId),
-                        nodeType: asString(rec.nodeType, 'paragraph'),
-                        preview: text.slice(0, 100),
-                        index: asNumber(rec.ordinal, pageOffset + i),
-                    });
-                });
-                scanned += scanBlocks.length;
-                const totalBlocksReported = explicitCount(scanRec ?? {}, 'total');
-                if (scanBlocks.length < SCAN_PAGE)
-                    break; // last page
-                if (totalBlocksReported != null && scanned >= totalBlocksReported)
-                    break;
-                if (pageOffset + SCAN_PAGE >= SCAN_CAP) {
-                    truncated = true;
-                    break;
-                }
-            }
+            const scanRaw = await safeCall(() => scanFn({ text: options.findText, limit: Math.min(20000, Math.trunc(findLimit)) }), null, recordError('blocks.findText'));
+            const scan = asRecord(scanRaw);
+            const scanError = asRecord(scan?.scanError);
+            if (typeof scanError?.message === 'string')
+                recordError('blocks.findText')(scanError.message);
+            const matches = Array.isArray(scan?.matches) ? scan.matches : [];
             finds = {
                 query: options.findText,
-                total: matches.length,
-                ...(truncated ? { truncated: true } : {}),
-                scannedBlocks: scanned,
-                matches: matches.slice(0, findLimit).map(({ index: _index, nodeId, ...m }) => ({
-                    ...m,
-                    ...(nodeId ? { nodeId } : {}),
-                })),
+                total: asNumber(scan?.total),
+                ...(scan?.truncated === true ? { truncated: true } : {}),
+                scannedBlocks: asNumber(scan?.scannedBlocks),
+                matches: matches.map((match) => {
+                    const rec = asRecord(match) ?? {};
+                    const nodeId = asString(rec.nodeId);
+                    return {
+                        ordinal: asNumber(rec.ordinal) + 1,
+                        ...(nodeId ? { nodeId } : {}),
+                        nodeType: asString(rec.nodeType, 'paragraph'),
+                        preview: asString(rec.preview),
+                    };
+                }),
             };
-            if (matches.length > 0 && options.blockOffset == null) {
-                blockOffset = Math.max(0, matches[0].index - 2);
+            if (typeof scan?.firstMatchOrdinal === 'number' && options.blockOffset == null) {
+                blockOffset = Math.max(0, scan.firstMatchOrdinal - 2);
                 blockLimit = options.blockLimit != null && options.blockLimit > 0 ? options.blockLimit : 12;
             }
         }
@@ -404,46 +422,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 +727,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 +999,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.