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

package/README.md

@@ -48,6 +48,51 @@ is not supported for Liveblocks or the standalone document host.
 
 See the [Node.js SDK guide](https://docs.superdoc.dev/agents/automation/node-sdk) for a complete workflow.
 
+## Agent execution evidence
+
+The core preset's `agent_apply`, `agent_verify`, and supported named actions
+collect the facts their targets and checks need. Supported document-host sessions
+can read body block identities and text, table shape, exact requested block
+counts, and document revisions without collecting complete snapshots. The named
+paths cover table creation and cell styling, body paragraph formatting and
+rewriting, and paragraph insertion around a selected anchor.
+
+The shared execution paths on supported hosts guard edits with document revisions.
+An intervening edit can stop a later step; a failed action may therefore include operations that already committed.
+
+This changes default receipts for eligible plans: `preSnapshot.counts` and
+`postSnapshot.counts` are absent, not zero. Callers that previously consumed these
+counts should request `evidence: 'full'`:
+
+```js
+import { dispatchSuperDocTool } from '@superdoc/sdk';
+
+const receipt = await dispatchSuperDocTool(document, 'agent_apply', {
+  evidence: 'full',
+  plan: {
+    intent: 'Append a paragraph with complete count evidence',
+    steps: [
+      { kind: 'apply', operationId: 'doc.create.paragraph', args: { text: 'Approved.' } },
+      { kind: 'verify', checks: [{ kind: 'revision-changed' }] },
+    ],
+  },
+}, { preset: 'core' });
+```
+
+`evidence: 'required'` is the default. Requested block-count checks remain exact
+without adding unrequested receipt summaries. `evidence: 'full'` is also available
+on `agent_verify` and the named `create_table`, `format_paragraph`, `rewrite_block`,
+and `insert_paragraphs` actions.
+
+Unsupported selectors and checks, inspection dependencies, multiple-operation
+plans, atomic plans, and save verification retain complete evidence. Older hosts
+with compact revision support retain the single-paragraph, revision-only path;
+other unsupported hosts and plain bound API handles use complete snapshots.
+
+A failed receipt can disclose a committed mutation when post-edit verification
+fails. Inspect `executedOperations` and the reported error before retrying; do not
+automatically replay the write.
+
 ## License
 
 AGPL-3.0. Commercial licenses are available from [SuperDoc](https://www.superdoc.dev).

package/dist/action-primitives/doc-index.cjs

@@ -26,9 +26,10 @@ async function listAllBlocks(documentHandle, invokeOptions, pageLimit) {
         const page = await documentHandle.blocks.list({ offset, limit: pageLimit, includeText: false }, invokeOptions);
         blocks.push(...page.blocks);
         offset += page.blocks.length;
-        if (page.blocks.length === 0 || offset >= page.total) {
+        if (offset >= page.total)
             break;
-        }
+        if (page.blocks.length === 0)
+            throw new Error('Required complete block index stopped before the reported total.');
     }
     return blocks;
 }
@@ -39,9 +40,10 @@ async function listAllListItems(documentHandle, invokeOptions, pageLimit) {
         const page = await documentHandle.lists.list({ offset, limit: pageLimit }, invokeOptions);
         items.push(...page.items);
         offset += page.items.length;
-        if (page.items.length === 0 || offset >= page.total) {
+        if (offset >= page.total)
             break;
-        }
+        if (page.items.length === 0)
+            throw new Error('Required complete list index stopped before the reported total.');
     }
     return items;
 }

package/dist/action-primitives/doc-index.js

@@ -24,9 +24,10 @@ async function listAllBlocks(documentHandle, invokeOptions, pageLimit) {
         const page = await documentHandle.blocks.list({ offset, limit: pageLimit, includeText: false }, invokeOptions);
         blocks.push(...page.blocks);
         offset += page.blocks.length;
-        if (page.blocks.length === 0 || offset >= page.total) {
+        if (offset >= page.total)
             break;
-        }
+        if (page.blocks.length === 0)
+            throw new Error('Required complete block index stopped before the reported total.');
     }
     return blocks;
 }
@@ -37,9 +38,10 @@ async function listAllListItems(documentHandle, invokeOptions, pageLimit) {
         const page = await documentHandle.lists.list({ offset, limit: pageLimit }, invokeOptions);
         items.push(...page.items);
         offset += page.items.length;
-        if (page.items.length === 0 || offset >= page.total) {
+        if (offset >= page.total)
             break;
-        }
+        if (page.items.length === 0)
+            throw new Error('Required complete list index stopped before the reported total.');
     }
     return items;
 }

package/dist/action-primitives/engine.cjs

@@ -1,5 +1,6 @@
 'use strict';
 
+var executionContext = require('../agent/execution-context.cjs');
 var docIndex = require('./doc-index.cjs');
 var receipt = require('./receipt.cjs');
 var sessionCache = require('./session-cache.cjs');
@@ -22,6 +23,7 @@ function workflowNotImplementedFailure(input) {
 function toIndexSummary(index) {
     return {
         revision: index.revision,
+        evidence: { coverage: 'complete', reason: 'action primitives require complete block/list/table indexes' },
         blocks: index.blocks.length,
         lists: index.lists.length,
         tables: index.tables.length,
@@ -40,12 +42,14 @@ async function ensureDocIndex(input) {
     if (cached != null) {
         return { sessionState, info, index: cached };
     }
-    const index = await docIndex.buildWorkflowDocIndex({
+    const facts = new executionContext.DocumentFacts(input.documentHandle, info.revision);
+    const acquired = await facts.completeIndex('action primitives require complete block/list/table indexes', () => docIndex.buildWorkflowDocIndex({
         documentHandle: input.documentHandle,
         documentKey: sessionState.documentKey,
         invokeOptions: input.invokeOptions,
         info,
-    });
+    }));
+    const index = acquired.value;
     input.cache.setCachedIndex(input.documentHandle, index);
     return { sessionState, info, index };
 }

package/dist/action-primitives/engine.js

@@ -1,3 +1,4 @@
+import { DocumentFacts } from '../agent/execution-context.js';
 import { buildWorkflowDocIndex } from './doc-index.js';
 import { createWorkflowFailureReceipt, createWorkflowNotImplementedReceipt, createWorkflowSuccessReceipt, } from './receipt.js';
 import { workflowPocSessionCache } from './session-cache.js';
@@ -19,6 +20,7 @@ export function workflowNotImplementedFailure(input) {
 function toIndexSummary(index) {
     return {
         revision: index.revision,
+        evidence: { coverage: 'complete', reason: 'action primitives require complete block/list/table indexes' },
         blocks: index.blocks.length,
         lists: index.lists.length,
         tables: index.tables.length,
@@ -37,12 +39,14 @@ async function ensureDocIndex(input) {
     if (cached != null) {
         return { sessionState, info, index: cached };
     }
-    const index = await buildWorkflowDocIndex({
+    const facts = new DocumentFacts(input.documentHandle, info.revision);
+    const acquired = await facts.completeIndex('action primitives require complete block/list/table indexes', () => buildWorkflowDocIndex({
         documentHandle: input.documentHandle,
         documentKey: sessionState.documentKey,
         invokeOptions: input.invokeOptions,
         info,
-    });
+    }));
+    const index = acquired.value;
     input.cache.setCachedIndex(input.documentHandle, index);
     return { sessionState, info, index };
 }

package/dist/action-primitives/receipt.d.ts

@@ -3,6 +3,10 @@ export declare const WORKFLOW_POC_PROFILE: "workflow-poc";
 export type WorkflowExecutionPhase = 'resolve' | 'plan' | 'execute' | 'verify';
 export type WorkflowReceiptStatus = 'success' | 'failed' | 'not_implemented';
 export type WorkflowIndexSummary = {
+    evidence?: {
+        coverage: 'complete';
+        reason: string;
+    };
     revision: string;
     blocks: number;
     lists: number;

package/dist/action-primitives/tools/structure-insert.d.ts

@@ -165,7 +165,7 @@ export type RunSuperdocStructureInsertInput = {
 };
 declare function summarizePlacement(placement: SuperdocStructureInsertPlacement): {
     mode: "document";
-    at: "document_end" | "document_start";
+    at: "document_start" | "document_end";
     source: "default" | "provided";
     position?: undefined;
     targetNodeId?: undefined;