@actiondock/core 2.6.0 → 2.8.0

package/dist/service/sse-stream.js

@@ -0,0 +1,139 @@
+import { ActionDockError, EVENT_CURSOR_EXPIRED, REMOTE_STREAM_UNAVAILABLE } from "../errors.js";
+import { assertSecureTransport } from "../profile/client.js";
+import { normalizeServerUrl } from "../profile/manager.js";
+import { getInsecureDispatcher } from "../server/dispatcher.js";
+import { parseSseMessages } from "./sse-parser.js";
+/**
+ * 将 SSE 消息载荷解码为统一执行事件。
+ *
+ * 非 JSON 数据行直接忽略；finish 事件取 data.result 字段，其余事件字段展开合并。
+ */
+export function decodeExecutionEvent(msg, runId) {
+    try {
+        const data = JSON.parse(msg.data);
+        if (msg.event === "finish") {
+            return {
+                eventId: msg.id ?? data.eventId,
+                type: "finish",
+                runId,
+                timestamp: new Date().toISOString(),
+                result: data.result || data,
+            };
+        }
+        else {
+            return {
+                eventId: msg.id ?? data.eventId,
+                type: (msg.event || "message"),
+                runId,
+                timestamp: new Date().toISOString(),
+                ...data,
+            };
+        }
+    }
+    catch {
+        // 忽略非 JSON 数据行
+        return undefined;
+    }
+}
+/**
+ * 订阅远端运行事件流（Server-Sent Events）。
+ *
+ * 候选路由探测与自动回退：优先尝试标准 v2 路由 /api/v2/runs/:runId/events，
+ * 失败时回退至既有路由 /api/v2/runs/:runId/stream；
+ * 全部候选均不可用（网络异常或非流式响应）时抛出携带各候选 URL 与
+ * 失败原因的 REMOTE_STREAM_UNAVAILABLE 聚合错误，严禁以空流伪装正常。
+ */
+export async function* streamRemoteEvents(serverUrl, runId, token, options) {
+    assertSecureTransport(serverUrl, token, {
+        allowInsecureHttp: options?.allowInsecureHttp,
+        insecure: options?.insecure,
+    });
+    const base = normalizeServerUrl(serverUrl);
+    const runRoute = `runs/${encodeURIComponent(runId)}`;
+    // 候选路由：v2 /events -> v2 /stream
+    const candidateUrls = [
+        `${base}/api/v2/${runRoute}/events`,
+        `${base}/api/v2/${runRoute}/stream`,
+    ];
+    const headers = {
+        Accept: "text/event-stream",
+    };
+    if (token && token.trim()) {
+        headers.Authorization = `Bearer ${token.trim()}`;
+    }
+    if (options?.after !== undefined) {
+        headers["Last-Event-ID"] = String(options.after);
+    }
+    /**
+     * 依次尝试全部候选路由，返回首个可用响应。
+     */
+    async function resolveStreamCandidate() {
+        const candidateFailures = [];
+        for (const url of candidateUrls) {
+            const fetchInit = {
+                headers,
+                signal: options?.signal,
+            };
+            if (options?.dispatcher) {
+                fetchInit.dispatcher = options.dispatcher;
+            }
+            else if (options?.insecure) {
+                fetchInit.dispatcher = getInsecureDispatcher();
+            }
+            try {
+                const resp = await fetch(url, fetchInit);
+                if (resp.status === 410) {
+                    let errJson;
+                    try {
+                        errJson = await resp.json();
+                    }
+                    catch { }
+                    throw new ActionDockError(errJson?.error?.code || EVENT_CURSOR_EXPIRED, errJson?.error?.message || "Event cursor has expired", errJson?.error?.details);
+                }
+                if (resp.ok && resp.body) {
+                    return { ok: true, body: resp.body };
+                }
+                candidateFailures.push({
+                    url,
+                    reason: `HTTP ${resp.status} ${resp.statusText || ""}`.trim(),
+                });
+            }
+            catch (err) {
+                if (err?.code === "EVENT_CURSOR_EXPIRED") {
+                    throw err;
+                }
+                candidateFailures.push({
+                    url,
+                    reason: err?.message ? `${err.name || "Error"}: ${err.message}` : String(err),
+                });
+            }
+        }
+        return { ok: false, candidateFailures };
+    }
+    function buildStreamUnavailableError(candidateFailures) {
+        const summary = candidateFailures
+            .map((f) => `${f.url} (${f.reason})`)
+            .join(", ");
+        return new ActionDockError(REMOTE_STREAM_UNAVAILABLE, `REMOTE_STREAM_UNAVAILABLE: All event stream candidates failed for run '${runId}': ${summary}`, {
+            runId,
+            candidates: candidateFailures.map((f) => ({ url: f.url, reason: f.reason })),
+        });
+    }
+    const res = await resolveStreamCandidate();
+    if (!res.ok) {
+        throw buildStreamUnavailableError(res.candidateFailures);
+    }
+    try {
+        for await (const msg of parseSseMessages(res.body, { signal: options?.signal })) {
+            const evt = decodeExecutionEvent(msg, runId);
+            if (evt)
+                yield evt;
+        }
+    }
+    catch (err) {
+        if (err.name === "AbortError" || options?.signal?.aborted) {
+            return;
+        }
+        throw err;
+    }
+}

package/dist/service/types.d.ts

@@ -0,0 +1,272 @@
+import type { ActionRef, ExecutionEvent, ExecutionResult, JsonValue, RunRecord } from "@actiondock/sdk";
+import type { ActionSpec, ActionSummary, ListActionsOptions, PackageInfo, PackageRuntime, PackageRuntimeOptions, PlaybookSpec, PlaybookSummary } from "../package/types.js";
+import type { CancelResult, ExecutionTicket } from "../execution/types.js";
+import type { ActionDockHostOptions } from "../host/types.js";
+import type { RuntimePlatform } from "../platform/types.js";
+import type { StateEntry } from "../storage/types.js";
+import { ActionDockError, type ErrorCode, PROTOCOL_UNSUPPORTED, SERVICE_RESULT_UNKNOWN, SERVICE_CLOSED } from "../errors.js";
+/**
+ * 公开运行控制选项（RunOptions）。
+ * 面向外部调用方的公开契约，彻底剥离内部 Lineage 字段，严禁污染内部运行时状态。
+ */
+export interface RunOptions {
+    /** 外部传入的 AbortSignal 取消信号 */
+    signal?: AbortSignal;
+    /** 最大超时时间（毫秒） */
+    timeoutMs?: number;
+    /** 执行级临时配置覆盖字典 */
+    config?: Record<string, JsonValue>;
+    /** 幂等请求标识 */
+    requestId?: string;
+}
+/**
+ * 统一协议版本常量。
+ */
+export declare const ACTIONDOCK_PROTOCOL_VERSION = "2.0";
+/**
+ * 服务端/通信协议错误码常量（单一事实源引用自 errors.ts）。
+ */
+export { PROTOCOL_UNSUPPORTED, SERVICE_RESULT_UNKNOWN, SERVICE_CLOSED };
+/**
+ * 结构化服务通信异常类。
+ */
+export declare class ServiceError extends ActionDockError {
+    readonly details?: Record<string, unknown>;
+    constructor(code: ErrorCode, message: string, details?: Record<string, unknown>);
+}
+/**
+ * 服务关闭超时异常类。
+ */
+export declare class CloseTimeoutError extends Error {
+    readonly runIds?: string[];
+    constructor(message?: string, runIds?: string[]);
+}
+/**
+ * 配置项安全视图契约。
+ * 屏蔽敏感配置原文，仅暴露是否已配置、是否为秘密及实际解析来源。
+ */
+export interface ConfigValueView {
+    /** 配置项键名 */
+    key: string;
+    /** 是否已显式配置或存在有效值 */
+    configured: boolean;
+    /** 是否为秘密敏感配置 */
+    secret: boolean;
+    /** 配置值实际解析来源 */
+    source: string;
+    /** 非秘密配置的实际数据值 */
+    value?: JsonValue;
+}
+/**
+ * 状态作用域与筛选控制选项。
+ */
+export interface StateScopeOptions {
+    /** 显式绑定的 Action 标识 */
+    actionId?: string;
+    /** 显式子命名空间（相对于 Action 根命名空间） */
+    namespace?: string;
+    /** 存活有效期（秒），仅在写入状态时生效 */
+    ttl?: number;
+    /** 键名前缀过滤匹配 */
+    prefix?: string;
+    /** 是否清空所有条目 */
+    all?: boolean;
+    /** 是否返回完整条目详情 */
+    detail?: boolean;
+}
+/**
+ * 任务运行记录列表查询选项。
+ */
+export interface ListRunsOptions {
+    /** 目标包唯一标识 */
+    packageId?: string;
+    /** Action 动作唯一标识 */
+    actionId?: string;
+    /** 运行终态状态筛选 */
+    status?: string;
+    /** 模糊意图检索模式 */
+    intent?: string;
+    /** 最大返回记录条数限制 */
+    limit?: number;
+}
+/**
+ * 远程服务连接配置选项。
+ */
+export interface RemoteServiceOptions {
+    /** 远端 ActionDock 服务 HTTP 根地址 */
+    serverUrl: string;
+    /** 鉴权 Bearer Token（可选） */
+    token?: string;
+    /** 是否允许向非回环地址发送明文 HTTP 请求（默认 false） */
+    allowInsecureHttp?: boolean;
+    /** 是否跳过 TLS 证书合法性校验（用于局域网自签证书） */
+    insecure?: boolean;
+    /** 自定义底层 HTTP 调度器（平台中立） */
+    dispatcher?: unknown;
+    /** 请求超时时间（毫秒） */
+    timeoutMs?: number;
+    /** 轮询等待基准底线超时时间（毫秒，默认 60000ms） */
+    baseTimeoutMs?: number;
+    /** 是否启用配置与状态管理端口（默认 true） */
+    enableManagement?: boolean;
+}
+/**
+ * 资产与元数据发现服务端口。
+ */
+export interface DiscoveryPort {
+    /** 列出已注册的所有宏包元数据 */
+    listPackages(): Promise<PackageInfo[]>;
+    /** 列出所有可用的 Action 摘要 */
+    listActions(options?: ListActionsOptions): Promise<ActionSummary[]>;
+    /** 查询指定 Action 的规范结构与模式定义 */
+    describeAction(ref: ActionRef | string): Promise<ActionSpec>;
+    /** 列出可用的 Playbook 规程摘要 */
+    listPlaybooks(options?: {
+        intent?: string;
+        package?: string;
+    }): Promise<PlaybookSummary[]>;
+    /** 查询指定 Playbook 的规范内容与操作指南 */
+    describePlaybook(id: string): Promise<PlaybookSpec>;
+}
+/**
+ * Action 执行调用服务端口。
+ */
+export interface ExecutionPort {
+    /** 同步执行指定 Action 并等待终态结果 */
+    run(ref: ActionRef | string, input?: unknown, options?: RunOptions): Promise<ExecutionResult>;
+    /** 异步启动指定 Action 并立即返回任务执行票据 */
+    start(ref: ActionRef | string, input?: unknown, options?: RunOptions): Promise<ExecutionTicket>;
+}
+/**
+ * 运行事件订阅控制选项。
+ */
+export interface RunEventSubscriptionOptions {
+    /** 起始游标位置（序号或标识） */
+    after?: number | string;
+    /** 外部取消信号 */
+    signal?: AbortSignal;
+    /** 最大背压队列深度 */
+    maxQueueSize?: number;
+}
+/**
+ * 任务执行事件流服务端口。
+ */
+export interface EventsPort {
+    /** 订阅指定运行的事件流 */
+    events(runId: string, options?: RunEventSubscriptionOptions): AsyncIterable<ExecutionEvent>;
+}
+/**
+ * 任务运行记录管理服务端口。
+ */
+export interface RunsPort {
+    /** 查询任务执行记录列表 */
+    list(query?: ListRunsOptions): Promise<RunRecord[]>;
+    /** 查询指定运行标识的记录详情 */
+    get(runId: string): Promise<RunRecord | undefined>;
+    /** 取消指定在运行的任务 */
+    cancel(runId: string, reason?: string): Promise<CancelResult>;
+    /** 清空历史任务运行记录 */
+    clear?(options?: {
+        packageId?: string;
+        actionId?: string;
+        status?: string;
+    }): Promise<number>;
+}
+/**
+ * 配置项管理服务端口。
+ */
+export interface ConfigPort {
+    /** 获取指定包的单项配置安全视图 */
+    get(packageId: string, key: string): Promise<ConfigValueView>;
+    /** 写入或覆盖指定包的配置项 */
+    set(packageId: string, key: string, value: JsonValue): Promise<void>;
+    /** 删除指定包的指定配置项 */
+    delete(packageId: string, key: string): Promise<boolean>;
+    /** 列出指定包所有配置项的安全视图列表 */
+    list(packageId: string): Promise<ConfigValueView[]>;
+}
+/**
+ * 状态存储管理服务端口。
+ */
+export interface StatePort {
+    /** 获取指定包指定动作的作用域状态值 */
+    get<T extends JsonValue = JsonValue>(packageId: string, actionId: string, key: string, options?: StateScopeOptions): Promise<T | undefined>;
+    /** 写入指定包指定动作的作用域状态值 */
+    set<T extends JsonValue = JsonValue>(packageId: string, actionId: string, key: string, value: T, options?: StateScopeOptions): Promise<void>;
+    /** 删除指定包指定动作的作用域状态项 */
+    delete(packageId: string, actionId: string, key: string, options?: StateScopeOptions): Promise<boolean>;
+    /** 列出指定包指定动作在存储中的状态键名列表 */
+    list(packageId: string, actionId: string, options?: StateScopeOptions): Promise<string[]>;
+    /** 清空指定包指定动作在存储中的状态条目 */
+    clear(packageId: string, actionId: string, options?: StateScopeOptions): Promise<number>;
+    /** 列出指定包在存储中的状态条目（含完整元数据） */
+    listEntries?(packageId: string, options?: any): Promise<StateEntry[]>;
+}
+/**
+ * ActionDock 统一聚合服务端口契约。
+ */
+export interface ActionDockService {
+    /** 获取所有包的基础信息概览 */
+    info(): Promise<PackageInfo[]>;
+    /** 发现服务端口 */
+    discovery: DiscoveryPort;
+    /** 执行服务端口 */
+    execution: ExecutionPort;
+    /** 运行记录服务端口 */
+    runs: RunsPort;
+    /** 执行事件流服务端口（可选，若通道不支持流式事件则为 undefined） */
+    events?: EventsPort;
+    /** 管理服务端口（可选，若服务端未开启管理能力则为 undefined） */
+    management?: {
+        config: ConfigPort;
+        state: StatePort;
+    };
+    /** 关闭服务并释放底层关联资源 */
+    close(options?: {
+        timeoutMs?: number;
+        graceMs?: number;
+    }): Promise<void>;
+}
+/**
+ * 创建 ActionDock 本地服务选项。
+ */
+export interface CreateActionDockOptions {
+    /** 模式类型（可选） */
+    type?: "local";
+    /** 单包 PackageRuntime 初始化配置 */
+    runtimeOptions?: PackageRuntimeOptions;
+    /** 宿主 Host 初始化配置 */
+    hostOptions?: ActionDockHostOptions;
+    /** 当前工程根目录绝对路径 */
+    projectRoot?: string;
+    /** 是否自动加载当前工程（默认为 true） */
+    autoLoadCurrentProject?: boolean;
+    /** 预注册包配置列表（PackageRuntime 实例、PackageRuntimeOptions 配置或包目录绝对物理路径） */
+    packages?: Array<PackageRuntime | PackageRuntimeOptions | string>;
+    /** 自定义 ActionDock 家目录 */
+    customHome?: string;
+    /** 是否采用纯内存运行模式 */
+    inMemory?: boolean;
+    /** 自定义全局数据存储目录 */
+    dataDir?: string;
+    /** 是否扫描已软链接的外部包 */
+    scanLinkedPackages?: boolean;
+    /** 运行时平台适配 */
+    platform?: RuntimePlatform;
+    /** 是否以数据目录持有者身份打开本地存储 */
+    recoverOrphans?: boolean;
+    /** 是否开启管理端口（默认 true） */
+    enableManagement?: boolean;
+}
+/**
+ * 连接 ActionDock 远程服务选项。
+ *
+ * 与 RemoteServiceOptions 字段同源：远程服务连接配置为单一事实源，
+ * 此处仅放宽 serverUrl 必选性并补充独立家目录差异字段，公开形状不变。
+ */
+export interface ConnectActionDockOptions extends Omit<RemoteServiceOptions, "serverUrl"> {
+    /** 远端 ActionDock 服务 HTTP 根地址（连接入口负责解析，此处可缺省） */
+    serverUrl?: string;
+    /** 自定义 ActionDock 家目录（用于读取自定义位置 profiles.json） */
+    customHome?: string;
+}

package/dist/service/types.js

@@ -0,0 +1,32 @@
+import { ActionDockError, PROTOCOL_UNSUPPORTED, SERVICE_RESULT_UNKNOWN, SERVICE_CLOSED, } from "../errors.js";
+/**
+ * 统一协议版本常量。
+ */
+export const ACTIONDOCK_PROTOCOL_VERSION = "2.0";
+/**
+ * 服务端/通信协议错误码常量（单一事实源引用自 errors.ts）。
+ */
+export { PROTOCOL_UNSUPPORTED, SERVICE_RESULT_UNKNOWN, SERVICE_CLOSED };
+/**
+ * 结构化服务通信异常类。
+ */
+export class ServiceError extends ActionDockError {
+    details;
+    constructor(code, message, details) {
+        super(code, message, details);
+        this.name = "ServiceError";
+        this.details = details;
+        Object.setPrototypeOf(this, ServiceError.prototype);
+    }
+}
+/**
+ * 服务关闭超时异常类。
+ */
+export class CloseTimeoutError extends Error {
+    runIds;
+    constructor(message = "Service close operation timed out", runIds) {
+        super(message);
+        this.name = "CloseTimeoutError";
+        this.runIds = runIds;
+    }
+}

package/dist/storage/data-dir-lock.js

@@ -2,6 +2,7 @@ import { existsSync, mkdirSync, renameSync, statSync, writeFileSync } from "node
 import { hostname } from "node:os";
 import { dirname, join } from "node:path";
 import { randomUUID } from "node:crypto";
+import { DATA_DIR_IN_USE, DATA_DIR_RECOVERY_REQUIRED } from "../errors.js";
 import { acquireDirectoryLock, cleanStaleQuarantines, isProcessAlive, parseQuarantineTimestamp, safeReleaseLock as coreSafeReleaseLock, safeRemoveStaleReclaimGuard, safeRollbackLock, } from "./lock-core.js";
 const LOCK_DIR_NAME = ".actiondock.data.lock";
 export { isProcessAlive, parseQuarantineTimestamp, cleanStaleQuarantines, safeRemoveStaleReclaimGuard, safeRollbackLock, };
@@ -89,8 +90,12 @@ export class DataDirLock {
                 renameSync(tmpPath, this.lockDirPath);
             }
         }
-        catch {
-            // 忽略刷新写入异常
+        catch (err) {
+            // 元数据刷新失败不可中断宿主启动，但绝不能静默吞没：childPids 是
+            // DATA_DIR_RECOVERY_REQUIRED 判定的唯一依据，丢失会使恢复决策退化为直接接管。
+            // 输出单行告警携带原因，保证降级事件可观测。
+            const reason = err instanceof Error ? err.message : String(err);
+            console.warn(`[actiondock] data dir lock metadata flush failed (lock='${this.lockDirPath}'): ${reason}`);
         }
     }
     /**
@@ -150,7 +155,7 @@ export class DataDirLock {
             acquireTimeoutMs: options.acquireTimeoutMs,
             createLockError(message) {
                 const timeoutErr = new Error(message);
-                timeoutErr.code = "DATA_DIR_IN_USE";
+                timeoutErr.code = DATA_DIR_IN_USE;
                 return timeoutErr;
             },
             messages: {
@@ -166,14 +171,14 @@ export class DataDirLock {
                 const holderPid = info.pid;
                 if (isProcessAlive(holderPid)) {
                     const inUseErr = new Error(`DATA_DIR_IN_USE: Data directory '${dataDir}' is in use by another active Host process (PID ${holderPid})`);
-                    inUseErr.code = "DATA_DIR_IN_USE";
+                    inUseErr.code = DATA_DIR_IN_USE;
                     throw inUseErr;
                 }
                 // 主进程已死亡，检查关联子进程存活状态
                 const activeChildren = (info.childPids || []).filter((childPid) => isProcessAlive(childPid));
                 if (activeChildren.length > 0) {
                     const recoveryErr = new Error(`DATA_DIR_RECOVERY_REQUIRED: Data directory recovery required for '${dataDir}': previous host (PID ${holderPid}) exited but child processes (${activeChildren.join(", ")}) are still running`);
-                    recoveryErr.code = "DATA_DIR_RECOVERY_REQUIRED";
+                    recoveryErr.code = DATA_DIR_RECOVERY_REQUIRED;
                     throw recoveryErr;
                 }
             },

package/dist/storage/driver.d.ts

@@ -1,7 +1,8 @@
 import { normalizeSqliteParams } from "./params.js";
+import { NodeSqliteDriver } from "./sqlite-driver.js";
 import type { SqliteDriver } from "./types.js";
 export type SqliteDriverFactory = (dbPath: string) => SqliteDriver;
-export { normalizeSqliteParams };
+export { normalizeSqliteParams, NodeSqliteDriver };
 /**
  * 创建默认 SQLite 驱动实例。
  * 基于 Node.js 原生 node:sqlite (DatabaseSync) 驱动实现，严格同步契约。

package/dist/storage/driver.js

@@ -1,59 +1,10 @@
-import { createRequire } from "node:module";
 import { normalizeSqliteParams } from "./params.js";
-export { normalizeSqliteParams };
-/** ESM 环境下可用的 CommonJS require，用于动态加载 node:sqlite */
-const cjsRequire = createRequire(import.meta.url);
+import { NodeSqliteDriver } from "./sqlite-driver.js";
+export { normalizeSqliteParams, NodeSqliteDriver };
 /**
  * 创建默认 SQLite 驱动实例。
  * 基于 Node.js 原生 node:sqlite (DatabaseSync) 驱动实现，严格同步契约。
  */
 export function createDefaultSqliteDriver(dbPath) {
-    try {
-        const { DatabaseSync } = cjsRequire("node:sqlite");
-        const db = new DatabaseSync(dbPath);
-        return {
-            exec(sql) {
-                db.exec(sql);
-            },
-            prepare(sql) {
-                const stmt = db.prepare(sql);
-                return {
-                    run(...args) {
-                        const params = normalizeSqliteParams(args);
-                        const res = stmt.run(...params);
-                        return { changes: res.changes, lastInsertRowid: res.lastInsertRowid };
-                    },
-                    get(...args) {
-                        const params = normalizeSqliteParams(args);
-                        return stmt.get(...params);
-                    },
-                    all(...args) {
-                        const params = normalizeSqliteParams(args);
-                        return stmt.all(...params);
-                    },
-                };
-            },
-            transaction(fn) {
-                db.exec("BEGIN");
-                try {
-                    const res = fn();
-                    if (res !== null && (typeof res === "object" || typeof res === "function") && typeof res.then === "function") {
-                        throw new Error("Async transactions are not allowed in SQLite");
-                    }
-                    db.exec("COMMIT");
-                    return res;
-                }
-                catch (e) {
-                    db.exec("ROLLBACK");
-                    throw e;
-                }
-            },
-            close() {
-                db.close();
-            },
-        };
-    }
-    catch (err) {
-        throw new Error(`Failed to initialize SQLite driver: ${err?.message || String(err)}`);
-    }
+    return new NodeSqliteDriver(dbPath);
 }

package/dist/storage/index.d.ts

@@ -2,6 +2,7 @@ import type { RuntimeStorage } from "./types.js";
 export { DataDirLock, type DataDirLockInfo, isProcessAlive, } from "./data-dir-lock.js";
 export * from "./clock.js";
 export * from "./driver.js";
+export * from "./sqlite-driver.js";
 export * from "./lazy.js";
 export * from "./mask.js";
 export * from "./params.js";

package/dist/storage/index.js

@@ -4,6 +4,7 @@ import { SqliteRuntimeStorage } from "./sqlite.js";
 export { DataDirLock, isProcessAlive, } from "./data-dir-lock.js";
 export * from "./clock.js";
 export * from "./driver.js";
+export * from "./sqlite-driver.js";
 export * from "./lazy.js";
 export * from "./mask.js";
 export * from "./params.js";

package/dist/storage/lock-core.d.ts

@@ -1,3 +1,5 @@
+import { isProcessAlive } from "../utils/process.js";
+export { isProcessAlive };
 /**
  * 目录锁元数据通用契约。
  * 工程锁与数据目录锁共用同一物理布局，仅部分字段按场景取舍。
@@ -30,12 +32,6 @@ export interface ReclaimGuardState {
     holderPid?: number;
     guardToken?: string;
 }
-/**
- * 检查目标进程是否处于存活状态。
- *
- * @param pid 待检测的进程标识符
- */
-export declare function isProcessAlive(pid: number): boolean;
 /**
  * 读取排他锁元数据并执行宽限期检测。
  */

package/dist/storage/lock-core.js

@@ -1,6 +1,10 @@
 import fs, { existsSync, mkdirSync, readdirSync, readFileSync, renameSync, rmSync, statSync, writeFileSync, } from "node:fs";
 import { basename, dirname, join } from "node:path";
 import { randomUUID } from "node:crypto";
+import { isProcessAlive } from "../utils/process.js";
+// isProcessAlive 已上移至 utils/process.ts（跨域通用谓词单一事实源），
+// 此处仅保留 re-export 兼容旧引用路径
+export { isProcessAlive };
 /**
  * 目录锁内核（单一事实源）。
  *
@@ -16,23 +20,6 @@ import { randomUUID } from "node:crypto";
  */
 const METADATA_FILE = "metadata.json";
 const RECLAIM_SUFFIX = ".reclaim";
-/**
- * 检查目标进程是否处于存活状态。
- *
- * @param pid 待检测的进程标识符
- */
-export function isProcessAlive(pid) {
-    if (typeof pid !== "number" || isNaN(pid) || pid <= 0) {
-        return false;
-    }
-    try {
-        process.kill(pid, 0);
-        return true;
-    }
-    catch (err) {
-        return Boolean(err && err.code === "EPERM");
-    }
-}
 /**
  * 同步休眠指定毫秒数。
  */

package/dist/storage/params.d.ts

@@ -1,13 +1,7 @@
 /**
  * SQLite 绑定参数规范化共享纯函数。
  *
- * 单一事实源：主线程驱动（core 默认驱动与 runtime-node 的 NodeSqliteDriver）
- * 与 WorkerSqliteDriver 的 worker 内联脚本均使用本模块生成的同一份实现。
- *
- * 工程说明：worker 内联脚本以字符串形式 eval 执行、无法直接 import 模块，
- * 因此 worker 侧通过 Function.prototype.toString 将本函数源码序列化注入脚本。
- * 该函数必须保持完全自包含：仅依赖运行时全局 Buffer 与 Uint8Array，
- * 不得引用任何模块作用域内的其他标识符，也不得引入会被打包器改写的外部闭包，
- * 否则序列化注入后将在 worker 作用域内产生未定义引用。
+ * 单一事实源：各同步驱动（如 NodeSqliteDriver）统一使用本实现，
+ * 避免参数归一逻辑出现双实现漂移。
  */
 export declare function normalizeSqliteParams(args: any[]): any[];

package/dist/storage/params.js

@@ -1,14 +1,8 @@
 /**
  * SQLite 绑定参数规范化共享纯函数。
  *
- * 单一事实源：主线程驱动（core 默认驱动与 runtime-node 的 NodeSqliteDriver）
- * 与 WorkerSqliteDriver 的 worker 内联脚本均使用本模块生成的同一份实现。
- *
- * 工程说明：worker 内联脚本以字符串形式 eval 执行、无法直接 import 模块，
- * 因此 worker 侧通过 Function.prototype.toString 将本函数源码序列化注入脚本。
- * 该函数必须保持完全自包含：仅依赖运行时全局 Buffer 与 Uint8Array，
- * 不得引用任何模块作用域内的其他标识符，也不得引入会被打包器改写的外部闭包，
- * 否则序列化注入后将在 worker 作用域内产生未定义引用。
+ * 单一事实源：各同步驱动（如 NodeSqliteDriver）统一使用本实现，
+ * 避免参数归一逻辑出现双实现漂移。
  */
 export function normalizeSqliteParams(args) {
     if (!args || args.length === 0) {