@actiondock/core 2.5.0 → 2.6.0

package/dist/registry/registry.js

@@ -60,8 +60,9 @@ export function parseRegistryContent(raw, filePath) {
                     const config = loadProjectConfig(link.path);
                     packages[config.id] = buildLinkedPackageEntry(config, resolve(link.path), link.linkedAt || new Date().toISOString());
                 }
-                catch {
-                    // 迁移时项目已损坏或配置非法：跳过该条 link，避免迁移整体失败
+                catch (err) {
+                    // 迁移时项目已损坏或配置非法：跳过该条 link 避免迁移整体失败，但必须输出告警，杜绝链接无声消失
+                    console.warn(`[Registry] Skipping corrupted package link during migration: '${link.path}' (${err?.message || String(err)})`);
                 }
             }
         }
@@ -259,8 +260,9 @@ export async function linkPackage(targetPath = process.cwd(), customHome, option
                     registry.packages[config.id] = entry;
                     linkedEntries.push(entry);
                 }
-                catch {
-                    // 子项目配置损坏：跳过该子项目条目，不影响 workspace 注册本身
+                catch (err) {
+                    // 子项目配置损坏：跳过该子项目条目不影响 workspace 注册本身，但必须输出告警含包路径，杜绝链接无声消失
+                    console.warn(`[Registry] Skipping corrupted workspace child package during link: '${root}' (${err?.message || String(err)})`);
                 }
             }
             await writeRegistryLocked(registry, customHome);

package/dist/registry/resolve.js

@@ -179,7 +179,7 @@ export async function probeActionAsync(projectRoot, config, actionId) {
         return true;
     }
     try {
-        const actions = await loadActions(projectRoot, config.actionsDir, { autoInstall: false });
+        const actions = await loadActions(projectRoot, config.actionsDir);
         return actions.has(actionId) ? true : undefined;
     }
     catch {

package/dist/runtime/action-registry.d.ts

@@ -0,0 +1,45 @@
+import type { ActionDefinition, ActionRef } from "@actiondock/sdk";
+/**
+ * 为匿名传入的 Action 定义对象解析或分配稳定标识。
+ */
+export declare function resolveAnonymousActionId(actions: Map<string, ActionDefinition>, action: ActionDefinition): string;
+/**
+ * Action 注册表：持有 Action 标识到定义的映射并提供注册与检索能力。
+ */
+export declare class ActionRegistry {
+    private actions;
+    constructor(actions?: Map<string, ActionDefinition>);
+    /** 底层映射表（调用方只读使用，写入仅经注册入口） */
+    get map(): Map<string, ActionDefinition>;
+    /**
+     * 注册单个 Action。
+     */
+    registerAction(id: string, action: ActionDefinition): void;
+    registerAction(action: ({
+        id: string;
+        action?: ActionDefinition;
+    } & Partial<ActionDefinition>) | ActionDefinition): void;
+    /**
+     * 根据 ID 检索注册的 Action。
+     */
+    getAction(id: string): ActionDefinition | undefined;
+    /**
+     * 检索全部已注册的 Action 列表。
+     */
+    listActions(): ActionDefinition[];
+}
+/**
+ * 本地注册表阶梯检索：跨包引用查 "pkg/action"，本包引用依次查短标识与限定标识。
+ */
+export declare function findLocalAction(actions: Map<string, ActionDefinition>, parsed: ActionRef, currentPackageId: string): ActionDefinition | undefined;
+/**
+ * 判定传入对象是否为可执行的 Action 定义对象（含 run 函数）。
+ *
+ * 判定语义与原内联实现完全一致：null 入参同样在 `in` 运算处抛出 TypeError，
+ * 不额外吞异或静默改道，保持边界行为零变化。
+ */
+export declare function isActionDefinitionObject(value: unknown): value is ActionDefinition;
+/**
+ * 解析 Action 引用或标识符（解析失败抛出原始异常，由调用方分类处理）。
+ */
+export declare function parseActionRef(ref: ActionRef | string): ActionRef;

package/dist/runtime/action-registry.js

@@ -0,0 +1,108 @@
+import { ActionResolver } from "../catalog/action-resolver.js";
+/**
+ * Action 注册表（单一职责模块）。
+ *
+ * 收敛 ActionRunner 原内联的纯注册逻辑：Action 注册与检索、匿名 Action 稳定标识
+ * 分配、以及本地注册表阶梯检索（跨包限定标识优先、本包短标识回退）。动态解析
+ * （自定义 resolver 委托与全局链接注册表按需加载）属于 Runner 编排职责，仍留在
+ * runner.ts 中，仅通过本注册表完成注册副作用。
+ */
+/** 匿名传入 Action 对象的稳定标识分配表（同一对象跨多次调用复用同一标识） */
+const anonymousActionIds = new WeakMap();
+let anonymousActionCounter = 0;
+/**
+ * 为匿名传入的 Action 定义对象解析或分配稳定标识。
+ */
+export function resolveAnonymousActionId(actions, action) {
+    const actObj = action;
+    let foundId;
+    for (const [id, a] of actions) {
+        if (a === action) {
+            foundId = id;
+            break;
+        }
+    }
+    if (foundId) {
+        return foundId;
+    }
+    let anonId = anonymousActionIds.get(action);
+    if (!anonId) {
+        anonymousActionCounter++;
+        anonId = `anonymous-action-${anonymousActionCounter}`;
+        anonymousActionIds.set(action, anonId);
+    }
+    try {
+        actObj.id = anonId;
+    }
+    catch { }
+    return anonId;
+}
+/**
+ * Action 注册表：持有 Action 标识到定义的映射并提供注册与检索能力。
+ */
+export class ActionRegistry {
+    actions;
+    constructor(actions) {
+        this.actions = actions || new Map();
+    }
+    /** 底层映射表（调用方只读使用，写入仅经注册入口） */
+    get map() {
+        return this.actions;
+    }
+    registerAction(idOrAction, actionDef) {
+        if (typeof idOrAction === "string") {
+            if (actionDef) {
+                this.actions.set(idOrAction, actionDef);
+            }
+        }
+        else {
+            const actObj = idOrAction;
+            const id = actObj.id || "anonymous-action";
+            const act = actObj.action || (actObj.run ? actObj : undefined);
+            if (act) {
+                this.actions.set(id, act);
+            }
+        }
+    }
+    /**
+     * 根据 ID 检索注册的 Action。
+     */
+    getAction(id) {
+        return this.actions.get(id);
+    }
+    /**
+     * 检索全部已注册的 Action 列表。
+     */
+    listActions() {
+        return Array.from(this.actions.values());
+    }
+}
+/**
+ * 本地注册表阶梯检索：跨包引用查 "pkg/action"，本包引用依次查短标识与限定标识。
+ */
+export function findLocalAction(actions, parsed, currentPackageId) {
+    const targetActionId = parsed.actionId;
+    const targetPackageId = parsed.packageId;
+    if (targetPackageId && targetPackageId !== currentPackageId) {
+        return actions.get(`${targetPackageId}/${targetActionId}`);
+    }
+    return (actions.get(targetActionId) ||
+        (currentPackageId ? actions.get(`${currentPackageId}/${targetActionId}`) : undefined));
+}
+/**
+ * 判定传入对象是否为可执行的 Action 定义对象（含 run 函数）。
+ *
+ * 判定语义与原内联实现完全一致：null 入参同样在 `in` 运算处抛出 TypeError，
+ * 不额外吞异或静默改道，保持边界行为零变化。
+ */
+export function isActionDefinitionObject(value) {
+    return (typeof value === "object" &&
+        "run" in value &&
+        typeof value.run === "function");
+}
+/**
+ * 解析 Action 引用或标识符（解析失败抛出原始异常，由调用方分类处理）。
+ */
+export function parseActionRef(ref) {
+    return ActionResolver.parseRef(ref);
+}

package/dist/runtime/clock.d.ts

@@ -1,19 +1,7 @@
 /**
- * 统一时间与时钟接口。
+ * 时钟契约单一事实源已下沉至 storage/clock.ts（基础契约层）。
+ *
+ * 此处 re-export 维持 `runtime/clock` 与 `@actiondock/core` 根入口的既有
+ * 导入路径兼容，外部消费方无需变更。
  */
-export interface Clock {
-    /** 获取当前系统墙上时间 */
-    now(): Date;
-    /** 获取单调递增时间戳（单位：毫秒） */
-    monotonic(): number;
-    /** 异步休眠指定毫秒 */
-    sleep(ms: number): Promise<void>;
-}
-/**
- * 生产环境系统时钟实现。
- */
-export declare class SystemClock implements Clock {
-    now(): Date;
-    monotonic(): number;
-    sleep(ms: number): Promise<void>;
-}
+export { type Clock, SystemClock } from "../storage/clock.js";

package/dist/runtime/clock.js

@@ -1,17 +1,7 @@
 /**
- * 生产环境系统时钟实现。
+ * 时钟契约单一事实源已下沉至 storage/clock.ts（基础契约层）。
+ *
+ * 此处 re-export 维持 `runtime/clock` 与 `@actiondock/core` 根入口的既有
+ * 导入路径兼容，外部消费方无需变更。
  */
-export class SystemClock {
-    now() {
-        return new Date();
-    }
-    monotonic() {
-        if (typeof performance !== "undefined" && typeof performance.now === "function") {
-            return performance.now();
-        }
-        return Date.now();
-    }
-    sleep(ms) {
-        return new Promise((resolve) => setTimeout(resolve, ms));
-    }
-}
+export { SystemClock } from "../storage/clock.js";

package/dist/runtime/context.d.ts

@@ -34,6 +34,9 @@ export declare class RuntimeConfig implements Config {
 }
 /**
  * 生产级状态存储实现，将状态持久化到 SQLite 中，完整支持命名空间分段隔离与 TTL。
+ *
+ * 读取严格限定当前命名空间（根作用域即空命名空间），不做跨命名空间隐式回扫；
+ * 跨命名空间模糊检索由 RuntimeStorage.findState 显式公共 API 承担。
  */
 export declare class RuntimeStateStore implements StateStore {
     private storage;

package/dist/runtime/context.js

@@ -23,53 +23,17 @@ export class RuntimeConfig {
         this.globalStorage = globalStorage;
     }
     get(key, defaultValue) {
-        // 1. CLI 临时参数覆盖
-        if (this.overrides.has(key)) {
-            return this.overrides.get(key);
-        }
-        // 2. 本地项目 SQLite 存储
-        const stored = this.storage.getConfig(key);
-        if (stored !== undefined) {
-            return stored;
+        // 委托 describe 五层解析链唯一事实源：整链未命中（source 为 default 且无值）时回退调用方默认值
+        const resolved = this.describe(key);
+        if (resolved.source === "default" && resolved.value === undefined) {
+            return defaultValue;
         }
-        // 3. 全局 SQLite 存储 (~/.actiondock/global.db)
-        if (this.globalStorage) {
-            try {
-                const globalStored = this.globalStorage.getConfig(key);
-                if (globalStored !== undefined) {
-                    return globalStored;
-                }
-            }
-            catch {
-                // 忽略全局存储读取异常
-            }
-        }
-        // 4. 环境变量（支持包名前缀、SNAKE_CASE 转换与类型自动推断）
-        const itemDef = this.projectConfig?.config?.[key];
-        const envResolved = resolveEnvValue(key, itemDef, this.projectConfig?.id);
-        if (envResolved !== undefined) {
-            return envResolved.value;
-        }
-        // 5. 项目声明的默认值 (actiondock.json)
-        if (itemDef?.default !== undefined) {
-            return itemDef.default;
-        }
-        // 6. 调用方传入的代码级回退默认值
-        return defaultValue;
+        return resolved.value;
     }
     has(key) {
-        if (this.overrides.has(key))
-            return true;
-        if (this.storage.getConfig(key) !== undefined)
-            return true;
-        if (this.globalStorage?.getConfig(key) !== undefined)
-            return true;
-        const itemDef = this.projectConfig?.config?.[key];
-        if (resolveEnvValue(key, itemDef, this.projectConfig?.id) !== undefined)
-            return true;
-        if (itemDef?.default !== undefined)
-            return true;
-        return false;
+        // 委托 describe 五层解析链唯一事实源：default 来源且无值即视为未配置
+        const resolved = this.describe(key);
+        return !(resolved.source === "default" && resolved.value === undefined);
     }
     /**
      * 结构化解析指定配置项的来源与取值视图。
@@ -87,7 +51,7 @@ export class RuntimeConfig {
         if (stored !== undefined) {
             return { source: "package", value: stored };
         }
-        // 3. 全局持久化存储
+        // 3. 全局持久化存储（读取异常时降级继续解析链，但记录警告确保不静默吞没）
         if (this.globalStorage) {
             try {
                 const globalStored = this.globalStorage.getConfig(key);
@@ -95,8 +59,8 @@ export class RuntimeConfig {
                     return { source: "global", value: globalStored };
                 }
             }
-            catch {
-                // 忽略全局存储读取异常
+            catch (err) {
+                console.warn(`[actiondock] global config read failed for ${key}: ${err instanceof Error ? err.message : String(err)}`);
             }
         }
         // 4. 环境变量
@@ -111,6 +75,9 @@ export class RuntimeConfig {
 }
 /**
  * 生产级状态存储实现，将状态持久化到 SQLite 中，完整支持命名空间分段隔离与 TTL。
+ *
+ * 读取严格限定当前命名空间（根作用域即空命名空间），不做跨命名空间隐式回扫；
+ * 跨命名空间模糊检索由 RuntimeStorage.findState 显式公共 API 承担。
  */
 export class RuntimeStateStore {
     storage;
@@ -120,15 +87,9 @@ export class RuntimeStateStore {
         this.namespace = namespace;
     }
     async get(key) {
-        if (this.namespace) {
-            return this.storage.getState(this.namespace, key);
-        }
-        const val = await this.storage.getState("", key);
-        if (val !== undefined) {
-            return val;
-        }
-        const found = await this.storage.findState(key);
-        return found?.value;
+        // 读取严格限定当前命名空间（根作用域即空命名空间），不做跨命名空间隐式回扫；
+        // 跨命名空间检索需求由 RuntimeStorage.findState 显式公共 API 承担
+        return this.storage.getState(this.namespace, key);
     }
     async set(key, value, ttl) {
         return this.storage.setState(this.namespace, key, value, ttl);

package/dist/runtime/index.d.ts

@@ -1,5 +1,8 @@
 export * from "./context.js";
 export * from "./action-collection.js";
+export * from "./action-registry.js";
+export * from "./run-persistence.js";
+export * from "./package-runner-factory.js";
 export * from "./runner.js";
 export * from "./execution-manager.js";
 export * from "./standalone.js";

package/dist/runtime/index.js

@@ -1,5 +1,8 @@
 export * from "./context.js";
 export * from "./action-collection.js";
+export * from "./action-registry.js";
+export * from "./run-persistence.js";
+export * from "./package-runner-factory.js";
 export * from "./runner.js";
 export * from "./execution-manager.js";
 export * from "./standalone.js";

package/dist/runtime/package-runner-factory.d.ts

@@ -0,0 +1,82 @@
+import type { ProcessAPI } from "@actiondock/sdk";
+import type { RuntimeStorage } from "../storage/types.js";
+import type { RuntimePlatform } from "../platform/types.js";
+import type { Clock } from "./clock.js";
+import type { ActionRunner, PackageContextResolver, RunnerOptions } from "./runner.js";
+/**
+ * 跨包 Runner 构建工厂参数（Runner 编排层注入的宿主执行环境快照）。
+ */
+export interface PackageRunnerFactoryOptions {
+    /** 全局共享持久化存储实例（传递给子包 Runner 复用） */
+    globalStorage?: RuntimeStorage;
+    /** 项目根目录绝对路径 */
+    projectRoot?: string;
+    /** 外部注入的进程执行器 */
+    process?: ProcessAPI;
+    /** 可选的时间与时钟源 */
+    clock?: Clock;
+    /** 可选的底层运行时平台契约 */
+    platform?: RuntimePlatform;
+    /** 最大调用嵌套深度限制 */
+    maxCallDepth: number;
+    /** 最大并发子任务数限制 */
+    maxSubRuns: number;
+    /** 动态解析 Action 的委托函数 */
+    actionResolver?: RunnerOptions["actionResolver"];
+    /** 跨包存储工厂 */
+    getStorageForPackage?: (packageId: string, projectRoot?: string) => RuntimeStorage;
+    /** 跨包运行上下文解析委托函数 */
+    packageContextResolver?: PackageContextResolver;
+    /** 自定义 ActionDock 用户家目录 */
+    customHome?: string;
+}
+/**
+ * 跨包 Runner 构建工厂与缓存（单一职责模块）。
+ *
+ * 收敛 ActionRunner 原内联的跨包执行域：已解析子包 Runner 缓存、构建中 in-flight
+ * Promise 去重（消除并发 check-then-act 竞态）、本工厂直接创建的子包存储清单与
+ * dispose 级联释放。子 Runner 实例构造委托 ActionRunner 公共构造器，形成单向
+ * 依赖：factory -> runner，不产生环。
+ */
+export declare class PackageRunnerFactory {
+    private readonly options;
+    private packageRunners;
+    /** 跨包 Runner 构建中的 in-flight Promise：并发调用 await 同一构建任务，消除 check-then-act 竞态 */
+    private pendingPackageRunners;
+    /** 本工厂直接为子包创建的存储连接（dispose 时级联关闭；外部注入存储不在此列） */
+    private packageStorages;
+    /** dispose 幂等守卫：并发调用复用同一次释放任务 */
+    private disposePromise;
+    /** 子包 Runner 构造委托（由 runner.ts 注入，避免本模块反向依赖 runner.ts） */
+    private readonly createRunner;
+    constructor(options: PackageRunnerFactoryOptions, createRunner: (options: RunnerOptions) => ActionRunner);
+    /**
+     * 已解析子包 Runner 缓存视图（调用方只读遍历使用）。
+     */
+    get runners(): Map<string, ActionRunner>;
+    /**
+     * 注入或更新跨包运行上下文解析委托。
+     */
+    setPackageContextResolver(resolver: PackageContextResolver): void;
+    /**
+     * 跨包运行时解析与获取（确保跨包执行具备独立的配置、存储、状态与 Action 注册表）。
+     *
+     * 缓存 miss 后存在长异步窗口（加载配置、扫描 Action、打开存储），并发调用会重复构建
+     * Runner、重复打开 SQLite 连接且子任务限流计数分裂；故以 in-flight Promise 去重，
+     * 并发方 await 同一构建任务，构建失败时移除该 Promise 以便后续重试。
+     */
+    resolveTargetPackageRunner(targetPackageId: string): Promise<ActionRunner | undefined>;
+    /**
+     * 实际构建跨包 Runner（仅由 resolveTargetPackageRunner 串行调度）。
+     */
+    private buildTargetPackageRunner;
+    /**
+     * 释放跨包资源：遍历关闭全部子包 Runner 及其独立创建的存储连接。
+     *
+     * 幂等且并发安全：重复调用直接复用首次 Promise；子包存储异常不阻断其余释放；
+     * 仅关闭由本工厂构建子包 Runner 时独立创建的存储，外部注入的存储（如经
+     * packageContextResolver 传入的目标包自身存储）生命周期归所有者管理，不在此误关。
+     */
+    dispose(): Promise<void>;
+    private disposeInternal;
+}

package/dist/runtime/package-runner-factory.js

@@ -0,0 +1,186 @@
+import { existsSync } from "node:fs";
+import { loadActions, loadProjectConfig } from "../project/loader.js";
+import { resolvePackageRoot } from "../registry/registry.js";
+/**
+ * 跨包 Runner 构建工厂与缓存（单一职责模块）。
+ *
+ * 收敛 ActionRunner 原内联的跨包执行域：已解析子包 Runner 缓存、构建中 in-flight
+ * Promise 去重（消除并发 check-then-act 竞态）、本工厂直接创建的子包存储清单与
+ * dispose 级联释放。子 Runner 实例构造委托 ActionRunner 公共构造器，形成单向
+ * 依赖：factory -> runner，不产生环。
+ */
+export class PackageRunnerFactory {
+    options;
+    packageRunners = new Map();
+    /** 跨包 Runner 构建中的 in-flight Promise：并发调用 await 同一构建任务，消除 check-then-act 竞态 */
+    pendingPackageRunners = new Map();
+    /** 本工厂直接为子包创建的存储连接（dispose 时级联关闭；外部注入存储不在此列） */
+    packageStorages = new Set();
+    /** dispose 幂等守卫：并发调用复用同一次释放任务 */
+    disposePromise;
+    /** 子包 Runner 构造委托（由 runner.ts 注入，避免本模块反向依赖 runner.ts） */
+    createRunner;
+    constructor(options, createRunner) {
+        this.options = options;
+        this.createRunner = createRunner;
+    }
+    /**
+     * 已解析子包 Runner 缓存视图（调用方只读遍历使用）。
+     */
+    get runners() {
+        return this.packageRunners;
+    }
+    /**
+     * 注入或更新跨包运行上下文解析委托。
+     */
+    setPackageContextResolver(resolver) {
+        this.options.packageContextResolver = resolver;
+    }
+    /**
+     * 跨包运行时解析与获取（确保跨包执行具备独立的配置、存储、状态与 Action 注册表）。
+     *
+     * 缓存 miss 后存在长异步窗口（加载配置、扫描 Action、打开存储），并发调用会重复构建
+     * Runner、重复打开 SQLite 连接且子任务限流计数分裂；故以 in-flight Promise 去重，
+     * 并发方 await 同一构建任务，构建失败时移除该 Promise 以便后续重试。
+     */
+    async resolveTargetPackageRunner(targetPackageId) {
+        const cached = this.packageRunners.get(targetPackageId);
+        if (cached) {
+            return cached;
+        }
+        const inFlight = this.pendingPackageRunners.get(targetPackageId);
+        if (inFlight) {
+            return inFlight;
+        }
+        const building = this.buildTargetPackageRunner(targetPackageId).finally(() => {
+            // 无论成败均移除 in-flight 记录：成功者已写入正式缓存，失败者允许重试
+            this.pendingPackageRunners.delete(targetPackageId);
+        });
+        this.pendingPackageRunners.set(targetPackageId, building);
+        return building;
+    }
+    /**
+     * 实际构建跨包 Runner（仅由 resolveTargetPackageRunner 串行调度）。
+     */
+    async buildTargetPackageRunner(targetPackageId) {
+        const opts = this.options;
+        if (opts.packageContextResolver) {
+            const resolved = await opts.packageContextResolver(targetPackageId);
+            if (resolved) {
+                const runner = this.createRunner({
+                    packageId: targetPackageId,
+                    packageInstanceId: resolved.packageInstanceId || resolved.projectConfig?.packageInstanceId || targetPackageId,
+                    generationId: resolved.generationId || resolved.projectConfig?.generationId || "1",
+                    storage: resolved.storage,
+                    globalStorage: opts.globalStorage,
+                    projectRoot: resolved.projectRoot,
+                    projectConfig: resolved.projectConfig,
+                    actions: resolved.actions,
+                    process: opts.process,
+                    clock: opts.clock,
+                    platform: opts.platform,
+                    maxCallDepth: opts.maxCallDepth,
+                    maxSubRuns: opts.maxSubRuns,
+                    actionResolver: opts.actionResolver,
+                    getStorageForPackage: opts.getStorageForPackage,
+                    packageContextResolver: opts.packageContextResolver,
+                });
+                this.packageRunners.set(targetPackageId, runner);
+                return runner;
+            }
+        }
+        const root = resolvePackageRoot(targetPackageId, opts.projectRoot, opts.customHome);
+        if (root && existsSync(root)) {
+            const config = loadProjectConfig(root);
+            let storage;
+            let ownsPackageStorage = false;
+            if (opts.getStorageForPackage) {
+                storage = opts.getStorageForPackage(targetPackageId, root);
+            }
+            else if (opts.platform) {
+                storage = opts.platform.storage.createStorage(targetPackageId, {
+                    projectRoot: root,
+                    customHome: opts.customHome,
+                    // 跨包子包存储由当前执行宿主持有，打开时收割遗留孤儿运行
+                    recoverOrphans: true,
+                });
+                ownsPackageStorage = true;
+            }
+            else {
+                // 回退分支与主路径共用 createStorage 单一事实源，确保 run 记录落在统一解析的库文件
+                const { createStorage } = await import("../storage/index.js");
+                storage = createStorage(targetPackageId, { projectRoot: root, customHome: opts.customHome, recoverOrphans: true });
+                ownsPackageStorage = true;
+            }
+            // 由本工厂直接创建的子包存储纳入级联释放清单（getStorageForPackage 注入方自管理生命周期）
+            if (ownsPackageStorage) {
+                this.packageStorages.add(storage);
+            }
+            const actionsMap = await loadActions(root, config.actionsDir, {
+                loader: opts.platform?.modules,
+            });
+            const runner = this.createRunner({
+                packageId: targetPackageId,
+                packageInstanceId: config.packageInstanceId || targetPackageId,
+                generationId: config.generationId || "1",
+                storage,
+                globalStorage: opts.globalStorage,
+                projectRoot: root,
+                projectConfig: config,
+                actions: actionsMap,
+                process: opts.process,
+                clock: opts.clock,
+                platform: opts.platform,
+                maxCallDepth: opts.maxCallDepth,
+                maxSubRuns: opts.maxSubRuns,
+                actionResolver: opts.actionResolver,
+                getStorageForPackage: opts.getStorageForPackage,
+                packageContextResolver: opts.packageContextResolver,
+                customHome: opts.customHome,
+            });
+            this.packageRunners.set(targetPackageId, runner);
+            return runner;
+        }
+        return undefined;
+    }
+    /**
+     * 释放跨包资源：遍历关闭全部子包 Runner 及其独立创建的存储连接。
+     *
+     * 幂等且并发安全：重复调用直接复用首次 Promise；子包存储异常不阻断其余释放；
+     * 仅关闭由本工厂构建子包 Runner 时独立创建的存储，外部注入的存储（如经
+     * packageContextResolver 传入的目标包自身存储）生命周期归所有者管理，不在此误关。
+     */
+    async dispose() {
+        if (this.disposePromise) {
+            return this.disposePromise;
+        }
+        this.disposePromise = this.disposeInternal();
+        return this.disposePromise;
+    }
+    async disposeInternal() {
+        // 深度优先递归释放子包 Runner（子 Runner 可能又构建了孙 Runner）
+        const children = Array.from(this.packageRunners.values());
+        this.packageRunners.clear();
+        await Promise.all(children.map(async (child) => {
+            try {
+                await child.dispose();
+            }
+            catch {
+                // 单个子 Runner 释放异常不阻断其余释放
+            }
+        }));
+        // 关闭由本工厂直接创建的子包存储（buildTargetPackageRunner 回退分支）
+        for (const storage of this.packageStorages) {
+            try {
+                const res = storage.close();
+                if (res && typeof res.then === "function") {
+                    await res;
+                }
+            }
+            catch {
+                // 存储重复关闭或已失效时忽略，保持释放链路继续
+            }
+        }
+        this.packageStorages.clear();
+    }
+}