@actiondock/core 2.20.0 → 2.21.0

package/dist/index.d.ts

@@ -17,12 +17,19 @@ export type { ResolvedEnv } from "./runtime/env.js";
 export type { ActionInvokeOptions, ActionRef, ResolvedActionRef, ExecutionResult, RunRecord, RunOrigin, ExecutionEvent, } from "@actiondock/sdk";
 export type { RunOptions, ExecutionTicket, CancelResult, } from "./execution/types.js";
 export type { ActionBindings, ActionBindingTarget } from "./invocation/bindings.js";
+export type { LocalPackagePreparationTarget, LocalPackagePreparationContext, LocalPackagePreparer, } from "./invocation/types.js";
 export type { ActionSpec, ActionSummary, PlaybookSpec, PlaybookSummary, PackageInfo, ListActionsOptions, } from "./package/types.js";
 export { createNodePlatform, } from "./platform/node.js";
 export { startActionDockServer, } from "./server/server.js";
 export type { ServerOptions, ServerOptions as ActionDockServerOptions, ActionDockServerInstance, } from "./server/types.js";
 export { initProject } from "./project/init.js";
 export { loadProjectConfig, findProjectRoot, } from "./project/loader.js";
+export { ensureProjectDependencies, } from "./project/dependencies.js";
+export type { EnsureProjectDependenciesOptions, EnsureProjectDependenciesResult, } from "./project/dependencies.js";
 export type { ProjectConfig, } from "./project/types.js";
 export type { PackageGraph, } from "./catalog/graph.js";
-export { ActionDockError, ProcessError, PACKAGE_NOT_FOUND, ACTION_PACKAGE_VERSION_CONFLICT, ACTION_NOT_FOUND, ACTION_LOAD_FAILED, ACTION_FAILED, ACTION_TIMEOUT, ACTION_CANCELLED, CONFIG_VALUE_INVALID, INPUT_VALIDATION_FAILED, OUTPUT_VALIDATION_FAILED, INPUT_NOT_JSON, OUTPUT_NOT_JSON, ACTION_SUBRUN_LIMIT, ACTION_CALL_CYCLE, UNDECLARED_ACTION_DEPENDENCY, INVALID_ACTION_REF, IDEMPOTENCY_CONFLICT, EXECUTION_FAILED, UNHANDLED_EXECUTION_ERROR, RUN_REPOSITORY_UNAVAILABLE, RUN_PERSISTENCE_FAILED, STANDALONE_ASYNC_UNSUPPORTED, HOST_PROCESS_EXITED, EXECUTION_ABORTED, TIMEOUT, NETWORK_ERROR, CAPABILITY_UNAVAILABLE, STATE_KEY_NOT_FOUND, STORAGE_BUSY, PROJECT_BUSY, PROJECT_RECOVERY_REQUIRED, EVENT_BACKPRESSURE_LIMIT, EVENT_CURSOR_EXPIRED, PROCESS_OUTPUT_LIMIT, PROCESS_SPAWN_ERROR, PROCESS_CANCELLED, PROCESS_TIMEOUT, UNAUTHORIZED, NOT_FOUND, SERVER_ERROR, PACKAGE_FORBIDDEN, ACTION_FORBIDDEN, PLAYBOOK_NOT_FOUND, REQUEST_TOO_LARGE, ACTION_START_FAILED, ACTION_EXECUTION_ERROR, DATA_DIR_IN_USE, DATA_DIR_RECOVERY_REQUIRED, PROCESS_FAILED, MCP_TOOL_NAME_COLLISION, ACCESS_DENIED, INVALID_FLAT_ARGUMENT, INVALID_JSON, INVALID_JSON_LITERAL, INPUT_PATH_CONFLICT, FLAT_INPUT_LIMIT_EXCEEDED, INPUT_LIMIT_EXCEEDED, INPUT_POLICY_VIOLATION, INPUT_CONFLICT, INPUT_FILE_NOT_FOUND, INPUT_FILE_READ_FAILED, INVALID_ARGUMENT, PACKAGE_NOT_ALLOWED, INVALID_PACKAGE_ID, PATH_TRAVERSAL, AMBIGUOUS_STATE_KEY, RUN_NOT_FOUND, RUN_ALREADY_FINISHED, PROJECT_ROOT_NOT_FOUND, describeActionLoadFailure, createErrorEnvelope, resolveExecutionHint, } from "./errors.js";
+export { ActionDockError, ProcessError, PACKAGE_NOT_FOUND, ACTION_PACKAGE_VERSION_CONFLICT, ACTION_NOT_FOUND, ACTION_LOAD_FAILED, ACTION_FAILED, ACTION_TIMEOUT, ACTION_CANCELLED, CONFIG_VALUE_INVALID, INPUT_VALIDATION_FAILED, OUTPUT_VALIDATION_FAILED, INPUT_NOT_JSON, OUTPUT_NOT_JSON, ACTION_SUBRUN_LIMIT, ACTION_CALL_CYCLE, UNDECLARED_ACTION_DEPENDENCY, INVALID_ACTION_REF, IDEMPOTENCY_CONFLICT, EXECUTION_FAILED, UNHANDLED_EXECUTION_ERROR, RUN_REPOSITORY_UNAVAILABLE, RUN_PERSISTENCE_FAILED, STANDALONE_ASYNC_UNSUPPORTED, HOST_PROCESS_EXITED, EXECUTION_ABORTED, TIMEOUT, NETWORK_ERROR, CAPABILITY_UNAVAILABLE, STATE_KEY_NOT_FOUND, STORAGE_BUSY, DEPENDENCIES_NOT_READY, DEPENDENCY_INSTALL_FAILED, PROJECT_BUSY, PROJECT_RECOVERY_REQUIRED, EVENT_BACKPRESSURE_LIMIT, EVENT_CURSOR_EXPIRED, PROCESS_OUTPUT_LIMIT, PROCESS_SPAWN_ERROR, PROCESS_CANCELLED, PROCESS_TIMEOUT, UNAUTHORIZED, CONFIG_ENCRYPTION_ERROR, CONFIG_DECRYPT_FAILED, NOT_FOUND, SERVER_ERROR, PACKAGE_FORBIDDEN, ACTION_FORBIDDEN, PLAYBOOK_NOT_FOUND, REQUEST_TOO_LARGE, ACTION_START_FAILED, ACTION_EXECUTION_ERROR, DATA_DIR_IN_USE, DATA_DIR_RECOVERY_REQUIRED, PROCESS_FAILED, MCP_TOOL_NAME_COLLISION, ACCESS_DENIED, INVALID_FLAT_ARGUMENT, INVALID_JSON, INVALID_JSON_LITERAL, INPUT_PATH_CONFLICT, FLAT_INPUT_LIMIT_EXCEEDED, INPUT_LIMIT_EXCEEDED, INPUT_POLICY_VIOLATION, INPUT_CONFLICT, INPUT_FILE_NOT_FOUND, INPUT_FILE_READ_FAILED, INVALID_ARGUMENT, PACKAGE_NOT_ALLOWED, INVALID_PACKAGE_ID, PATH_TRAVERSAL, AMBIGUOUS_STATE_KEY, RUN_NOT_FOUND, RUN_ALREADY_FINISHED, PROJECT_ROOT_NOT_FOUND, describeActionLoadFailure, createErrorEnvelope, resolveExecutionHint, } from "./errors.js";
+export { executeCommand } from "./process/command-executor.js";
+export type { ExecuteCommandOptions, CommandExecutionResult, } from "./process/command-executor.js";
+export type { ConfigEncryptionKey, ConfigKeyProvider, } from "./security/config-cipher.js";
+export { createConfigKeyProvider } from "./security/config-key.js";

package/dist/index.js

@@ -19,5 +19,9 @@ export { startActionDockServer, } from "./server/server.js";
 // 6. 核心工程辅助
 export { initProject } from "./project/init.js";
 export { loadProjectConfig, findProjectRoot, } from "./project/loader.js";
+export { ensureProjectDependencies, } from "./project/dependencies.js";
 // 8. 统一错误模型与核心标准错误码常量
-export { ActionDockError, ProcessError, PACKAGE_NOT_FOUND, ACTION_PACKAGE_VERSION_CONFLICT, ACTION_NOT_FOUND, ACTION_LOAD_FAILED, ACTION_FAILED, ACTION_TIMEOUT, ACTION_CANCELLED, CONFIG_VALUE_INVALID, INPUT_VALIDATION_FAILED, OUTPUT_VALIDATION_FAILED, INPUT_NOT_JSON, OUTPUT_NOT_JSON, ACTION_SUBRUN_LIMIT, ACTION_CALL_CYCLE, UNDECLARED_ACTION_DEPENDENCY, INVALID_ACTION_REF, IDEMPOTENCY_CONFLICT, EXECUTION_FAILED, UNHANDLED_EXECUTION_ERROR, RUN_REPOSITORY_UNAVAILABLE, RUN_PERSISTENCE_FAILED, STANDALONE_ASYNC_UNSUPPORTED, HOST_PROCESS_EXITED, EXECUTION_ABORTED, TIMEOUT, NETWORK_ERROR, CAPABILITY_UNAVAILABLE, STATE_KEY_NOT_FOUND, STORAGE_BUSY, PROJECT_BUSY, PROJECT_RECOVERY_REQUIRED, EVENT_BACKPRESSURE_LIMIT, EVENT_CURSOR_EXPIRED, PROCESS_OUTPUT_LIMIT, PROCESS_SPAWN_ERROR, PROCESS_CANCELLED, PROCESS_TIMEOUT, UNAUTHORIZED, NOT_FOUND, SERVER_ERROR, PACKAGE_FORBIDDEN, ACTION_FORBIDDEN, PLAYBOOK_NOT_FOUND, REQUEST_TOO_LARGE, ACTION_START_FAILED, ACTION_EXECUTION_ERROR, DATA_DIR_IN_USE, DATA_DIR_RECOVERY_REQUIRED, PROCESS_FAILED, MCP_TOOL_NAME_COLLISION, ACCESS_DENIED, INVALID_FLAT_ARGUMENT, INVALID_JSON, INVALID_JSON_LITERAL, INPUT_PATH_CONFLICT, FLAT_INPUT_LIMIT_EXCEEDED, INPUT_LIMIT_EXCEEDED, INPUT_POLICY_VIOLATION, INPUT_CONFLICT, INPUT_FILE_NOT_FOUND, INPUT_FILE_READ_FAILED, INVALID_ARGUMENT, PACKAGE_NOT_ALLOWED, INVALID_PACKAGE_ID, PATH_TRAVERSAL, AMBIGUOUS_STATE_KEY, RUN_NOT_FOUND, RUN_ALREADY_FINISHED, PROJECT_ROOT_NOT_FOUND, describeActionLoadFailure, createErrorEnvelope, resolveExecutionHint, } from "./errors.js";
+export { ActionDockError, ProcessError, PACKAGE_NOT_FOUND, ACTION_PACKAGE_VERSION_CONFLICT, ACTION_NOT_FOUND, ACTION_LOAD_FAILED, ACTION_FAILED, ACTION_TIMEOUT, ACTION_CANCELLED, CONFIG_VALUE_INVALID, INPUT_VALIDATION_FAILED, OUTPUT_VALIDATION_FAILED, INPUT_NOT_JSON, OUTPUT_NOT_JSON, ACTION_SUBRUN_LIMIT, ACTION_CALL_CYCLE, UNDECLARED_ACTION_DEPENDENCY, INVALID_ACTION_REF, IDEMPOTENCY_CONFLICT, EXECUTION_FAILED, UNHANDLED_EXECUTION_ERROR, RUN_REPOSITORY_UNAVAILABLE, RUN_PERSISTENCE_FAILED, STANDALONE_ASYNC_UNSUPPORTED, HOST_PROCESS_EXITED, EXECUTION_ABORTED, TIMEOUT, NETWORK_ERROR, CAPABILITY_UNAVAILABLE, STATE_KEY_NOT_FOUND, STORAGE_BUSY, DEPENDENCIES_NOT_READY, DEPENDENCY_INSTALL_FAILED, PROJECT_BUSY, PROJECT_RECOVERY_REQUIRED, EVENT_BACKPRESSURE_LIMIT, EVENT_CURSOR_EXPIRED, PROCESS_OUTPUT_LIMIT, PROCESS_SPAWN_ERROR, PROCESS_CANCELLED, PROCESS_TIMEOUT, UNAUTHORIZED, CONFIG_ENCRYPTION_ERROR, CONFIG_DECRYPT_FAILED, NOT_FOUND, SERVER_ERROR, PACKAGE_FORBIDDEN, ACTION_FORBIDDEN, PLAYBOOK_NOT_FOUND, REQUEST_TOO_LARGE, ACTION_START_FAILED, ACTION_EXECUTION_ERROR, DATA_DIR_IN_USE, DATA_DIR_RECOVERY_REQUIRED, PROCESS_FAILED, MCP_TOOL_NAME_COLLISION, ACCESS_DENIED, INVALID_FLAT_ARGUMENT, INVALID_JSON, INVALID_JSON_LITERAL, INPUT_PATH_CONFLICT, FLAT_INPUT_LIMIT_EXCEEDED, INPUT_LIMIT_EXCEEDED, INPUT_POLICY_VIOLATION, INPUT_CONFLICT, INPUT_FILE_NOT_FOUND, INPUT_FILE_READ_FAILED, INVALID_ARGUMENT, PACKAGE_NOT_ALLOWED, INVALID_PACKAGE_ID, PATH_TRAVERSAL, AMBIGUOUS_STATE_KEY, RUN_NOT_FOUND, RUN_ALREADY_FINISHED, PROJECT_ROOT_NOT_FOUND, describeActionLoadFailure, createErrorEnvelope, resolveExecutionHint, } from "./errors.js";
+// 一次性工程命令执行工具
+export { executeCommand } from "./process/command-executor.js";
+export { createConfigKeyProvider } from "./security/config-key.js";

package/dist/invocation/types.d.ts

@@ -4,6 +4,29 @@ import { createPackageIdentity, type PackageIdentity } from "../runtime/identity
 export { createPackageIdentity };
 export type { PackageIdentity };
 export type { RunOptions } from "../service/types.js";
+/**
+ * 本地包准备目标契约。
+ */
+export interface LocalPackagePreparationTarget {
+    /** 目标包物理与快照身份标识 */
+    readonly identity: PackageIdentity;
+    /** 目标包物理根路径 */
+    readonly packageRoot: string;
+}
+/**
+ * 本地包准备上下文契约。
+ */
+export interface LocalPackagePreparationContext {
+    /** 取消信号 */
+    readonly signal: AbortSignal;
+    /** 根运行标识（用于在途合并与调用链追踪） */
+    readonly rootRunId: string;
+}
+/**
+ * 本地包准备协调器回调契约。
+ * 在本地 Action 实际执行前触发调用，确保包运行环境与依赖就绪。
+ */
+export type LocalPackagePreparer = (target: LocalPackagePreparationTarget, context: LocalPackagePreparationContext) => Promise<void>;
 /**
  * 构造默认进程归属所有者（ProcessOwner）的单一事实源工厂。
  *
@@ -57,6 +80,10 @@ export interface InvocationContext {
     readonly signal: AbortSignal;
     /** 超时毫秒数 */
     readonly timeoutMs?: number;
+    /** 初始超时毫秒数（原始预算） */
+    readonly initialTimeoutMs?: number;
+    /** 绝对超时时间戳 */
+    readonly deadline?: number;
     /** 配置覆盖项 */
     readonly config?: Record<string, unknown>;
     /** 幂等请求标识 */
@@ -105,6 +132,10 @@ export interface CreateRootInvocationContextOptions {
     signal?: AbortSignal;
     /** 最大超时时间（毫秒） */
     timeoutMs?: number;
+    /** 初始超时毫秒数（原始预算） */
+    initialTimeoutMs?: number;
+    /** 绝对超时时间戳 */
+    deadline?: number;
     /** 执行级临时配置覆盖字典 */
     config?: Record<string, unknown>;
     /** 幂等请求标识 */

package/dist/invocation/types.js

@@ -35,6 +35,8 @@ export function createInvocationContext(options) {
         package: pkg,
         signal: options.signal ?? new AbortController().signal,
         timeoutMs: options.timeoutMs,
+        initialTimeoutMs: options.initialTimeoutMs,
+        deadline: options.deadline,
         config: options.config,
         requestId: options.requestId,
         tenantId: options.tenantId,
@@ -64,11 +66,16 @@ export function createInvocationContext(options) {
  * parentRunId 与 caller 为 undefined，并按根调用契约挑选字段，保持无血缘血缘字段的键序不变。
  */
 export function createRootInvocationContext(options) {
+    const initialTimeoutMs = options.initialTimeoutMs ?? (typeof options.timeoutMs === "number" && options.timeoutMs > 0 ? options.timeoutMs : undefined);
+    const deadline = options.deadline ?? (initialTimeoutMs !== undefined ? Date.now() + initialTimeoutMs : undefined);
+    const remainingBudget = deadline !== undefined ? Math.max(0, deadline - Date.now()) : options.timeoutMs;
     const base = createInvocationContext({
         package: options.targetPackage,
         callStack: options.callStack,
         signal: options.signal,
-        timeoutMs: options.timeoutMs,
+        timeoutMs: remainingBudget,
+        initialTimeoutMs,
+        deadline,
         config: options.config,
         requestId: options.requestId,
         hostSessionId: options.hostSessionId,
@@ -90,6 +97,8 @@ export function createRootInvocationContext(options) {
         package: base.package,
         signal: base.signal,
         timeoutMs: base.timeoutMs,
+        initialTimeoutMs: base.initialTimeoutMs,
+        deadline: base.deadline,
         config: base.config,
         requestId: base.requestId,
         hostSessionId: base.hostSessionId,

package/dist/package/index.d.ts

@@ -19,4 +19,4 @@ 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";
-export type { RuntimeStorage, SqliteDriver, StateEntry, } from "../storage/types.js";
+export type { RuntimeStorage, SqliteDriver, StateEntry, ConfigWriteOptions, ConfigSnapshot, } from "../storage/types.js";

package/dist/package/runtime.js

@@ -6,6 +6,7 @@ import { findProjectRoot, loadProjectConfig } from "../project/loader.js";
 import { RuntimeConfig } from "../runtime/context.js";
 import { normalizeActionCollection } from "../runtime/action-collection.js";
 import { redactConfigValue, sanitizeConfigDefinitions } from "../storage/mask.js";
+import { redactConfigValueWithProtection } from "../storage/index.js";
 import { assertConcreteConfigKey, assertValidConfigDeclarations, isConfigTemplate, resolveConfigDeclaration, validateConfigValue, } from "../project/config-declarations.js";
 import { decodeStateKey, SqliteRuntimeStorage } from "../storage/sqlite.js";
 import { createPackageIdentity } from "../runtime/identity.js";
@@ -239,6 +240,7 @@ export class DefaultPackageRuntime {
     }
     /** 构造包存储工厂选项（单一事实源，异步与同步打开路径共用） */
     buildStorageOptions() {
+        const config = this.projectConfig?.config;
         return {
             projectRoot: this.packageRoot,
             dataDir: this.options.dataDir,
@@ -247,6 +249,9 @@ export class DefaultPackageRuntime {
             // 默认持有者语义：App 主路径打开时收割死亡会话遗留非终态运行记录；
             // CLI 查询旁观视图显式置 recoverOrphans: false 跳过收割
             recoverOrphans: this.options.recoverOrphans !== false,
+            // 供旧版本库自动迁移判定敏感性（各字典内具体键优先于模板）；
+            // 仅在库需要迁移时被读取，不引入新的生命周期
+            ...(config && Object.keys(config).length > 0 ? { configDeclarations: [config] } : {}),
         };
     }
     /**
@@ -300,12 +305,15 @@ export class DefaultPackageRuntime {
             this.globalStorageRes = { kind: "own", storage };
             return storage;
         }
+        const config = this.projectConfig?.config;
         const globalOpts = {
             customHome: this.options.customHome,
             dataDir: this.options.dataDir,
             inMemory: this.options.inMemory,
             // 与主存储保持同侧收割语义（全局库 runs 表为空集，收割无实际副作用）
             recoverOrphans: this.options.recoverOrphans !== false,
+            // 独立全局库迁移以当前包声明为并集口径；Host 共享路径由 Host 汇集全部已加载包声明
+            ...(config && Object.keys(config).length > 0 ? { configDeclarations: [config] } : {}),
         };
         const storage = this.platform.storage.createGlobalStorage(globalOpts);
         this.globalStorageRes = { kind: "own", storage };
@@ -708,12 +716,16 @@ export class DefaultPackageRuntime {
         this.assertOpen();
         assertConcreteConfigKey(key);
         const decl = resolveConfigDeclaration(this.projectConfig.config, key);
-        // 委托 RuntimeConfig 五层优先级链单一事实源，避免重复实现解析链
-        const resolved = this.ensureRuntimeConfig().describe(key);
+        // 委托 RuntimeConfig 五层优先级链单一事实源，取值与历史保护声明同链原子解析
+        const resolved = this.ensureRuntimeConfig().describeWithProtection(key);
         // configured 显式判定：仅真实显式来源（override/package/global/env）为 true，
         // default 与整链未命中（source null）均为 false，不得依赖与 "default" 的不等比较
         const configured = resolved.source !== null && resolved.source !== "default";
-        const redacted = redactConfigValue(resolved.value, decl?.item);
+        // 当前声明与存储持久化的历史保护声明合并脱敏：删除或弱化声明后仍保持既有保护；
+        // 无历史保护时沿用单声明脱敏原语，保持既有视图行为不变
+        const redacted = resolved.protection !== undefined
+            ? redactConfigValueWithProtection(resolved.value, decl?.item ? [decl.item] : [], resolved.protection)
+            : redactConfigValue(resolved.value, decl?.item);
         return {
             key,
             configured,
@@ -728,7 +740,9 @@ export class DefaultPackageRuntime {
         assertConcreteConfigKey(key);
         const decl = resolveConfigDeclaration(this.projectConfig.config, key);
         validateConfigValue(key, value, decl?.item);
-        await (await this.prepareStorageAsync()).setConfig(key, value);
+        // 传递当前有效声明（具体键优先于模板解析结果），
+        // 由存储统一判定整键加密并合并历史保护，禁止保护弱化
+        await (await this.prepareStorageAsync()).setConfig(key, value, decl?.item ? { declarations: [decl.item] } : undefined);
     }
     async deleteConfig(key) {
         this.assertOpen();

package/dist/platform/node.d.ts

@@ -4,6 +4,7 @@ import { type ModuleLoader } from "./module-loader.js";
 import { ProcessManager } from "../process/process-manager.js";
 import type { ProcessDriver } from "../process/driver.js";
 import { type SqliteDriver } from "../storage/index.js";
+import type { ConfigKeyProvider } from "../security/config-cipher.js";
 import type { EventSink } from "../runtime/events.js";
 import type { RuntimePlatform, StorageFactory } from "./types.js";
 /**
@@ -35,6 +36,11 @@ export interface NodePlatformOptions {
     clock?: Clock;
     /** 自定义存储工厂（默认基于 NodeSqliteDriver 构造） */
     storage?: StorageFactory;
+    /**
+     * 显式注入的配置加密密钥提供器：优先于由有效 customHome/dataDir 派生的默认提供器，
+     * 显式注入时对内存库同样生效（供测试注入固定密钥）。
+     */
+    configKeyProvider?: ConfigKeyProvider;
     /** 可选注入的执行事件接收器 */
     eventSink?: EventSink;
     /** 可选注入的统一日志记录器 */

package/dist/platform/node.js

@@ -7,6 +7,7 @@ import { NodeProcessDriver } from "../process/process-driver.js";
 import { ProcessManager } from "../process/process-manager.js";
 import { NodeSqliteDriver } from "../storage/sqlite-driver.js";
 import { resolveDatabasePath, resolveGlobalDatabasePath, SqliteRuntimeStorage, } from "../storage/index.js";
+import { createConfigKeyProvider } from "../security/config-key.js";
 function ensureDirectoryForDb(dbPath) {
     if (dbPath !== ":memory:") {
         const dir = dirname(dbPath);
@@ -72,43 +73,85 @@ export function createNodePlatform(options = {}) {
         return cachedModules;
     };
     const createDriver = options.driverFactory ?? ((dbPath) => new NodeSqliteDriver(dbPath));
+    // - 配置加密密钥提供器按每次建库时的有效路径派生：密钥必须与数据库共享同一
+    //   dataDir/customHome 域，禁止密钥落真实 home 而数据库在别处（或反向）。
+    //   提供器懒加载：仅构造平台或读取普通配置不创建 keys 目录；
+    //   内存库不注入派生提供器，由存储使用随机内存密钥，即使环境提供密钥也不触真实密钥源；
+    //   显式注入的测试提供器对内存库保留生效。
+    const resolveConfigKeyProvider = (dbPath, effectiveCustomHome, effectiveDataDir) => {
+        if (options.configKeyProvider) {
+            return options.configKeyProvider;
+        }
+        if (dbPath === ":memory:") {
+            return undefined;
+        }
+        return createConfigKeyProvider({
+            customHome: effectiveCustomHome,
+            dataDir: effectiveDataDir,
+        });
+    };
+    // - 自建驱动构造失败时释放句柄：SqliteRuntimeStorage 将注入 driver 视为外部资源，
+    //   构造抛出不会代为关闭，此处回收驱动，避免锁泄漏后原样透传错误
+    const createStorageWithDriverCleanup = (build, dbPath) => {
+        const driver = createDriver(dbPath);
+        try {
+            return build(driver);
+        }
+        catch (err) {
+            try {
+                driver.close();
+            }
+            catch {
+                // 忽略清理阶段副异常，确保原始错误优先透传
+            }
+            throw err;
+        }
+    };
     const storage = options.storage ?? {
         createStorage(packageId, opts) {
+            // 显式 opts 中的 undefined 不得覆盖平台级路径：密钥与数据库必须解析同一有效路径
+            const effectiveCustomHome = opts?.customHome ?? options.customHome;
+            const effectiveDataDir = opts?.dataDir ?? options.dataDir;
             const mergedOpts = {
-                customHome: options.customHome,
-                dataDir: options.dataDir,
-                ...opts,
+                customHome: effectiveCustomHome,
+                dataDir: effectiveDataDir,
+                inMemory: opts?.inMemory,
+                projectRoot: opts?.projectRoot,
             };
             const dbPath = resolveDatabasePath(packageId, mergedOpts);
             ensureDirectoryForDb(dbPath);
-            return new SqliteRuntimeStorage({
+            const configKeyProvider = resolveConfigKeyProvider(dbPath, effectiveCustomHome, effectiveDataDir);
+            return createStorageWithDriverCleanup((driver) => new SqliteRuntimeStorage({
                 dbPath,
                 packageId,
                 clock,
-                driver: createDriver(dbPath),
+                driver,
                 recoverOrphans: opts?.recoverOrphans === true,
                 retentionPolicy: opts?.retentionPolicy,
                 logger: options.logger,
-            });
+                ...(configKeyProvider ? { configKeyProvider } : {}),
+                ...(opts?.configDeclarations?.length ? { configDeclarations: opts.configDeclarations } : {}),
+            }), dbPath);
         },
         createGlobalStorage(opts) {
-            const mergedOpts = {
-                customHome: options.customHome,
-                dataDir: options.dataDir,
-                ...opts,
-            };
-            const dbPath = mergedOpts.inMemory
+            const effectiveCustomHome = opts?.customHome ?? options.customHome;
+            const effectiveDataDir = opts?.dataDir ?? options.dataDir;
+            const inMemory = Boolean(opts?.inMemory);
+            const dbPath = inMemory
                 ? ":memory:"
-                : resolveGlobalDatabasePath({ dataDir: mergedOpts.dataDir, customHome: mergedOpts.customHome });
+                : resolveGlobalDatabasePath({ dataDir: effectiveDataDir, customHome: effectiveCustomHome });
             ensureDirectoryForDb(dbPath);
-            return new SqliteRuntimeStorage({
+            const configKeyProvider = resolveConfigKeyProvider(dbPath, effectiveCustomHome, effectiveDataDir);
+            return createStorageWithDriverCleanup((driver) => new SqliteRuntimeStorage({
                 dbPath,
                 packageId: "__global__",
                 clock,
-                driver: createDriver(dbPath),
+                driver,
                 recoverOrphans: opts?.recoverOrphans === true,
                 logger: options.logger,
-            });
+                ...(configKeyProvider ? { configKeyProvider } : {}),
+                ...(opts?.configDeclarations?.length ? { configDeclarations: opts.configDeclarations } : {}),
+            }), dbPath);
         },
     };
     const platform = {

package/dist/platform/types.d.ts

@@ -4,6 +4,7 @@ import type { ModuleLoader } from "./module-loader.js";
 import type { RunsRetentionPolicy, RuntimeStorage } from "../storage/types.js";
 import type { EventSink } from "../runtime/events.js";
 import type { PackageRuntime } from "../package/types.js";
+import type { ConfigItemDefinition } from "../project/types.js";
 /**
  * 跨运行时持久化存储工厂配置选项。
  */
@@ -19,6 +20,11 @@ export interface StorageFactoryOptions {
     recoverOrphans?: boolean;
     /** 运行记录保留策略配置 */
     retentionPolicy?: RunsRetentionPolicy;
+    /**
+     * 供旧版本数据库迁移判定的配置声明字典集合（包级存储传当前包声明）。
+     * 仅在库需要迁移时被读取；版本迁移只在首次打开执行。
+     */
+    configDeclarations?: readonly Record<string, ConfigItemDefinition>[];
 }
 /**
  * 跨运行时全局存储工厂配置选项。
@@ -29,6 +35,11 @@ export interface GlobalStorageFactoryOptions {
     customHome?: string;
     /** 是否以持有者身份打开并收割遗留非终态运行记录（默认 false，旁观语义） */
     recoverOrphans?: boolean;
+    /**
+     * 供旧版本全局库迁移判定的配置声明字典集合（通常为所有已加载包的声明并集）。
+     * 仅在库需要迁移时被读取；版本迁移只在首次打开执行。
+     */
+    configDeclarations?: readonly Record<string, ConfigItemDefinition>[];
 }
 /**
  * 跨运行时持久化存储工厂契约。

package/dist/process/command-executor.d.ts

@@ -0,0 +1,35 @@
+import type { ProcessDriver } from "./driver.js";
+/**
+ * 工程工具命令执行配置选项。
+ */
+export interface ExecuteCommandOptions {
+    cwd?: string;
+    env?: Record<string, string | undefined>;
+    signal?: AbortSignal;
+    timeoutMs?: number;
+    maxOutputBytes?: number;
+    onOutput?: (stream: "stdout" | "stderr", text: string) => void;
+    driver?: ProcessDriver;
+}
+/**
+ * 工程工具命令执行结果。
+ */
+export interface CommandExecutionResult {
+    status: number | null;
+    signal: string | null;
+    stdout: string;
+    stderr: string;
+    truncated: boolean;
+}
+/**
+ * 面向工程工具的一次性命令适配执行器。
+ *
+ * 核心设计契约：
+ * - 复用底层 ProcessDriver 平台驱动，严格保持进程组隔离与进程树收敛能力；
+ * - 绝不启用系统 Shell，参数列表原样透传，杜绝命令注入与参数转义漏洞；
+ * - 默认每流上限 512KiB 字节有界捕获，超出上限继续排空或转发并置 truncated 标志；
+ * - 捕获字节独立深拷贝，脱离原始底层缓冲区以防内存滞留与复用篡改；
+ * - 仅当显式指定 onOutput 时流式转发，严格保证跨分块 UTF-8 字符解码完整性；
+ * - 规范化取消、超时与异常收敛：等待 driver.terminate 与 outputClosed 终态后抛出结构化 ProcessError。
+ */
+export declare function executeCommand(executable: string, args: readonly string[], options?: ExecuteCommandOptions): Promise<CommandExecutionResult>;