@actiondock/core 2.5.1 → 2.7.0

package/dist/storage/index.d.ts

@@ -1,11 +1,13 @@
 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 "./lazy.js";
 export * from "./mask.js";
 export * from "./params.js";
 export * from "./sqlite.js";
 export * from "./types.js";
+export * from "./utils.js";
 /**
  * 解析并计算目标 SQLite 数据库文件的绝对路径。
  *
@@ -26,14 +28,19 @@ export declare function resolveDatabasePath(packageId: string, options?: {
 /**
  * 工厂函数：为指定 Package 创建或连接 RuntimeStorage 实例。
  *
+ * 默认旁观打开：不收割库内遗留非终态运行（recoverOrphans 默认 false），
+ * 供 CLI 查询类命令安全并发访问持有者进程正在写入的同一库文件；
+ * 执行宿主路径应传入 recoverOrphans: true 或后续显式调用 recoverDeadSessionRuns。
+ *
  * @param packageId 目标 Package ID
- * @param options 存储配置参数（支持 dataDir, inMemory, customHome）
+ * @param options 存储配置参数（支持 dataDir, inMemory, customHome, recoverOrphans）
  */
 export declare function createStorage(packageId: string, options?: {
     projectRoot?: string;
     dataDir?: string;
     inMemory?: boolean;
     customHome?: string;
+    recoverOrphans?: boolean;
 }): RuntimeStorage;
 /**
  * 解析全局共享数据库（global.db）文件的绝对路径。

package/dist/storage/index.js

@@ -2,12 +2,14 @@ import { join, relative, resolve } from "node:path";
 import { assertValidPackageId, getActionDockHome, isPathOutsideBoundary } from "../utils/index.js";
 import { SqliteRuntimeStorage } from "./sqlite.js";
 export { DataDirLock, isProcessAlive, } from "./data-dir-lock.js";
+export * from "./clock.js";
 export * from "./driver.js";
 export * from "./lazy.js";
 export * from "./mask.js";
 export * from "./params.js";
 export * from "./sqlite.js";
 export * from "./types.js";
+export * from "./utils.js";
 /**
  * 解析并计算目标 SQLite 数据库文件的绝对路径。
  *
@@ -47,12 +49,16 @@ export function resolveDatabasePath(packageId, options = {}) {
 /**
  * 工厂函数：为指定 Package 创建或连接 RuntimeStorage 实例。
  *
+ * 默认旁观打开：不收割库内遗留非终态运行（recoverOrphans 默认 false），
+ * 供 CLI 查询类命令安全并发访问持有者进程正在写入的同一库文件；
+ * 执行宿主路径应传入 recoverOrphans: true 或后续显式调用 recoverDeadSessionRuns。
+ *
  * @param packageId 目标 Package ID
- * @param options 存储配置参数（支持 dataDir, inMemory, customHome）
+ * @param options 存储配置参数（支持 dataDir, inMemory, customHome, recoverOrphans）
  */
 export function createStorage(packageId, options = {}) {
     const dbPath = resolveDatabasePath(packageId, options);
-    return new SqliteRuntimeStorage({ dbPath, packageId });
+    return new SqliteRuntimeStorage({ dbPath, packageId, recoverOrphans: options.recoverOrphans });
 }
 /**
  * 解析全局共享数据库（global.db）文件的绝对路径。

package/dist/storage/lazy.js

@@ -23,6 +23,7 @@ export function createLazyStorage(factory) {
             if (prop === "close") {
                 return () => {
                     if (instance) {
+                        // 驱动关闭异常不吞没：延迟代理层透传给调用方，由上层统一记录或处理
                         instance.close();
                     }
                 };

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

@@ -0,0 +1,162 @@
+/**
+ * 目录锁元数据通用契约。
+ * 工程锁与数据目录锁共用同一物理布局，仅部分字段按场景取舍。
+ */
+export interface DirectoryLockMetadata {
+    pid?: number;
+    sessionToken?: string;
+    lockToken?: string;
+    guardToken?: string;
+    childPids?: number[];
+    createdAt?: number | string;
+    [key: string]: unknown;
+}
+/**
+ * 带宽限期检测的锁状态快照。
+ */
+export interface LockGraceState {
+    exists: boolean;
+    isDir: boolean;
+    info?: DirectoryLockMetadata;
+    inGracePeriod: boolean;
+}
+/**
+ * 接管守卫（reclaim guard）状态快照。
+ */
+export interface ReclaimGuardState {
+    exists: boolean;
+    active: boolean;
+    isStale: boolean;
+    holderPid?: number;
+    guardToken?: string;
+}
+/**
+ * 检查目标进程是否处于存活状态。
+ *
+ * @param pid 待检测的进程标识符
+ */
+export declare function isProcessAlive(pid: number): boolean;
+/**
+ * 读取排他锁元数据并执行宽限期检测。
+ */
+export declare function readLockWithGracePeriod(lockPath: string, gracePeriodMs?: number, deadline?: number): LockGraceState;
+/**
+ * 检查接管守卫（reclaim guard）目录状态。
+ *
+ * - 若目录不存在：返回非活跃。
+ * - 若处于宽限期内或持有者存活：返回活跃，禁止抢先创建主锁。
+ * - 若持有者已死亡且超过宽限期：返回陈旧，可供安全清理。
+ */
+export declare function checkReclaimGuard(reclaimPath: string, gracePeriodMs?: number): ReclaimGuardState;
+/**
+ * 尝试原子获取接管守卫（reclaim guard）。
+ * 基于 mkdirSync 原子创建目录并写入自身元数据与唯一 guardToken。
+ */
+export declare function tryAcquireReclaimGuard(reclaimPath: string, pid: number, guardToken: string): boolean;
+/**
+ * 安全清理陈旧接管守卫（reclaim guard）。
+ * 采用原子重命名检疫并严格核对 guardToken 与持有者存活状态，确保仅删除目标陈旧 guard，严禁误删活跃守卫或并发新守卫。
+ *
+ * @param reclaimPath 目标守卫路径
+ * @param expectedGuardToken 预期持有的守卫令牌（必填，拒绝未指定令牌的盲目清理）
+ */
+export declare function safeRemoveStaleReclaimGuard(reclaimPath: string, expectedGuardToken: string): void;
+/**
+ * 从隔离或回滚临时目录名称中解析操作者 PID 与隔离生成时间戳。
+ * 命名规范：*.(quarantine|rollback|release).<pid>.<timestamp>.<uuid> 或 *.orphan.<timestamp>.<uuid>
+ */
+export declare function parseQuarantineTimestamp(entryName: string): {
+    operatorPid?: number;
+    timestamp?: number;
+};
+/**
+ * 清理过期的隔离目录（GC 回收机制）。
+ * 实施分流存活校验，防止误删活跃持锁者与回滚中目录，同时防止孤儿目录无限泄漏：
+ * - 共同前置条件：存活年龄必须超过 maxAgeMs（默认 10000ms），未超期前严禁清理（保持宽限期）。
+ * - 活跃隔离目录（quarantine / rollback / release）：若 operatorPid 存活或内部 metadata.json 记录的 pid 与 childPids 存活，跳过不予清理。
+ * - 孤儿脱离目录（orphan）：内部旧 metadata.pid 不再作为续命依据；提取其内部 orphanToken，仅当当前规范主路径（主锁目录与 reclaim 目录）依然持有该凭证时保守跳过；规范路径不存在或已变更凭据时直接安全清理。
+ */
+export declare function cleanStaleQuarantines(parentDir: string, basePrefix: string, maxAgeMs?: number, deadline?: number): void;
+/**
+ * 安全回滚当前进程创建的主锁。
+ * 优先核对 lockToken，回退核对 sessionToken，防止误删接管者或并发新锁。
+ */
+export declare function safeRollbackLock(lockPath: string, expectedSessionToken: string, expectedLockToken?: string): void;
+/**
+ * 安全隔离并清理陈旧主锁。
+ * 隔离后复核元数据，确保仅删除目标陈旧锁，若已被更新或仍有存活所有者则恢复原位。
+ */
+export declare function safeQuarantineStaleLock(lockPath: string, expectedSessionToken?: string, expectedLockToken?: string): boolean;
+/**
+ * 安全释放主锁。
+ * 仅当锁目录中持有当前 lockToken / sessionToken 时才删除，杜绝删除他人新锁。
+ * 传入 gcAfterRelease 时在释放结束后以主锁文件名为前缀触发一轮隔离目录 GC。
+ */
+export declare function safeReleaseLock(lockPath: string, expectedSessionToken: string, expectedLockToken?: string, options?: {
+    gcAfterRelease?: boolean;
+}): void;
+/**
+ * 目录锁获取流程的各类超时错误消息模板。
+ * 由上层模块注入，保证各领域错误文案与错误码完全保持原语义。
+ */
+export interface DirectoryLockMessages {
+    /** 等待活跃接管守卫超时 */
+    timeoutWaitingReclaimGuard(holderPid?: number): string;
+    /** 因他人活跃接管守卫导致获取主锁超时 */
+    timeoutAcquireBlockedByGuard(holderPid?: number): string;
+    /** 获取主锁通用超时 */
+    timeoutAcquire(): string;
+    /** 等待主锁元数据宽限期超时 */
+    timeoutGracePeriod(): string;
+    /** 争抢接管守卫超时 */
+    timeoutGuardContention(): string;
+    /** 接管陈旧主锁超时 */
+    timeoutReclaimStale(): string;
+    /** 创建新主锁超时 */
+    timeoutCreate(): string;
+}
+/**
+ * 目录锁获取流程配置。
+ * 上层模块以此注入锁路径、令牌、错误构造与领域差异钩子。
+ */
+export interface AcquireDirectoryLockConfig<T> {
+    /** 主锁目录完整路径 */
+    lockPath: string;
+    /** 主锁所在父目录（用于隔离目录 GC） */
+    parentDir: string;
+    /** 主锁目录在父目录中的基础名称前缀 */
+    basePrefix: string;
+    /** 待写入主锁的元数据 JSON 文本 */
+    metadataContent: string;
+    /** 自身会话令牌 */
+    sessionToken: string;
+    /** 自身内部排他锁令牌 */
+    lockToken: string;
+    /** 获取锁的超时时间，默认 5000ms */
+    acquireTimeoutMs?: number;
+    /** 构造带错误码的占用异常 */
+    createLockError(message: string): Error & {
+        code: string;
+    };
+    /** 各类超时场景的错误消息模板 */
+    messages: DirectoryLockMessages;
+    /** 陈旧锁持有者复核回调：若持有者仍阻断接管则直接抛错 */
+    assertStaleHolderReclaimable(info: DirectoryLockMetadata): void;
+    /** 成功获取主锁后的返回值构造 */
+    onAcquired(): T;
+}
+/**
+ * 目录锁统一获取仲裁流程。
+ *
+ * 仲裁规则：
+ * - 引入所有竞争者均遵守的原子 reclaim guard 机制（lockPath.reclaim），每个 guard 具备全局唯一 guardToken。
+ * - 基于原子目录创建 mkdirSync(lockPath, { mode: 0o700 }) 确立所有权，并在其下存放 metadata.json。
+ * - 若检测到 reclaim guard 存在且处于宽限期内或持有者存活，必须等待，禁止抢先创建主锁。
+ * - 若锁目录已存在，通过宽限期机制防止将并发写入中的元数据误判为锁死亡。
+ * - 若持有者仍存活（判定由 assertStaleHolderReclaimable 注入），抛出上层领域错误拒绝并发接管。
+ * - 当识别到主锁为陈旧锁时，竞争者必须先原子竞争获取 reclaim guard。
+ * - 仅成功获取 reclaim guard 的唯一胜利者获准执行：复核主锁陈旧性 -> 验证并清理陈旧主锁 -> 原子创建新主锁并写入自身元数据 -> 清理 reclaim guard。
+ * - 竞争失败者等待并 continue 重试；若 reclaim guard 持有者意外崩溃，其他竞争者在超过宽限期且 PID 已死后通过 safeRemoveStaleReclaimGuard 核对 guardToken 并清理。
+ * - 严禁在获取新主锁遇到 EEXIST 时盲目 rmSync；后检发现他人活跃 guard 时，仅通过 safeRollbackLock 核对自身 sessionToken 回滚自身锁。
+ */
+export declare function acquireDirectoryLock<T>(config: AcquireDirectoryLockConfig<T>): T;