@superdoc/sdk 2.7.0 → 2.9.0-next.1

package/dist/runtime/host.cjs

@@ -8,6 +8,7 @@ var documentRpc = require('./document-rpc.cjs');
 
 const HOST_PROTOCOL_VERSION = '1.0';
 const CLI_HOST_REQUIRED_FEATURES = ['cli.invoke', 'host.shutdown'];
+const COLLABORATION_AUTH_PER_OPEN_FEATURE = 'collaboration.auth.perOpen';
 const DOCUMENT_HOST_REQUIRED_FEATURES = [...documentRpc.DOCUMENT_RPC_FEATURES, 'host.shutdown'];
 const CHANGE_MODES = ['direct', 'tracked'];
 const FORWARD_HOST_STDERR = typeof process !== 'undefined' && typeof process.env?.SUPERDOC_DEBUG_TEXT_REWRITE === 'string'
@@ -98,9 +99,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 +128,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,10 +183,32 @@ 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) {
+        const collaborationAuth = options.collaborationAuth === undefined ? undefined : transportCommon.normalizeCollaborationAuth(options.collaborationAuth);
+        if (collaborationAuth !== undefined) {
+            if (operation.operationId !== 'doc.open') {
+                throw new errors.SuperDocCliError('collaborationAuth is supported only for doc.open requests.', {
+                    code: 'INVALID_ARGUMENT',
+                });
+            }
+            if (this.processMode !== 'cli') {
+                throw new errors.SuperDocCliError('Per-open collaboration authentication is not supported by the standalone document host.', {
+                    code: 'CAPABILITY_UNSUPPORTED',
+                    details: { feature: COLLABORATION_AUTH_PER_OPEN_FEATURE },
+                });
+            }
+        }
         await this.ensureConnected();
+        if (collaborationAuth !== undefined && !this.hostFeatures.has(COLLABORATION_AUTH_PER_OPEN_FEATURE)) {
+            throw new errors.SuperDocCliError('The connected CLI host does not support per-open collaboration authentication.', {
+                code: 'CAPABILITY_UNSUPPORTED',
+                details: { feature: COLLABORATION_AUTH_PER_OPEN_FEATURE },
+            });
+        }
         const shouldOpenThroughCliTimeoutFallback = this.processMode === 'cli' &&
             (this.requestTimeoutMs !== undefined ||
                 (options.timeoutMs !== undefined && !this.hostFeatures.has(documentRpc.DOCUMENT_RPC_REQUEST_TIMEOUT_FEATURE)));
@@ -163,6 +223,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 +233,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') {
@@ -202,6 +303,7 @@ class HostTransport {
         const response = await this.sendJsonRpcRequest('cli.invoke', {
             argv,
             stdinBase64,
+            ...(collaborationAuth === undefined ? {} : { collaborationAuth }),
         }, watchdogTimeout);
         if (typeof response !== 'object' || response == null || Array.isArray(response)) {
             throw new errors.SuperDocCliError('Host returned invalid cli.invoke result.', {
@@ -212,6 +314,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 +380,7 @@ class HostTransport {
             }));
         });
         child.on('close', (code, signal) => {
-            if (this.stopping) {
+            if (this.stopping && this.dirtyDocumentRpcSessions.size === 0) {
                 this.cleanupProcess(null);
                 return;
             }
@@ -350,6 +466,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 +656,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();
@@ -507,6 +691,7 @@ class HostTransport {
     }
 }
 
+exports.COLLABORATION_AUTH_PER_OPEN_FEATURE = COLLABORATION_AUTH_PER_OPEN_FEATURE;
 exports.HostTransport = HostTransport;
 exports.buildDocumentHostSpawnArgs = buildDocumentHostSpawnArgs;
 exports.buildHostSpawnArgs = buildHostSpawnArgs;

package/dist/runtime/host.d.ts

@@ -1,4 +1,5 @@
-import { type InvokeOptions, type OperationSpec, type SuperDocClientOptions } from './transport-common.js';
+import { type OperationSpec, type SuperDocClientOptions, type TransportInvokeOptions } from './transport-common.js';
+export declare const COLLABORATION_AUTH_PER_OPEN_FEATURE = "collaboration.auth.perOpen";
 export declare function mapCliInvocationResult(operation: OperationSpec, value: unknown): unknown;
 /**
  * Builds the argv passed to `spawn` for `superdoc host --stdio`. Propagates
@@ -46,21 +47,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>;
-    invoke<TData = unknown>(operation: OperationSpec, params?: Record<string, unknown>, options?: InvokeOptions): Promise<TData>;
+    private disposeAfterActiveCalls;
+    invoke<TData = unknown>(operation: OperationSpec, params?: Record<string, unknown>, options?: TransportInvokeOptions): 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

@@ -1,10 +1,11 @@
 import { spawn } from 'node:child_process';
 import { createInterface } from 'node:readline';
-import { buildOperationArgv, resolveInvocation, } from './transport-common.js';
+import { buildOperationArgv, normalizeCollaborationAuth, 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'];
+export const COLLABORATION_AUTH_PER_OPEN_FEATURE = 'collaboration.auth.perOpen';
 const DOCUMENT_HOST_REQUIRED_FEATURES = [...DOCUMENT_RPC_FEATURES, 'host.shutdown'];
 const CHANGE_MODES = ['direct', 'tracked'];
 const FORWARD_HOST_STDERR = typeof process !== 'undefined' && typeof process.env?.SUPERDOC_DEBUG_TEXT_REWRITE === 'string'
@@ -95,9 +96,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 +125,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,10 +180,32 @@ 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) {
+        const collaborationAuth = options.collaborationAuth === undefined ? undefined : normalizeCollaborationAuth(options.collaborationAuth);
+        if (collaborationAuth !== undefined) {
+            if (operation.operationId !== 'doc.open') {
+                throw new SuperDocCliError('collaborationAuth is supported only for doc.open requests.', {
+                    code: 'INVALID_ARGUMENT',
+                });
+            }
+            if (this.processMode !== 'cli') {
+                throw new SuperDocCliError('Per-open collaboration authentication is not supported by the standalone document host.', {
+                    code: 'CAPABILITY_UNSUPPORTED',
+                    details: { feature: COLLABORATION_AUTH_PER_OPEN_FEATURE },
+                });
+            }
+        }
         await this.ensureConnected();
+        if (collaborationAuth !== undefined && !this.hostFeatures.has(COLLABORATION_AUTH_PER_OPEN_FEATURE)) {
+            throw new SuperDocCliError('The connected CLI host does not support per-open collaboration authentication.', {
+                code: 'CAPABILITY_UNSUPPORTED',
+                details: { feature: COLLABORATION_AUTH_PER_OPEN_FEATURE },
+            });
+        }
         const shouldOpenThroughCliTimeoutFallback = this.processMode === 'cli' &&
             (this.requestTimeoutMs !== undefined ||
                 (options.timeoutMs !== undefined && !this.hostFeatures.has(DOCUMENT_RPC_REQUEST_TIMEOUT_FEATURE)));
@@ -160,6 +220,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 +230,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') {
@@ -199,6 +300,7 @@ export class HostTransport {
         const response = await this.sendJsonRpcRequest('cli.invoke', {
             argv,
             stdinBase64,
+            ...(collaborationAuth === undefined ? {} : { collaborationAuth }),
         }, watchdogTimeout);
         if (typeof response !== 'object' || response == null || Array.isArray(response)) {
             throw new SuperDocCliError('Host returned invalid cli.invoke result.', {
@@ -209,6 +311,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 +377,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 +463,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 +653,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/process.cjs

@@ -32,6 +32,10 @@ function resolveRuntimeProcess(options = {}, embedded = {
         processMode: 'cli',
     };
 }
+function toSafeInvokeTraceOptions(options) {
+    const { collaborationAuth: _collaborationAuth, ...traceOptions } = options;
+    return traceOptions;
+}
 /**
  * Internal runtime that delegates operations to a persistent host transport.
  *
@@ -60,7 +64,7 @@ class SuperDocRuntime {
             phase: 'start',
             operationId: operation.operationId,
             params,
-            options,
+            options: toSafeInvokeTraceOptions(options),
         });
         try {
             const result = await this.transport.invoke(operation, params, options);
@@ -88,3 +92,4 @@ class SuperDocRuntime {
 
 exports.SuperDocRuntime = SuperDocRuntime;
 exports.resolveRuntimeProcess = resolveRuntimeProcess;
+exports.toSafeInvokeTraceOptions = toSafeInvokeTraceOptions;

package/dist/runtime/process.d.ts

@@ -1,4 +1,4 @@
-import type { DocumentRuntimeKind, InvokeOptions, OperationParamSpec, OperationSpec, RuntimeInvoker, SuperDocClientOptions } from './transport-common.js';
+import type { CollaborationAuth, DocumentRuntimeKind, DocOpenOptions, InvokeOptions, TransportInvokeOptions, OperationParamSpec, OperationSpec, RuntimeInvoker, SuperDocClientOptions } from './transport-common.js';
 type RuntimeProcessResolution = {
     hostBin: string;
     processMode: 'cli' | 'document';
@@ -8,6 +8,7 @@ type EmbeddedRuntimeResolvers = {
     documentHost: () => string;
 };
 export declare function resolveRuntimeProcess(options?: SuperDocClientOptions, embedded?: EmbeddedRuntimeResolvers): RuntimeProcessResolution;
+export declare function toSafeInvokeTraceOptions(options: TransportInvokeOptions): InvokeOptions;
 /**
  * Internal runtime that delegates operations to a persistent host transport.
  *
@@ -19,6 +20,6 @@ export declare class SuperDocRuntime {
     constructor(options?: SuperDocClientOptions);
     connect(): Promise<void>;
     dispose(): Promise<void>;
-    invoke<TData = unknown>(operation: OperationSpec, params?: Record<string, unknown>, options?: InvokeOptions): Promise<TData>;
+    invoke<TData = unknown>(operation: OperationSpec, params?: Record<string, unknown>, options?: TransportInvokeOptions): Promise<TData>;
 }
-export type { DocumentRuntimeKind, InvokeOptions, OperationParamSpec, OperationSpec, RuntimeInvoker, SuperDocClientOptions, };
+export type { CollaborationAuth, DocumentRuntimeKind, DocOpenOptions, InvokeOptions, OperationParamSpec, OperationSpec, RuntimeInvoker, SuperDocClientOptions, };