@superdoc/sdk 2.18.0-next.2 → 2.18.0-next.4

package/dist/index.cjs

@@ -54,6 +54,9 @@ class BoundRuntime {
     supportsDocumentFacts() {
         return !this.closed && this.runtime.supportsDocumentFacts(this.sessionId);
     }
+    usesCliDocumentFacts() {
+        return !this.closed && this.runtime.usesCliDocumentFacts(this.sessionId);
+    }
     async readRevision() {
         if (this.closed)
             throw new errors.SuperDocCliError('Document handle is closed; cannot read its revision.', { code: 'DOCUMENT_CLOSED' });
@@ -84,7 +87,7 @@ class SuperDocDocumentCore {
         this.client = client$1;
         attachBoundDocApi(this, client.createBoundDocApi(this.boundRuntime));
         documentEvidence.registerDocumentRevisionReader(this, () => this.boundRuntime.readRevision());
-        documentEvidence.registerDocumentFactCapability(this, () => this.boundRuntime.supportsDocumentFacts());
+        documentEvidence.registerDocumentFactCapability(this, () => this.boundRuntime.supportsDocumentFacts(), () => this.boundRuntime.usesCliDocumentFacts());
     }
     get sessionId() {
         return this._sessionId;

package/dist/index.d.ts

@@ -14,6 +14,7 @@ declare class BoundRuntime implements RuntimeInvoker {
     invoke<TData = unknown>(operation: OperationSpec, params?: Record<string, unknown>, options?: InvokeOptions): Promise<TData>;
     replaceFile(source: ReplaceFileSource, options?: ReplaceFileOptions): Promise<ReplaceFileResult>;
     supportsDocumentFacts(): boolean;
+    usesCliDocumentFacts(): boolean;
     readRevision(): Promise<string | undefined>;
     markClosed(): void;
 }

package/dist/index.js

@@ -42,6 +42,9 @@ class BoundRuntime {
     supportsDocumentFacts() {
         return !this.closed && this.runtime.supportsDocumentFacts(this.sessionId);
     }
+    usesCliDocumentFacts() {
+        return !this.closed && this.runtime.usesCliDocumentFacts(this.sessionId);
+    }
     async readRevision() {
         if (this.closed)
             throw new SuperDocCliError('Document handle is closed; cannot read its revision.', { code: 'DOCUMENT_CLOSED' });
@@ -72,7 +75,7 @@ class SuperDocDocumentCore {
         this.client = client;
         attachBoundDocApi(this, createBoundDocApi(this.boundRuntime));
         registerDocumentRevisionReader(this, () => this.boundRuntime.readRevision());
-        registerDocumentFactCapability(this, () => this.boundRuntime.supportsDocumentFacts());
+        registerDocumentFactCapability(this, () => this.boundRuntime.supportsDocumentFacts(), () => this.boundRuntime.usesCliDocumentFacts());
     }
     get sessionId() {
         return this._sessionId;

package/dist/runtime/document-evidence.cjs

@@ -18,17 +18,23 @@ function getDocumentRevisionReader(document) {
     return revisionReaders.get(document);
 }
 const factCapabilities = new WeakMap();
-function registerDocumentFactCapability(document, supported) {
+const summaryCapabilities = new WeakMap();
+function registerDocumentFactCapability(document, supported, summaryCounts) {
     factCapabilities.set(document, supported);
+    if (summaryCounts)
+        summaryCapabilities.set(document, summaryCounts);
 }
 function supportsDocumentFacts(document) {
     return factCapabilities.get(document)?.() === true;
 }
+function requiresSummaryCounts(document) {
+    return summaryCapabilities.get(document)?.() === true;
+}
 function forwardDocumentEvidence(source, target) {
     const reader = getDocumentRevisionReader(source);
     if (reader)
         registerDocumentRevisionReader(target, reader);
-    registerDocumentFactCapability(target, () => supportsDocumentFacts(source));
+    registerDocumentFactCapability(target, () => supportsDocumentFacts(source), () => requiresSummaryCounts(source));
 }
 
 exports.forwardDocumentEvidence = forwardDocumentEvidence;
@@ -37,4 +43,5 @@ exports.getMutationRevision = getMutationRevision;
 exports.registerDocumentFactCapability = registerDocumentFactCapability;
 exports.registerDocumentRevisionReader = registerDocumentRevisionReader;
 exports.registerMutationRevision = registerMutationRevision;
+exports.requiresSummaryCounts = requiresSummaryCounts;
 exports.supportsDocumentFacts = supportsDocumentFacts;

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

@@ -7,7 +7,8 @@ export declare function registerMutationRevision(result: unknown, revision: Muta
 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 registerDocumentFactCapability(document: object, supported: () => boolean, summaryCounts?: () => boolean): void;
 export declare function supportsDocumentFacts(document: object): boolean;
+export declare function requiresSummaryCounts(document: object): boolean;
 export declare function forwardDocumentEvidence(source: object, target: object): void;
 export {};

package/dist/runtime/document-evidence.js

@@ -16,15 +16,21 @@ export function getDocumentRevisionReader(document) {
     return revisionReaders.get(document);
 }
 const factCapabilities = new WeakMap();
-export function registerDocumentFactCapability(document, supported) {
+const summaryCapabilities = new WeakMap();
+export function registerDocumentFactCapability(document, supported, summaryCounts) {
     factCapabilities.set(document, supported);
+    if (summaryCounts)
+        summaryCapabilities.set(document, summaryCounts);
 }
 export function supportsDocumentFacts(document) {
     return factCapabilities.get(document)?.() === true;
 }
+export function requiresSummaryCounts(document) {
+    return summaryCapabilities.get(document)?.() === true;
+}
 export function forwardDocumentEvidence(source, target) {
     const reader = getDocumentRevisionReader(source);
     if (reader)
         registerDocumentRevisionReader(target, reader);
-    registerDocumentFactCapability(target, () => supportsDocumentFacts(source));
+    registerDocumentFactCapability(target, () => supportsDocumentFacts(source), () => requiresSummaryCounts(source));
 }

package/dist/runtime/host.cjs

@@ -4,6 +4,7 @@ var node_child_process = require('node:child_process');
 var transportCommon = require('./transport-common.cjs');
 var errors = require('./errors.cjs');
 var documentEvidence = require('./document-evidence.cjs');
+var contract = require('../generated/contract.cjs');
 var documentRpc = require('./document-rpc.cjs');
 
 const HOST_PROTOCOL_VERSION = '1.0';
@@ -106,6 +107,7 @@ class HostTransport {
     activeCalls = new Set();
     hostFeatures = new Set();
     documentRpcSessions = new Set();
+    cliLocalSessions = new Set();
     dirtyDocumentRpcSessions = new Set();
     documentRpcMutationStates = new Map();
     indeterminateDiscardCloses = new Set();
@@ -132,13 +134,28 @@ class HostTransport {
         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'));
+        return (this.usesCliDocumentFacts(sessionId) ||
+            (this.documentRpcSessions.has(sessionId) &&
+                this.hostFeatures.has('document.currentRevision') &&
+                this.hostFeatures.has('document.executionFacts') &&
+                this.hostFeatures.has('document.mutationRevision')));
+    }
+    usesCliDocumentFacts(sessionId) {
+        return this.cliLocalSessions.has(sessionId) && this.hostFeatures.has('cli.invoke.localExecutionFacts');
     }
     async readDocumentRevision(sessionId) {
         return this.runWhileActive(async () => {
+            if (this.usesCliDocumentFacts(sessionId)) {
+                const revisionOperation = contract.CONTRACT.operations['doc.blocks.list'];
+                const page = await this.invoke(revisionOperation, {
+                    sessionId,
+                    offset: Number.MAX_SAFE_INTEGER,
+                    limit: 1,
+                });
+                if (typeof page.revision !== 'string' || !page.revision || page.revision === 'unknown')
+                    throw new errors.SuperDocCliError('CLI returned an invalid execution revision.', { code: 'HOST_PROTOCOL_ERROR' });
+                return page.revision;
+            }
             if (!this.documentRpcSessions.has(sessionId) || !this.hostFeatures.has('document.currentRevision')) {
                 return undefined;
             }
@@ -359,9 +376,23 @@ class HostTransport {
         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);
+        const structuredInput = this.hostFeatures.has('cli.invoke.structuredReads')
+            ? transportCommon.buildStructuredReadInput(operation, params, options, argv)
+            : undefined;
+        const includeRevision = sessionId !== undefined &&
+            this.usesCliDocumentFacts(sessionId) &&
+            operation.mutates === true;
         const response = await this.sendJsonRpcRequest('cli.invoke', {
-            argv,
-            stdinBase64,
+            ...(structuredInput === undefined
+                ? { argv, stdinBase64 }
+                : {
+                    operationId: operation.operationId,
+                    input: structuredInput,
+                    ...((options.timeoutMs ?? this.requestTimeoutMs) === undefined
+                        ? {}
+                        : { timeoutMs: options.timeoutMs ?? this.requestTimeoutMs }),
+                }),
+            ...(includeRevision ? { includeRevision: true } : {}),
             ...(collaborationAuth === undefined ? {} : { collaborationAuth }),
         }, watchdogTimeout, {
             requestTimeoutMs: supportsRequestTimeoutMetadata ? options.timeoutMs : undefined,
@@ -373,7 +404,18 @@ class HostTransport {
             });
         }
         const resultRecord = response;
-        return mapCliInvocationResult(operation, resultRecord.data);
+        const result = mapCliInvocationResult(operation, resultRecord.data);
+        if (operation.operationId === 'doc.open' && typeof result === 'object' && result !== null) {
+            const opened = result;
+            if (typeof opened.contextId === 'string' && opened.sessionType === 'local')
+                this.cliLocalSessions.add(opened.contextId);
+        }
+        if (operation.operationId === 'doc.close' && sessionId)
+            this.cliLocalSessions.delete(sessionId);
+        const revision = resultRecord.meta?.revision;
+        if (includeRevision && revision)
+            documentEvidence.registerMutationRevision(result, revision);
+        return result;
     }
     runWhileActive(start) {
         if (this.terminalDisposalError) {

package/dist/runtime/host.d.ts

@@ -54,6 +54,7 @@ export declare class HostTransport {
     private readonly activeCalls;
     private readonly hostFeatures;
     private readonly documentRpcSessions;
+    private readonly cliLocalSessions;
     private readonly dirtyDocumentRpcSessions;
     private readonly documentRpcMutationStates;
     private readonly indeterminateDiscardCloses;
@@ -63,6 +64,7 @@ export declare class HostTransport {
     } & SuperDocClientOptions);
     connect(): Promise<void>;
     supportsDocumentFacts(sessionId: string): boolean;
+    usesCliDocumentFacts(sessionId: string): boolean;
     readDocumentRevision(sessionId: string): Promise<string | undefined>;
     dispose(): Promise<void>;
     private disposeAfterActiveCalls;

package/dist/runtime/host.js

@@ -1,7 +1,8 @@
 import { spawn } from 'node:child_process';
-import { buildOperationArgv, normalizeCollaborationAuth, resolveInvocation, } from './transport-common.js';
+import { buildOperationArgv, buildStructuredReadInput, normalizeCollaborationAuth, resolveInvocation, } from './transport-common.js';
 import { SuperDocCliError } from './errors.js';
 import { registerMutationRevision } from './document-evidence.js';
+import { CONTRACT } from '../generated/contract.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'];
@@ -103,6 +104,7 @@ export class HostTransport {
     activeCalls = new Set();
     hostFeatures = new Set();
     documentRpcSessions = new Set();
+    cliLocalSessions = new Set();
     dirtyDocumentRpcSessions = new Set();
     documentRpcMutationStates = new Map();
     indeterminateDiscardCloses = new Set();
@@ -129,13 +131,28 @@ export class HostTransport {
         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'));
+        return (this.usesCliDocumentFacts(sessionId) ||
+            (this.documentRpcSessions.has(sessionId) &&
+                this.hostFeatures.has('document.currentRevision') &&
+                this.hostFeatures.has('document.executionFacts') &&
+                this.hostFeatures.has('document.mutationRevision')));
+    }
+    usesCliDocumentFacts(sessionId) {
+        return this.cliLocalSessions.has(sessionId) && this.hostFeatures.has('cli.invoke.localExecutionFacts');
     }
     async readDocumentRevision(sessionId) {
         return this.runWhileActive(async () => {
+            if (this.usesCliDocumentFacts(sessionId)) {
+                const revisionOperation = CONTRACT.operations['doc.blocks.list'];
+                const page = await this.invoke(revisionOperation, {
+                    sessionId,
+                    offset: Number.MAX_SAFE_INTEGER,
+                    limit: 1,
+                });
+                if (typeof page.revision !== 'string' || !page.revision || page.revision === 'unknown')
+                    throw new SuperDocCliError('CLI returned an invalid execution revision.', { code: 'HOST_PROTOCOL_ERROR' });
+                return page.revision;
+            }
             if (!this.documentRpcSessions.has(sessionId) || !this.hostFeatures.has('document.currentRevision')) {
                 return undefined;
             }
@@ -356,9 +373,23 @@ export class HostTransport {
         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);
+        const structuredInput = this.hostFeatures.has('cli.invoke.structuredReads')
+            ? buildStructuredReadInput(operation, params, options, argv)
+            : undefined;
+        const includeRevision = sessionId !== undefined &&
+            this.usesCliDocumentFacts(sessionId) &&
+            operation.mutates === true;
         const response = await this.sendJsonRpcRequest('cli.invoke', {
-            argv,
-            stdinBase64,
+            ...(structuredInput === undefined
+                ? { argv, stdinBase64 }
+                : {
+                    operationId: operation.operationId,
+                    input: structuredInput,
+                    ...((options.timeoutMs ?? this.requestTimeoutMs) === undefined
+                        ? {}
+                        : { timeoutMs: options.timeoutMs ?? this.requestTimeoutMs }),
+                }),
+            ...(includeRevision ? { includeRevision: true } : {}),
             ...(collaborationAuth === undefined ? {} : { collaborationAuth }),
         }, watchdogTimeout, {
             requestTimeoutMs: supportsRequestTimeoutMetadata ? options.timeoutMs : undefined,
@@ -370,7 +401,18 @@ export class HostTransport {
             });
         }
         const resultRecord = response;
-        return mapCliInvocationResult(operation, resultRecord.data);
+        const result = mapCliInvocationResult(operation, resultRecord.data);
+        if (operation.operationId === 'doc.open' && typeof result === 'object' && result !== null) {
+            const opened = result;
+            if (typeof opened.contextId === 'string' && opened.sessionType === 'local')
+                this.cliLocalSessions.add(opened.contextId);
+        }
+        if (operation.operationId === 'doc.close' && sessionId)
+            this.cliLocalSessions.delete(sessionId);
+        const revision = resultRecord.meta?.revision;
+        if (includeRevision && revision)
+            registerMutationRevision(result, revision);
+        return result;
     }
     runWhileActive(start) {
         if (this.terminalDisposalError) {

package/dist/runtime/process.cjs

@@ -60,6 +60,9 @@ class SuperDocRuntime {
     supportsDocumentFacts(sessionId) {
         return this.transport.supportsDocumentFacts(sessionId);
     }
+    usesCliDocumentFacts(sessionId) {
+        return this.transport.usesCliDocumentFacts(sessionId);
+    }
     async readDocumentRevision(sessionId) {
         return this.transport.readDocumentRevision(sessionId);
     }

package/dist/runtime/process.d.ts

@@ -33,6 +33,7 @@ export declare class SuperDocRuntime {
     constructor(options?: SuperDocClientOptions);
     connect(): Promise<void>;
     supportsDocumentFacts(sessionId: string): boolean;
+    usesCliDocumentFacts(sessionId: string): boolean;
     readDocumentRevision(sessionId: string): Promise<string | undefined>;
     dispose(): Promise<void>;
     invoke<TData = unknown>(operation: OperationSpec, params?: Record<string, unknown>, options?: TransportInvokeOptions): Promise<TData>;

package/dist/runtime/process.js

@@ -57,6 +57,9 @@ export class SuperDocRuntime {
     supportsDocumentFacts(sessionId) {
         return this.transport.supportsDocumentFacts(sessionId);
     }
+    usesCliDocumentFacts(sessionId) {
+        return this.transport.usesCliDocumentFacts(sessionId);
+    }
     async readDocumentRevision(sessionId) {
         return this.transport.readDocumentRevision(sessionId);
     }

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

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

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

@@ -1 +1 @@
-export declare const SDK_VERSION = "2.18.0-next.2";
+export declare const SDK_VERSION = "2.18.0-next.4";

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

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

package/dist/runtime/transport-common.cjs

@@ -1,7 +1,96 @@
 'use strict';
 
+var node_util = require('node:util');
 var errors = require('./errors.cjs');
 
+function buildStructuredReadInput(operation, params, options, encodedArgv) {
+    if (!['doc.info', 'doc.blocks.list', 'doc.query.match'].includes(operation.operationId))
+        return undefined;
+    if (node_util.types.isProxy(params))
+        return undefined;
+    const prototype = Object.getPrototypeOf(params);
+    if (prototype !== Object.prototype && prototype !== null)
+        return undefined;
+    for (const descriptor of Object.values(Object.getOwnPropertyDescriptors(params)))
+        if (descriptor.get || descriptor.set)
+            return undefined;
+    if (typeof params.sessionId !== 'string' ||
+        !params.sessionId ||
+        params.doc != null ||
+        options.stdinBytes !== undefined ||
+        options.collaborationAuth !== undefined)
+        return undefined;
+    if (!encodedArgv)
+        return undefined;
+    const flags = new Map(operation.params.filter((spec) => spec.kind !== 'doc').map((spec) => [`--${spec.flag ?? spec.name}`, spec]));
+    const encoded = new Map();
+    // Read the completed encoding; later serializers may have mutated earlier params.
+    for (let index = operation.commandTokens.length; index < encodedArgv.length; index += 2) {
+        const flag = encodedArgv[index];
+        const value = encodedArgv[index + 1];
+        if (typeof value !== 'string')
+            return undefined;
+        if (flag === '--output' || flag === '--timeout-ms')
+            continue;
+        const spec = flags.get(flag);
+        if (!spec || (spec.kind !== 'jsonFlag' && value.startsWith('-')))
+            return undefined;
+        const values = encoded.get(spec.name) ?? [];
+        values.push(value);
+        encoded.set(spec.name, values);
+    }
+    const input = {};
+    for (const spec of operation.params) {
+        const value = params[spec.name];
+        const values = encoded.get(spec.name);
+        if (!values) {
+            if (spec.required)
+                return undefined;
+            continue;
+        }
+        if (spec.type !== 'string[]' && values.length !== 1)
+            return undefined;
+        const token = values[0];
+        if (spec.kind === 'jsonFlag') {
+            // Reuse the existing encoding so custom serializers and getters run once.
+            if (value === null)
+                return undefined;
+            try {
+                input[spec.name] = JSON.parse(token);
+            }
+            catch {
+                return undefined;
+            }
+            continue;
+        }
+        // Coercions and unusual scalar tokens retain the existing argv validator.
+        if (spec.type === 'number') {
+            if (typeof value !== 'number' ||
+                !Number.isFinite(value) ||
+                value < 0 ||
+                !Number.isFinite(Number(token)) ||
+                Number(token) < 0)
+                return undefined;
+            input[spec.name] = Number(token);
+        }
+        else if (spec.type === 'boolean') {
+            if (typeof value !== 'boolean' || !['true', 'false'].includes(token))
+                return undefined;
+            input[spec.name] = token === 'true';
+        }
+        else if (spec.type === 'string[]') {
+            if (values.some((item) => !item || item.trim() !== item))
+                return undefined;
+            input[spec.name] = values;
+        }
+        else {
+            if (typeof value !== 'string' || !token || token.trim() !== token)
+                return undefined;
+            input[spec.name] = token;
+        }
+    }
+    return input;
+}
 function normalizeCollaborationAuth(value) {
     if (typeof value !== 'object' || value === null || Array.isArray(value)) {
         throw new errors.SuperDocCliError('collaborationAuth must be an object.', { code: 'INVALID_ARGUMENT' });
@@ -192,5 +281,6 @@ function buildOperationArgv(operation, params, options, runtimeTimeoutMs, defaul
 
 exports.applyOperationParamAliases = applyOperationParamAliases;
 exports.buildOperationArgv = buildOperationArgv;
+exports.buildStructuredReadInput = buildStructuredReadInput;
 exports.normalizeCollaborationAuth = normalizeCollaborationAuth;
 exports.resolveInvocation = resolveInvocation;

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

@@ -12,6 +12,7 @@ export interface OperationSpec {
     readonly commandTokens: readonly string[];
     readonly params: readonly OperationParamSpec[];
 }
+export declare function buildStructuredReadInput(operation: OperationSpec, params: Record<string, unknown>, options: TransportInvokeOptions, encodedArgv?: readonly string[]): Record<string, unknown> | undefined;
 export interface InvokeOptions {
     timeoutMs?: number;
     stdinBytes?: Uint8Array;

package/dist/runtime/transport-common.js

@@ -1,4 +1,93 @@
+import { types as utilTypes } from 'node:util';
 import { SuperDocCliError } from './errors.js';
+export function buildStructuredReadInput(operation, params, options, encodedArgv) {
+    if (!['doc.info', 'doc.blocks.list', 'doc.query.match'].includes(operation.operationId))
+        return undefined;
+    if (utilTypes.isProxy(params))
+        return undefined;
+    const prototype = Object.getPrototypeOf(params);
+    if (prototype !== Object.prototype && prototype !== null)
+        return undefined;
+    for (const descriptor of Object.values(Object.getOwnPropertyDescriptors(params)))
+        if (descriptor.get || descriptor.set)
+            return undefined;
+    if (typeof params.sessionId !== 'string' ||
+        !params.sessionId ||
+        params.doc != null ||
+        options.stdinBytes !== undefined ||
+        options.collaborationAuth !== undefined)
+        return undefined;
+    if (!encodedArgv)
+        return undefined;
+    const flags = new Map(operation.params.filter((spec) => spec.kind !== 'doc').map((spec) => [`--${spec.flag ?? spec.name}`, spec]));
+    const encoded = new Map();
+    // Read the completed encoding; later serializers may have mutated earlier params.
+    for (let index = operation.commandTokens.length; index < encodedArgv.length; index += 2) {
+        const flag = encodedArgv[index];
+        const value = encodedArgv[index + 1];
+        if (typeof value !== 'string')
+            return undefined;
+        if (flag === '--output' || flag === '--timeout-ms')
+            continue;
+        const spec = flags.get(flag);
+        if (!spec || (spec.kind !== 'jsonFlag' && value.startsWith('-')))
+            return undefined;
+        const values = encoded.get(spec.name) ?? [];
+        values.push(value);
+        encoded.set(spec.name, values);
+    }
+    const input = {};
+    for (const spec of operation.params) {
+        const value = params[spec.name];
+        const values = encoded.get(spec.name);
+        if (!values) {
+            if (spec.required)
+                return undefined;
+            continue;
+        }
+        if (spec.type !== 'string[]' && values.length !== 1)
+            return undefined;
+        const token = values[0];
+        if (spec.kind === 'jsonFlag') {
+            // Reuse the existing encoding so custom serializers and getters run once.
+            if (value === null)
+                return undefined;
+            try {
+                input[spec.name] = JSON.parse(token);
+            }
+            catch {
+                return undefined;
+            }
+            continue;
+        }
+        // Coercions and unusual scalar tokens retain the existing argv validator.
+        if (spec.type === 'number') {
+            if (typeof value !== 'number' ||
+                !Number.isFinite(value) ||
+                value < 0 ||
+                !Number.isFinite(Number(token)) ||
+                Number(token) < 0)
+                return undefined;
+            input[spec.name] = Number(token);
+        }
+        else if (spec.type === 'boolean') {
+            if (typeof value !== 'boolean' || !['true', 'false'].includes(token))
+                return undefined;
+            input[spec.name] = token === 'true';
+        }
+        else if (spec.type === 'string[]') {
+            if (values.some((item) => !item || item.trim() !== item))
+                return undefined;
+            input[spec.name] = values;
+        }
+        else {
+            if (typeof value !== 'string' || !token || token.trim() !== token)
+                return undefined;
+            input[spec.name] = token;
+        }
+    }
+    return input;
+}
 export function normalizeCollaborationAuth(value) {
     if (typeof value !== 'object' || value === null || Array.isArray(value)) {
         throw new SuperDocCliError('collaborationAuth must be an object.', { code: 'INVALID_ARGUMENT' });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@superdoc/sdk",
-  "version": "2.18.0-next.2",
+  "version": "2.18.0-next.4",
   "description": "Node SDK for SuperDoc, wrapping the SuperDoc CLI to read and edit .docx files from JavaScript and TypeScript.",
   "private": false,
   "license": "AGPL-3.0",
@@ -38,11 +38,11 @@
     "typescript": "^5.9.2"
   },
   "optionalDependencies": {
-    "@superdoc/sdk-darwin-arm64": "2.18.0-next.2",
-    "@superdoc/sdk-darwin-x64": "2.18.0-next.2",
-    "@superdoc/sdk-linux-x64": "2.18.0-next.2",
-    "@superdoc/sdk-linux-arm64": "2.18.0-next.2",
-    "@superdoc/sdk-windows-x64": "2.18.0-next.2"
+    "@superdoc/sdk-darwin-arm64": "2.18.0-next.4",
+    "@superdoc/sdk-darwin-x64": "2.18.0-next.4",
+    "@superdoc/sdk-linux-x64": "2.18.0-next.4",
+    "@superdoc/sdk-linux-arm64": "2.18.0-next.4",
+    "@superdoc/sdk-windows-x64": "2.18.0-next.4"
   },
   "publishConfig": {
     "access": "public"
@@ -53,7 +53,7 @@
     "typecheck": "tsc --noEmit",
     "typecheck:consumer": "tsc --noEmit --strict --skipLibCheck --target ES2022 --module NodeNext --moduleResolution NodeNext ../../../../tests/consumer-typecheck/src/sdk-per-open-collaboration-auth.mts ../../../../tests/consumer-typecheck/src/sdk-replace-file.mts ../../../../tests/consumer-typecheck/src/sdk-agent-evidence.mts ../../../../tests/consumer-typecheck/src/sdk-custom-actions.mts ../../../../tests/consumer-typecheck/src/sd4807-sdk-inspect.mts ../../../../tests/consumer-typecheck/src/sdk-tracked-only-policy.mts ../../../../tests/consumer-typecheck/src/sdk-tracked-review-route.mts ../../../../tests/consumer-typecheck/src/sd5266-sdk-placeholder-null.mts",
     "test:agent-actions": "bun test src/__tests__/actions.test.ts src/__tests__/agent-runtime.test.ts src/__tests__/custom-actions.test.ts src/__tests__/textbox-snapshot.test.ts",
-    "test:document-host": "bun test src/runtime/__tests__/host-spawn-args.test.ts src/runtime/__tests__/document-rpc.test.ts src/__tests__/tracked-review-route.test.ts src/__tests__/structured-document-rpc.e2e.test.ts src/__tests__/request-timeout-ms.e2e.test.ts src/__tests__/agent-evidence.e2e.test.ts src/__tests__/agent-apply.e2e.test.ts src/__tests__/find-text.e2e.test.ts src/__tests__/custom-actions.e2e.test.ts",
+    "test:document-host": "bun test src/__tests__/default-cli-optimization.e2e.test.ts src/runtime/__tests__/host-spawn-args.test.ts src/runtime/__tests__/document-rpc.test.ts src/__tests__/tracked-review-route.test.ts src/__tests__/structured-document-rpc.e2e.test.ts src/__tests__/request-timeout-ms.e2e.test.ts src/__tests__/agent-evidence.e2e.test.ts src/__tests__/agent-apply.e2e.test.ts src/__tests__/find-text.e2e.test.ts src/__tests__/custom-actions.e2e.test.ts",
     "smoke:product-action": "node scripts/product-action-smoke.mjs"
   }
 }