@actiondock/core 2.10.0 → 2.12.0

package/dist/package/static-index.d.ts

@@ -6,11 +6,11 @@ import type { ActionSpec, PlaybookSpec } from "./types.js";
  * 入参不可变（同实例内复用解析结果的前提），字段与 App 实例的运行时只读状态一一对应。
  */
 export interface StaticIndexInput {
-    /** 包根目录（磁盘清单来源；缺省时仅聚合配置与内存注入来源） */
+    /** 包根目录（缺省时仅聚合配置与内存注入来源） */
     packageRoot?: string;
     /** 包唯一标识 */
     packageId: string;
-    /** 项目配置（Manifest v2 声明来源） */
+    /** 项目配置（规范化清单配置快照，单一事实源） */
     projectConfig: ProjectConfig;
 }
 /** Action 索引构建入参：静态事实来源之上叠加内存注入的 Action 定义集合 */
@@ -23,11 +23,8 @@ export interface StaticActionIndexInput extends StaticIndexInput {
  * 不产生全量模块导入与执行副作用。
  *
  * 聚合优先级（后者覆盖前者同名字段，缺省字段回退前者）：
- * - 磁盘声明式清单文件（actiondock.json）；
- * - 项目配置中声明的 actions（Manifest v2 格式）；
+ * - 项目清单配置快照中声明的 actions（Manifest v2 格式，单一事实源）；
  * - 内存显式注入的 Action 定义。
- *
- * 清单文件不存在属于合法空态；解析失败（损坏 JSON 等）输出告警并跳过清单部分。
  */
 export declare function buildStaticActionMap(input: StaticActionIndexInput): Map<string, ActionSpec>;
 /**

package/dist/package/static-index.js

@@ -1,7 +1,7 @@
 import { existsSync, readFileSync } from "node:fs";
 import { join, resolve } from "node:path";
 import { loadPlaybooks } from "../project/loader.js";
-import { loadManifest, MANIFEST_FILE_NAME } from "../project/manifest.js";
+import { MANIFEST_FILE_NAME } from "../project/manifest.js";
 /**
  * 将增量声明合并到既有 Action 规范之上（纯函数，单一事实源）。
  *
@@ -45,53 +45,23 @@ function mergeSpec(base, id, packageId, patch, packageRoot, policy = {}) {
  * 不产生全量模块导入与执行副作用。
  *
  * 聚合优先级（后者覆盖前者同名字段，缺省字段回退前者）：
- * - 磁盘声明式清单文件（actiondock.json）；
- * - 项目配置中声明的 actions（Manifest v2 格式）；
+ * - 项目清单配置快照中声明的 actions（Manifest v2 格式，单一事实源）；
  * - 内存显式注入的 Action 定义。
- *
- * 清单文件不存在属于合法空态；解析失败（损坏 JSON 等）输出告警并跳过清单部分。
  */
 export function buildStaticActionMap(input) {
     const { packageRoot, packageId, projectConfig, actionsMap } = input;
     const map = new Map();
-    // 读取声明式清单文件 (actiondock.json)
-    if (packageRoot) {
-        const manifestPath = join(packageRoot, MANIFEST_FILE_NAME);
-        // 文件不存在属于合法空态（无清单包）；解析失败（损坏 JSON 等）则输出告警并跳过清单部分
-        if (!existsSync(manifestPath)) {
-            // 合法空态：无清单文件，仅依赖后续配置与内存注入来源
-        }
-        else {
-            try {
-                const manifest = loadManifest(packageRoot);
-                if (manifest?.actions) {
-                    for (const [id, item] of Object.entries(manifest.actions)) {
-                        // 磁盘清单为最底层来源：无更低层可回退，tags 与 uses 缺省时归一为空数组
-                        map.set(id, mergeSpec(undefined, id, packageId, {
-                            ...item,
-                            tags: item.tags ?? [],
-                            uses: item.uses ?? [],
-                        }, packageRoot, {
-                            arrayFields: ["tags", "uses"],
-                            deriveFilePath: true,
-                        }));
-                    }
-                }
-            }
-            catch (err) {
-                console.warn(`[App] Failed to load manifest for package '${packageId}' from '${manifestPath}': ${err?.message || String(err)}`);
-            }
-        }
-    }
-    // 读取项目配置文件中声明的 actions (Manifest v2 格式)
+    // 读取规范化清单配置快照中声明的 actions (Manifest v2 格式)
     if (projectConfig && projectConfig.actions) {
         const rawActions = projectConfig.actions;
         if (typeof rawActions === "object" && rawActions !== null) {
             for (const [id, item] of Object.entries(rawActions)) {
-                // 配置声明层：覆盖磁盘清单层，entry 变化时重算物理路径；数组字段直传引用
-                map.set(id, mergeSpec(map.get(id), id, packageId, item, packageRoot, {
+                map.set(id, mergeSpec(undefined, id, packageId, {
+                    ...item,
+                    tags: item.tags ?? [],
+                    uses: item.uses ?? [],
+                }, packageRoot, {
                     arrayFields: ["tags", "uses"],
-                    arrayCopy: false,
                     deriveFilePath: true,
                 }));
             }
@@ -106,7 +76,7 @@ export function buildStaticActionMap(input) {
                 continue;
             }
         }
-        // 内存注入层：保留磁盘层解析出的 entry 与 filePath，仅覆盖动态定义相关字段
+        // 内存注入层：保留清单层解析出的 entry 与 filePath，仅覆盖动态定义相关字段
         map.set(id, mergeSpec(map.get(id), id, packageId, act, packageRoot, {
             arrayFields: ["tags", "uses"],
             preserveEntry: true,
@@ -127,7 +97,8 @@ export function buildStaticPlaybookMap(input) {
     if (packageRoot) {
         const playbooksDir = projectConfig?.playbooksDir || "playbooks";
         const dirPath = join(packageRoot, playbooksDir);
-        if (existsSync(dirPath)) {
+        const manifestPath = join(packageRoot, MANIFEST_FILE_NAME);
+        if (existsSync(manifestPath) || existsSync(dirPath)) {
             try {
                 const loaded = loadPlaybooks(packageRoot, playbooksDir);
                 for (const [id, def] of loaded) {

package/dist/package/types.d.ts

@@ -209,8 +209,14 @@ export interface PackageRuntimeInternalOptions extends PackageRuntimeOptions {
     identity?: PackageIdentity;
     /** 显式注入的项目级运行时存储实例 */
     storage?: RuntimeStorage;
-    /** 显式注入的全局运行时存储实例 */
+    /** 显式注入的全局运行时存储实例（优先级最高） */
     globalStorage?: RuntimeStorage;
+    /**
+     * Host 共享全局存储提供函数（同步求值，首次需要时才调用）。
+     * 优先级低于显式 globalStorage 注入，高于包自建全局库；
+     * 提供函数必须同步，因 RuntimeConfig 与 ctx.config.get() 的读取契约是同步的。
+     */
+    globalStorageProvider?: () => RuntimeStorage;
     /** 显式注入的事件接收器 */
     eventSink?: EventSink;
     /** 子任务动作调用委托器 */
@@ -237,6 +243,8 @@ export interface PackageRuntime {
     readonly packageRoot?: string;
     /** 项目配置对象（actiondock.json 解析结果） */
     readonly projectConfig: ProjectConfig;
+    /** 是否采用纯内存运行模式 */
+    readonly inMemory?: boolean;
     /**
      * 受信任内部调用方法（Host 或子任务执行主链调用入口）。
      * 委托内部 ExecutionService 执行，确保全生命周期指标与事件不发生分裂。
@@ -260,6 +268,8 @@ export interface PackageRuntime {
     startAction(id: string, input: JsonValue, options?: RunOptions): Promise<ExecutionTicket>;
     /** 查询任务执行记录列表 */
     listRuns(options?: ListRunsOptions): Promise<RunRecord[]>;
+    /** 统计符合条件的任务执行记录总数 */
+    countRuns?(options?: ListRunsOptions): Promise<number>;
     /** 查询指定运行标识的记录详情 */
     getRun(runId: string): Promise<RunRecord | undefined>;
     /** 取消指定在运行的任务 */
@@ -292,7 +302,7 @@ export interface PackageRuntime {
     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>;
@@ -304,10 +314,10 @@ export interface PackageRuntime {
     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>;
     /** 列出当前包在存储中的状态条目（含完整元数据） */
     listStateEntries?(options?: any): Promise<StateEntry[]>;
     /** 优雅关闭应用并收尾清理所有底层资源 */
@@ -320,4 +330,9 @@ export interface PackageRuntime {
  */
 export interface HostManagedPackageRuntime extends PackageRuntime {
     setActionInvoker(invoker?: ActionInvoker): void;
+    /**
+     * 内部存储准备入口（Host 持有者路径预热专用）：打开包存储并完成运行记录恢复，
+     * 只扩展内部装配契约，不加入公共服务端口。
+     */
+    prepareResources?(): Promise<void>;
 }

package/dist/platform/index.d.ts

@@ -1,3 +1,4 @@
 export * from "./types.js";
-export * from "./node-fs.js";
 export * from "./node.js";
+export * from "./module-loader.js";
+export * from "./loader-hook.js";

package/dist/platform/index.js

@@ -1,3 +1,4 @@
 export * from "./types.js";
-export * from "./node-fs.js";
 export * from "./node.js";
+export * from "./module-loader.js";
+export * from "./loader-hook.js";

package/dist/platform/loader-hook.d.ts

@@ -0,0 +1,32 @@
+/**
+ * 标准 ESM 解析上下文接口。
+ */
+export interface ResolveContext {
+    conditions: string[];
+    parentURL?: string;
+    importAttributes?: Record<string, string>;
+}
+/**
+ * 标准 ESM nextResolve 函数契约。
+ */
+export type NextResolve = (specifier: string, context?: ResolveContext) => Promise<{
+    format?: string | null;
+    shortCircuit?: boolean;
+    url: string;
+}>;
+/**
+ * 全链路 ESM 路径重映射解析钩子。
+ * 遵循 TypeScript NodeNext 模块规范与 Node.js 官方标准钩子协议：
+ * - 仅拦截处于 file: 上下文中的相对路径导入（./、../、.、..）；
+ * - 当目标请求路径在物理磁盘上不存在或为目录时：
+ *   - 若以 .js 结尾，自动探测是否存在同名 .ts 或 .tsx；若存在，重定向返回；
+ *   - 若以 .mjs 结尾，自动探测是否存在同名 .mts；若存在，重定向返回；
+ *   - 若以 .cjs 结尾，自动探测是否存在同名 .cts；若存在，重定向返回；
+ *   - 若无扩展名或为目录，自动探测补全 .ts、.tsx、.js、.mjs 以及目录 index 文件；
+ * - 针对已存在物理实体文件或非相对导入，全面透传 nextResolve。
+ */
+export declare function resolve(specifier: string, context: ResolveContext, nextResolve: NextResolve): Promise<{
+    format?: string | null;
+    shortCircuit?: boolean;
+    url: string;
+}>;

package/dist/platform/loader-hook.js

@@ -0,0 +1,90 @@
+import { statSync } from "node:fs";
+import { extname, join } from "node:path";
+import { fileURLToPath, pathToFileURL } from "node:url";
+/**
+ * 判断指定文件路径是否存在且为常规物理文件。
+ * 使用 throwIfNoEntry: false 避免 ENOENT 抛错开销，保持微秒级解析性能。
+ */
+function isPhysicalFile(filePath) {
+    try {
+        const stat = statSync(filePath, { throwIfNoEntry: false });
+        return stat !== undefined && stat.isFile();
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * 判断指定路径是否为物理目录。
+ */
+function isDirectory(filePath) {
+    try {
+        const stat = statSync(filePath, { throwIfNoEntry: false });
+        return stat !== undefined && stat.isDirectory();
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * 全链路 ESM 路径重映射解析钩子。
+ * 遵循 TypeScript NodeNext 模块规范与 Node.js 官方标准钩子协议：
+ * - 仅拦截处于 file: 上下文中的相对路径导入（./、../、.、..）；
+ * - 当目标请求路径在物理磁盘上不存在或为目录时：
+ *   - 若以 .js 结尾，自动探测是否存在同名 .ts 或 .tsx；若存在，重定向返回；
+ *   - 若以 .mjs 结尾，自动探测是否存在同名 .mts；若存在，重定向返回；
+ *   - 若以 .cjs 结尾，自动探测是否存在同名 .cts；若存在，重定向返回；
+ *   - 若无扩展名或为目录，自动探测补全 .ts、.tsx、.js、.mjs 以及目录 index 文件；
+ * - 针对已存在物理实体文件或非相对导入，全面透传 nextResolve。
+ */
+export async function resolve(specifier, context, nextResolve) {
+    const { parentURL } = context;
+    const isRelative = specifier.startsWith("./") ||
+        specifier.startsWith("../") ||
+        specifier === "." ||
+        specifier === "..";
+    if (isRelative && typeof parentURL === "string" && parentURL.startsWith("file:")) {
+        let targetUrl;
+        try {
+            targetUrl = new URL(specifier, parentURL);
+        }
+        catch {
+            return nextResolve(specifier, context);
+        }
+        const targetPath = fileURLToPath(targetUrl);
+        // 目标已存在且为常规文件，直接透传原生解析流程
+        if (isPhysicalFile(targetPath)) {
+            return nextResolve(specifier, context);
+        }
+        const isDir = isDirectory(targetPath);
+        const ext = extname(targetPath);
+        const candidates = [];
+        if (ext === ".js") {
+            const base = targetPath.slice(0, -3);
+            candidates.push(base + ".ts", base + ".tsx");
+        }
+        else if (ext === ".mjs") {
+            const base = targetPath.slice(0, -4);
+            candidates.push(base + ".mts");
+        }
+        else if (ext === ".cjs") {
+            const base = targetPath.slice(0, -4);
+            candidates.push(base + ".cts");
+        }
+        else if (!ext || isDir) {
+            if (!isDir) {
+                candidates.push(targetPath + ".ts", targetPath + ".tsx", targetPath + ".js", targetPath + ".mjs");
+            }
+            candidates.push(join(targetPath, "index.ts"), join(targetPath, "index.tsx"), join(targetPath, "index.js"), join(targetPath, "index.mjs"));
+        }
+        for (const candidate of candidates) {
+            if (isPhysicalFile(candidate)) {
+                const candidateUrl = pathToFileURL(candidate);
+                candidateUrl.search = targetUrl.search;
+                candidateUrl.hash = targetUrl.hash;
+                return nextResolve(candidateUrl.href, context);
+            }
+        }
+    }
+    return nextResolve(specifier, context);
+}

package/dist/{node → platform}/module-loader.d.ts

@@ -1,3 +1,15 @@
+export { resolve as esmResolveHook } from "./loader-hook.js";
+/**
+ * 获取模块加载器解析钩子模块的绝对 URL。
+ * 兼容源码开发态（.ts）、编译分发态（.js）及独立 ES 模块态（.mjs）。
+ */
+export declare function getLoaderHookUrl(): string;
+/**
+ * 注册全链路 ESM 路径重映射加载器钩子。
+ * 依托 Node.js 官方 module.register 标准机制，
+ * 在进程全局生命周期内只注册一次（基于 Symbol.for 保护）。
+ */
+export declare function registerModuleLoaderHook(): void;
 /**
  * 统一源码模块加载器接口。
  * 解耦 Action 与各类扩展模块的具体加载机制（如 ECMAScript 原生 import、tsx 动态转译加载等）。
@@ -39,6 +51,7 @@ export declare function unwrapDefaultExport<T = any>(moduleExports: any): T;
  * - 完全移除第三方转译运行时依赖
  */
 export declare class NodeModuleLoader implements ModuleLoader {
+    constructor();
     /**
      * 解析模块标识符与路径，严格要求显式扩展名且拒绝目录补全。
      *

package/dist/{node → platform}/module-loader.js

@@ -1,7 +1,51 @@
+import { register } from "node:module";
 import { existsSync, statSync } from "node:fs";
 import { dirname, extname, isAbsolute, resolve } from "node:path";
 import { fileURLToPath, pathToFileURL } from "node:url";
-import { ActionDockError, ACTION_LOAD_FAILED } from "../errors.js";
+import { ActionDockError, ACTION_LOAD_FAILED, MODULE_RESOLVE_FAILED } from "../errors.js";
+export { resolve as esmResolveHook } from "./loader-hook.js";
+/**
+ * 进程全局加载钩子防重注册标记 Symbol。
+ */
+const LOADER_HOOK_REGISTERED = Symbol.for("actiondock.esm.loader.hook.registered");
+/**
+ * 获取模块加载器解析钩子模块的绝对 URL。
+ * 兼容源码开发态（.ts）、编译分发态（.js）及独立 ES 模块态（.mjs）。
+ */
+export function getLoaderHookUrl() {
+    const jsUrl = new URL("./loader-hook.js", import.meta.url);
+    if (existsSync(fileURLToPath(jsUrl))) {
+        return jsUrl.href;
+    }
+    const tsUrl = new URL("./loader-hook.ts", import.meta.url);
+    if (existsSync(fileURLToPath(tsUrl))) {
+        return tsUrl.href;
+    }
+    const mjsUrl = new URL("./loader-hook.mjs", import.meta.url);
+    if (existsSync(fileURLToPath(mjsUrl))) {
+        return mjsUrl.href;
+    }
+    return jsUrl.href;
+}
+/**
+ * 注册全链路 ESM 路径重映射加载器钩子。
+ * 依托 Node.js 官方 module.register 标准机制，
+ * 在进程全局生命周期内只注册一次（基于 Symbol.for 保护）。
+ */
+export function registerModuleLoaderHook() {
+    const globalRef = globalThis;
+    if (globalRef[LOADER_HOOK_REGISTERED]) {
+        return;
+    }
+    globalRef[LOADER_HOOK_REGISTERED] = true;
+    try {
+        const hookUrl = getLoaderHookUrl();
+        register(hookUrl);
+    }
+    catch {
+        // 防御保护：环境不支持或受限场景安全降级
+    }
+}
 /**
  * Node 原生 TypeScript 与 ESM 模块支持的扩展名集合。
  */
@@ -36,6 +80,9 @@ export function unwrapDefaultExport(moduleExports) {
  * - 完全移除第三方转译运行时依赖
  */
 export class NodeModuleLoader {
+    constructor() {
+        registerModuleLoaderHook();
+    }
     /**
      * 解析模块标识符与路径，严格要求显式扩展名且拒绝目录补全。
      *
@@ -68,13 +115,13 @@ export class NodeModuleLoader {
         const candidateBasePath = isAbsolute(target) ? target : resolve(baseDir, target);
         const ext = extname(candidateBasePath);
         if (!ext) {
-            throw new Error(`Cannot resolve module '${specifier}' from '${parentPath || process.cwd()}': missing file extension. Explicit .ts, .mts, .js, or .mjs extension is required.`);
+            throw new ActionDockError(MODULE_RESOLVE_FAILED, `Cannot resolve module '${specifier}' from '${parentPath || process.cwd()}': missing file extension. Explicit .ts, .mts, .js, or .mjs extension is required.`);
         }
         if (!ALLOWED_EXTENSIONS.has(ext)) {
-            throw new Error(`Cannot resolve module '${specifier}' from '${parentPath || process.cwd()}': unsupported extension '${ext}'. Only .ts, .mts, .js, and .mjs are supported.`);
+            throw new ActionDockError(MODULE_RESOLVE_FAILED, `Cannot resolve module '${specifier}' from '${parentPath || process.cwd()}': unsupported extension '${ext}'. Only .ts, .mts, .js, and .mjs are supported.`);
         }
         if (!existsSync(candidateBasePath)) {
-            throw new Error(`Cannot resolve module '${specifier}' from '${parentPath || process.cwd()}': file not found`);
+            throw new ActionDockError(MODULE_RESOLVE_FAILED, `Cannot resolve module '${specifier}' from '${parentPath || process.cwd()}': file not found`);
         }
         let stat;
         try {

package/dist/platform/node.d.ts

@@ -1,10 +1,11 @@
-import type { ProcessAPI } from "@actiondock/sdk";
-import { type Clock } from "../runtime/clock.js";
-import { type ModuleLoader } from "../node/module-loader.js";
+import type { Logger, ProcessAPI } from "@actiondock/sdk";
+import { type Clock } from "../storage/clock.js";
+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 { FileSystem, RuntimePlatform, StorageFactory } from "./types.js";
+import type { EventSink } from "../runtime/events.js";
+import type { RuntimePlatform, StorageFactory } from "./types.js";
 /**
  * Node 平台构建配置选项。
  */
@@ -15,7 +16,10 @@ export interface NodePlatformOptions {
     dataDir?: string;
     /** 自定义家目录路径 */
     customHome?: string;
-    /** 文件系统安全沙箱根路径 */
+    /**
+     * 历史兼容保留属性（已废弃：文件系统抽象已由原生模块接管）。
+     * @deprecated 文件系统抽象已清理，该字段已无实际效果。
+     */
     rootDir?: string;
     /** 自定义 SQLite 驱动工厂函数（必须返回满足同步契约的 SqliteDriver，默认实例化 NodeSqliteDriver） */
     driverFactory?: (dbPath: string) => SqliteDriver;
@@ -27,12 +31,14 @@ export interface NodePlatformOptions {
     processManager?: ProcessManager;
     /** 自定义源码加载驱动（默认实例化 NodeModuleLoader） */
     modules?: ModuleLoader;
-    /** 自定义文件系统实现（默认实例化 NodeFileSystem） */
-    files?: FileSystem;
     /** 自定义时钟驱动（默认实例化 SystemClock） */
     clock?: Clock;
     /** 自定义存储工厂（默认基于 NodeSqliteDriver 构造） */
     storage?: StorageFactory;
+    /** 可选注入的执行事件接收器 */
+    eventSink?: EventSink;
+    /** 可选注入的统一日志记录器 */
+    logger?: Logger;
 }
 /**
  * 创建 Node 运行时平台实例。
@@ -40,9 +46,14 @@ export interface NodePlatformOptions {
  * - NodeSqliteDriver 同步持久化存储驱动
  * - NodeProcessDriver 原生进程驱动与 ProcessManager 受管进程引擎
  * - NodeModuleLoader 原生源码加载器
- * - NodeFileSystem 文件系统
  * - SystemClock 系统时钟
  *
+ * 资源按需装配原则：
+ * - clock 与存储工厂可立即创建（存储工厂本身不打开任何数据库）；
+ * - process 与 modules 采用缓存访问器，首次真正访问时才装配默认驱动，
+ *   静态发现等旁观路径不触发进程管理器与模块加载钩子的创建成本；
+ * - 模块加载钩子注册收敛至 NodeModuleLoader 构造内部，不再在平台工厂入口执行。
+ *
  * @param options 平台配置选项
  */
 export declare function createNodePlatform(options?: NodePlatformOptions): RuntimePlatform;

package/dist/platform/node.js

@@ -1,12 +1,12 @@
 import { existsSync, mkdirSync } from "node:fs";
 import { dirname } from "node:path";
-import { SystemClock } from "../runtime/clock.js";
-import { NodeModuleLoader } from "../node/module-loader.js";
+import { ActionDockError, STORAGE_INIT_FAILED } from "../errors.js";
+import { SystemClock } from "../storage/clock.js";
+import { NodeModuleLoader } from "./module-loader.js";
 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 { NodeFileSystem } from "./node-fs.js";
 function ensureDirectoryForDb(dbPath) {
     if (dbPath !== ":memory:") {
         const dir = dirname(dbPath);
@@ -18,7 +18,7 @@ function ensureDirectoryForDb(dbPath) {
                 if (err?.code === "EEXIST" || err?.code === "EISDIR") {
                     return;
                 }
-                throw new Error(`Failed to create data directory '${dir}' for database '${dbPath}': ${err?.message || String(err)}`, { cause: err });
+                throw new ActionDockError(STORAGE_INIT_FAILED, `Failed to create data directory '${dir}' for database '${dbPath}': ${err?.message || String(err)}`, { cause: err });
             }
         }
     }
@@ -29,25 +29,48 @@ function ensureDirectoryForDb(dbPath) {
  * - NodeSqliteDriver 同步持久化存储驱动
  * - NodeProcessDriver 原生进程驱动与 ProcessManager 受管进程引擎
  * - NodeModuleLoader 原生源码加载器
- * - NodeFileSystem 文件系统
  * - SystemClock 系统时钟
  *
+ * 资源按需装配原则：
+ * - clock 与存储工厂可立即创建（存储工厂本身不打开任何数据库）；
+ * - process 与 modules 采用缓存访问器，首次真正访问时才装配默认驱动，
+ *   静态发现等旁观路径不触发进程管理器与模块加载钩子的创建成本；
+ * - 模块加载钩子注册收敛至 NodeModuleLoader 构造内部，不再在平台工厂入口执行。
+ *
  * @param options 平台配置选项
  */
 export function createNodePlatform(options = {}) {
     const platformName = options.name ?? "node";
     const clock = options.clock ?? new SystemClock();
-    const files = options.files ?? new NodeFileSystem({ rootDir: options.rootDir });
-    const modules = options.modules ?? new NodeModuleLoader();
-    const processDriver = options.processDriver ?? new NodeProcessDriver();
-    const processManager = options.processManager ?? new ProcessManager({ driver: processDriver });
-    const process = options.process ??
-        processManager.forOwner({
-            tenantId: "default",
-            principalId: "default",
-            packageInstanceId: "default",
-            generationId: "default",
-        });
+    // - 进程接口缓存访问器：显式注入直接透传；缺省时按需装配一次默认驱动链
+    let cachedProcess;
+    const resolveProcess = () => {
+        if (options.process) {
+            return options.process;
+        }
+        if (!cachedProcess) {
+            const processDriver = options.processDriver ?? new NodeProcessDriver();
+            const processManager = options.processManager ?? new ProcessManager({ driver: processDriver });
+            cachedProcess = processManager.forOwner({
+                tenantId: "default",
+                principalId: "default",
+                packageInstanceId: "default",
+                generationId: "default",
+            });
+        }
+        return cachedProcess;
+    };
+    // - 模块加载器缓存访问器：首次访问时才创建默认加载器（构造内部注册加载钩子）
+    let cachedModules;
+    const resolveModules = () => {
+        if (options.modules) {
+            return options.modules;
+        }
+        if (!cachedModules) {
+            cachedModules = new NodeModuleLoader();
+        }
+        return cachedModules;
+    };
     const createDriver = options.driverFactory ?? ((dbPath) => new NodeSqliteDriver(dbPath));
     const storage = options.storage ?? {
         createStorage(packageId, opts) {
@@ -65,6 +88,7 @@ export function createNodePlatform(options = {}) {
                 driver: createDriver(dbPath),
                 recoverOrphans: opts?.recoverOrphans === true,
                 retentionPolicy: opts?.retentionPolicy,
+                logger: options.logger,
             });
         },
         createGlobalStorage(opts) {
@@ -83,15 +107,21 @@ export function createNodePlatform(options = {}) {
                 clock,
                 driver: createDriver(dbPath),
                 recoverOrphans: opts?.recoverOrphans === true,
+                logger: options.logger,
             });
         },
     };
-    return {
+    const platform = {
         name: platformName,
         clock,
-        files,
-        modules,
-        process,
+        eventSink: options.eventSink,
+        get process() {
+            return resolveProcess();
+        },
+        get modules() {
+            return resolveModules();
+        },
         storage,
     };
+    return platform;
 }