@actiondock/core 2.10.0 → 2.11.0

package/dist/ipc/host.js

@@ -16,8 +16,9 @@ const IPC_METHOD_HANDLERS = {
     describePlaybook: async (service, a) => service.discovery.describePlaybook(a[0]),
     runAction: async (service, a) => service.execution.run(a[0], a[1], a[2]),
     startAction: async (service, a) => service.execution.start(a[0], a[1], a[2]),
-    listRuns: async (service, a) => service.runs.list(a[0]),
-    getRun: async (service, a) => service.runs.get(a[0]),
+    listRuns: async (service, a) => service.runs.list(a[0], a[1]),
+    countRuns: async (service, a) => typeof service.runs.count === "function" ? service.runs.count(a[0], a[1]) : undefined,
+    getRun: async (service, a) => service.runs.get(a[0], a[1]),
     cancelRun: async (service, a) => service.runs.cancel(a[0], a[1]),
     clearRuns: async (service, a) => service.runs.clear ? await service.runs.clear(a[0]) : 0,
     cleanExpiredRuns: async (service, a) => service.runs.cleanExpired ? await service.runs.cleanExpired(a[0]) : 0,
@@ -75,8 +76,11 @@ export async function serveParentIpc(service) {
             return arg;
         }
         const { [IPC_SIGNAL_MARKER]: _marker, ...rest } = arg;
-        const controller = new AbortController();
-        activeControllers.set(id, controller);
+        let controller = activeControllers.get(id);
+        if (!controller) {
+            controller = new AbortController();
+            activeControllers.set(id, controller);
+        }
         return { ...rest, signal: controller.signal };
     };
     // 监听父进程断连或退出信号
@@ -119,15 +123,23 @@ export async function serveParentIpc(service) {
                 }
             }
             catch (err) {
+                const isAbort = err?.name === "AbortError" ||
+                    err?.code === "ABORT_ERR" ||
+                    err?.code === "EXECUTION_ABORTED" ||
+                    err?.code === "OPERATION_ABORTED";
                 const response = {
                     id,
                     type: "response",
                     ok: false,
                     error: {
-                        code: err?.code || SERVICE_ERROR,
+                        code: err?.code || (isAbort ? "OPERATION_ABORTED" : SERVICE_ERROR),
                         message: err?.message || String(err),
                         stack: err?.stack,
-                        details: err?.details,
+                        details: err?.details !== undefined
+                            ? (typeof err?.details === "object" && err?.details !== null && err?.name === "AbortError"
+                                ? { name: err?.name, ...err.details }
+                                : err.details)
+                            : (err?.name === "AbortError" ? { name: err?.name } : undefined),
                     },
                 };
                 if (process.send) {
@@ -144,7 +156,9 @@ export async function serveParentIpc(service) {
             const abortMsg = msg;
             const controller = activeControllers.get(abortMsg.id);
             if (controller) {
-                controller.abort(new Error(abortMsg.reason || "Execution was aborted via IPC"));
+                const abortError = new Error(abortMsg.reason || "Execution was aborted via IPC");
+                abortError.name = "AbortError";
+                controller.abort(abortError);
             }
         }
         else if (msg.type === "close") {

package/dist/ipc/service.d.ts

@@ -2,6 +2,10 @@ import { type ChildProcess } from "node:child_process";
 import type { PackageInfo } from "../package/types.js";
 import type { ActionDockService, ConfigPort, DiscoveryPort, ExecutionPort, RunsPort, StatePort } from "../service/types.js";
 import type { IpcServiceOptions } from "./types.js";
+/**
+ * 创建标准 AbortError 异常对象。
+ */
+export declare function createAbortError(reason?: unknown): Error;
 /**
  * 跨进程取消信号占位标记字段名。
  * AbortSignal 不可序列化，序列化 options 时把 signal 字段替换为该标记，
@@ -12,6 +16,16 @@ export declare const IPC_SIGNAL_MARKER = "__ipcSignal";
  * 判断执行选项中是否携带跨进程取消信号占位标记。
  */
 export declare function hasIpcSignalMarker(value: unknown): value is Record<string, unknown>;
+/**
+ * 序列化执行选项与查询选项的边界收敛函数。
+ *
+ * 序列化边界决策：
+ * - 剥离不可序列化对象：AbortSignal 无法通过 Node IPC 通道传递，在此转换为 IPC_SIGNAL_MARKER 占位标记，由远端宿主根据标记重建 AbortController 接入取消链路。
+ * - 过滤非安全值：全面剔除函数、undefined、Symbol 与 BigInt 等无法安全跨进程传递的值，防止 IPC 序列化异常或意外的远端反射。
+ * - 循环引用防御：递归遍历嵌套对象（如 config 配置项或 filter 筛选条件）时基于调用栈祖先集合进行环检测，阻断循环引用进入 IPC 通道，且不误伤跨字段复用的合法对象。
+ * - 支持跨进程选项透传：安全保留 RunOptions 与 RunReadOptions、ListRunsOptions 中的合法字段（包含 timeoutMs、config、requestId、limit、offset、packageId、action、status、since、until、requestIds、filter 等）。
+ */
+export declare function markIpcSignal<T extends Record<string, any>>(options?: T): Record<string, unknown> | undefined;
 /**
  * 基于 Node IPC 监督进程通信通道的 ActionDockService 实现。
  * 遵循标准 Service Ports 体系，隔离子进程生命周期并暴露结构化服务端口。

package/dist/ipc/service.js

@@ -1,7 +1,20 @@
 import { randomUUID } from "node:crypto";
 import { fork } from "node:child_process";
 import { DiagnosticForwarder } from "./diagnostic.js";
-import { ActionDockError, CAPABILITY_UNAVAILABLE, EXECUTION_ABORTED, HOST_PROCESS_EXITED, IPC_ERROR, SERVICE_CLOSED, } from "../errors.js";
+import { ActionDockError, CAPABILITY_UNAVAILABLE, EXECUTION_ABORTED, HOST_PROCESS_EXITED, INVALID_ARGUMENT, IPC_ERROR, SERVICE_CLOSED, } from "../errors.js";
+/**
+ * 创建标准 AbortError 异常对象。
+ */
+export function createAbortError(reason) {
+    const message = reason instanceof Error
+        ? (reason.message || "The operation was aborted")
+        : reason !== undefined
+            ? String(reason)
+            : "The operation was aborted";
+    const err = new Error(message, reason !== undefined ? { cause: reason } : undefined);
+    err.name = "AbortError";
+    return err;
+}
 /**
  * 跨进程取消信号占位标记字段名。
  * AbortSignal 不可序列化，序列化 options 时把 signal 字段替换为该标记，
@@ -17,22 +30,79 @@ export function hasIpcSignalMarker(value) {
         value[IPC_SIGNAL_MARKER] === true);
 }
 /**
- * 序列化执行选项：剥离不可序列化的 AbortSignal 并写入占位标记。
+ * 安全收敛可跨进程传递的数据值，过滤函数、undefined、Symbol、BigInt 并防御循环引用。
+ */
+function sanitizeIpcValue(value, ancestors) {
+    if (value === null || typeof value === "string" || typeof value === "number" || typeof value === "boolean") {
+        return value;
+    }
+    if (typeof value === "undefined" || typeof value === "function" || typeof value === "symbol" || typeof value === "bigint") {
+        return undefined;
+    }
+    if (typeof value === "object") {
+        if (ancestors.has(value)) {
+            return undefined;
+        }
+        ancestors.add(value);
+        try {
+            if (Array.isArray(value)) {
+                const result = [];
+                for (const item of value) {
+                    const sanitized = sanitizeIpcValue(item, ancestors);
+                    if (sanitized !== undefined) {
+                        result.push(sanitized);
+                    }
+                }
+                return result;
+            }
+            const result = {};
+            for (const [key, val] of Object.entries(value)) {
+                const sanitized = sanitizeIpcValue(val, ancestors);
+                if (sanitized !== undefined) {
+                    result[key] = sanitized;
+                }
+            }
+            return result;
+        }
+        finally {
+            ancestors.delete(value);
+        }
+    }
+    return undefined;
+}
+/**
+ * 序列化执行选项与查询选项的边界收敛函数。
+ *
+ * 序列化边界决策：
+ * - 剥离不可序列化对象：AbortSignal 无法通过 Node IPC 通道传递，在此转换为 IPC_SIGNAL_MARKER 占位标记，由远端宿主根据标记重建 AbortController 接入取消链路。
+ * - 过滤非安全值：全面剔除函数、undefined、Symbol 与 BigInt 等无法安全跨进程传递的值，防止 IPC 序列化异常或意外的远端反射。
+ * - 循环引用防御：递归遍历嵌套对象（如 config 配置项或 filter 筛选条件）时基于调用栈祖先集合进行环检测，阻断循环引用进入 IPC 通道，且不误伤跨字段复用的合法对象。
+ * - 支持跨进程选项透传：安全保留 RunOptions 与 RunReadOptions、ListRunsOptions 中的合法字段（包含 timeoutMs、config、requestId、limit、offset、packageId、action、status、since、until、requestIds、filter 等）。
  */
-function markIpcSignal(options) {
-    if (!options)
+export function markIpcSignal(options) {
+    if (!options || typeof options !== "object")
         return undefined;
-    const clean = {};
-    if (options.timeoutMs !== undefined)
-        clean.timeoutMs = options.timeoutMs;
-    if (options.config !== undefined)
-        clean.config = options.config;
-    if (options.requestId !== undefined)
-        clean.requestId = options.requestId;
-    if (options.signal) {
-        clean[IPC_SIGNAL_MARKER] = true;
+    const ancestors = new Set();
+    ancestors.add(options);
+    try {
+        const clean = {};
+        for (const [key, value] of Object.entries(options)) {
+            if (key === "signal") {
+                if (value) {
+                    clean[IPC_SIGNAL_MARKER] = true;
+                }
+                continue;
+            }
+            const sanitized = sanitizeIpcValue(value, ancestors);
+            if (sanitized !== undefined) {
+                clean[key] = sanitized;
+            }
+        }
+        return clean;
+    }
+    finally {
+        ancestors.delete(options);
     }
-    return clean;
 }
 /**
  * 基于 Node IPC 监督进程通信通道的 ActionDockService 实现。
@@ -51,8 +121,6 @@ export class IpcActionDockService {
     management;
     constructor(options) {
         this.forwarder = new DiagnosticForwarder({
-            maxBytes: options.maxDiagnosticBytes,
-            maxRateBytesPerSec: options.maxDiagnosticRate,
             target: options.diagnosticTarget,
         });
         if (options.childProcess) {
@@ -66,7 +134,7 @@ export class IpcActionDockService {
             });
         }
         else {
-            throw new Error("IpcActionDockService requires either 'childProcess' or 'scriptPath'");
+            throw new ActionDockError(INVALID_ARGUMENT, "IpcActionDockService requires either 'childProcess' or 'scriptPath'");
         }
         if (this.child.stdout) {
             this.forwarder.attach(this.child.stdout, "stdout");
@@ -93,7 +161,13 @@ export class IpcActionDockService {
                         pending.resolve(resp.data);
                     }
                     else {
-                        const err = new ActionDockError(resp.error?.code || IPC_ERROR, resp.error?.message || "IPC Service call failed", resp.error?.details);
+                        const isAbort = resp.error?.code === "EXECUTION_ABORTED" ||
+                            resp.error?.code === "OPERATION_ABORTED" ||
+                            resp.error?.code === "ABORT_ERR" ||
+                            resp.error?.details?.name === "AbortError";
+                        const err = isAbort
+                            ? createAbortError(resp.error?.message)
+                            : new ActionDockError(resp.error?.code || IPC_ERROR, resp.error?.message || "IPC Service call failed", resp.error?.details);
                         pending.reject(err);
                     }
                 }
@@ -129,7 +203,7 @@ export class IpcActionDockService {
          * 生成方法级端口转发器：把端口方法调用映射为 callRemote 远端调用。
          * 方法名与参数列表的对应关系即唯一事实源，杜绝手写转发样板膨胀。
          */
-        const forward = (method, args) => self.callRemote(method, args);
+        const forward = (method, args, signal) => self.callRemote(method, args, signal);
         this.discovery = {
             async listPackages() {
                 return forward("listPackages", []);
@@ -171,11 +245,38 @@ export class IpcActionDockService {
             },
         };
         this.runs = {
-            async list(query) {
-                return forward("listRuns", [query]);
+            async list(query, options) {
+                const signal = options?.signal ?? query?.signal;
+                if (signal?.aborted) {
+                    throw createAbortError(signal.reason);
+                }
+                const serializableQuery = markIpcSignal(query);
+                const serializableOptions = markIpcSignal(options);
+                const args = serializableOptions !== undefined
+                    ? [serializableQuery ?? {}, serializableOptions]
+                    : [serializableQuery];
+                return forward("listRuns", args, signal);
+            },
+            async count(query, options) {
+                const signal = options?.signal ?? query?.signal;
+                if (signal?.aborted) {
+                    throw createAbortError(signal.reason);
+                }
+                const serializableQuery = markIpcSignal(query);
+                const serializableOptions = markIpcSignal(options);
+                const args = serializableOptions !== undefined
+                    ? [serializableQuery ?? {}, serializableOptions]
+                    : [serializableQuery];
+                return forward("countRuns", args, signal);
             },
-            async get(runId) {
-                const res = await forward("getRun", [runId]);
+            async get(runId, options) {
+                const signal = options?.signal ?? options?.query?.signal;
+                if (signal?.aborted) {
+                    throw createAbortError(signal.reason);
+                }
+                const serializableOptions = markIpcSignal(options);
+                const args = serializableOptions !== undefined ? [runId, serializableOptions] : [runId];
+                const res = await forward("getRun", args, signal);
                 return res ?? undefined;
             },
             async cancel(runId, reason) {
@@ -243,9 +344,7 @@ export class IpcActionDockService {
         }
         await this.readyPromise;
         if (signal?.aborted) {
-            const err = new Error(signal.reason ? String(signal.reason) : "Operation aborted");
-            err.name = "AbortError";
-            throw err;
+            throw createAbortError(signal.reason);
         }
         const id = randomUUID();
         const message = {
@@ -258,6 +357,13 @@ export class IpcActionDockService {
         if (signal && !signal.aborted) {
             onAbort = () => {
                 this.sendAbort(id);
+                if (method !== "runAction") {
+                    const pending = this.pendingCalls.get(id);
+                    if (pending) {
+                        this.pendingCalls.delete(id);
+                        pending.reject(createAbortError(signal.reason));
+                    }
+                }
             };
             signal.addEventListener("abort", onAbort, { once: true });
         }

package/dist/ipc/types.d.ts

@@ -46,10 +46,6 @@ export interface IpcServiceOptions {
     cwd?: string;
     /** 环境变量 */
     env?: NodeJS.ProcessEnv;
-    /** 诊断流最大缓冲字节数 */
-    maxDiagnosticBytes?: number;
-    /** 诊断流每秒最大字节速率 */
-    maxDiagnosticRate?: number;
     /** 诊断流目标输出 */
     diagnosticTarget?: any;
     /** 是否启用管理端口（默认 true） */

package/dist/package/index.d.ts

@@ -10,13 +10,12 @@ export { createPackageRuntime, DefaultPackageRuntime, } from "./runtime.js";
 export { createNonClosingStorageView } from "./storage-view.js";
 export { findExecutable } from "../utils/index.js";
 export type { PackageRuntime, PackageRuntimeOptions, PackageInfo, ActionSpec, ActionSummary, PlaybookSpec, PlaybookSummary, } from "./types.js";
-export type { RuntimePlatform, FileSystem, StorageFactory, StorageFactoryOptions, GlobalStorageFactoryOptions, } from "../platform/types.js";
-export { type Clock, SystemClock, } from "../runtime/clock.js";
-export type { ModuleLoader } from "../node/module-loader.js";
+export type { RuntimePlatform, StorageFactory, StorageFactoryOptions, GlobalStorageFactoryOptions, } from "../platform/types.js";
+export { type Clock, SystemClock, } from "../storage/clock.js";
+export type { ModuleLoader } from "../platform/module-loader.js";
 export { InMemoryEventSink, type EventSink, } from "../runtime/events.js";
 export { ProcessManager, type ProcessOwner, } from "../process/process-manager.js";
-export type { ProcessExecutor } from "../runtime/process.js";
-export { NodeProcessExecutor } from "../process/process-executor.js";
+export type { ProcessAPI as ProcessExecutor } from "@actiondock/sdk";
 export type { ProcessDriver, ProcessDriverCallbacks, ProcessDriverHandle, ProcessHandle, ProcessObserver, } from "../process/driver.js";
 export { createStorage, resolveDatabasePath, } from "../storage/index.js";
 export { SqliteRuntimeStorage } from "../storage/sqlite.js";

package/dist/package/index.js

@@ -9,10 +9,9 @@
 export { createPackageRuntime, DefaultPackageRuntime, } from "./runtime.js";
 export { createNonClosingStorageView } from "./storage-view.js";
 export { findExecutable } from "../utils/index.js";
-export { SystemClock, } from "../runtime/clock.js";
+export { SystemClock, } from "../storage/clock.js";
 export { InMemoryEventSink, } from "../runtime/events.js";
 export { ProcessManager, } from "../process/process-manager.js";
-export { NodeProcessExecutor } from "../process/process-executor.js";
 // 存储契约与驱动
 export { createStorage, resolveDatabasePath, } from "../storage/index.js";
 export { SqliteRuntimeStorage } from "../storage/sqlite.js";

package/dist/package/runtime.d.ts

@@ -7,6 +7,13 @@ import type { ActionSpec, ActionSummary, ConfigValueView, HostManagedPackageRunt
 /**
  * ActionDock 统一包运行时默认实现。
  * 封装并管理单个 Action Package 的执行引擎、静态元数据索引、配置与状态存储生命周期。
+ *
+ * 资源按需装配契约：
+ * - 构造函数只完成身份、清单与内存注入动作的归一化，不打开数据库、
+ *   不创建进程接口、不注册模块加载钩子、不实例化执行服务；
+ * - 包存储、执行服务、全局存储与配置解析器拆分为内部资源槽位，
+ *   首次实际调用时准备并缓存复用；
+ * - info / list / describe / 规程发现等静态查询全程零资源创建。
  */
 export declare class DefaultPackageRuntime implements HostManagedPackageRuntime {
     readonly identity: PackageIdentity;
@@ -15,15 +22,20 @@ export declare class DefaultPackageRuntime implements HostManagedPackageRuntime
     readonly generationId: string;
     readonly packageRoot?: string;
     readonly projectConfig: ProjectConfig;
+    readonly inMemory: boolean;
     private readonly platform;
-    private readonly storage;
-    private readonly globalStorage?;
-    private readonly executionService;
     private readonly actionsMap;
     private readonly options;
-    private runtimeConfig;
     private isClosed;
-    private injectedGlobalStorage;
+    private storageSlot;
+    private executionSlot;
+    /** 全局存储：显式注入或首次准备后固定，配合 ownership 判定关闭归属 */
+    private globalStorageRes?;
+    private runtimeConfig?;
+    /** 执行委托暂存：执行服务尚未创建时只保存，不触发资源初始化 */
+    private pendingInvoker?;
+    /** Host 会话级恢复标记：存储准备阶段收敛执行一次，避免重复执行恢复链 */
+    private recoveredForHostSession;
     /** 静态清单索引缓存：包静态事实（根目录、配置、内存注入集合）在实例生命周期内不变，解析结果同实例内复用 */
     private staticActionIndex?;
     private staticPlaybookIndex?;
@@ -39,6 +51,58 @@ export declare class DefaultPackageRuntime implements HostManagedPackageRuntime
      * 聚合逻辑委托 static-index 单一事实源；同实例内复用首次解析结果。
      */
     private getStaticPlaybookMap;
+    private assertOpen;
+    /**
+     * 准备包存储：打开（或复用注入的）包数据库，等待可选的 ensureInitialized，
+     * 并在持有者模式下完成运行记录恢复（允许返回 Promise 的恢复接口必须被等待）。
+     * 并发首次调用共享同一在途 Promise；失败时释放新建资源、清空失败 Promise、透传原始错误。
+     */
+    private ensureStorage;
+    private openStorageAsync;
+    /** 构造包存储工厂选项（单一事实源，异步与同步打开路径共用） */
+    private buildStorageOptions;
+    /**
+     * Host 会话级运行记录恢复：同实例生命周期内最多执行一次。
+     * 允许返回 Promise 的恢复接口被等待：恢复完成（或失败透传）前存储不发布；
+     * 恢复失败沿用既有可观测处理（告警透传），不因异步化静默丢失。
+     */
+    private recoverForHostSessionOnce;
+    /**
+     * 准备全局存储：显式注入优先，其次 Host 共享提供函数，最后独立使用平台存储工厂。
+     * 同步契约：RuntimeConfig 与 ctx.config.get() 的读取是同步的，故全局库必须同步可得。
+     */
+    private ensureGlobalStorageSync;
+    /**
+     * 异步准备全局存储：供执行服务装配前调用，保证可选的异步初始化完成。
+     * 同步路径（RuntimeConfig 读取）仍走 ensureGlobalStorageSync 复用同一实例。
+     */
+    private ensureGlobalStorage;
+    /**
+     * 准备配置解析器：依赖包存储与全局存储（五层优先级链既有实现不变）。
+     * 同步契约：RuntimeConfig 与 ctx.config.get() 的读取是同步的，故同步打开包库；
+     * 若异步准备已在途，同步路径仅在实例已发布后复用，避免双打开竞态。
+     */
+    private ensureRuntimeConfig;
+    /**
+     * 获取已就绪的包存储（同步契约专用）：
+     * - 已发布实例直接复用；
+     * - 异步准备在途时等待其结算后复用同一实例；
+     * - 未准备时同步打开并登记在途 Promise 已完成状态。
+     * 单一事实源：同步打开也走 buildStorageOptions，并补齐会话恢复等待语义的同步近似。
+     */
+    private getStorageAlreadyPrepared;
+    /** 同步打开包存储（仅当异步准备从未发起时使用） */
+    private openStorageSync;
+    /**
+     * 准备执行服务：等待存储与全局存储就绪后创建唯一 DefaultExecutionService。
+     * 失败时只回收执行初始化独自新建的资源，不关闭仍被状态查询使用的包存储。
+     */
+    private ensureExecutionService;
+    private buildExecutionService;
+    /** 异步等待存储准备完成（供执行准备与异步入口复用；单一赋值入口） */
+    private prepareStorageAsync;
+    /** 获取已创建的执行服务（若存在），不触发创建 */
+    private peekExecutionService;
     info(options?: {
         exposeDebugInfo?: boolean;
     }): Promise<PackageInfo>;
@@ -50,6 +114,8 @@ export declare class DefaultPackageRuntime implements HostManagedPackageRuntime
     runAction(id: string, input: JsonValue, options?: RunOptions): Promise<ExecutionResult>;
     startAction(id: string, input: JsonValue, options?: RunOptions): Promise<ExecutionTicket>;
     startInvocation(actionId: string, input: JsonValue, context: InvocationContext): Promise<ExecutionTicket>;
+    /** 执行前统一准备：关闭检查与执行服务就绪 */
+    private prepareExecution;
     getRun(runId: string): Promise<RunRecord | undefined>;
     cancelRun(runId: string, reason?: string): Promise<CancelResult>;
     events(runId: string, options?: {
@@ -58,42 +124,47 @@ export declare class DefaultPackageRuntime implements HostManagedPackageRuntime
         maxQueueSize?: number;
     }): AsyncIterable<ExecutionEvent>;
     setActionInvoker(invoker?: ActionInvoker): void;
+    /**
+     * Host 持有者路径预热入口：完成包存储准备（含运行记录恢复），不创建执行服务。
+     * 延迟装配下旁观路径零资源创建，持有者工厂在返回前调用本方法保持既有初始化时机。
+     */
+    prepareResources(): Promise<void>;
+    /**
+     * 显式触发运行记录恢复（Host 持有者路径兼容入口）。
+     * 延迟装配下恢复已收敛到存储准备路径，本方法确保存储已就绪后按需补一次会话恢复。
+     */
     recoverDeadSessionRuns(sessionId?: string): void;
     listConfig(): Promise<ConfigValueView[]>;
     getConfig(key: string): Promise<ConfigValueView>;
     setConfig(key: string, value: JsonValue): Promise<void>;
     deleteConfig(key: string): Promise<boolean>;
     /**
-     * 状态作用域统一解析辅助函数（单一事实源）。
-     *
-     * 完成重载消歧后委托 mergeStateScope 计算最终生效的命名空间：
-     * - (actionId, key, options) 形态：位置 actionId 参与冲突校验；
-     * - (key, options) 扁平形态：首参是状态键，options.actionId 属合法显式指定。
-     */
-    private resolveStateScope;
-    /**
-     * 合并位置 actionId 与 options.actionId 并计算最终命名空间（单一事实源）。
-     *
-     * - positionalActionId 非 undefined：调用形态携带位置 actionId，
-     *   options.actionId 与其冲突时抛出异常（空串同样参与冲突校验）；
-     * - positionalActionId 为 undefined：无位置 actionId 的扁平调用形态，
-     *   options.actionId 属合法显式指定，直接采纳。
+     * 将可能携带命名空间前缀的状态键解码为 (namespace, key)。
+     * 解码失败时按无命名空间处理。
      */
-    private mergeStateScope;
+    private decodeStateKeyParts;
+    private hasExplicitStateScope;
+    private computeStateNamespace;
+    private getStateInternal;
+    private setStateInternal;
+    private deleteStateInternal;
+    private listStateKeysInternal;
+    private clearStateInternal;
     getState<T extends JsonValue = JsonValue>(key: string, options?: StateScopeOptions): Promise<T | undefined>;
     getState<T extends JsonValue = JsonValue>(actionId: string, key: string, options?: StateScopeOptions): Promise<T | undefined>;
     setState<T extends JsonValue = JsonValue>(key: string, value: T, options?: StateScopeOptions): Promise<void>;
-    setState<T extends JsonValue = JsonValue>(actionId: string, key: string, value: T, options: StateScopeOptions): Promise<void>;
+    setState<T extends JsonValue = JsonValue>(actionId: string, key: string, value: T, options?: StateScopeOptions): Promise<void>;
     deleteState(key: string, options?: StateScopeOptions): Promise<boolean>;
     deleteState(actionId: string, key: string, options?: StateScopeOptions): Promise<boolean>;
     getActionState<T extends JsonValue = JsonValue>(actionId: string, key: string, options?: StateScopeOptions): Promise<T | undefined>;
     setActionState<T extends JsonValue = JsonValue>(actionId: string, key: string, value: T, options?: StateScopeOptions): Promise<void>;
     deleteActionState(actionId: string, key: string, options?: StateScopeOptions): Promise<boolean>;
     listStateKeys(options?: StateScopeOptions): Promise<string[]>;
-    listStateKeys(actionId: string, options?: StateScopeOptions): Promise<string[]>;
+    listStateKeys(actionId?: string, options?: StateScopeOptions): Promise<string[]>;
     clearState(options?: StateScopeOptions): Promise<number>;
-    clearState(actionId: string, options?: StateScopeOptions): Promise<number>;
+    clearState(actionId?: string, options?: StateScopeOptions): Promise<number>;
     listRuns(options?: ListRunsOptions): Promise<RunRecord[]>;
+    countRuns(options?: ListRunsOptions): Promise<number>;
     clearRuns(options?: {
         actionId?: string;
         status?: string;