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

package/dist/index.cjs

@@ -1,5 +1,6 @@
 'use strict';
 
+var documentEvidence = require('./runtime/document-evidence.cjs');
 var client = require('./generated/client.cjs');
 var contract = require('./generated/contract.cjs');
 var process = require('./runtime/process.cjs');
@@ -37,6 +38,23 @@ class BoundRuntime {
         }
         return this.runtime.invoke(operation, { ...params, sessionId: this.sessionId }, options);
     }
+    async replaceFile(source, options = {}) {
+        if (this.closed) {
+            throw new errors.SuperDocCliError('Document handle is closed; cannot replace its file.', {
+                code: 'DOCUMENT_CLOSED',
+                details: { sessionId: this.sessionId },
+            });
+        }
+        return this.runtime.replaceFile(this.sessionId, source, options);
+    }
+    supportsDocumentFacts() {
+        return !this.closed && this.runtime.supportsDocumentFacts(this.sessionId);
+    }
+    async readRevision() {
+        if (this.closed)
+            throw new errors.SuperDocCliError('Document handle is closed; cannot read its revision.', { code: 'DOCUMENT_CLOSED' });
+        return this.runtime.readDocumentRevision(this.sessionId);
+    }
     markClosed() {
         this.closed = true;
     }
@@ -61,6 +79,8 @@ class SuperDocDocumentCore {
         this._openResult = openResult;
         this.client = client$1;
         attachBoundDocApi(this, client.createBoundDocApi(this.boundRuntime));
+        documentEvidence.registerDocumentRevisionReader(this, () => this.boundRuntime.readRevision());
+        documentEvidence.registerDocumentFactCapability(this, () => this.boundRuntime.supportsDocumentFacts());
     }
     get sessionId() {
         return this._sessionId;
@@ -72,6 +92,9 @@ class SuperDocDocumentCore {
     async save(params = {}, options = {}) {
         return this.boundRuntime.invoke(contract.CONTRACT.operations['doc.save'], params, options);
     }
+    async replaceFile(source, options = {}) {
+        return this.boundRuntime.replaceFile(source, options);
+    }
     async close(params = {}, options = {}) {
         const result = await this.boundRuntime.invoke(contract.CONTRACT.operations['doc.close'], params, options);
         this.boundRuntime.markClosed();

package/dist/index.d.ts

@@ -1,5 +1,5 @@
 import { type BoundDocApi, type DocCloseBoundParams, type DocCloseResult, type DocFormatApplyBoundParams, type DocFormatApplyResult, type DocOpenParams as GeneratedDocOpenParams, type DocOpenResult, type DocSaveBoundParams, type DocSaveResult } from './generated/client.js';
-import { SuperDocRuntime, type SuperDocClientOptions, type DocOpenOptions, type InvokeOptions, type OperationSpec, type RuntimeInvoker } from './runtime/process.js';
+import { SuperDocRuntime, type SuperDocClientOptions, type DocOpenOptions, type InvokeOptions, type OperationSpec, type ReplaceFileOptions, type ReplaceFileResult, type ReplaceFileSource, type RuntimeInvoker } from './runtime/process.js';
 /**
  * Wraps a raw runtime and injects a fixed sessionId into every invoke call.
  * Implements RuntimeInvoker so generated code can use it directly.
@@ -12,6 +12,9 @@ declare class BoundRuntime implements RuntimeInvoker {
     private closed;
     constructor(runtime: SuperDocRuntime, sessionId: string);
     invoke<TData = unknown>(operation: OperationSpec, params?: Record<string, unknown>, options?: InvokeOptions): Promise<TData>;
+    replaceFile(source: ReplaceFileSource, options?: ReplaceFileOptions): Promise<ReplaceFileResult>;
+    supportsDocumentFacts(): boolean;
+    readRevision(): Promise<string | undefined>;
     markClosed(): void;
 }
 export interface DocFormatRangeBoundParams extends Omit<DocFormatApplyBoundParams, 'inline'> {
@@ -33,6 +36,7 @@ declare class SuperDocDocumentCore {
     /** Read-only snapshot of the initial doc.open response metadata. */
     get openResult(): DocOpenResult;
     save(params?: DocSaveBoundParams, options?: InvokeOptions): Promise<DocSaveResult>;
+    replaceFile(source: ReplaceFileSource, options?: ReplaceFileOptions): Promise<ReplaceFileResult>;
     close(params?: DocCloseBoundParams, options?: InvokeOptions): Promise<DocCloseResult>;
     /** @internal */
     markClosed(): void;
@@ -42,6 +46,7 @@ type SuperDocDocumentInstance = SuperDocDocumentCore & BoundDocApi;
 export declare const SuperDocDocument: new (boundRuntime: BoundRuntime, sessionId: string, openResult: DocOpenResult, client: SuperDocClient) => SuperDocDocumentInstance;
 export type SuperDocDocument = SuperDocDocumentInstance;
 export type DocOpenParams = GeneratedDocOpenParams;
+export type { ReplaceFileOptions, ReplaceFileResult, ReplaceFileSource };
 export interface DocDescribeCommandParams {
     operationId: string;
     [key: string]: unknown;
@@ -89,7 +94,7 @@ export { dispatchIntentTool } from './generated/intent-dispatch.generated.js';
 export { wrapV2PresetCompat } from './agent/v2-preset-compat.js';
 export type { BoundDocApi } from './generated/client.js';
 export type { ActionName } from './agent/actions.js';
-export type { AgentReceipt } from './agent/runtime.js';
+export type { AgentReceipt, AgentApplyArgs, AgentVerifyArgs } from './agent/runtime.js';
 export type { GetSystemPromptOptions, GetToolsOptions, GetToolsResult, PresetDescriptor } from './presets.js';
 export { createAgentToolkit } from './tools.js';
 export type { AgentToolkit, CreateAgentToolkitInput } from './tools.js';

package/dist/index.js

@@ -1,3 +1,4 @@
+import { registerDocumentRevisionReader, registerDocumentFactCapability } from './runtime/document-evidence.js';
 import { createDocApi, createBoundDocApi, } from './generated/client.js';
 import { CONTRACT } from './generated/contract.js';
 import { SuperDocRuntime, } from './runtime/process.js';
@@ -29,6 +30,23 @@ class BoundRuntime {
         }
         return this.runtime.invoke(operation, { ...params, sessionId: this.sessionId }, options);
     }
+    async replaceFile(source, options = {}) {
+        if (this.closed) {
+            throw new SuperDocCliError('Document handle is closed; cannot replace its file.', {
+                code: 'DOCUMENT_CLOSED',
+                details: { sessionId: this.sessionId },
+            });
+        }
+        return this.runtime.replaceFile(this.sessionId, source, options);
+    }
+    supportsDocumentFacts() {
+        return !this.closed && this.runtime.supportsDocumentFacts(this.sessionId);
+    }
+    async readRevision() {
+        if (this.closed)
+            throw new SuperDocCliError('Document handle is closed; cannot read its revision.', { code: 'DOCUMENT_CLOSED' });
+        return this.runtime.readDocumentRevision(this.sessionId);
+    }
     markClosed() {
         this.closed = true;
     }
@@ -53,6 +71,8 @@ class SuperDocDocumentCore {
         this._openResult = openResult;
         this.client = client;
         attachBoundDocApi(this, createBoundDocApi(this.boundRuntime));
+        registerDocumentRevisionReader(this, () => this.boundRuntime.readRevision());
+        registerDocumentFactCapability(this, () => this.boundRuntime.supportsDocumentFacts());
     }
     get sessionId() {
         return this._sessionId;
@@ -64,6 +84,9 @@ class SuperDocDocumentCore {
     async save(params = {}, options = {}) {
         return this.boundRuntime.invoke(CONTRACT.operations['doc.save'], params, options);
     }
+    async replaceFile(source, options = {}) {
+        return this.boundRuntime.replaceFile(source, options);
+    }
     async close(params = {}, options = {}) {
         const result = await this.boundRuntime.invoke(CONTRACT.operations['doc.close'], params, options);
         this.boundRuntime.markClosed();

package/dist/presets/core.cjs

@@ -245,7 +245,7 @@ function compactAgentReceipt(receipt) {
             : {}),
         ...(verification
             ? {
-                verificationPassed: verification.every((entry) => entry.passed),
+                verificationPassed: verification.length > 0 && verification.every((entry) => entry.passed),
                 verification: verification.map((entry) => ({
                     check: pickScalarFields(entry.check, undefined, 6),
                     passed: entry.passed,

package/dist/presets/core.js

@@ -241,7 +241,7 @@ function compactAgentReceipt(receipt) {
             : {}),
         ...(verification
             ? {
-                verificationPassed: verification.every((entry) => entry.passed),
+                verificationPassed: verification.length > 0 && verification.every((entry) => entry.passed),
                 verification: verification.map((entry) => ({
                     check: pickScalarFields(entry.check, undefined, 6),
                     passed: entry.passed,

package/dist/runtime/document-evidence.cjs

@@ -0,0 +1,40 @@
+'use strict';
+
+const mutationRevisions = new WeakMap();
+function registerMutationRevision(result, revision) {
+    if (result && typeof result === 'object')
+        mutationRevisions.set(result, revision);
+}
+function getMutationRevision(result) {
+    return result && typeof result === 'object' ? mutationRevisions.get(result) : undefined;
+}
+// Keep transport capabilities off the public document API and tied to the live
+// handle. Undefined means unsupported, never a cached or unknown revision.
+const revisionReaders = new WeakMap();
+function registerDocumentRevisionReader(document, reader) {
+    revisionReaders.set(document, reader);
+}
+function getDocumentRevisionReader(document) {
+    return revisionReaders.get(document);
+}
+const factCapabilities = new WeakMap();
+function registerDocumentFactCapability(document, supported) {
+    factCapabilities.set(document, supported);
+}
+function supportsDocumentFacts(document) {
+    return factCapabilities.get(document)?.() === true;
+}
+function forwardDocumentEvidence(source, target) {
+    const reader = getDocumentRevisionReader(source);
+    if (reader)
+        registerDocumentRevisionReader(target, reader);
+    registerDocumentFactCapability(target, () => supportsDocumentFacts(source));
+}
+
+exports.forwardDocumentEvidence = forwardDocumentEvidence;
+exports.getDocumentRevisionReader = getDocumentRevisionReader;
+exports.getMutationRevision = getMutationRevision;
+exports.registerDocumentFactCapability = registerDocumentFactCapability;
+exports.registerDocumentRevisionReader = registerDocumentRevisionReader;
+exports.registerMutationRevision = registerMutationRevision;
+exports.supportsDocumentFacts = supportsDocumentFacts;

package/dist/runtime/document-evidence.d.ts

@@ -0,0 +1,13 @@
+type RevisionReader = () => Promise<string | undefined>;
+type MutationRevision = {
+    before: string;
+    after: string;
+};
+export declare function registerMutationRevision(result: unknown, revision: MutationRevision): void;
+export declare function getMutationRevision(result: unknown): MutationRevision | undefined;
+export declare function registerDocumentRevisionReader(document: object, reader: RevisionReader): void;
+export declare function getDocumentRevisionReader(document: object): RevisionReader | undefined;
+export declare function registerDocumentFactCapability(document: object, supported: () => boolean): void;
+export declare function supportsDocumentFacts(document: object): boolean;
+export declare function forwardDocumentEvidence(source: object, target: object): void;
+export {};

package/dist/runtime/document-evidence.js

@@ -0,0 +1,30 @@
+const mutationRevisions = new WeakMap();
+export function registerMutationRevision(result, revision) {
+    if (result && typeof result === 'object')
+        mutationRevisions.set(result, revision);
+}
+export function getMutationRevision(result) {
+    return result && typeof result === 'object' ? mutationRevisions.get(result) : undefined;
+}
+// Keep transport capabilities off the public document API and tied to the live
+// handle. Undefined means unsupported, never a cached or unknown revision.
+const revisionReaders = new WeakMap();
+export function registerDocumentRevisionReader(document, reader) {
+    revisionReaders.set(document, reader);
+}
+export function getDocumentRevisionReader(document) {
+    return revisionReaders.get(document);
+}
+const factCapabilities = new WeakMap();
+export function registerDocumentFactCapability(document, supported) {
+    factCapabilities.set(document, supported);
+}
+export function supportsDocumentFacts(document) {
+    return factCapabilities.get(document)?.() === true;
+}
+export function forwardDocumentEvidence(source, target) {
+    const reader = getDocumentRevisionReader(source);
+    if (reader)
+        registerDocumentRevisionReader(target, reader);
+    registerDocumentFactCapability(target, () => supportsDocumentFacts(source));
+}

package/dist/runtime/document-rpc.cjs

@@ -5,6 +5,7 @@ var errors = require('./errors.cjs');
 var transportCommon = require('./transport-common.cjs');
 
 const DOCUMENT_RPC_FEATURES = ['document.open', 'document.invoke', 'document.save', 'document.close'];
+const DOCUMENT_RPC_REPLACE_FILE_FEATURE = 'document.replaceFile';
 const DOCUMENT_RPC_DEFAULT_CHANGE_MODE_FEATURE = 'document.open.defaultChangeMode';
 const DOCUMENT_RPC_SOURCE_SAVE_FEATURE = 'document.save.source';
 const DOCUMENT_RPC_REQUEST_TIMEOUT_FEATURE = 'host.request.timeoutMs';
@@ -103,6 +104,30 @@ function mapDocumentOpenResult(response, sessionId, path) {
         dirty: false,
     };
 }
+function mapDocumentReplaceFileResult(response, sessionId) {
+    if (typeof response !== 'object' || response == null || Array.isArray(response)) {
+        throw new errors.SuperDocCliError('Host returned invalid document.replaceFile result.', {
+            code: 'HOST_PROTOCOL_ERROR',
+            details: { result: response },
+        });
+    }
+    const record = response;
+    if (record.sessionId !== sessionId ||
+        record.replaced !== true ||
+        typeof record.byteLength !== 'number' ||
+        typeof record.revision !== 'string') {
+        throw new errors.SuperDocCliError('Host returned invalid document.replaceFile session metadata.', {
+            code: 'HOST_PROTOCOL_ERROR',
+            details: { expectedSessionId: sessionId, result: response },
+        });
+    }
+    return {
+        contextId: sessionId,
+        runtime: 'v2',
+        replaced: true,
+        document: { byteLength: record.byteLength, revision: record.revision },
+    };
+}
 function supportsTrackedMode(operation) {
     return operation.supportsTrackedMode === true || operation.supportsConditionalTrackedMode === true;
 }
@@ -316,6 +341,7 @@ function mapDocumentLifecycleResult(operationId, response, sessionId, expectedIn
 
 exports.DOCUMENT_RPC_DEFAULT_CHANGE_MODE_FEATURE = DOCUMENT_RPC_DEFAULT_CHANGE_MODE_FEATURE;
 exports.DOCUMENT_RPC_FEATURES = DOCUMENT_RPC_FEATURES;
+exports.DOCUMENT_RPC_REPLACE_FILE_FEATURE = DOCUMENT_RPC_REPLACE_FILE_FEATURE;
 exports.DOCUMENT_RPC_REQUEST_TIMEOUT_FEATURE = DOCUMENT_RPC_REQUEST_TIMEOUT_FEATURE;
 exports.DOCUMENT_RPC_SOURCE_SAVE_FEATURE = DOCUMENT_RPC_SOURCE_SAVE_FEATURE;
 exports.buildDocumentInvokeParams = buildDocumentInvokeParams;
@@ -325,4 +351,5 @@ exports.documentRpcEnabled = documentRpcEnabled;
 exports.documentRpcRequestSupportsResponseTimeout = documentRpcRequestSupportsResponseTimeout;
 exports.mapDocumentLifecycleResult = mapDocumentLifecycleResult;
 exports.mapDocumentOpenResult = mapDocumentOpenResult;
+exports.mapDocumentReplaceFileResult = mapDocumentReplaceFileResult;
 exports.supportsDocumentRpc = supportsDocumentRpc;

package/dist/runtime/document-rpc.d.ts

@@ -1,5 +1,6 @@
 import { type ChangeMode, type InvokeOptions, type OperationSpec, type UserIdentity } from './transport-common.js';
 export declare const DOCUMENT_RPC_FEATURES: readonly ["document.open", "document.invoke", "document.save", "document.close"];
+export declare const DOCUMENT_RPC_REPLACE_FILE_FEATURE = "document.replaceFile";
 export declare const DOCUMENT_RPC_DEFAULT_CHANGE_MODE_FEATURE = "document.open.defaultChangeMode";
 export declare const DOCUMENT_RPC_SOURCE_SAVE_FEATURE = "document.save.source";
 export declare const DOCUMENT_RPC_REQUEST_TIMEOUT_FEATURE = "host.request.timeoutMs";
@@ -15,6 +16,7 @@ export declare function buildDocumentOpenParams(params: Record<string, unknown>,
     readonly params: Record<string, unknown>;
 };
 export declare function mapDocumentOpenResult(response: unknown, sessionId: string, path: string): Record<string, unknown>;
+export declare function mapDocumentReplaceFileResult(response: unknown, sessionId: string): Record<string, unknown>;
 export declare function buildDocumentInvokeParams(sessionId: string, operation: OperationSpec, params: Record<string, unknown>, options: InvokeOptions, hostFeatures?: ReadonlySet<string>): {
     readonly method: string;
     readonly params: Record<string, unknown>;

package/dist/runtime/document-rpc.js

@@ -2,6 +2,7 @@ import { randomUUID } from 'node:crypto';
 import { SuperDocCliError } from './errors.js';
 import { applyOperationParamAliases, } from './transport-common.js';
 export const DOCUMENT_RPC_FEATURES = ['document.open', 'document.invoke', 'document.save', 'document.close'];
+export const DOCUMENT_RPC_REPLACE_FILE_FEATURE = 'document.replaceFile';
 export const DOCUMENT_RPC_DEFAULT_CHANGE_MODE_FEATURE = 'document.open.defaultChangeMode';
 export const DOCUMENT_RPC_SOURCE_SAVE_FEATURE = 'document.save.source';
 export const DOCUMENT_RPC_REQUEST_TIMEOUT_FEATURE = 'host.request.timeoutMs';
@@ -100,6 +101,30 @@ export function mapDocumentOpenResult(response, sessionId, path) {
         dirty: false,
     };
 }
+export function mapDocumentReplaceFileResult(response, sessionId) {
+    if (typeof response !== 'object' || response == null || Array.isArray(response)) {
+        throw new SuperDocCliError('Host returned invalid document.replaceFile result.', {
+            code: 'HOST_PROTOCOL_ERROR',
+            details: { result: response },
+        });
+    }
+    const record = response;
+    if (record.sessionId !== sessionId ||
+        record.replaced !== true ||
+        typeof record.byteLength !== 'number' ||
+        typeof record.revision !== 'string') {
+        throw new SuperDocCliError('Host returned invalid document.replaceFile session metadata.', {
+            code: 'HOST_PROTOCOL_ERROR',
+            details: { expectedSessionId: sessionId, result: response },
+        });
+    }
+    return {
+        contextId: sessionId,
+        runtime: 'v2',
+        replaced: true,
+        document: { byteLength: record.byteLength, revision: record.revision },
+    };
+}
 function supportsTrackedMode(operation) {
     return operation.supportsTrackedMode === true || operation.supportsConditionalTrackedMode === true;
 }

package/dist/runtime/host.cjs

@@ -4,6 +4,7 @@ var node_child_process = require('node:child_process');
 var node_readline = require('node:readline');
 var transportCommon = require('./transport-common.cjs');
 var errors = require('./errors.cjs');
+var documentEvidence = require('./document-evidence.cjs');
 var documentRpc = require('./document-rpc.cjs');
 
 const HOST_PROTOCOL_VERSION = '1.0';
@@ -130,6 +131,28 @@ class HostTransport {
     async connect() {
         await this.runWhileActive(() => this.ensureConnected());
     }
+    supportsDocumentFacts(sessionId) {
+        return (this.documentRpcSessions.has(sessionId) &&
+            this.hostFeatures.has('document.currentRevision') &&
+            this.hostFeatures.has('document.executionFacts') &&
+            this.hostFeatures.has('document.mutationRevision'));
+    }
+    async readDocumentRevision(sessionId) {
+        return this.runWhileActive(async () => {
+            if (!this.documentRpcSessions.has(sessionId) || !this.hostFeatures.has('document.currentRevision')) {
+                return undefined;
+            }
+            await this.ensureConnected();
+            const revision = await this.sendJsonRpcRequest('document.currentRevision', { sessionId }, this.resolveWatchdogTimeout(undefined), { requestTimeoutMs: this.resolveDocumentRequestTimeout(undefined) });
+            if (typeof revision !== 'string' || revision.trim().length === 0 || revision === 'unknown') {
+                throw new errors.SuperDocCliError('Document host returned an invalid current revision.', {
+                    code: 'HOST_PROTOCOL_ERROR',
+                    details: { sessionId },
+                });
+            }
+            return revision;
+        });
+    }
     async dispose() {
         if (this.disposePromise)
             return this.disposePromise;
@@ -187,6 +210,34 @@ class HostTransport {
     async invoke(operation, params = {}, options = {}) {
         return this.runWhileActive(() => this.invokeWhileActive(operation, params, options));
     }
+    async replaceFile(sessionId, path, options = {}) {
+        return this.runWhileActive(async () => {
+            await this.ensureConnected();
+            if (!this.hostFeatures.has(documentRpc.DOCUMENT_RPC_REPLACE_FILE_FEATURE)) {
+                throw new errors.SuperDocCliError('The connected host does not support document replacement.', {
+                    code: 'CAPABILITY_UNSUPPORTED',
+                    details: { feature: documentRpc.DOCUMENT_RPC_REPLACE_FILE_FEATURE },
+                });
+            }
+            const tracksDirectSession = this.documentRpcSessions.has(sessionId);
+            if (tracksDirectSession)
+                this.beginDocumentRpcMutation(sessionId);
+            try {
+                const response = await this.sendJsonRpcRequest(documentRpc.DOCUMENT_RPC_REPLACE_FILE_FEATURE, { sessionId, path }, this.resolveWatchdogTimeout(options.timeoutMs));
+                const result = documentRpc.mapDocumentReplaceFileResult(response, sessionId);
+                if (tracksDirectSession)
+                    this.settleDocumentRpcMutation(sessionId, 'applied');
+                return result;
+            }
+            catch (error) {
+                if (tracksDirectSession) {
+                    const indeterminate = error instanceof errors.SuperDocCliError && ['TIMEOUT', 'HOST_TIMEOUT', 'HOST_DISCONNECTED'].includes(error.code);
+                    this.settleDocumentRpcMutation(sessionId, indeterminate ? 'indeterminate' : 'not-applied');
+                }
+                throw error;
+            }
+        });
+    }
     async invokeWhileActive(operation, params, options) {
         const collaborationAuth = options.collaborationAuth === undefined ? undefined : transportCommon.normalizeCollaborationAuth(options.collaborationAuth);
         if (collaborationAuth !== undefined) {
@@ -240,12 +291,17 @@ class HostTransport {
                 ? request.params.options
                 : undefined;
             const tracksMutation = request.method === 'document.invoke' && documentOperation.mutates === true && requestOptions?.dryRun !== true;
+            const includeRevision = request.method === 'document.invoke' &&
+                documentOperation.mutates === true &&
+                this.hostFeatures.has('document.mutationRevision');
             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);
+                const response = await this.sendJsonRpcRequest(request.method, { ...request.params, ...(includeRevision ? { includeRevision: true } : {}) }, this.resolveWatchdogTimeout(options.timeoutMs), { requestTimeoutMs });
+                result = documentRpc.mapDocumentLifecycleResult(operation.operationId, includeRevision ? response.result : response, sessionId, operation.operationId === 'doc.save' ? request.params.path === undefined : undefined);
+                if (includeRevision)
+                    documentEvidence.registerMutationRevision(result, response.revision);
             }
             catch (error) {
                 if (tracksMutation) {
@@ -285,8 +341,11 @@ class HostTransport {
                 details: { operationId: operation.operationId },
             });
         }
+        const supportsRequestTimeoutMetadata = this.hostFeatures.has(documentRpc.DOCUMENT_RPC_REQUEST_TIMEOUT_FEATURE);
         const cliHostRequestTimeoutMs = this.requestTimeoutMs ?? HOST_DEFAULT_REQUEST_TIMEOUT_MS;
-        if (options.timeoutMs !== undefined && options.timeoutMs > cliHostRequestTimeoutMs) {
+        if (!supportsRequestTimeoutMetadata &&
+            options.timeoutMs !== undefined &&
+            options.timeoutMs > cliHostRequestTimeoutMs) {
             throw new errors.SuperDocCliError(`CLI host cannot honor timeoutMs=${options.timeoutMs} above its ${cliHostRequestTimeoutMs}ms request ceiling.`, {
                 code: 'DOCUMENT_RPC_INPUT_UNSUPPORTED',
                 details: {
@@ -304,7 +363,9 @@ class HostTransport {
             argv,
             stdinBase64,
             ...(collaborationAuth === undefined ? {} : { collaborationAuth }),
-        }, watchdogTimeout);
+        }, watchdogTimeout, {
+            requestTimeoutMs: supportsRequestTimeoutMetadata ? options.timeoutMs : undefined,
+        });
         if (typeof response !== 'object' || response == null || Array.isArray(response)) {
             throw new errors.SuperDocCliError('Host returned invalid cli.invoke result.', {
                 code: 'HOST_PROTOCOL_ERROR',

package/dist/runtime/host.d.ts

@@ -61,9 +61,12 @@ export declare class HostTransport {
         processMode?: 'cli' | 'document';
     } & SuperDocClientOptions);
     connect(): Promise<void>;
+    supportsDocumentFacts(sessionId: string): boolean;
+    readDocumentRevision(sessionId: string): Promise<string | undefined>;
     dispose(): Promise<void>;
     private disposeAfterActiveCalls;
     invoke<TData = unknown>(operation: OperationSpec, params?: Record<string, unknown>, options?: TransportInvokeOptions): Promise<TData>;
+    replaceFile(sessionId: string, path: string, options?: TransportInvokeOptions): Promise<Record<string, unknown>>;
     private invokeWhileActive;
     private runWhileActive;
     private ensureConnected;

package/dist/runtime/host.js

@@ -2,7 +2,8 @@ import { spawn } from 'node:child_process';
 import { createInterface } from 'node:readline';
 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, DOCUMENT_RPC_SOURCE_SAVE_FEATURE, buildDocumentInvokeParams, buildDocumentOpenParams, canOpenWithDocumentRpc, documentRpcRequestSupportsResponseTimeout, documentRpcEnabled, mapDocumentLifecycleResult, mapDocumentOpenResult, supportsDocumentRpc, } from './document-rpc.js';
+import { registerMutationRevision } from './document-evidence.js';
+import { DOCUMENT_RPC_FEATURES, DOCUMENT_RPC_DEFAULT_CHANGE_MODE_FEATURE, DOCUMENT_RPC_REQUEST_TIMEOUT_FEATURE, DOCUMENT_RPC_REPLACE_FILE_FEATURE, DOCUMENT_RPC_SOURCE_SAVE_FEATURE, buildDocumentInvokeParams, buildDocumentOpenParams, canOpenWithDocumentRpc, documentRpcRequestSupportsResponseTimeout, documentRpcEnabled, mapDocumentLifecycleResult, mapDocumentOpenResult, mapDocumentReplaceFileResult, 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';
@@ -127,6 +128,28 @@ export class HostTransport {
     async connect() {
         await this.runWhileActive(() => this.ensureConnected());
     }
+    supportsDocumentFacts(sessionId) {
+        return (this.documentRpcSessions.has(sessionId) &&
+            this.hostFeatures.has('document.currentRevision') &&
+            this.hostFeatures.has('document.executionFacts') &&
+            this.hostFeatures.has('document.mutationRevision'));
+    }
+    async readDocumentRevision(sessionId) {
+        return this.runWhileActive(async () => {
+            if (!this.documentRpcSessions.has(sessionId) || !this.hostFeatures.has('document.currentRevision')) {
+                return undefined;
+            }
+            await this.ensureConnected();
+            const revision = await this.sendJsonRpcRequest('document.currentRevision', { sessionId }, this.resolveWatchdogTimeout(undefined), { requestTimeoutMs: this.resolveDocumentRequestTimeout(undefined) });
+            if (typeof revision !== 'string' || revision.trim().length === 0 || revision === 'unknown') {
+                throw new SuperDocCliError('Document host returned an invalid current revision.', {
+                    code: 'HOST_PROTOCOL_ERROR',
+                    details: { sessionId },
+                });
+            }
+            return revision;
+        });
+    }
     async dispose() {
         if (this.disposePromise)
             return this.disposePromise;
@@ -184,6 +207,34 @@ export class HostTransport {
     async invoke(operation, params = {}, options = {}) {
         return this.runWhileActive(() => this.invokeWhileActive(operation, params, options));
     }
+    async replaceFile(sessionId, path, options = {}) {
+        return this.runWhileActive(async () => {
+            await this.ensureConnected();
+            if (!this.hostFeatures.has(DOCUMENT_RPC_REPLACE_FILE_FEATURE)) {
+                throw new SuperDocCliError('The connected host does not support document replacement.', {
+                    code: 'CAPABILITY_UNSUPPORTED',
+                    details: { feature: DOCUMENT_RPC_REPLACE_FILE_FEATURE },
+                });
+            }
+            const tracksDirectSession = this.documentRpcSessions.has(sessionId);
+            if (tracksDirectSession)
+                this.beginDocumentRpcMutation(sessionId);
+            try {
+                const response = await this.sendJsonRpcRequest(DOCUMENT_RPC_REPLACE_FILE_FEATURE, { sessionId, path }, this.resolveWatchdogTimeout(options.timeoutMs));
+                const result = mapDocumentReplaceFileResult(response, sessionId);
+                if (tracksDirectSession)
+                    this.settleDocumentRpcMutation(sessionId, 'applied');
+                return result;
+            }
+            catch (error) {
+                if (tracksDirectSession) {
+                    const indeterminate = error instanceof SuperDocCliError && ['TIMEOUT', 'HOST_TIMEOUT', 'HOST_DISCONNECTED'].includes(error.code);
+                    this.settleDocumentRpcMutation(sessionId, indeterminate ? 'indeterminate' : 'not-applied');
+                }
+                throw error;
+            }
+        });
+    }
     async invokeWhileActive(operation, params, options) {
         const collaborationAuth = options.collaborationAuth === undefined ? undefined : normalizeCollaborationAuth(options.collaborationAuth);
         if (collaborationAuth !== undefined) {
@@ -237,12 +288,17 @@ export class HostTransport {
                 ? request.params.options
                 : undefined;
             const tracksMutation = request.method === 'document.invoke' && documentOperation.mutates === true && requestOptions?.dryRun !== true;
+            const includeRevision = request.method === 'document.invoke' &&
+                documentOperation.mutates === true &&
+                this.hostFeatures.has('document.mutationRevision');
             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);
+                const response = await this.sendJsonRpcRequest(request.method, { ...request.params, ...(includeRevision ? { includeRevision: true } : {}) }, this.resolveWatchdogTimeout(options.timeoutMs), { requestTimeoutMs });
+                result = mapDocumentLifecycleResult(operation.operationId, includeRevision ? response.result : response, sessionId, operation.operationId === 'doc.save' ? request.params.path === undefined : undefined);
+                if (includeRevision)
+                    registerMutationRevision(result, response.revision);
             }
             catch (error) {
                 if (tracksMutation) {
@@ -282,8 +338,11 @@ export class HostTransport {
                 details: { operationId: operation.operationId },
             });
         }
+        const supportsRequestTimeoutMetadata = this.hostFeatures.has(DOCUMENT_RPC_REQUEST_TIMEOUT_FEATURE);
         const cliHostRequestTimeoutMs = this.requestTimeoutMs ?? HOST_DEFAULT_REQUEST_TIMEOUT_MS;
-        if (options.timeoutMs !== undefined && options.timeoutMs > cliHostRequestTimeoutMs) {
+        if (!supportsRequestTimeoutMetadata &&
+            options.timeoutMs !== undefined &&
+            options.timeoutMs > cliHostRequestTimeoutMs) {
             throw new SuperDocCliError(`CLI host cannot honor timeoutMs=${options.timeoutMs} above its ${cliHostRequestTimeoutMs}ms request ceiling.`, {
                 code: 'DOCUMENT_RPC_INPUT_UNSUPPORTED',
                 details: {
@@ -301,7 +360,9 @@ export class HostTransport {
             argv,
             stdinBase64,
             ...(collaborationAuth === undefined ? {} : { collaborationAuth }),
-        }, watchdogTimeout);
+        }, watchdogTimeout, {
+            requestTimeoutMs: supportsRequestTimeoutMetadata ? options.timeoutMs : undefined,
+        });
         if (typeof response !== 'object' || response == null || Array.isArray(response)) {
             throw new SuperDocCliError('Host returned invalid cli.invoke result.', {
                 code: 'HOST_PROTOCOL_ERROR',