@actiondock/core 2.10.0 → 2.11.0

package/dist/registry/lock.js

@@ -1,7 +1,4 @@
-import { randomUUID } from "node:crypto";
-import { readFile, mkdir, rename, rm, stat, utimes, writeFile } from "node:fs/promises";
-import { join } from "node:path";
-import { isProcessAlive } from "../utils/process.js";
+import { withFileLock } from "../storage/file-lock.js";
 /**
  * 锁目录最近一次心跳（创建或续期）后超过该时长且持有进程已死亡，
  * 才视为持有进程异常退出的残留锁。
@@ -18,99 +15,12 @@ export const REGISTRY_LOCK_ACQUIRE_TIMEOUT_MS = 15000;
 export const REGISTRY_LOCK_RETRY_DELAY_MS = 25;
 /**
  * 持锁期间的心跳续期间隔。持有者定期 touch 锁目录刷新 mtime，
- * 使长耗时持锁操作（如 linkPackage 的深度扫描）不会仅因耗时超过
- * stale 阈值而被等待方误判为残留锁抢占。
+ * 使长耗时持锁操作不会仅因耗时超过 stale 阈值而被等待方误判为残留锁抢占。
  */
 export const REGISTRY_LOCK_HEARTBEAT_MS = 3000;
-/**
- * 锁目录内的持有者元数据文件名。
- */
-const LOCK_METADATA_FILE = "metadata.json";
-function sleep(ms) {
-    return new Promise((r) => setTimeout(r, ms));
-}
-/**
- * 读取锁目录中的持有者元数据；缺失、不可读或结构非法时返回 undefined。
- * 元数据信息缺失时陈旧判定退化为仅看 mtime 年龄（与历史行为兼容）。
- */
-async function readLockMetadata(lockDir) {
-    let raw;
-    try {
-        raw = await readFile(join(lockDir, LOCK_METADATA_FILE), "utf-8");
-    }
-    catch {
-        return undefined;
-    }
-    try {
-        const parsed = JSON.parse(raw);
-        if (parsed &&
-            typeof parsed === "object" &&
-            typeof parsed.pid === "number" &&
-            typeof parsed.token === "string") {
-            return {
-                pid: parsed.pid,
-                token: parsed.token,
-                createdAt: typeof parsed.createdAt === "string" ? parsed.createdAt : "",
-            };
-        }
-    }
-    catch {
-        // 损坏的元数据视同缺失
-    }
-    return undefined;
-}
-/**
- * 本进程当前持有的注册表锁目录集合。
- * 用于区分「同进程在途持锁」（不可回收，需等待）与「同进程历史泄漏锁」
- * （释放阶段 rm 失败遗留，pid 存活复核下仍应可回收），
- * 避免存活 pid 保守判定把自身泄漏锁变成永久死锁。
- */
-const activeLockDirs = new Set();
-/**
- * 判定锁目录是否为可回收的残留锁。
- *
- * 判定语义（保守优先，保护并发正确性）：
- * - mtime 未超龄：一律不回收（正常持锁或心跳间隔内的活跃锁）。
- * - mtime 超龄 且元数据含存活 pid：不回收（慢磁盘下长扫描的持锁者仍活着；
- *   同进程在途持锁同样不回收，交由释放后重试获取）。
- * - mtime 超龄 且元数据 pid 已死：回收。
- * - mtime 超龄 且元数据缺失/非法：仅看 mtime 维持历史行为回收
- *   （兼容旧版本无元数据锁目录与竞态窗口内的半初始化锁目录）。
- */
-async function isStaleLock(lockDir, staleMs = REGISTRY_LOCK_STALE_MS) {
-    let lockAgeMs;
-    try {
-        const info = await stat(lockDir);
-        lockAgeMs = Date.now() - info.mtimeMs;
-    }
-    catch (err) {
-        // ENOENT：持有者恰好在两次探测之间释放，交由调用方立即重试获取
-        throw err;
-    }
-    if (lockAgeMs <= staleMs) {
-        return false;
-    }
-    const metadata = await readLockMetadata(lockDir);
-    if (metadata === undefined) {
-        return true;
-    }
-    if (metadata.pid === process.pid) {
-        // 同进程：仅在途持锁不可回收，历史泄漏锁（不在活跃集合）可回收
-        return !activeLockDirs.has(lockDir);
-    }
-    return !isProcessAlive(metadata.pid);
-}
 /**
  * 异步注册表锁（防止多进程并发读写导致 registry.json 损坏）。
- *
- * 获取方式：fs/promises mkdir 的原子性保证同一时刻仅一个进程能创建锁目录，
- * 创建成功后立即写入含 pid 与随机 token 的 metadata.json。
- * 冲突处理：EEXIST 时按保守语义判定残留（见 isStaleLock）：mtime 超龄且
- * pid 已死才抢占——抢占仍通过原子 rename 到隔离名实现，rename 仅有一个
- * 进程能成功，失败方回到等待重试，消除「检查后删除再重建」的竞态窗口；
- * 未过期的锁通过 sleep 让出事件循环后重试。
- * 心跳续期：持锁期间以固定间隔 touch 锁目录刷新 mtime，使 linkPackage 等
- * 长耗时持锁操作不会仅因耗时被误判残留；fn 完成后停止心跳并删除锁目录。
+ * 基于统一轻量文件锁原语实现。
  *
  * @param filePath 注册表文件路径，锁目录为其同级 `${filePath}.lock`
  * @param fn 持锁期间执行的操作（同步或异步）
@@ -119,95 +29,16 @@ async function isStaleLock(lockDir, staleMs = REGISTRY_LOCK_STALE_MS) {
  * @throws 超过 acquireTimeoutMs 仍未获取时抛出描述性错误
  */
 export async function withRegistryLock(filePath, fn, options) {
-    const staleMs = options?.staleMs ?? REGISTRY_LOCK_STALE_MS;
-    const acquireTimeoutMs = options?.acquireTimeoutMs ?? REGISTRY_LOCK_ACQUIRE_TIMEOUT_MS;
-    const retryDelayMs = options?.retryDelayMs ?? REGISTRY_LOCK_RETRY_DELAY_MS;
-    const heartbeatMs = options?.heartbeatMs ?? REGISTRY_LOCK_HEARTBEAT_MS;
     const lockDir = `${filePath}.lock`;
-    const deadline = Date.now() + acquireTimeoutMs;
-    while (true) {
-        try {
-            // 原子获取：目录创建成功即持有锁，无需二次确认
-            await mkdir(lockDir);
-            activeLockDirs.add(lockDir);
-            break;
-        }
-        catch (err) {
-            if (err.code !== "EEXIST") {
-                throw err;
-            }
-        }
-        // 锁被占用，检查是否为可回收的残留锁
-        let stale;
-        try {
-            stale = await isStaleLock(lockDir, staleMs);
-        }
-        catch (err) {
-            if (err.code === "ENOENT") {
-                // 持有者恰好在两次探测之间释放，立即重试获取
-                continue;
-            }
-            throw err;
-        }
-        if (stale) {
-            // 原子抢占：rename 到含进程号与时间戳的隔离名，仅一个进程能成功；
-            // 失败方说明已被其他等待者抢先处理，回到等待重试即可
-            const quarantine = `${lockDir}.stale.${process.pid}.${Date.now()}`;
-            try {
-                await rename(lockDir, quarantine);
-                await rm(quarantine, { recursive: true, force: true });
-                continue;
-            }
-            catch (err) {
-                if (err.code === "ENOENT") {
-                    // 其他等待者已抢先回收该残留锁
-                    continue;
-                }
-                // 其他原因的 rename 失败（如瞬时权限问题）不视为致命，退回等待重试
-            }
-        }
-        if (Date.now() > deadline) {
-            throw new Error(`Failed to acquire registry lock '${lockDir}' within ${acquireTimeoutMs}ms. ` +
-                `The lock may be held by another ActionDock process; retry after it exits or remove the stale lock directory manually.`);
-        }
-        await sleep(retryDelayMs);
-    }
-    // 持有者元数据写入失败不阻断持锁（退化为仅 mtime 判定），但保证可观测
-    try {
-        const metadata = {
-            pid: process.pid,
-            token: randomUUID(),
-            createdAt: new Date().toISOString(),
-        };
-        await writeFile(join(lockDir, LOCK_METADATA_FILE), JSON.stringify(metadata, null, 2), "utf-8");
-    }
-    catch (err) {
-        const reason = err instanceof Error ? err.message : String(err);
-        console.warn(`[Registry] Failed to write lock metadata in '${lockDir}': ${reason}`);
-    }
-    // 心跳续期：定期 touch 锁目录刷新 mtime，防止长耗时持锁操作被误判残留。
-    // 单次 touch 失败仅告警不中断（mtime 未刷新仅会提前暴露为陈旧候选，
-    // 由 pid 存活复核兜底，不会破坏互斥）。
-    const heartbeat = setInterval(() => {
-        const now = new Date();
-        utimes(lockDir, now, now).catch((err) => {
-            const reason = err instanceof Error ? err.message : String(err);
-            console.warn(`[Registry] Failed to refresh lock heartbeat for '${lockDir}': ${reason}`);
-        });
-    }, heartbeatMs);
-    heartbeat.unref?.();
-    try {
-        return await fn();
-    }
-    finally {
-        clearInterval(heartbeat);
-        activeLockDirs.delete(lockDir);
-        try {
-            await rm(lockDir, { recursive: true, force: true });
-        }
-        catch {
-            // 释放失败可忽略：进程未清理的锁目录会随时间超过 stale 阈值，
-            // 被后续获取方的原子 rename 抢占回收，不会造成永久死锁
-        }
-    }
+    const acquireTimeoutMs = options?.acquireTimeoutMs ?? REGISTRY_LOCK_ACQUIRE_TIMEOUT_MS;
+    const lockOptions = {
+        staleMs: options?.staleMs ?? REGISTRY_LOCK_STALE_MS,
+        acquireTimeoutMs,
+        retryDelayMs: options?.retryDelayMs ?? REGISTRY_LOCK_RETRY_DELAY_MS,
+        heartbeatMs: options?.heartbeatMs ?? REGISTRY_LOCK_HEARTBEAT_MS,
+        mtimeFirst: true,
+        createLockError: () => new Error(`Failed to acquire registry lock '${lockDir}' within ${acquireTimeoutMs}ms. ` +
+            `The lock may be held by another ActionDock process; retry after it exits or remove the stale lock directory manually.`),
+    };
+    return await withFileLock(lockDir, fn, lockOptions);
 }

package/dist/registry/registry.d.ts

@@ -21,12 +21,7 @@ export declare function loadRegistry(customHome?: string): GlobalRegistryData;
  */
 export declare function loadRegistryAsync(customHome?: string): Promise<GlobalRegistryData>;
 /**
- * 原子写入注册表：临时文件写盘后 rename，持锁执行，避免并发撕裂。
- */
-export declare function saveRegistry(data: GlobalRegistryData, customHome?: string): Promise<void>;
-/**
- * 在已持有注册表锁的上下文中直接原子落盘（供复合读改写流程使用，
- * 避免与 saveRegistry 的锁重入死等）；调用方必须已持有对应锁。
+ * 在已持有注册表锁的上下文中直接原子落盘（供复合读改写流程使用）；调用方必须已持有对应锁。
  */
 export declare function writeRegistryLocked(data: GlobalRegistryData, customHome?: string): Promise<void>;
 export declare function linkPackage(targetPath?: string, customHome?: string, options?: {

package/dist/registry/registry.js

@@ -3,6 +3,7 @@ import { readFile, rename, writeFile } from "node:fs/promises";
 import { basename, dirname, join, resolve, sep } from "node:path";
 import { findProjectRoot, loadProjectConfig } from "../project/loader.js";
 import { getActionDockHome, getPackageSlug } from "../utils/index.js";
+import { ActionDockError, MANIFEST_NOT_FOUND, REGISTRY_CORRUPTED } from "../errors.js";
 import { withRegistryLock } from "./lock.js";
 import { buildLinkedPackageEntry, discoverProjectConfigs, discoverProjects, } from "./scan.js";
 /**
@@ -32,12 +33,12 @@ export function parseRegistryContent(raw, filePath) {
         parsed = JSON.parse(raw);
     }
     catch (err) {
-        throw new Error(`Registry file '${filePath}' is corrupted (invalid JSON: ${err.message}). ` +
+        throw new ActionDockError(REGISTRY_CORRUPTED, `Registry file '${filePath}' is corrupted (invalid JSON: ${err.message}). ` +
             `The original data has been preserved as '${filePath}.corrupt' and can be restored manually. ` +
             `Fix or restore the file, or remove it to start with an empty registry.`);
     }
     if (!parsed || typeof parsed !== "object") {
-        throw new Error(`Registry file '${filePath}' is corrupted (top-level value is not an object). ` +
+        throw new ActionDockError(REGISTRY_CORRUPTED, `Registry file '${filePath}' is corrupted (top-level value is not an object). ` +
             `The original data has been preserved as '${filePath}.corrupt' and can be restored manually. ` +
             `Fix or restore the file, or remove it to start with an empty registry.`);
     }
@@ -177,20 +178,7 @@ function buildUnifiedPayload(data) {
 }
 let tmpFileSeq = 0;
 /**
- * 原子写入注册表：临时文件写盘后 rename，持锁执行，避免并发撕裂。
- */
-export async function saveRegistry(data, customHome) {
-    const filePath = getRegistryFilePath(customHome);
-    ensureRegistryDir(filePath);
-    const unifiedData = buildUnifiedPayload(data);
-    const payload = JSON.stringify(unifiedData, null, 2) + "\n";
-    await withRegistryLock(filePath, async () => {
-        await writeRegistryPayloadLocked(filePath, payload);
-    });
-}
-/**
- * 在已持有注册表锁的上下文中直接原子落盘（供复合读改写流程使用，
- * 避免与 saveRegistry 的锁重入死等）；调用方必须已持有对应锁。
+ * 在已持有注册表锁的上下文中直接原子落盘（供复合读改写流程使用）；调用方必须已持有对应锁。
  */
 export async function writeRegistryLocked(data, customHome) {
     const filePath = getRegistryFilePath(customHome);
@@ -298,7 +286,7 @@ export async function linkPackage(targetPath = process.cwd(), customHome, option
             };
         });
     }
-    throw new Error(`Cannot link: actiondock.json not found in '${absPath}' or its subdirectories`);
+    throw new ActionDockError(MANIFEST_NOT_FOUND, `Cannot link: actiondock.json not found in '${absPath}' or its subdirectories`);
 }
 export async function unlinkPackage(identifier = process.cwd(), customHome) {
     const filePath = getRegistryFilePath(customHome);

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

@@ -1,4 +1,4 @@
-import type { ActionDefinition, ActionRef } from "@actiondock/sdk";
+import type { ActionDefinition } from "@actiondock/sdk";
 /**
  * 为匿名传入的 Action 定义对象解析或分配稳定标识。
  */
@@ -28,10 +28,6 @@ export declare class ActionRegistry {
      */
     listActions(): ActionDefinition[];
 }
-/**
- * 本地注册表阶梯检索：跨包引用查 "pkg/action"，本包引用依次查短标识与限定标识。
- */
-export declare function findLocalAction(actions: Map<string, ActionDefinition>, parsed: ActionRef, currentPackageId: string): ActionDefinition | undefined;
 /**
  * 判定传入对象是否为可执行的 Action 定义对象（含 run 函数）。
  *

package/dist/runtime/action-registry.js

@@ -76,18 +76,6 @@ export class ActionRegistry {
         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 函数）。
  *

package/dist/runtime/context.js

@@ -1,7 +1,7 @@
 import { MemoryProcessDriver, ProcessManager } from "../process/index.js";
 import { createDefaultProcessOwner } from "../invocation/types.js";
 import { resolveEnvValue } from "./env.js";
-import { ActionDockError, INVALID_ACTION_REF } from "../errors.js";
+import { ActionDockError, INVALID_ACTION_REF, INVALID_STATE } from "../errors.js";
 /**
  * 生产级配置解析器实现。
  * 严格践行 5 层配置解析优先级链：
@@ -177,7 +177,7 @@ export function createActionContext(options) {
         if (options.onActionInvoke) {
             return (await options.onActionInvoke(action, input, currentRunId));
         }
-        throw new Error("ActionInvoker not configured with an invocation delegate");
+        throw new ActionDockError(INVALID_STATE, "ActionInvoker not configured with an invocation delegate");
     };
     const invokerFn = (ref, input) => invoke(ref, input);
     const invoker = Object.assign(invokerFn, { invoke });

package/dist/runtime/events.d.ts

@@ -1,7 +1,10 @@
 import type { ExecutionEvent } from "@actiondock/sdk";
 export interface EventSinkSubscribeOptions {
+    /** 起始游标位置（序号或事件标识） */
     after?: number | string;
+    /** 外部取消信号 */
     signal?: AbortSignal;
+    /** 订阅者事件队列上限（默认 1000） */
     maxQueueSize?: number;
 }
 export interface EventSink {
@@ -11,83 +14,41 @@ export interface EventSink {
     close?(): void;
 }
 export interface InMemoryEventSinkOptions {
-    /** 单个运行最大缓冲事件数（默认 1024） */
+    /** 单个运行最大缓冲事件数（默认 1000） */
     maxEventsPerRun?: number;
-    /** 单个运行最大缓冲字节数（默认 1024 * 1024 = 1MiB） */
-    maxBytesPerRun?: number;
     /** 全局最大缓存运行数（默认 500） */
     maxRuns?: number;
-    /** 慢订阅者事件队列背压有界上限（默认 1024） */
+    /** 订阅者事件队列上限（默认 1000） */
     maxSubscriberQueueSize?: number;
 }
 /**
- * 进程内有界事件缓冲区实现。
+ * 进程内轻量发布订阅事件广播器。
  * 遵循设计规范：
- * - 单运行双配额保护：上限 1024 条事件或 1MiB 字节数，优先淘汰日志与进度，保护终态。
+ * - 轻量发布订阅：保留订阅、退订、按 runId 过滤与事件分发。
+ * - 纯净广播：事件原样广播，绝不进行字节估算，绝不篡改用户执行结果。
+ * - 有界缓冲队列：简单条数上限（如 1000 条），队列满时丢弃最旧并计数，不切断通道。
  * - 全局有界回收：限制最大运行数（默认 500），溢出时优先淘汰已完成运行。
- * - 原子订阅衔接：先注册实时队列再回放历史快照，去重并杜绝并发丢事件窗口。
- * - 严格生命周期清理：迭代退出或中断时彻底注销监听器与 AbortSignal 事件。
- * - 慢订阅者背压保护：队列超出上限时推送终止事件并切断通道，主运行不受阻。
- * - 游标断点续传：支持全局持久化 eventId 与序列号，过期游标返回 EVENT_CURSOR_EXPIRED。
+ * - 错误隔离保护：单个订阅者监听器异常不扩散，保障系统整体稳定性。
  */
 export declare class InMemoryEventSink implements EventSink {
     private runs;
     private listeners;
-    private wakeups;
     private evictions;
     private evictedRuns;
     private globalEventSeq;
     private maxEventsPerRun;
-    private maxBytesPerRun;
     private maxRuns;
     private maxSubscriberQueueSize;
     constructor(options?: InMemoryEventSinkOptions);
     emit(event: ExecutionEvent): void;
     subscribe(runId: string, options?: EventSinkSubscribeOptions): AsyncIterable<ExecutionEvent>;
-    /**
-     * 断言请求游标仍处于保留窗口内（过期则抛出 EVENT_CURSOR_EXPIRED 错误）。
-     */
-    private assertCursorRetained;
-    /**
-     * 记录已交付事件并推进游标（已交付序号与最后确认游标）。
-     */
-    private trackDeliveredEvent;
-    /**
-     * 终止谓词：finish 事件或背压终止事件交付后订阅应立即结束。
-     */
-    private isTerminalDelivery;
-    /**
-     * 从实时队列取出下一条应交付的事件（跳过已交付序号），并同步推进游标。
-     */
-    private takeNextDeliverable;
-    /**
-     * 挂起等待下一条实时事件、通道终止或运行淘汰唤醒（严格注销监听避免泄漏）。
-     */
-    private waitForNextEvent;
-    /**
-     * 手动修剪已终态运行中早于指定序列号的历史事件（用于模拟过期清理）。
-     */
-    pruneEvents(runId: string, upToSequence: number): void;
     clear(runId: string): void;
-    /**
-     * 获取指定运行的事件统计信息（调试与测试用）。
-     */
     getRunStats(runId: string): {
         count: number;
-        bytes: number;
         isTerminal: boolean;
+        droppedCount: number;
     } | undefined;
-    /**
-     * 获取全局缓存的运行数。
-     */
     getRunCount(): number;
-    /**
-     * 淘汰最久未活跃的运行记录。
-     * 优先淘汰已终态运行；若无终态运行则淘汰最旧活动运行，严格保证 runs.size <= maxRuns。
-     */
     private evictOldestRun;
-    /**
-     * 关闭事件接收器并唤醒所有活跃订阅者退出。
-     */
     close(): void;
 }