@superdoc/sdk 2.7.0 → 2.8.0

package/dist/generated/client.d.ts

@@ -29333,6 +29333,7 @@ export interface DocOpenParams {
         url: string;
         documentId?: string;
         tokenEnv?: string;
+        headersEnv?: string;
         params?: Record<string, unknown>;
         syncTimeoutMs?: number;
         roomMode?: "join" | "create";

package/dist/generated/contract.cjs

@@ -296902,6 +296902,10 @@ const CONTRACT = {
                                         "type": "string",
                                         "description": "Environment variable name containing the auth token."
                                     },
+                                    "headersEnv": {
+                                        "type": "string",
+                                        "description": "Environment variable name containing JSON WebSocket headers. Supported by y-websocket."
+                                    },
                                     "params": {
                                         "type": "object",
                                         "description": "Custom query parameters appended to the WebSocket URL. Values must be strings. Reserved keys: token.",
@@ -297149,6 +297153,10 @@ const CONTRACT = {
                                         "type": "string",
                                         "description": "Environment variable name containing the auth token."
                                     },
+                                    "headersEnv": {
+                                        "type": "string",
+                                        "description": "Environment variable name containing JSON WebSocket headers. Supported by y-websocket."
+                                    },
                                     "params": {
                                         "type": "object",
                                         "description": "Custom query parameters appended to the WebSocket URL. Values must be strings. Reserved keys: token.",

package/dist/generated/contract.js

@@ -299816,6 +299816,10 @@ export const CONTRACT = {
                                         "type": "string",
                                         "description": "Environment variable name containing the auth token."
                                     },
+                                    "headersEnv": {
+                                        "type": "string",
+                                        "description": "Environment variable name containing JSON WebSocket headers. Supported by y-websocket."
+                                    },
                                     "params": {
                                         "type": "object",
                                         "description": "Custom query parameters appended to the WebSocket URL. Values must be strings. Reserved keys: token.",
@@ -300063,6 +300067,10 @@ export const CONTRACT = {
                                         "type": "string",
                                         "description": "Environment variable name containing the auth token."
                                     },
+                                    "headersEnv": {
+                                        "type": "string",
+                                        "description": "Environment variable name containing JSON WebSocket headers. Supported by y-websocket."
+                                    },
                                     "params": {
                                         "type": "object",
                                         "description": "Custom query parameters appended to the WebSocket URL. Values must be strings. Reserved keys: token.",

package/dist/index.cjs

@@ -153,11 +153,11 @@ class SuperDocClient {
         return introspection.describeContractOperation(params);
     }
     async dispose() {
+        await this.runtime.dispose();
         for (const handle of this.handles.values()) {
             handle.markClosed();
         }
         this.handles.clear();
-        await this.runtime.dispose();
     }
     /** @internal */
     removeHandle(sessionId) {

package/dist/index.js

@@ -145,11 +145,11 @@ export class SuperDocClient {
         return describeContractOperation(params);
     }
     async dispose() {
+        await this.runtime.dispose();
         for (const handle of this.handles.values()) {
             handle.markClosed();
         }
         this.handles.clear();
-        await this.runtime.dispose();
     }
     /** @internal */
     removeHandle(sessionId) {

package/dist/runtime/embedded-platform.cjs

@@ -4,6 +4,7 @@ var node_fs = require('node:fs');
 var node_module = require('node:module');
 var path = require('node:path');
 var node_url = require('node:url');
+var sdkVersion_generated = require('./sdk-version.generated.cjs');
 
 var _documentCurrentScript = typeof document !== 'undefined' ? document.currentScript : null;
 const require$1 = node_module.createRequire((typeof document === 'undefined' ? require('u' + 'rl').pathToFileURL(__filename).href : (_documentCurrentScript && _documentCurrentScript.tagName.toUpperCase() === 'SCRIPT' && _documentCurrentScript.src || new URL('runtime/embedded-platform.cjs', document.baseURI).href)));
@@ -50,31 +51,36 @@ function resolveFromPackageLocal(target, binaryName) {
  * Resolve the platform package through Node, and reject a version that is not
  * this SDK's own.
  *
- * `require.resolve` falls back to NODE_PATH, which package managers set to a
- * flat store directory (pnpm does it for every binary shim). A host binary from
- * an unrelated SDK version installed anywhere in that store then satisfies this
- * lookup, and the SDK silently drives a foreign engine: seen in the wild as an
- * SDK 2.2.1 install executing a hoisted 2.0.0 host, which failed operations the
- * matching host performs correctly. optionalDependencies pin the platform
- * package to an exact version, so a mismatch here is never legitimate.
+ * Resolution starts from the installed SDK so pnpm's isolated optional
+ * dependency remains visible after the SDK itself is bundled. `require.resolve`
+ * can also fall back to NODE_PATH, so the version check prevents a host binary
+ * from an unrelated SDK version in a flat store from satisfying this lookup.
+ * optionalDependencies pin the platform package to an exact version, so a
+ * mismatch here is never legitimate.
  */
 function resolveFromPlatformPackage(target, binaryName) {
     const pkg = TARGET_TO_PACKAGE[target];
+    let sdkRequire;
+    try {
+        sdkRequire = node_module.createRequire(require$1.resolve('@superdoc/sdk'));
+    }
+    catch {
+        sdkRequire = require$1;
+    }
     let binaryPath;
     try {
-        binaryPath = require$1.resolve(`${pkg}/bin/${binaryName}`);
+        binaryPath = sdkRequire.resolve(`${pkg}/bin/${binaryName}`);
     }
     catch {
         return null;
     }
     try {
-        const platformVersion = require$1(require$1.resolve(`${pkg}/package.json`)).version;
-        const ownVersion = require$1(node_url.fileURLToPath(new URL('../../package.json', (typeof document === 'undefined' ? require('u' + 'rl').pathToFileURL(__filename).href : (_documentCurrentScript && _documentCurrentScript.tagName.toUpperCase() === 'SCRIPT' && _documentCurrentScript.src || new URL('runtime/embedded-platform.cjs', document.baseURI).href))))).version;
-        if (platformVersion !== ownVersion)
+        const platformVersion = sdkRequire(sdkRequire.resolve(`${pkg}/package.json`)).version;
+        if (platformVersion !== sdkVersion_generated.SDK_VERSION)
             return null;
     }
     catch {
-        // Either manifest being unreadable is itself disqualifying: an unverifiable
+        // An unreadable platform manifest is itself disqualifying: an unverifiable
         // host is exactly the case this guard exists to reject.
         return null;
     }

package/dist/runtime/embedded-platform.js

@@ -2,6 +2,7 @@ import { chmodSync, existsSync } from 'node:fs';
 import { createRequire } from 'node:module';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
+import { SDK_VERSION } from './sdk-version.generated.js';
 const require = createRequire(import.meta.url);
 const TARGET_TO_PACKAGE = {
     'darwin-arm64': '@superdoc/sdk-darwin-arm64',
@@ -46,31 +47,36 @@ function resolveFromPackageLocal(target, binaryName) {
  * Resolve the platform package through Node, and reject a version that is not
  * this SDK's own.
  *
- * `require.resolve` falls back to NODE_PATH, which package managers set to a
- * flat store directory (pnpm does it for every binary shim). A host binary from
- * an unrelated SDK version installed anywhere in that store then satisfies this
- * lookup, and the SDK silently drives a foreign engine: seen in the wild as an
- * SDK 2.2.1 install executing a hoisted 2.0.0 host, which failed operations the
- * matching host performs correctly. optionalDependencies pin the platform
- * package to an exact version, so a mismatch here is never legitimate.
+ * Resolution starts from the installed SDK so pnpm's isolated optional
+ * dependency remains visible after the SDK itself is bundled. `require.resolve`
+ * can also fall back to NODE_PATH, so the version check prevents a host binary
+ * from an unrelated SDK version in a flat store from satisfying this lookup.
+ * optionalDependencies pin the platform package to an exact version, so a
+ * mismatch here is never legitimate.
  */
 function resolveFromPlatformPackage(target, binaryName) {
     const pkg = TARGET_TO_PACKAGE[target];
+    let sdkRequire;
+    try {
+        sdkRequire = createRequire(require.resolve('@superdoc/sdk'));
+    }
+    catch {
+        sdkRequire = require;
+    }
     let binaryPath;
     try {
-        binaryPath = require.resolve(`${pkg}/bin/${binaryName}`);
+        binaryPath = sdkRequire.resolve(`${pkg}/bin/${binaryName}`);
     }
     catch {
         return null;
     }
     try {
-        const platformVersion = require(require.resolve(`${pkg}/package.json`)).version;
-        const ownVersion = require(fileURLToPath(new URL('../../package.json', import.meta.url))).version;
-        if (platformVersion !== ownVersion)
+        const platformVersion = sdkRequire(sdkRequire.resolve(`${pkg}/package.json`)).version;
+        if (platformVersion !== SDK_VERSION)
             return null;
     }
     catch {
-        // Either manifest being unreadable is itself disqualifying: an unverifiable
+        // An unreadable platform manifest is itself disqualifying: an unverifiable
         // host is exactly the case this guard exists to reject.
         return null;
     }

package/dist/runtime/host.cjs

@@ -98,9 +98,15 @@ class HostTransport {
     pending = new Map();
     nextRequestId = 1;
     connecting = null;
+    disposePromise = null;
+    terminalDisposalError = null;
     stopping = false;
+    activeCalls = new Set();
     hostFeatures = new Set();
     documentRpcSessions = new Set();
+    dirtyDocumentRpcSessions = new Set();
+    documentRpcMutationStates = new Map();
+    indeterminateDiscardCloses = new Set();
     constructor(options) {
         this.hostBin = options.hostBin;
         this.processMode = options.processMode ?? 'cli';
@@ -121,12 +127,43 @@ class HostTransport {
         this.documentRpcEnabled = this.processMode === 'document' || documentRpc.documentRpcEnabled(options.env);
     }
     async connect() {
-        await this.ensureConnected();
+        await this.runWhileActive(() => this.ensureConnected());
     }
     async dispose() {
-        if (!this.child)
+        if (this.disposePromise)
+            return this.disposePromise;
+        if (this.terminalDisposalError)
+            throw this.terminalDisposalError;
+        if (!this.child && !this.connecting && this.activeCalls.size === 0)
             return;
         this.stopping = true;
+        const disposal = this.disposeAfterActiveCalls();
+        this.disposePromise = disposal;
+        try {
+            await disposal;
+        }
+        finally {
+            if (this.disposePromise === disposal)
+                this.disposePromise = null;
+            this.stopping = false;
+        }
+    }
+    async disposeAfterActiveCalls() {
+        await Promise.allSettled(Array.from(this.activeCalls));
+        if (this.terminalDisposalError)
+            throw this.terminalDisposalError;
+        if (!this.child)
+            return;
+        try {
+            await this.reconcileIndeterminateDiscardCloses();
+            await this.persistDirtyDocumentRpcSessions();
+        }
+        catch (error) {
+            if (!this.child && error instanceof errors.SuperDocCliError) {
+                this.terminalDisposalError = error;
+            }
+            throw error;
+        }
         const child = this.child;
         try {
             await this.sendJsonRpcRequest('host.shutdown', {}, this.shutdownTimeoutMs);
@@ -145,9 +182,11 @@ class HostTransport {
             });
         });
         this.cleanupProcess(null);
-        this.stopping = false;
     }
     async invoke(operation, params = {}, options = {}) {
+        return this.runWhileActive(() => this.invokeWhileActive(operation, params, options));
+    }
+    async invokeWhileActive(operation, params, options) {
         await this.ensureConnected();
         const shouldOpenThroughCliTimeoutFallback = this.processMode === 'cli' &&
             (this.requestTimeoutMs !== undefined ||
@@ -163,6 +202,7 @@ class HostTransport {
             const response = await this.sendJsonRpcRequest('document.open', opened.params, this.resolveWatchdogTimeout(options.timeoutMs), { requestTimeoutMs });
             const result = documentRpc.mapDocumentOpenResult(response, opened.sessionId, params.doc);
             this.documentRpcSessions.add(opened.sessionId);
+            this.indeterminateDiscardCloses.delete(opened.sessionId);
             return result;
         }
         const sessionId = typeof params.sessionId === 'string' ? params.sessionId : undefined;
@@ -172,10 +212,50 @@ class HostTransport {
             const requestTimeoutMs = supportsResponseTimeout
                 ? this.resolveDocumentRequestTimeout(options.timeoutMs)
                 : undefined;
-            const response = await this.sendJsonRpcRequest(request.method, request.params, this.resolveWatchdogTimeout(options.timeoutMs), { requestTimeoutMs });
-            const result = documentRpc.mapDocumentLifecycleResult(operation.operationId, response, sessionId, operation.operationId === 'doc.save' ? request.params.path === undefined : undefined);
-            if (operation.operationId === 'doc.close')
+            const documentOperation = operation;
+            const requestOptions = typeof request.params.options === 'object' &&
+                request.params.options !== null &&
+                !Array.isArray(request.params.options)
+                ? request.params.options
+                : undefined;
+            const tracksMutation = request.method === 'document.invoke' && documentOperation.mutates === true && requestOptions?.dryRun !== true;
+            if (tracksMutation)
+                this.beginDocumentRpcMutation(sessionId);
+            let result;
+            try {
+                const response = await this.sendJsonRpcRequest(request.method, request.params, this.resolveWatchdogTimeout(options.timeoutMs), { requestTimeoutMs });
+                result = documentRpc.mapDocumentLifecycleResult(operation.operationId, response, sessionId, operation.operationId === 'doc.save' ? request.params.path === undefined : undefined);
+            }
+            catch (error) {
+                if (tracksMutation) {
+                    const indeterminate = error instanceof errors.SuperDocCliError && ['TIMEOUT', 'HOST_TIMEOUT', 'HOST_DISCONNECTED'].includes(error.code);
+                    this.settleDocumentRpcMutation(sessionId, indeterminate ? 'indeterminate' : 'not-applied');
+                }
+                if (operation.operationId === 'doc.close' &&
+                    request.params.discard === true &&
+                    error instanceof errors.SuperDocCliError &&
+                    error.code === 'TIMEOUT') {
+                    this.indeterminateDiscardCloses.add(sessionId);
+                }
+                throw error;
+            }
+            if (tracksMutation) {
+                const failedReceipt = typeof result === 'object' &&
+                    result !== null &&
+                    !Array.isArray(result) &&
+                    result.success === false;
+                this.settleDocumentRpcMutation(sessionId, failedReceipt ? 'not-applied' : 'applied');
+            }
+            if (operation.operationId === 'doc.close') {
                 this.documentRpcSessions.delete(sessionId);
+                this.clearDirtyDocumentRpcSession(sessionId);
+                this.indeterminateDiscardCloses.delete(sessionId);
+            }
+            else if (operation.operationId === 'doc.save') {
+                if (request.params.mode === undefined || request.params.mode === 'review-preserving') {
+                    this.markDocumentRpcSessionSaved(sessionId);
+                }
+            }
             return result;
         }
         if (this.processMode === 'document') {
@@ -212,6 +292,20 @@ class HostTransport {
         const resultRecord = response;
         return mapCliInvocationResult(operation, resultRecord.data);
     }
+    runWhileActive(start) {
+        if (this.terminalDisposalError) {
+            return Promise.reject(this.terminalDisposalError);
+        }
+        if (this.stopping) {
+            return Promise.reject(new errors.SuperDocCliError('Host is disposing.', {
+                code: 'HOST_DISCONNECTED',
+            }));
+        }
+        const activeCall = start();
+        this.activeCalls.add(activeCall);
+        void activeCall.then(() => this.activeCalls.delete(activeCall), () => this.activeCalls.delete(activeCall));
+        return activeCall;
+    }
     async ensureConnected() {
         if (this.connecting) {
             await this.connecting;
@@ -264,7 +358,7 @@ class HostTransport {
             }));
         });
         child.on('close', (code, signal) => {
-            if (this.stopping) {
+            if (this.stopping && this.dirtyDocumentRpcSessions.size === 0) {
                 this.cleanupProcess(null);
                 return;
             }
@@ -350,6 +444,65 @@ class HostTransport {
             details: { feature: documentRpc.DOCUMENT_RPC_REQUEST_TIMEOUT_FEATURE },
         });
     }
+    beginDocumentRpcMutation(sessionId) {
+        const state = this.documentRpcMutationStates.get(sessionId) ?? {
+            confirmedDirty: this.dirtyDocumentRpcSessions.has(sessionId),
+            pendingCount: 0,
+        };
+        state.pendingCount += 1;
+        this.documentRpcMutationStates.set(sessionId, state);
+        this.dirtyDocumentRpcSessions.add(sessionId);
+    }
+    settleDocumentRpcMutation(sessionId, outcome) {
+        const state = this.documentRpcMutationStates.get(sessionId);
+        if (!state)
+            return;
+        state.pendingCount = Math.max(0, state.pendingCount - 1);
+        if (outcome !== 'not-applied')
+            state.confirmedDirty = true;
+        if (state.confirmedDirty || state.pendingCount > 0) {
+            this.dirtyDocumentRpcSessions.add(sessionId);
+            return;
+        }
+        this.clearDirtyDocumentRpcSession(sessionId);
+    }
+    clearDirtyDocumentRpcSession(sessionId) {
+        this.dirtyDocumentRpcSessions.delete(sessionId);
+        this.documentRpcMutationStates.delete(sessionId);
+    }
+    markDocumentRpcSessionSaved(sessionId) {
+        const state = this.documentRpcMutationStates.get(sessionId);
+        if (!state || state.pendingCount === 0) {
+            this.clearDirtyDocumentRpcSession(sessionId);
+            return;
+        }
+        state.confirmedDirty = false;
+        this.dirtyDocumentRpcSessions.add(sessionId);
+    }
+    async persistDirtyDocumentRpcSessions() {
+        if (this.dirtyDocumentRpcSessions.size === 0)
+            return;
+        if (!this.hostFeatures.has(documentRpc.DOCUMENT_RPC_SOURCE_SAVE_FEATURE)) {
+            throw new errors.SuperDocCliError('Document host cannot persist dirty sessions during client disposal because it does not support source saves.', {
+                code: 'DOCUMENT_RPC_INPUT_UNSUPPORTED',
+                details: { feature: documentRpc.DOCUMENT_RPC_SOURCE_SAVE_FEATURE },
+            });
+        }
+        for (const sessionId of this.dirtyDocumentRpcSessions) {
+            const response = await this.sendJsonRpcRequest('document.save', { sessionId }, this.resolveWatchdogTimeout(undefined));
+            documentRpc.mapDocumentLifecycleResult('doc.save', response, sessionId, true);
+            this.markDocumentRpcSessionSaved(sessionId);
+        }
+    }
+    async reconcileIndeterminateDiscardCloses() {
+        for (const sessionId of this.indeterminateDiscardCloses) {
+            const response = await this.sendJsonRpcRequest('document.close', { sessionId, discard: true }, this.resolveWatchdogTimeout(undefined));
+            documentRpc.mapDocumentLifecycleResult('doc.close', response, sessionId);
+            this.documentRpcSessions.delete(sessionId);
+            this.clearDirtyDocumentRpcSession(sessionId);
+            this.indeterminateDiscardCloses.delete(sessionId);
+        }
+    }
     async sendJsonRpcRequest(method, params, watchdogTimeoutMs, metadata = {}) {
         const child = this.child;
         if (!child || !child.stdin.writable) {
@@ -481,8 +634,17 @@ class HostTransport {
         this.cleanupProcess(error);
     }
     cleanupProcess(error) {
+        if (error && this.dirtyDocumentRpcSessions.size > 0 && !this.terminalDisposalError) {
+            this.terminalDisposalError = new errors.SuperDocCliError('Document host disconnected before dirty sessions could be persisted.', {
+                code: 'HOST_DISCONNECTED',
+                details: { causeCode: error.code, causeDetails: error.details },
+            });
+        }
         this.hostFeatures.clear();
         this.documentRpcSessions.clear();
+        this.dirtyDocumentRpcSessions.clear();
+        this.documentRpcMutationStates.clear();
+        this.indeterminateDiscardCloses.clear();
         const child = this.child;
         if (child) {
             child.removeAllListeners();

package/dist/runtime/host.d.ts

@@ -46,21 +46,36 @@ export declare class HostTransport {
     private readonly pending;
     private nextRequestId;
     private connecting;
+    private disposePromise;
+    private terminalDisposalError;
     private stopping;
+    private readonly activeCalls;
     private readonly hostFeatures;
     private readonly documentRpcSessions;
+    private readonly dirtyDocumentRpcSessions;
+    private readonly documentRpcMutationStates;
+    private readonly indeterminateDiscardCloses;
     constructor(options: {
         hostBin: string;
         processMode?: 'cli' | 'document';
     } & SuperDocClientOptions);
     connect(): Promise<void>;
     dispose(): Promise<void>;
+    private disposeAfterActiveCalls;
     invoke<TData = unknown>(operation: OperationSpec, params?: Record<string, unknown>, options?: InvokeOptions): Promise<TData>;
+    private invokeWhileActive;
+    private runWhileActive;
     private ensureConnected;
     private startHostProcess;
     private assertCapabilities;
     private resolveWatchdogTimeout;
     private resolveDocumentRequestTimeout;
+    private beginDocumentRpcMutation;
+    private settleDocumentRpcMutation;
+    private clearDirtyDocumentRpcSession;
+    private markDocumentRpcSessionSaved;
+    private persistDirtyDocumentRpcSessions;
+    private reconcileIndeterminateDiscardCloses;
     private sendJsonRpcRequest;
     private onStdoutLine;
     private mapJsonRpcError;

package/dist/runtime/host.js

@@ -2,7 +2,7 @@ import { spawn } from 'node:child_process';
 import { createInterface } from 'node:readline';
 import { buildOperationArgv, resolveInvocation, } from './transport-common.js';
 import { SuperDocCliError } from './errors.js';
-import { DOCUMENT_RPC_FEATURES, DOCUMENT_RPC_DEFAULT_CHANGE_MODE_FEATURE, DOCUMENT_RPC_REQUEST_TIMEOUT_FEATURE, buildDocumentInvokeParams, buildDocumentOpenParams, canOpenWithDocumentRpc, documentRpcRequestSupportsResponseTimeout, documentRpcEnabled, mapDocumentLifecycleResult, mapDocumentOpenResult, supportsDocumentRpc, } from './document-rpc.js';
+import { DOCUMENT_RPC_FEATURES, DOCUMENT_RPC_DEFAULT_CHANGE_MODE_FEATURE, DOCUMENT_RPC_REQUEST_TIMEOUT_FEATURE, DOCUMENT_RPC_SOURCE_SAVE_FEATURE, buildDocumentInvokeParams, buildDocumentOpenParams, canOpenWithDocumentRpc, documentRpcRequestSupportsResponseTimeout, documentRpcEnabled, mapDocumentLifecycleResult, mapDocumentOpenResult, supportsDocumentRpc, } from './document-rpc.js';
 const HOST_PROTOCOL_VERSION = '1.0';
 const CLI_HOST_REQUIRED_FEATURES = ['cli.invoke', 'host.shutdown'];
 const DOCUMENT_HOST_REQUIRED_FEATURES = [...DOCUMENT_RPC_FEATURES, 'host.shutdown'];
@@ -95,9 +95,15 @@ export class HostTransport {
     pending = new Map();
     nextRequestId = 1;
     connecting = null;
+    disposePromise = null;
+    terminalDisposalError = null;
     stopping = false;
+    activeCalls = new Set();
     hostFeatures = new Set();
     documentRpcSessions = new Set();
+    dirtyDocumentRpcSessions = new Set();
+    documentRpcMutationStates = new Map();
+    indeterminateDiscardCloses = new Set();
     constructor(options) {
         this.hostBin = options.hostBin;
         this.processMode = options.processMode ?? 'cli';
@@ -118,12 +124,43 @@ export class HostTransport {
         this.documentRpcEnabled = this.processMode === 'document' || documentRpcEnabled(options.env);
     }
     async connect() {
-        await this.ensureConnected();
+        await this.runWhileActive(() => this.ensureConnected());
     }
     async dispose() {
-        if (!this.child)
+        if (this.disposePromise)
+            return this.disposePromise;
+        if (this.terminalDisposalError)
+            throw this.terminalDisposalError;
+        if (!this.child && !this.connecting && this.activeCalls.size === 0)
             return;
         this.stopping = true;
+        const disposal = this.disposeAfterActiveCalls();
+        this.disposePromise = disposal;
+        try {
+            await disposal;
+        }
+        finally {
+            if (this.disposePromise === disposal)
+                this.disposePromise = null;
+            this.stopping = false;
+        }
+    }
+    async disposeAfterActiveCalls() {
+        await Promise.allSettled(Array.from(this.activeCalls));
+        if (this.terminalDisposalError)
+            throw this.terminalDisposalError;
+        if (!this.child)
+            return;
+        try {
+            await this.reconcileIndeterminateDiscardCloses();
+            await this.persistDirtyDocumentRpcSessions();
+        }
+        catch (error) {
+            if (!this.child && error instanceof SuperDocCliError) {
+                this.terminalDisposalError = error;
+            }
+            throw error;
+        }
         const child = this.child;
         try {
             await this.sendJsonRpcRequest('host.shutdown', {}, this.shutdownTimeoutMs);
@@ -142,9 +179,11 @@ export class HostTransport {
             });
         });
         this.cleanupProcess(null);
-        this.stopping = false;
     }
     async invoke(operation, params = {}, options = {}) {
+        return this.runWhileActive(() => this.invokeWhileActive(operation, params, options));
+    }
+    async invokeWhileActive(operation, params, options) {
         await this.ensureConnected();
         const shouldOpenThroughCliTimeoutFallback = this.processMode === 'cli' &&
             (this.requestTimeoutMs !== undefined ||
@@ -160,6 +199,7 @@ export class HostTransport {
             const response = await this.sendJsonRpcRequest('document.open', opened.params, this.resolveWatchdogTimeout(options.timeoutMs), { requestTimeoutMs });
             const result = mapDocumentOpenResult(response, opened.sessionId, params.doc);
             this.documentRpcSessions.add(opened.sessionId);
+            this.indeterminateDiscardCloses.delete(opened.sessionId);
             return result;
         }
         const sessionId = typeof params.sessionId === 'string' ? params.sessionId : undefined;
@@ -169,10 +209,50 @@ export class HostTransport {
             const requestTimeoutMs = supportsResponseTimeout
                 ? this.resolveDocumentRequestTimeout(options.timeoutMs)
                 : undefined;
-            const response = await this.sendJsonRpcRequest(request.method, request.params, this.resolveWatchdogTimeout(options.timeoutMs), { requestTimeoutMs });
-            const result = mapDocumentLifecycleResult(operation.operationId, response, sessionId, operation.operationId === 'doc.save' ? request.params.path === undefined : undefined);
-            if (operation.operationId === 'doc.close')
+            const documentOperation = operation;
+            const requestOptions = typeof request.params.options === 'object' &&
+                request.params.options !== null &&
+                !Array.isArray(request.params.options)
+                ? request.params.options
+                : undefined;
+            const tracksMutation = request.method === 'document.invoke' && documentOperation.mutates === true && requestOptions?.dryRun !== true;
+            if (tracksMutation)
+                this.beginDocumentRpcMutation(sessionId);
+            let result;
+            try {
+                const response = await this.sendJsonRpcRequest(request.method, request.params, this.resolveWatchdogTimeout(options.timeoutMs), { requestTimeoutMs });
+                result = mapDocumentLifecycleResult(operation.operationId, response, sessionId, operation.operationId === 'doc.save' ? request.params.path === undefined : undefined);
+            }
+            catch (error) {
+                if (tracksMutation) {
+                    const indeterminate = error instanceof SuperDocCliError && ['TIMEOUT', 'HOST_TIMEOUT', 'HOST_DISCONNECTED'].includes(error.code);
+                    this.settleDocumentRpcMutation(sessionId, indeterminate ? 'indeterminate' : 'not-applied');
+                }
+                if (operation.operationId === 'doc.close' &&
+                    request.params.discard === true &&
+                    error instanceof SuperDocCliError &&
+                    error.code === 'TIMEOUT') {
+                    this.indeterminateDiscardCloses.add(sessionId);
+                }
+                throw error;
+            }
+            if (tracksMutation) {
+                const failedReceipt = typeof result === 'object' &&
+                    result !== null &&
+                    !Array.isArray(result) &&
+                    result.success === false;
+                this.settleDocumentRpcMutation(sessionId, failedReceipt ? 'not-applied' : 'applied');
+            }
+            if (operation.operationId === 'doc.close') {
                 this.documentRpcSessions.delete(sessionId);
+                this.clearDirtyDocumentRpcSession(sessionId);
+                this.indeterminateDiscardCloses.delete(sessionId);
+            }
+            else if (operation.operationId === 'doc.save') {
+                if (request.params.mode === undefined || request.params.mode === 'review-preserving') {
+                    this.markDocumentRpcSessionSaved(sessionId);
+                }
+            }
             return result;
         }
         if (this.processMode === 'document') {
@@ -209,6 +289,20 @@ export class HostTransport {
         const resultRecord = response;
         return mapCliInvocationResult(operation, resultRecord.data);
     }
+    runWhileActive(start) {
+        if (this.terminalDisposalError) {
+            return Promise.reject(this.terminalDisposalError);
+        }
+        if (this.stopping) {
+            return Promise.reject(new SuperDocCliError('Host is disposing.', {
+                code: 'HOST_DISCONNECTED',
+            }));
+        }
+        const activeCall = start();
+        this.activeCalls.add(activeCall);
+        void activeCall.then(() => this.activeCalls.delete(activeCall), () => this.activeCalls.delete(activeCall));
+        return activeCall;
+    }
     async ensureConnected() {
         if (this.connecting) {
             await this.connecting;
@@ -261,7 +355,7 @@ export class HostTransport {
             }));
         });
         child.on('close', (code, signal) => {
-            if (this.stopping) {
+            if (this.stopping && this.dirtyDocumentRpcSessions.size === 0) {
                 this.cleanupProcess(null);
                 return;
             }
@@ -347,6 +441,65 @@ export class HostTransport {
             details: { feature: DOCUMENT_RPC_REQUEST_TIMEOUT_FEATURE },
         });
     }
+    beginDocumentRpcMutation(sessionId) {
+        const state = this.documentRpcMutationStates.get(sessionId) ?? {
+            confirmedDirty: this.dirtyDocumentRpcSessions.has(sessionId),
+            pendingCount: 0,
+        };
+        state.pendingCount += 1;
+        this.documentRpcMutationStates.set(sessionId, state);
+        this.dirtyDocumentRpcSessions.add(sessionId);
+    }
+    settleDocumentRpcMutation(sessionId, outcome) {
+        const state = this.documentRpcMutationStates.get(sessionId);
+        if (!state)
+            return;
+        state.pendingCount = Math.max(0, state.pendingCount - 1);
+        if (outcome !== 'not-applied')
+            state.confirmedDirty = true;
+        if (state.confirmedDirty || state.pendingCount > 0) {
+            this.dirtyDocumentRpcSessions.add(sessionId);
+            return;
+        }
+        this.clearDirtyDocumentRpcSession(sessionId);
+    }
+    clearDirtyDocumentRpcSession(sessionId) {
+        this.dirtyDocumentRpcSessions.delete(sessionId);
+        this.documentRpcMutationStates.delete(sessionId);
+    }
+    markDocumentRpcSessionSaved(sessionId) {
+        const state = this.documentRpcMutationStates.get(sessionId);
+        if (!state || state.pendingCount === 0) {
+            this.clearDirtyDocumentRpcSession(sessionId);
+            return;
+        }
+        state.confirmedDirty = false;
+        this.dirtyDocumentRpcSessions.add(sessionId);
+    }
+    async persistDirtyDocumentRpcSessions() {
+        if (this.dirtyDocumentRpcSessions.size === 0)
+            return;
+        if (!this.hostFeatures.has(DOCUMENT_RPC_SOURCE_SAVE_FEATURE)) {
+            throw new SuperDocCliError('Document host cannot persist dirty sessions during client disposal because it does not support source saves.', {
+                code: 'DOCUMENT_RPC_INPUT_UNSUPPORTED',
+                details: { feature: DOCUMENT_RPC_SOURCE_SAVE_FEATURE },
+            });
+        }
+        for (const sessionId of this.dirtyDocumentRpcSessions) {
+            const response = await this.sendJsonRpcRequest('document.save', { sessionId }, this.resolveWatchdogTimeout(undefined));
+            mapDocumentLifecycleResult('doc.save', response, sessionId, true);
+            this.markDocumentRpcSessionSaved(sessionId);
+        }
+    }
+    async reconcileIndeterminateDiscardCloses() {
+        for (const sessionId of this.indeterminateDiscardCloses) {
+            const response = await this.sendJsonRpcRequest('document.close', { sessionId, discard: true }, this.resolveWatchdogTimeout(undefined));
+            mapDocumentLifecycleResult('doc.close', response, sessionId);
+            this.documentRpcSessions.delete(sessionId);
+            this.clearDirtyDocumentRpcSession(sessionId);
+            this.indeterminateDiscardCloses.delete(sessionId);
+        }
+    }
     async sendJsonRpcRequest(method, params, watchdogTimeoutMs, metadata = {}) {
         const child = this.child;
         if (!child || !child.stdin.writable) {
@@ -478,8 +631,17 @@ export class HostTransport {
         this.cleanupProcess(error);
     }
     cleanupProcess(error) {
+        if (error && this.dirtyDocumentRpcSessions.size > 0 && !this.terminalDisposalError) {
+            this.terminalDisposalError = new SuperDocCliError('Document host disconnected before dirty sessions could be persisted.', {
+                code: 'HOST_DISCONNECTED',
+                details: { causeCode: error.code, causeDetails: error.details },
+            });
+        }
         this.hostFeatures.clear();
         this.documentRpcSessions.clear();
+        this.dirtyDocumentRpcSessions.clear();
+        this.documentRpcMutationStates.clear();
+        this.indeterminateDiscardCloses.clear();
         const child = this.child;
         if (child) {
             child.removeAllListeners();

package/dist/runtime/sdk-version.generated.cjs

@@ -0,0 +1,8 @@
+'use strict';
+
+// AUTO-GENERATED by scripts/embed-version.mjs — DO NOT EDIT.
+// Source of truth: package.json. Regenerated on every SDK build so the
+// SDK retains its own version identity when bundled into another package.
+const SDK_VERSION = '2.8.0';
+
+exports.SDK_VERSION = SDK_VERSION;

package/dist/runtime/sdk-version.generated.d.ts

@@ -0,0 +1 @@
+export declare const SDK_VERSION = "2.8.0";

package/dist/runtime/sdk-version.generated.js

@@ -0,0 +1,4 @@
+// AUTO-GENERATED by scripts/embed-version.mjs — DO NOT EDIT.
+// Source of truth: package.json. Regenerated on every SDK build so the
+// SDK retains its own version identity when bundled into another package.
+export const SDK_VERSION = '2.8.0';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@superdoc/sdk",
-  "version": "2.7.0",
+  "version": "2.8.0",
   "description": "Node SDK for SuperDoc, wrapping the SuperDoc CLI to read and edit .docx files from JavaScript and TypeScript.",
   "private": false,
   "license": "AGPL-3.0",
@@ -37,17 +37,17 @@
     "typescript": "^5.9.2"
   },
   "optionalDependencies": {
-    "@superdoc/sdk-darwin-arm64": "2.7.0",
-    "@superdoc/sdk-darwin-x64": "2.7.0",
-    "@superdoc/sdk-linux-x64": "2.7.0",
-    "@superdoc/sdk-linux-arm64": "2.7.0",
-    "@superdoc/sdk-windows-x64": "2.7.0"
+    "@superdoc/sdk-darwin-arm64": "2.8.0",
+    "@superdoc/sdk-darwin-x64": "2.8.0",
+    "@superdoc/sdk-linux-x64": "2.8.0",
+    "@superdoc/sdk-linux-arm64": "2.8.0",
+    "@superdoc/sdk-windows-x64": "2.8.0"
   },
   "publishConfig": {
     "access": "public"
   },
   "scripts": {
-    "build": "rm -rf dist && node scripts/embed-prompts.mjs && node scripts/embed-tools.mjs && tsc && rollup -c rollup.cjs.config.mjs && rm -rf dist/prompts && mkdir -p dist/prompts && cp src/prompts/*.md dist/prompts/ && pnpm run audit:publish",
+    "build": "rm -rf dist && node scripts/embed-version.mjs && node scripts/embed-prompts.mjs && node scripts/embed-tools.mjs && tsc && rollup -c rollup.cjs.config.mjs && rm -rf dist/prompts && mkdir -p dist/prompts && cp src/prompts/*.md dist/prompts/ && pnpm run audit:publish",
     "audit:publish": "node ../../../../scripts/audit-publish-artifact.mjs dist --label sdk-node-dist",
     "typecheck": "tsc --noEmit",
     "test:document-host": "bun test src/runtime/__tests__/host-spawn-args.test.ts src/runtime/__tests__/document-rpc.test.ts src/__tests__/structured-document-rpc.e2e.test.ts src/__tests__/request-timeout-ms.e2e.test.ts",