@superdoc/sdk 2.25.0-next.9 → 2.26.0-next.1

package/dist/agent/action-change-mode.cjs

@@ -2,12 +2,22 @@
 
 var documentEvidence = require('../runtime/document-evidence.cjs');
 var operationCatalog = require('./operation-catalog.cjs');
+var contract = require('../generated/contract.cjs');
+var errors = require('../runtime/errors.cjs');
 
 const unboundDocuments = new WeakMap();
 function withoutActionChangeMode(document) {
     return unboundDocuments.get(document) ?? document;
 }
 function bindActionChangeMode(document, changeMode) {
+    return bindActionInvokeOptions(document, { changeMode });
+}
+function bindActionExpectedRevision(document, expectedRevision) {
+    return bindActionInvokeOptions(document, { expectedRevision });
+}
+function bindActionInvokeOptions(document, invocation) {
+    let pendingRevision = invocation.expectedRevision;
+    const changeMode = invocation.changeMode;
     const wrap = (value, path, owner) => new Proxy(value, {
         get(target, property, receiver) {
             const member = Reflect.get(target, property, receiver);
@@ -15,12 +25,39 @@ function bindActionChangeMode(document, changeMode) {
                 return member;
             const memberPath = [...path, property];
             if (typeof member === 'function' && operationCatalog.getOperationCatalogEntry(`doc.${memberPath.join('.')}`)?.isMutating) {
-                return (input = {}, options) => Reflect.apply(member, target, [
-                    // CLI inputs can already contain a mode. Keep it consistent with
-                    // the options used by in-process Document API hosts.
-                    input.changeMode === undefined ? input : { ...input, changeMode },
-                    { ...options, changeMode },
-                ]);
+                return (input = {}, options) => {
+                    let expectedRevision = pendingRevision;
+                    if (expectedRevision !== undefined) {
+                        const spec = contract.CONTRACT.operations[`doc.${memberPath.join('.')}`]?.params.find((param) => param.name === 'expectedRevision');
+                        if (spec?.type === 'number') {
+                            const numeric = Number(expectedRevision);
+                            if (!/^(0|[1-9]\d*)$/.test(expectedRevision) || !Number.isSafeInteger(numeric))
+                                throw new errors.SuperDocCliError('This operation requires a canonical numeric revision.', {
+                                    code: 'INVALID_ARGUMENT',
+                                });
+                            expectedRevision = numeric;
+                        }
+                        else if (spec?.type !== 'string') {
+                            throw new errors.SuperDocCliError('This operation cannot enforce an expected revision.', {
+                                code: 'CAPABILITY_UNSUPPORTED',
+                            });
+                        }
+                        pendingRevision = undefined;
+                    }
+                    return Reflect.apply(member, target, [
+                        // CLI inputs can already contain a mode. Keep it consistent with
+                        // the options used by in-process Document API hosts.
+                        {
+                            ...(input.changeMode === undefined || changeMode === undefined ? input : { ...input, changeMode }),
+                            ...(expectedRevision === undefined ? {} : { expectedRevision }),
+                        },
+                        {
+                            ...options,
+                            ...(changeMode === undefined ? {} : { changeMode }),
+                            ...(expectedRevision === undefined ? {} : { expectedRevision }),
+                        },
+                    ]);
+                };
             }
             if (member && (typeof member === 'object' || typeof member === 'function')) {
                 return wrap(member, memberPath, target);
@@ -38,4 +75,5 @@ function bindActionChangeMode(document, changeMode) {
 }
 
 exports.bindActionChangeMode = bindActionChangeMode;
+exports.bindActionExpectedRevision = bindActionExpectedRevision;
 exports.withoutActionChangeMode = withoutActionChangeMode;

package/dist/agent/action-change-mode.d.ts

@@ -2,3 +2,4 @@ import type { BoundDocApi } from '../generated/client.js';
 import type { AgentChangeMode } from './ir.js';
 export declare function withoutActionChangeMode(document: BoundDocApi): BoundDocApi;
 export declare function bindActionChangeMode(document: BoundDocApi, changeMode: AgentChangeMode): BoundDocApi;
+export declare function bindActionExpectedRevision(document: BoundDocApi, expectedRevision: string): BoundDocApi;

package/dist/agent/action-change-mode.js

@@ -1,10 +1,20 @@
 import { forwardDocumentEvidence } from '../runtime/document-evidence.js';
 import { getOperationCatalogEntry } from './operation-catalog.js';
+import { CONTRACT } from '../generated/contract.js';
+import { SuperDocCliError } from '../runtime/errors.js';
 const unboundDocuments = new WeakMap();
 export function withoutActionChangeMode(document) {
     return unboundDocuments.get(document) ?? document;
 }
 export function bindActionChangeMode(document, changeMode) {
+    return bindActionInvokeOptions(document, { changeMode });
+}
+export function bindActionExpectedRevision(document, expectedRevision) {
+    return bindActionInvokeOptions(document, { expectedRevision });
+}
+function bindActionInvokeOptions(document, invocation) {
+    let pendingRevision = invocation.expectedRevision;
+    const changeMode = invocation.changeMode;
     const wrap = (value, path, owner) => new Proxy(value, {
         get(target, property, receiver) {
             const member = Reflect.get(target, property, receiver);
@@ -12,12 +22,39 @@ export function bindActionChangeMode(document, changeMode) {
                 return member;
             const memberPath = [...path, property];
             if (typeof member === 'function' && getOperationCatalogEntry(`doc.${memberPath.join('.')}`)?.isMutating) {
-                return (input = {}, options) => Reflect.apply(member, target, [
-                    // CLI inputs can already contain a mode. Keep it consistent with
-                    // the options used by in-process Document API hosts.
-                    input.changeMode === undefined ? input : { ...input, changeMode },
-                    { ...options, changeMode },
-                ]);
+                return (input = {}, options) => {
+                    let expectedRevision = pendingRevision;
+                    if (expectedRevision !== undefined) {
+                        const spec = CONTRACT.operations[`doc.${memberPath.join('.')}`]?.params.find((param) => param.name === 'expectedRevision');
+                        if (spec?.type === 'number') {
+                            const numeric = Number(expectedRevision);
+                            if (!/^(0|[1-9]\d*)$/.test(expectedRevision) || !Number.isSafeInteger(numeric))
+                                throw new SuperDocCliError('This operation requires a canonical numeric revision.', {
+                                    code: 'INVALID_ARGUMENT',
+                                });
+                            expectedRevision = numeric;
+                        }
+                        else if (spec?.type !== 'string') {
+                            throw new SuperDocCliError('This operation cannot enforce an expected revision.', {
+                                code: 'CAPABILITY_UNSUPPORTED',
+                            });
+                        }
+                        pendingRevision = undefined;
+                    }
+                    return Reflect.apply(member, target, [
+                        // CLI inputs can already contain a mode. Keep it consistent with
+                        // the options used by in-process Document API hosts.
+                        {
+                            ...(input.changeMode === undefined || changeMode === undefined ? input : { ...input, changeMode }),
+                            ...(expectedRevision === undefined ? {} : { expectedRevision }),
+                        },
+                        {
+                            ...options,
+                            ...(changeMode === undefined ? {} : { changeMode }),
+                            ...(expectedRevision === undefined ? {} : { expectedRevision }),
+                        },
+                    ]);
+                };
             }
             if (member && (typeof member === 'object' || typeof member === 'function')) {
                 return wrap(member, memberPath, target);

package/dist/agent/actions.cjs

@@ -1111,7 +1111,7 @@ function granularGlobalEvidence({ applied }, skippedEdits, requested) {
     };
 }
 async function runGlobalReplace(doc, args, pre) {
-    assertExpectedReplacementRevision(args.expectedRevision, pre.revision);
+    assertExpectedActionRevision(args.expectedRevision, pre.revision);
     assertReplacementTextPayloads(args.edits);
     if (args.edits.length === 0) {
         return failedReceipt('replace_text', new Error('edits must be non-empty'), pre);
@@ -4779,12 +4779,17 @@ function parseReplacementGranularity(value) {
     }
     return granularity;
 }
-function assertExpectedReplacementRevision(expected, actual) {
-    if (expected != null && expected !== actual) {
-        throw new errors.SuperDocCliError('replace_text: expectedRevision is stale. Inspect this live document again before editing.', {
-            code: 'REVISION_CONFLICT',
-        });
-    }
+function staleRevisionError(action) {
+    return new errors.SuperDocCliError(`${action}: expectedRevision is stale. Inspect this live document again before editing.`, {
+        code: 'REVISION_CONFLICT',
+    });
+}
+function assertExpectedActionRevision(expected, actual, action = 'replace_text') {
+    if (expected != null && expected !== actual)
+        throw staleRevisionError(action);
+}
+function staleActionRevisionReceipt(action, liveRevision) {
+    return { ...failedReceipt(action, staleRevisionError(action)), preSnapshot: { revision: liveRevision } };
 }
 // Ranges of the block text that may show a body field's result. Field
 // results carry no offsets, so every place the result text occurs counts,
@@ -4825,7 +4830,7 @@ async function fieldResultRanges(doc, nodeId, blockText) {
 async function resolveScopedReplaceTarget(doc, args) {
     assertReplacementTextPayloads(args.edits);
     const pre = await docSnapshot.buildMutationSnapshot(doc, { includeDomains: ['blocks', 'tables'] });
-    assertExpectedReplacementRevision(args.expectedRevision, pre.revision);
+    assertExpectedActionRevision(args.expectedRevision, pre.revision);
     const matched = docSnapshot.resolveSnapshotSelector(pre, args.selector);
     if (matched.length !== 1) {
         const failure = describeSelectorFailure(args.selector, matched, pre, args.edits.map((e) => e.find));
@@ -7990,10 +7995,12 @@ exports.ACTION_DISPOSITIONS = ACTION_DISPOSITIONS;
 exports.ACTION_GROUPS = ACTION_GROUPS;
 exports.ACTION_HINTS = ACTION_HINTS;
 exports.ACTION_NAMES_LIST = ACTION_NAMES_LIST;
+exports.assertExpectedActionRevision = assertExpectedActionRevision;
 exports.getActionDispositions = getActionDispositions;
 exports.getUnavailableTrackedActions = getUnavailableTrackedActions;
 exports.isActionName = isActionName;
 exports.markerShapeOf = markerShapeOf;
+exports.staleActionRevisionReceipt = staleActionRevisionReceipt;
 exports.superdocPerformAction = superdocPerformAction;
 exports.typedCaptionSpanOf = typedCaptionSpanOf;
 exports.typedMarkerPrefixOf = typedMarkerPrefixOf;

package/dist/agent/actions.d.ts

@@ -493,6 +493,8 @@ export type AddHyperlinkArgs = {
     url: string;
     tooltip?: string;
 };
+export declare function assertExpectedActionRevision(expected: string | undefined, actual: string, action?: string): void;
+export declare function staleActionRevisionReceipt(action: string, liveRevision: string): AgentReceipt;
 export declare function typedMarkerPrefixOf(text: string): {
     prefix: string;
     marker: string;

package/dist/agent/actions.js

@@ -1108,7 +1108,7 @@ function granularGlobalEvidence({ applied }, skippedEdits, requested) {
     };
 }
 async function runGlobalReplace(doc, args, pre) {
-    assertExpectedReplacementRevision(args.expectedRevision, pre.revision);
+    assertExpectedActionRevision(args.expectedRevision, pre.revision);
     assertReplacementTextPayloads(args.edits);
     if (args.edits.length === 0) {
         return failedReceipt('replace_text', new Error('edits must be non-empty'), pre);
@@ -4776,12 +4776,17 @@ function parseReplacementGranularity(value) {
     }
     return granularity;
 }
-function assertExpectedReplacementRevision(expected, actual) {
-    if (expected != null && expected !== actual) {
-        throw new SuperDocCliError('replace_text: expectedRevision is stale. Inspect this live document again before editing.', {
-            code: 'REVISION_CONFLICT',
-        });
-    }
+function staleRevisionError(action) {
+    return new SuperDocCliError(`${action}: expectedRevision is stale. Inspect this live document again before editing.`, {
+        code: 'REVISION_CONFLICT',
+    });
+}
+export function assertExpectedActionRevision(expected, actual, action = 'replace_text') {
+    if (expected != null && expected !== actual)
+        throw staleRevisionError(action);
+}
+export function staleActionRevisionReceipt(action, liveRevision) {
+    return { ...failedReceipt(action, staleRevisionError(action)), preSnapshot: { revision: liveRevision } };
 }
 // Ranges of the block text that may show a body field's result. Field
 // results carry no offsets, so every place the result text occurs counts,
@@ -4822,7 +4827,7 @@ async function fieldResultRanges(doc, nodeId, blockText) {
 async function resolveScopedReplaceTarget(doc, args) {
     assertReplacementTextPayloads(args.edits);
     const pre = await buildMutationSnapshot(doc, { includeDomains: ['blocks', 'tables'] });
-    assertExpectedReplacementRevision(args.expectedRevision, pre.revision);
+    assertExpectedActionRevision(args.expectedRevision, pre.revision);
     const matched = resolveSnapshotSelector(pre, args.selector);
     if (matched.length !== 1) {
         const failure = describeSelectorFailure(args.selector, matched, pre, args.edits.map((e) => e.find));