@superdoc/sdk 2.6.0 → 2.7.0

package/dist/runtime/embedded-platform.js

@@ -0,0 +1,93 @@
+import { chmodSync, existsSync } from 'node:fs';
+import { createRequire } from 'node:module';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+const require = createRequire(import.meta.url);
+const TARGET_TO_PACKAGE = {
+    'darwin-arm64': '@superdoc/sdk-darwin-arm64',
+    'darwin-x64': '@superdoc/sdk-darwin-x64',
+    'linux-x64': '@superdoc/sdk-linux-x64',
+    'linux-arm64': '@superdoc/sdk-linux-arm64',
+    'windows-x64': '@superdoc/sdk-windows-x64',
+};
+const TARGET_TO_DIR = {
+    'darwin-arm64': 'sdk-darwin-arm64',
+    'darwin-x64': 'sdk-darwin-x64',
+    'linux-x64': 'sdk-linux-x64',
+    'linux-arm64': 'sdk-linux-arm64',
+    'windows-x64': 'sdk-windows-x64',
+};
+export function resolveEmbeddedTarget(platform = process.platform, arch = process.arch) {
+    if (platform === 'darwin' && arch === 'arm64')
+        return 'darwin-arm64';
+    if (platform === 'darwin' && arch === 'x64')
+        return 'darwin-x64';
+    if (platform === 'linux' && arch === 'x64')
+        return 'linux-x64';
+    if (platform === 'linux' && arch === 'arm64')
+        return 'linux-arm64';
+    if (platform === 'win32' && arch === 'x64')
+        return 'windows-x64';
+    return null;
+}
+export function embeddedPlatformPackage(target) {
+    return TARGET_TO_PACKAGE[target];
+}
+/**
+ * The binary shipped inside this package (`platforms/<target>/bin/`). A build
+ * that carries its own host is authoritative — it is the only copy guaranteed
+ * to match this SDK's code — so it is tried before any resolver lookup.
+ */
+function resolveFromPackageLocal(target, binaryName) {
+    const workspacePath = path.resolve(fileURLToPath(new URL('../../platforms', import.meta.url)), TARGET_TO_DIR[target], 'bin', binaryName);
+    return existsSync(workspacePath) ? workspacePath : null;
+}
+/**
+ * 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.
+ */
+function resolveFromPlatformPackage(target, binaryName) {
+    const pkg = TARGET_TO_PACKAGE[target];
+    let binaryPath;
+    try {
+        binaryPath = require.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)
+            return null;
+    }
+    catch {
+        // Either manifest being unreadable is itself disqualifying: an unverifiable
+        // host is exactly the case this guard exists to reject.
+        return null;
+    }
+    return binaryPath;
+}
+export function resolveEmbeddedPlatformBinary(target, binaryName) {
+    // Package-local first: a self-contained build must never be overridden by
+    // whatever the module resolver happens to find on NODE_PATH.
+    return resolveFromPackageLocal(target, binaryName) ?? resolveFromPlatformPackage(target, binaryName);
+}
+export function ensureEmbeddedExecutable(binaryPath) {
+    if (process.platform === 'win32')
+        return;
+    try {
+        chmodSync(binaryPath, 0o755);
+    }
+    catch {
+        // Non-fatal: spawn() reports the actionable execution error.
+    }
+}

package/dist/runtime/host.cjs

@@ -23,6 +23,21 @@ const HOST_DEFAULT_REQUEST_TIMEOUT_MS = 30_000;
 // abort. The buffer absorbs JSON-RPC serialization, stdio drain, and event-
 // loop latency.
 const WATCHDOG_HEADROOM_MS = 5_000;
+function mapCliInvocationResult(operation, value) {
+    const envelopeKey = operation.responseEnvelopeKey;
+    if (envelopeKey === null || envelopeKey === undefined)
+        return value;
+    if (typeof envelopeKey !== 'string' || envelopeKey.length === 0) {
+        throw new errors.SuperDocCliError('Generated operation has invalid response envelope metadata.', {
+            code: 'HOST_PROTOCOL_ERROR',
+            details: { operationId: operation.operationId, responseEnvelopeKey: envelopeKey },
+        });
+    }
+    if (typeof value !== 'object' || value === null || Array.isArray(value))
+        return value;
+    const extracted = value[envelopeKey];
+    return extracted === undefined ? value : extracted;
+}
 /**
  * Builds the argv passed to `spawn` for `superdoc host --stdio`. Propagates
  * `requestTimeoutMs` to the host via `--request-timeout-ms`, since the SDK
@@ -101,14 +116,9 @@ class HostTransport {
                 details: { defaultChangeMode: options.defaultChangeMode },
             });
         }
-        this.defaultChangeMode = options.defaultChangeMode;
+        this.defaultChangeMode = options.defaultChangeMode ?? undefined;
         this.user = options.user;
-        this.documentRpcEnabled = documentRpc.documentRpcEnabled(options.env);
-        if (this.processMode === 'document' && !this.documentRpcEnabled) {
-            throw new errors.SuperDocCliError('SUPERDOC_SDK_DOCUMENT_HOST_BIN requires SUPERDOC_SDK_DOCUMENT_RPC=1.', {
-                code: 'INVALID_ARGUMENT',
-            });
-        }
+        this.documentRpcEnabled = this.processMode === 'document' || documentRpc.documentRpcEnabled(options.env);
     }
     async connect() {
         await this.ensureConnected();
@@ -139,23 +149,31 @@ class HostTransport {
     }
     async invoke(operation, params = {}, options = {}) {
         await this.ensureConnected();
+        const shouldOpenThroughCliTimeoutFallback = this.processMode === 'cli' &&
+            (this.requestTimeoutMs !== undefined ||
+                (options.timeoutMs !== undefined && !this.hostFeatures.has(documentRpc.DOCUMENT_RPC_REQUEST_TIMEOUT_FEATURE)));
         if (this.documentRpcEnabled &&
             documentRpc.supportsDocumentRpc(this.hostFeatures) &&
-            this.defaultChangeMode === undefined &&
-            this.user === undefined &&
+            (this.defaultChangeMode === undefined || this.hostFeatures.has(documentRpc.DOCUMENT_RPC_DEFAULT_CHANGE_MODE_FEATURE)) &&
             operation.operationId === 'doc.open' &&
-            documentRpc.canOpenWithDocumentRpc(params, options)) {
-            const opened = documentRpc.buildDocumentOpenParams(params);
-            const response = await this.sendJsonRpcRequest('document.open', opened.params, this.resolveWatchdogTimeout(options.timeoutMs));
+            documentRpc.canOpenWithDocumentRpc(params, options) &&
+            !shouldOpenThroughCliTimeoutFallback) {
+            const opened = documentRpc.buildDocumentOpenParams(params, this.user, this.defaultChangeMode);
+            const requestTimeoutMs = this.resolveDocumentRequestTimeout(options.timeoutMs);
+            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);
             return result;
         }
         const sessionId = typeof params.sessionId === 'string' ? params.sessionId : undefined;
         if (sessionId !== undefined && this.documentRpcSessions.has(sessionId)) {
-            const request = documentRpc.buildDocumentInvokeParams(sessionId, operation, params, options);
-            const response = await this.sendJsonRpcRequest(request.method, request.params, this.resolveWatchdogTimeout(options.timeoutMs));
-            const result = documentRpc.mapDocumentLifecycleResult(operation.operationId, response, sessionId);
+            const request = documentRpc.buildDocumentInvokeParams(sessionId, operation, params, options, this.hostFeatures);
+            const supportsResponseTimeout = documentRpc.documentRpcRequestSupportsResponseTimeout(operation, request);
+            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')
                 this.documentRpcSessions.delete(sessionId);
             return result;
@@ -166,6 +184,18 @@ class HostTransport {
                 details: { operationId: operation.operationId },
             });
         }
+        const cliHostRequestTimeoutMs = this.requestTimeoutMs ?? HOST_DEFAULT_REQUEST_TIMEOUT_MS;
+        if (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: {
+                    feature: documentRpc.DOCUMENT_RPC_REQUEST_TIMEOUT_FEATURE,
+                    operationId: operation.operationId,
+                    timeoutMs: options.timeoutMs,
+                    hostRequestTimeoutMs: cliHostRequestTimeoutMs,
+                },
+            });
+        }
         const argv = transportCommon.buildOperationArgv(operation, params, options, this.requestTimeoutMs, this.defaultChangeMode, this.user);
         const stdinBase64 = options.stdinBytes ? Buffer.from(options.stdinBytes).toString('base64') : '';
         const watchdogTimeout = this.resolveWatchdogTimeout(options.timeoutMs);
@@ -180,7 +210,7 @@ class HostTransport {
             });
         }
         const resultRecord = response;
-        return resultRecord.data;
+        return mapCliInvocationResult(operation, resultRecord.data);
     }
     async ensureConnected() {
         if (this.connecting) {
@@ -206,7 +236,7 @@ class HostTransport {
         const child = node_child_process.spawn(command, args, {
             env: {
                 ...process.env,
-                ...(this.env ?? {}),
+                ...this.env,
             },
             stdio: ['pipe', 'pipe', 'pipe'],
         });
@@ -285,7 +315,13 @@ class HostTransport {
                 details: { features },
             });
         }
-        const requiredFeatures = this.processMode === 'document' ? DOCUMENT_HOST_REQUIRED_FEATURES : CLI_HOST_REQUIRED_FEATURES;
+        const requiredFeatures = this.processMode === 'document'
+            ? [
+                ...DOCUMENT_HOST_REQUIRED_FEATURES,
+                ...(this.defaultChangeMode === undefined ? [] : [documentRpc.DOCUMENT_RPC_DEFAULT_CHANGE_MODE_FEATURE]),
+                ...(this.requestTimeoutMs === undefined ? [] : [documentRpc.DOCUMENT_RPC_REQUEST_TIMEOUT_FEATURE]),
+            ]
+            : CLI_HOST_REQUIRED_FEATURES;
         for (const requiredFeature of requiredFeatures) {
             if (!features.includes(requiredFeature)) {
                 throw new errors.SuperDocCliError(`Host does not support required feature: ${requiredFeature}`, {
@@ -301,7 +337,20 @@ class HostTransport {
     resolveWatchdogTimeout(timeoutMsOverride) {
         return resolveJsWatchdogTimeout(this.watchdogTimeoutMs, this.requestTimeoutMs, timeoutMsOverride);
     }
-    async sendJsonRpcRequest(method, params, watchdogTimeoutMs) {
+    resolveDocumentRequestTimeout(timeoutMsOverride) {
+        const requestTimeoutMs = timeoutMsOverride ?? this.requestTimeoutMs;
+        if (requestTimeoutMs === undefined)
+            return undefined;
+        if (this.hostFeatures.has(documentRpc.DOCUMENT_RPC_REQUEST_TIMEOUT_FEATURE))
+            return requestTimeoutMs;
+        if (this.processMode === 'cli' && timeoutMsOverride === undefined)
+            return undefined;
+        throw new errors.SuperDocCliError(`Structured document RPC host does not support ${documentRpc.DOCUMENT_RPC_REQUEST_TIMEOUT_FEATURE}.`, {
+            code: 'DOCUMENT_RPC_INPUT_UNSUPPORTED',
+            details: { feature: documentRpc.DOCUMENT_RPC_REQUEST_TIMEOUT_FEATURE },
+        });
+    }
+    async sendJsonRpcRequest(method, params, watchdogTimeoutMs, metadata = {}) {
         const child = this.child;
         if (!child || !child.stdin.writable) {
             throw new errors.SuperDocCliError('Host process is not available.', {
@@ -321,6 +370,7 @@ class HostTransport {
             id,
             method,
             params,
+            ...(metadata.requestTimeoutMs === undefined ? {} : { requestTimeoutMs: metadata.requestTimeoutMs }),
         });
         const promise = new Promise((resolve, reject) => {
             const timer = setTimeout(() => {
@@ -460,4 +510,5 @@ class HostTransport {
 exports.HostTransport = HostTransport;
 exports.buildDocumentHostSpawnArgs = buildDocumentHostSpawnArgs;
 exports.buildHostSpawnArgs = buildHostSpawnArgs;
+exports.mapCliInvocationResult = mapCliInvocationResult;
 exports.resolveJsWatchdogTimeout = resolveJsWatchdogTimeout;

package/dist/runtime/host.d.ts

@@ -1,4 +1,5 @@
 import { type InvokeOptions, type OperationSpec, type SuperDocClientOptions } from './transport-common.js';
+export declare function mapCliInvocationResult(operation: OperationSpec, value: unknown): unknown;
 /**
  * Builds the argv passed to `spawn` for `superdoc host --stdio`. Propagates
  * `requestTimeoutMs` to the host via `--request-timeout-ms`, since the SDK
@@ -59,6 +60,7 @@ export declare class HostTransport {
     private startHostProcess;
     private assertCapabilities;
     private resolveWatchdogTimeout;
+    private resolveDocumentRequestTimeout;
     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, buildDocumentInvokeParams, buildDocumentOpenParams, canOpenWithDocumentRpc, documentRpcEnabled, mapDocumentLifecycleResult, mapDocumentOpenResult, supportsDocumentRpc, } from './document-rpc.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';
 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'];
@@ -20,6 +20,21 @@ const HOST_DEFAULT_REQUEST_TIMEOUT_MS = 30_000;
 // abort. The buffer absorbs JSON-RPC serialization, stdio drain, and event-
 // loop latency.
 const WATCHDOG_HEADROOM_MS = 5_000;
+export function mapCliInvocationResult(operation, value) {
+    const envelopeKey = operation.responseEnvelopeKey;
+    if (envelopeKey === null || envelopeKey === undefined)
+        return value;
+    if (typeof envelopeKey !== 'string' || envelopeKey.length === 0) {
+        throw new SuperDocCliError('Generated operation has invalid response envelope metadata.', {
+            code: 'HOST_PROTOCOL_ERROR',
+            details: { operationId: operation.operationId, responseEnvelopeKey: envelopeKey },
+        });
+    }
+    if (typeof value !== 'object' || value === null || Array.isArray(value))
+        return value;
+    const extracted = value[envelopeKey];
+    return extracted === undefined ? value : extracted;
+}
 /**
  * Builds the argv passed to `spawn` for `superdoc host --stdio`. Propagates
  * `requestTimeoutMs` to the host via `--request-timeout-ms`, since the SDK
@@ -98,14 +113,9 @@ export class HostTransport {
                 details: { defaultChangeMode: options.defaultChangeMode },
             });
         }
-        this.defaultChangeMode = options.defaultChangeMode;
+        this.defaultChangeMode = options.defaultChangeMode ?? undefined;
         this.user = options.user;
-        this.documentRpcEnabled = documentRpcEnabled(options.env);
-        if (this.processMode === 'document' && !this.documentRpcEnabled) {
-            throw new SuperDocCliError('SUPERDOC_SDK_DOCUMENT_HOST_BIN requires SUPERDOC_SDK_DOCUMENT_RPC=1.', {
-                code: 'INVALID_ARGUMENT',
-            });
-        }
+        this.documentRpcEnabled = this.processMode === 'document' || documentRpcEnabled(options.env);
     }
     async connect() {
         await this.ensureConnected();
@@ -136,23 +146,31 @@ export class HostTransport {
     }
     async invoke(operation, params = {}, options = {}) {
         await this.ensureConnected();
+        const shouldOpenThroughCliTimeoutFallback = this.processMode === 'cli' &&
+            (this.requestTimeoutMs !== undefined ||
+                (options.timeoutMs !== undefined && !this.hostFeatures.has(DOCUMENT_RPC_REQUEST_TIMEOUT_FEATURE)));
         if (this.documentRpcEnabled &&
             supportsDocumentRpc(this.hostFeatures) &&
-            this.defaultChangeMode === undefined &&
-            this.user === undefined &&
+            (this.defaultChangeMode === undefined || this.hostFeatures.has(DOCUMENT_RPC_DEFAULT_CHANGE_MODE_FEATURE)) &&
             operation.operationId === 'doc.open' &&
-            canOpenWithDocumentRpc(params, options)) {
-            const opened = buildDocumentOpenParams(params);
-            const response = await this.sendJsonRpcRequest('document.open', opened.params, this.resolveWatchdogTimeout(options.timeoutMs));
+            canOpenWithDocumentRpc(params, options) &&
+            !shouldOpenThroughCliTimeoutFallback) {
+            const opened = buildDocumentOpenParams(params, this.user, this.defaultChangeMode);
+            const requestTimeoutMs = this.resolveDocumentRequestTimeout(options.timeoutMs);
+            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);
             return result;
         }
         const sessionId = typeof params.sessionId === 'string' ? params.sessionId : undefined;
         if (sessionId !== undefined && this.documentRpcSessions.has(sessionId)) {
-            const request = buildDocumentInvokeParams(sessionId, operation, params, options);
-            const response = await this.sendJsonRpcRequest(request.method, request.params, this.resolveWatchdogTimeout(options.timeoutMs));
-            const result = mapDocumentLifecycleResult(operation.operationId, response, sessionId);
+            const request = buildDocumentInvokeParams(sessionId, operation, params, options, this.hostFeatures);
+            const supportsResponseTimeout = documentRpcRequestSupportsResponseTimeout(operation, request);
+            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')
                 this.documentRpcSessions.delete(sessionId);
             return result;
@@ -163,6 +181,18 @@ export class HostTransport {
                 details: { operationId: operation.operationId },
             });
         }
+        const cliHostRequestTimeoutMs = this.requestTimeoutMs ?? HOST_DEFAULT_REQUEST_TIMEOUT_MS;
+        if (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: {
+                    feature: DOCUMENT_RPC_REQUEST_TIMEOUT_FEATURE,
+                    operationId: operation.operationId,
+                    timeoutMs: options.timeoutMs,
+                    hostRequestTimeoutMs: cliHostRequestTimeoutMs,
+                },
+            });
+        }
         const argv = buildOperationArgv(operation, params, options, this.requestTimeoutMs, this.defaultChangeMode, this.user);
         const stdinBase64 = options.stdinBytes ? Buffer.from(options.stdinBytes).toString('base64') : '';
         const watchdogTimeout = this.resolveWatchdogTimeout(options.timeoutMs);
@@ -177,7 +207,7 @@ export class HostTransport {
             });
         }
         const resultRecord = response;
-        return resultRecord.data;
+        return mapCliInvocationResult(operation, resultRecord.data);
     }
     async ensureConnected() {
         if (this.connecting) {
@@ -203,7 +233,7 @@ export class HostTransport {
         const child = spawn(command, args, {
             env: {
                 ...process.env,
-                ...(this.env ?? {}),
+                ...this.env,
             },
             stdio: ['pipe', 'pipe', 'pipe'],
         });
@@ -282,7 +312,13 @@ export class HostTransport {
                 details: { features },
             });
         }
-        const requiredFeatures = this.processMode === 'document' ? DOCUMENT_HOST_REQUIRED_FEATURES : CLI_HOST_REQUIRED_FEATURES;
+        const requiredFeatures = this.processMode === 'document'
+            ? [
+                ...DOCUMENT_HOST_REQUIRED_FEATURES,
+                ...(this.defaultChangeMode === undefined ? [] : [DOCUMENT_RPC_DEFAULT_CHANGE_MODE_FEATURE]),
+                ...(this.requestTimeoutMs === undefined ? [] : [DOCUMENT_RPC_REQUEST_TIMEOUT_FEATURE]),
+            ]
+            : CLI_HOST_REQUIRED_FEATURES;
         for (const requiredFeature of requiredFeatures) {
             if (!features.includes(requiredFeature)) {
                 throw new SuperDocCliError(`Host does not support required feature: ${requiredFeature}`, {
@@ -298,7 +334,20 @@ export class HostTransport {
     resolveWatchdogTimeout(timeoutMsOverride) {
         return resolveJsWatchdogTimeout(this.watchdogTimeoutMs, this.requestTimeoutMs, timeoutMsOverride);
     }
-    async sendJsonRpcRequest(method, params, watchdogTimeoutMs) {
+    resolveDocumentRequestTimeout(timeoutMsOverride) {
+        const requestTimeoutMs = timeoutMsOverride ?? this.requestTimeoutMs;
+        if (requestTimeoutMs === undefined)
+            return undefined;
+        if (this.hostFeatures.has(DOCUMENT_RPC_REQUEST_TIMEOUT_FEATURE))
+            return requestTimeoutMs;
+        if (this.processMode === 'cli' && timeoutMsOverride === undefined)
+            return undefined;
+        throw new SuperDocCliError(`Structured document RPC host does not support ${DOCUMENT_RPC_REQUEST_TIMEOUT_FEATURE}.`, {
+            code: 'DOCUMENT_RPC_INPUT_UNSUPPORTED',
+            details: { feature: DOCUMENT_RPC_REQUEST_TIMEOUT_FEATURE },
+        });
+    }
+    async sendJsonRpcRequest(method, params, watchdogTimeoutMs, metadata = {}) {
         const child = this.child;
         if (!child || !child.stdin.writable) {
             throw new SuperDocCliError('Host process is not available.', {
@@ -318,6 +367,7 @@ export class HostTransport {
             id,
             method,
             params,
+            ...(metadata.requestTimeoutMs === undefined ? {} : { requestTimeoutMs: metadata.requestTimeoutMs }),
         });
         const promise = new Promise((resolve, reject) => {
             const timer = setTimeout(() => {

package/dist/runtime/process.cjs

@@ -2,9 +2,36 @@
 
 var host = require('./host.cjs');
 var embeddedCli = require('./embedded-cli.cjs');
+var embeddedDocumentHost = require('./embedded-document-host.cjs');
 var debugTrace = require('./debug-trace.cjs');
 var errors = require('./errors.cjs');
 
+function resolveRuntimeProcess(options = {}, embedded = {
+    cli: embeddedCli.resolveEmbeddedCliBinary,
+    documentHost: embeddedDocumentHost.resolveEmbeddedDocumentHostBinary,
+}) {
+    const configuredDocumentHostPath = options.documentHostPath;
+    if (configuredDocumentHostPath !== undefined && configuredDocumentHostPath.trim().length === 0) {
+        throw new errors.SuperDocCliError('documentHostPath must be a non-empty path.', {
+            code: 'INVALID_ARGUMENT',
+        });
+    }
+    const configuredDocumentHostBin = options.env?.SUPERDOC_SDK_DOCUMENT_HOST_BIN ?? process.env.SUPERDOC_SDK_DOCUMENT_HOST_BIN;
+    const documentHostBin = configuredDocumentHostPath ??
+        (configuredDocumentHostBin === 'embedded' ? embedded.documentHost() : configuredDocumentHostBin);
+    if (documentHostBin !== undefined && documentHostBin.trim().length === 0) {
+        throw new errors.SuperDocCliError('SUPERDOC_SDK_DOCUMENT_HOST_BIN must be a non-empty path.', {
+            code: 'INVALID_ARGUMENT',
+        });
+    }
+    if (documentHostBin !== undefined) {
+        return { hostBin: documentHostBin, processMode: 'document' };
+    }
+    return {
+        hostBin: options.env?.SUPERDOC_CLI_BIN ?? process.env.SUPERDOC_CLI_BIN ?? embedded.cli(),
+        processMode: 'cli',
+    };
+}
 /**
  * Internal runtime that delegates operations to a persistent host transport.
  *
@@ -14,17 +41,10 @@ var errors = require('./errors.cjs');
 class SuperDocRuntime {
     transport;
     constructor(options = {}) {
-        const documentHostBin = options.env?.SUPERDOC_SDK_DOCUMENT_HOST_BIN ?? process.env.SUPERDOC_SDK_DOCUMENT_HOST_BIN;
-        if (documentHostBin !== undefined && documentHostBin.trim().length === 0) {
-            throw new errors.SuperDocCliError('SUPERDOC_SDK_DOCUMENT_HOST_BIN must be a non-empty path.', {
-                code: 'INVALID_ARGUMENT',
-            });
-        }
-        const hostBin = documentHostBin ?? options.env?.SUPERDOC_CLI_BIN ?? process.env.SUPERDOC_CLI_BIN ?? embeddedCli.resolveEmbeddedCliBinary();
+        const runtimeProcess = resolveRuntimeProcess(options);
         this.transport = new host.HostTransport({
             ...options,
-            hostBin,
-            processMode: documentHostBin === undefined ? 'cli' : 'document',
+            ...runtimeProcess,
         });
     }
     async connect() {
@@ -67,3 +87,4 @@ class SuperDocRuntime {
 }
 
 exports.SuperDocRuntime = SuperDocRuntime;
+exports.resolveRuntimeProcess = resolveRuntimeProcess;

package/dist/runtime/process.d.ts

@@ -1,4 +1,13 @@
 import type { DocumentRuntimeKind, InvokeOptions, OperationParamSpec, OperationSpec, RuntimeInvoker, SuperDocClientOptions } from './transport-common.js';
+type RuntimeProcessResolution = {
+    hostBin: string;
+    processMode: 'cli' | 'document';
+};
+type EmbeddedRuntimeResolvers = {
+    cli: () => string;
+    documentHost: () => string;
+};
+export declare function resolveRuntimeProcess(options?: SuperDocClientOptions, embedded?: EmbeddedRuntimeResolvers): RuntimeProcessResolution;
 /**
  * Internal runtime that delegates operations to a persistent host transport.
  *

package/dist/runtime/process.js

@@ -1,7 +1,34 @@
 import { HostTransport } from './host.js';
 import { resolveEmbeddedCliBinary } from './embedded-cli.js';
+import { resolveEmbeddedDocumentHostBinary } from './embedded-document-host.js';
 import { writeSdkDebugTrace } from './debug-trace.js';
 import { SuperDocCliError } from './errors.js';
+export function resolveRuntimeProcess(options = {}, embedded = {
+    cli: resolveEmbeddedCliBinary,
+    documentHost: resolveEmbeddedDocumentHostBinary,
+}) {
+    const configuredDocumentHostPath = options.documentHostPath;
+    if (configuredDocumentHostPath !== undefined && configuredDocumentHostPath.trim().length === 0) {
+        throw new SuperDocCliError('documentHostPath must be a non-empty path.', {
+            code: 'INVALID_ARGUMENT',
+        });
+    }
+    const configuredDocumentHostBin = options.env?.SUPERDOC_SDK_DOCUMENT_HOST_BIN ?? process.env.SUPERDOC_SDK_DOCUMENT_HOST_BIN;
+    const documentHostBin = configuredDocumentHostPath ??
+        (configuredDocumentHostBin === 'embedded' ? embedded.documentHost() : configuredDocumentHostBin);
+    if (documentHostBin !== undefined && documentHostBin.trim().length === 0) {
+        throw new SuperDocCliError('SUPERDOC_SDK_DOCUMENT_HOST_BIN must be a non-empty path.', {
+            code: 'INVALID_ARGUMENT',
+        });
+    }
+    if (documentHostBin !== undefined) {
+        return { hostBin: documentHostBin, processMode: 'document' };
+    }
+    return {
+        hostBin: options.env?.SUPERDOC_CLI_BIN ?? process.env.SUPERDOC_CLI_BIN ?? embedded.cli(),
+        processMode: 'cli',
+    };
+}
 /**
  * Internal runtime that delegates operations to a persistent host transport.
  *
@@ -11,17 +38,10 @@ import { SuperDocCliError } from './errors.js';
 export class SuperDocRuntime {
     transport;
     constructor(options = {}) {
-        const documentHostBin = options.env?.SUPERDOC_SDK_DOCUMENT_HOST_BIN ?? process.env.SUPERDOC_SDK_DOCUMENT_HOST_BIN;
-        if (documentHostBin !== undefined && documentHostBin.trim().length === 0) {
-            throw new SuperDocCliError('SUPERDOC_SDK_DOCUMENT_HOST_BIN must be a non-empty path.', {
-                code: 'INVALID_ARGUMENT',
-            });
-        }
-        const hostBin = documentHostBin ?? options.env?.SUPERDOC_CLI_BIN ?? process.env.SUPERDOC_CLI_BIN ?? resolveEmbeddedCliBinary();
+        const runtimeProcess = resolveRuntimeProcess(options);
         this.transport = new HostTransport({
             ...options,
-            hostBin,
-            processMode: documentHostBin === undefined ? 'cli' : 'document',
+            ...runtimeProcess,
         });
     }
     async connect() {

package/dist/runtime/transport-common.cjs

@@ -163,5 +163,6 @@ function buildOperationArgv(operation, params, options, runtimeTimeoutMs, defaul
     return argv;
 }
 
+exports.applyOperationParamAliases = applyOperationParamAliases;
 exports.buildOperationArgv = buildOperationArgv;
 exports.resolveInvocation = resolveInvocation;

package/dist/runtime/transport-common.d.ts

@@ -34,6 +34,14 @@ export interface UserIdentity {
 }
 export interface SuperDocClientOptions {
     env?: Record<string, string | undefined>;
+    /**
+     * Standalone document-host entry to use instead of the embedded CLI.
+     *
+     * The host-only path supports local lifecycle methods and generated Document
+     * API operations through structured RPC. Interface-only conveniences fail
+     * without CLI fallback.
+     */
+    documentHostPath?: string;
     /**
      * Default document engine for `client.open(...)`. Explicit `runtime` on an
      * individual open call takes precedence.
@@ -42,11 +50,13 @@ export interface SuperDocClientOptions {
     startupTimeoutMs?: number;
     shutdownTimeoutMs?: number;
     /**
-     * Upper bound (ms) on how long the host process may spend on a single
-     * `cli.invoke` request before it kills the operation and returns a
-     * `RequestTimeout` error. Propagated to the host via `--request-timeout-ms`
-     * at spawn. Raise this for documents that legitimately need more than 30s
-     * to process; the SDK widens its own JSON-RPC watchdog to match.
+     * Upper bound (ms) on how long the host process may spend on a request
+     * before it returns a `RequestTimeout` error. Retry-safe structured document
+     * requests carry this budget as transport metadata; requests that may apply
+     * non-idempotent side effects await a definitive result instead. CLI-host
+     * requests also receive the budget through `--request-timeout-ms` at spawn.
+     * Raise this for documents that legitimately need more than 30s to process;
+     * the SDK widens its own JSON-RPC watchdog to match.
      *
      * Defaults to the host's own default (30s) when unset.
      */
@@ -54,11 +64,13 @@ export interface SuperDocClientOptions {
     /**
      * JS-side watchdog (ms) the SDK waits for a host reply before giving up.
      * Independent of {@link requestTimeoutMs} (which controls the host-side
-     * operation budget). Most callers should leave this at its default and use
-     * {@link requestTimeoutMs} as the single operation-timeout knob —
-     * `resolveWatchdogTimeout` already widens the watchdog above the host
-     * ceiling automatically. Override only when you need to detect a hung or
-     * crashed host faster than the operation budget allows.
+     * operation budget). Structured requests that may apply non-idempotent side
+     * effects wait for a definitive host result instead of applying an unsafe
+     * response deadline. Most callers should leave this at its default and use
+     * {@link requestTimeoutMs} as the single timeout knob for retry-safe work —
+     * `resolveWatchdogTimeout` already widens the watchdog above the host ceiling
+     * automatically. Override only when you need to detect a hung or crashed host
+     * faster than the operation budget allows.
      */
     watchdogTimeoutMs?: number;
     maxQueueDepth?: number;
@@ -70,6 +82,12 @@ export interface CliInvocation {
     prefixArgs: string[];
 }
 export declare function resolveInvocation(cliBin: string): CliInvocation;
+/**
+ * Resolve contract-shaped param aliases onto their canonical generated names.
+ * Returns the same object when no alias applies. Throws on a conflicting
+ * canonical/alias pair so divergent values can never be silently coalesced.
+ */
+export declare function applyOperationParamAliases(operation: OperationSpec, params: Record<string, unknown>): Record<string, unknown>;
 /**
  * Build the CLI argument vector for an operation invocation.
  *

package/dist/runtime/transport-common.js

@@ -54,7 +54,7 @@ function assertKnownTemplatesApplyParams(operation, params) {
  * Returns the same object when no alias applies. Throws on a conflicting
  * canonical/alias pair so divergent values can never be silently coalesced.
  */
-function applyOperationParamAliases(operation, params) {
+export function applyOperationParamAliases(operation, params) {
     const aliasMap = OPERATION_PARAM_ALIASES[operation.operationId];
     if (!aliasMap)
         return params;