@actiondock/core 2.7.0 → 2.8.0

package/dist/registry/lock.js

@@ -1,6 +1,10 @@
-import { mkdir, rename, rm, stat } from "node:fs/promises";
+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";
 /**
- * 锁目录创建后超过该时长仍未释放，视为持有进程异常退出的残留锁。
+ * 锁目录最近一次心跳（创建或续期）后超过该时长且持有进程已死亡，
+ * 才视为持有进程异常退出的残留锁。
  */
 export const REGISTRY_LOCK_STALE_MS = 10000;
 /**
@@ -12,29 +16,120 @@ export const REGISTRY_LOCK_ACQUIRE_TIMEOUT_MS = 15000;
  * 两次获取尝试之间的退避间隔，休眠让出事件循环，避免忙等阻塞。
  */
 export const REGISTRY_LOCK_RETRY_DELAY_MS = 25;
+/**
+ * 持锁期间的心跳续期间隔。持有者定期 touch 锁目录刷新 mtime，
+ * 使长耗时持锁操作（如 linkPackage 的深度扫描）不会仅因耗时超过
+ * 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 的原子性保证同一时刻仅一个进程能创建锁目录。
- * 冲突处理：EEXIST 时 stat 检查锁目录年龄，超过 stale 阈值则先原子 rename 到
- * 隔离名再删除——rename 仅有一个进程能成功，失败方回到等待重试，消除
- * 「stat 检查后删除再重建」的竞态窗口；未过期的锁通过 sleep 让出事件循环后重试。
+ * 获取方式：fs/promises mkdir 的原子性保证同一时刻仅一个进程能创建锁目录，
+ * 创建成功后立即写入含 pid 与随机 token 的 metadata.json。
+ * 冲突处理：EEXIST 时按保守语义判定残留（见 isStaleLock）：mtime 超龄且
+ * pid 已死才抢占——抢占仍通过原子 rename 到隔离名实现，rename 仅有一个
+ * 进程能成功，失败方回到等待重试，消除「检查后删除再重建」的竞态窗口；
+ * 未过期的锁通过 sleep 让出事件循环后重试。
+ * 心跳续期：持锁期间以固定间隔 touch 锁目录刷新 mtime，使 linkPackage 等
+ * 长耗时持锁操作不会仅因耗时被误判残留；fn 完成后停止心跳并删除锁目录。
  *
  * @param filePath 注册表文件路径，锁目录为其同级 `${filePath}.lock`
  * @param fn 持锁期间执行的操作（同步或异步）
+ * @param options 可选锁超时与重试配置
  * @returns fn 的返回值
- * @throws 超过 REGISTRY_LOCK_ACQUIRE_TIMEOUT_MS 仍未获取时抛出描述性错误
+ * @throws 超过 acquireTimeoutMs 仍未获取时抛出描述性错误
  */
-export async function withRegistryLock(filePath, fn) {
+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() + REGISTRY_LOCK_ACQUIRE_TIMEOUT_MS;
+    const deadline = Date.now() + acquireTimeoutMs;
     while (true) {
         try {
             // 原子获取：目录创建成功即持有锁，无需二次确认
             await mkdir(lockDir);
+            activeLockDirs.add(lockDir);
             break;
         }
         catch (err) {
@@ -42,11 +137,10 @@ export async function withRegistryLock(filePath, fn) {
                 throw err;
             }
         }
-        // 锁被占用，检查是否为残留的过期锁
-        let lockAgeMs;
+        // 锁被占用，检查是否为可回收的残留锁
+        let stale;
         try {
-            const info = await stat(lockDir);
-            lockAgeMs = Date.now() - info.mtimeMs;
+            stale = await isStaleLock(lockDir, staleMs);
         }
         catch (err) {
             if (err.code === "ENOENT") {
@@ -55,7 +149,7 @@ export async function withRegistryLock(filePath, fn) {
             }
             throw err;
         }
-        if (lockAgeMs > REGISTRY_LOCK_STALE_MS) {
+        if (stale) {
             // 原子抢占：rename 到含进程号与时间戳的隔离名，仅一个进程能成功；
             // 失败方说明已被其他等待者抢先处理，回到等待重试即可
             const quarantine = `${lockDir}.stale.${process.pid}.${Date.now()}`;
@@ -73,15 +167,41 @@ export async function withRegistryLock(filePath, fn) {
             }
         }
         if (Date.now() > deadline) {
-            throw new Error(`Failed to acquire registry lock '${lockDir}' within ${REGISTRY_LOCK_ACQUIRE_TIMEOUT_MS}ms. ` +
+            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(REGISTRY_LOCK_RETRY_DELAY_MS);
+        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 });
         }

package/dist/registry/registry.d.ts

@@ -1,4 +1,4 @@
-import type { GlobalRegistryData, LinkedPackageEntry, LinkedWorkspaceEntry, LinkResult, PruneResult, RegistryStatusReport, ResolvedActionProject, ResolvedPlaybookProject, UnlinkResult } from "./types.js";
+import type { GlobalRegistryData, LinkedPackageEntry, LinkedWorkspaceEntry, LinkResult, PruneResult, RegistryStatusReport, UnlinkResult } from "./types.js";
 /**
  * 注册表内容解析与 links 迁移（纯函数，同步与异步加载共享的唯一事实源）。
  *
@@ -34,11 +34,7 @@ export declare function linkPackage(targetPath?: string, customHome?: string, op
 }): Promise<LinkResult>;
 export declare function unlinkPackage(identifier?: string, customHome?: string): Promise<UnlinkResult | null>;
 export declare function listLinkedPackages(customHome?: string): LinkedPackageEntry[];
-export declare function listLinkedPackagesAsync(customHome?: string): Promise<LinkedPackageEntry[]>;
 export declare function listLinkedWorkspaces(customHome?: string): LinkedWorkspaceEntry[];
-export declare function resolveActionProjectSync(actionIdentifier: string, cwd?: string, customHome?: string): ResolvedActionProject;
-export declare function resolveActionProject(actionIdentifier: string, cwd?: string, customHome?: string): Promise<ResolvedActionProject>;
-export declare function resolvePlaybookProject(playbookIdentifier: string, cwd?: string, customHome?: string): ResolvedPlaybookProject;
 export declare function resolvePackageRoot(packageIdOrPath?: string, cwd?: string, customHome?: string): string | null;
 export declare function getRegistryStatus(customHome?: string): RegistryStatusReport;
 export declare function pruneRegistry(customHome?: string): Promise<PruneResult>;

package/dist/registry/registry.js

@@ -4,8 +4,7 @@ import { basename, dirname, join, resolve, sep } from "node:path";
 import { findProjectRoot, loadProjectConfig } from "../project/loader.js";
 import { getActionDockHome, getPackageSlug } from "../utils/index.js";
 import { withRegistryLock } from "./lock.js";
-import { buildLinkedPackageEntry, discoverProjectConfigs, discoverProjectConfigsAsync, discoverProjects, pathExistsAsync, } from "./scan.js";
-import { probeActionAsync, probeActionSync, probePlaybook, resolveEntityFlow, runFlowAsync, runFlowSync, } from "./resolve.js";
+import { buildLinkedPackageEntry, discoverProjectConfigs, discoverProjects, } from "./scan.js";
 /**
  * 空注册表初始结构。
  */
@@ -400,61 +399,10 @@ export function listLinkedPackages(customHome) {
     }
     return Object.values(result);
 }
-export async function listLinkedPackagesAsync(customHome) {
-    const registry = await loadRegistryAsync(customHome);
-    const result = { ...registry.packages };
-    if (registry.workspaces) {
-        for (const ws of Object.values(registry.workspaces)) {
-            if (!(await pathExistsAsync(ws.path)))
-                continue;
-            for (const { root, config } of await discoverProjectConfigsAsync(ws.path)) {
-                if (!result[config.id] || result[config.id].workspaceRoot === ws.path) {
-                    result[config.id] = buildLinkedPackageEntry(config, root, ws.linkedAt, ws.path);
-                }
-            }
-        }
-    }
-    return Object.values(result);
-}
 export function listLinkedWorkspaces(customHome) {
     const registry = loadRegistry(customHome);
     return Object.values(registry.workspaces || {});
 }
-export function resolveActionProjectSync(actionIdentifier, cwd = process.cwd(), customHome) {
-    return runFlowSync(resolveEntityFlow({
-        identifier: actionIdentifier,
-        cwd,
-        entityNoun: "Action",
-        listLinkedPackages: () => listLinkedPackages(customHome),
-        probe: (root, config, id) => probeActionSync(root, config, id),
-        buildResult: (projectRoot, packageId, actionId) => ({ projectRoot, packageId, actionId }),
-    }));
-}
-export async function resolveActionProject(actionIdentifier, cwd = process.cwd(), customHome) {
-    return runFlowAsync(resolveEntityFlow({
-        identifier: actionIdentifier,
-        cwd,
-        entityNoun: "Action",
-        listLinkedPackages: () => listLinkedPackagesAsync(customHome),
-        probe: (root, config, id) => probeActionAsync(root, config, id),
-        buildResult: (projectRoot, packageId, actionId) => ({ projectRoot, packageId, actionId }),
-    }));
-}
-export function resolvePlaybookProject(playbookIdentifier, cwd = process.cwd(), customHome) {
-    return runFlowSync(resolveEntityFlow({
-        identifier: playbookIdentifier,
-        cwd,
-        entityNoun: "Playbook",
-        listLinkedPackages: () => listLinkedPackages(customHome),
-        probe: (root, config, id) => probePlaybook(root, config, id),
-        buildResult: (projectRoot, packageId, playbookId, playbook) => ({
-            projectRoot,
-            packageId,
-            playbookId,
-            playbook,
-        }),
-    }));
-}
 export function resolvePackageRoot(packageIdOrPath, cwd, customHome) {
     if (!packageIdOrPath) {
         return findProjectRoot(cwd);

package/dist/registry/scan.d.ts

@@ -8,10 +8,6 @@ export declare const IGNORED_SCAN_DIRS: Set<string>;
  * 递归扫描包含 actiondock.json 的子项目根目录（同步版本）。
  */
 export declare function discoverProjects(dir: string, maxDepth?: number): string[];
-/**
- * 递归扫描包含 actiondock.json 的子项目根目录（异步版本，逻辑与同步版一致）。
- */
-export declare function discoverProjectsAsync(dir: string, maxDepth?: number): Promise<string[]>;
 /**
  * 扫描并加载全部子项目配置（同步版本）。
  * 损坏项目（配置缺失或非法）跳过不中断：注册表操作面对的是外部任意目录，
@@ -21,18 +17,7 @@ export declare function discoverProjectConfigs(dir: string, maxDepth?: number):
     root: string;
     config: ReturnType<typeof loadProjectConfig>;
 }>;
-/**
- * 扫描并加载全部子项目配置（异步版本，跳过策略与同步版一致）。
- */
-export declare function discoverProjectConfigsAsync(dir: string, maxDepth?: number): Promise<Array<{
-    root: string;
-    config: ReturnType<typeof loadProjectConfig>;
-}>>;
 /**
  * 由项目配置构造注册表链接条目（纯函数，无副作用）。
  */
 export declare function buildLinkedPackageEntry(config: ReturnType<typeof loadProjectConfig>, path: string, linkedAt: string, workspaceRoot?: string): LinkedPackageEntry;
-/**
- * 异步探测路径是否存在。
- */
-export declare function pathExistsAsync(path: string): Promise<boolean>;

package/dist/registry/scan.js

@@ -1,5 +1,4 @@
 import { readdirSync } from "node:fs";
-import { readdir, stat } from "node:fs/promises";
 import { join, resolve } from "node:path";
 import { loadProjectConfig } from "../project/loader.js";
 /**
@@ -45,37 +44,6 @@ export function discoverProjects(dir, maxDepth = 3) {
     walk(resolvedDir, 1);
     return results;
 }
-/**
- * 递归扫描包含 actiondock.json 的子项目根目录（异步版本，逻辑与同步版一致）。
- */
-export async function discoverProjectsAsync(dir, maxDepth = 3) {
-    const results = [];
-    const resolvedDir = resolve(dir);
-    async function walk(currentDir, currentDepth) {
-        if (currentDepth > maxDepth)
-            return;
-        let entries;
-        try {
-            entries = await readdir(currentDir, { withFileTypes: true });
-        }
-        catch {
-            // 忽略无法读取的目录：扫描是尽力而为的探测，单目录不可读不应中断整体发现
-            return;
-        }
-        const hasActiondock = entries.some((e) => e.isFile() && e.name === "actiondock.json");
-        if (hasActiondock && currentDir !== resolvedDir) {
-            results.push(currentDir);
-            return; // 不再向项目内部子目录递归
-        }
-        for (const entry of entries) {
-            if (entry.isDirectory() && !IGNORED_SCAN_DIRS.has(entry.name)) {
-                await walk(join(currentDir, entry.name), currentDepth + 1);
-            }
-        }
-    }
-    await walk(resolvedDir, 1);
-    return results;
-}
 /**
  * 扫描并加载全部子项目配置（同步版本）。
  * 损坏项目（配置缺失或非法）跳过不中断：注册表操作面对的是外部任意目录，
@@ -93,21 +61,6 @@ export function discoverProjectConfigs(dir, maxDepth = 3) {
     }
     return results;
 }
-/**
- * 扫描并加载全部子项目配置（异步版本，跳过策略与同步版一致）。
- */
-export async function discoverProjectConfigsAsync(dir, maxDepth = 3) {
-    const results = [];
-    for (const root of await discoverProjectsAsync(dir, maxDepth)) {
-        try {
-            results.push({ root, config: loadProjectConfig(root) });
-        }
-        catch {
-            // 跳过损坏项目：其 actiondock.json 缺失必要字段或非法，无法构成有效链接条目
-        }
-    }
-    return results;
-}
 /**
  * 由项目配置构造注册表链接条目（纯函数，无副作用）。
  */
@@ -121,15 +74,3 @@ export function buildLinkedPackageEntry(config, path, linkedAt, workspaceRoot) {
         ...(workspaceRoot ? { workspaceRoot } : {}),
     };
 }
-/**
- * 异步探测路径是否存在。
- */
-export async function pathExistsAsync(path) {
-    try {
-        await stat(path);
-        return true;
-    }
-    catch {
-        return false;
-    }
-}

package/dist/registry/store.d.ts

@@ -0,0 +1,42 @@
+import type { GlobalRegistryData, LinkedPackageEntry, LinkedWorkspaceEntry, LinkResult, PruneResult, RegistryStatusReport, UnlinkResult } from "./types.js";
+/**
+ * 用户显式注册位置存储契约。
+ * 职责严格限制为存储与读取用户显式 link/unlink 的物理位置（packages 与 workspaces）。
+ */
+export interface RegistryStore {
+    readonly customHome?: string;
+    getFilePath(): string;
+    load(): GlobalRegistryData;
+    loadAsync(): Promise<GlobalRegistryData>;
+    save(data: GlobalRegistryData): Promise<void>;
+    listPackages(): LinkedPackageEntry[];
+    listWorkspaces(): LinkedWorkspaceEntry[];
+    link(path: string, options?: {
+        recursive?: boolean;
+    }): Promise<LinkResult>;
+    unlink(idOrPath: string): Promise<UnlinkResult | null>;
+    prune(): Promise<PruneResult>;
+    getStatus(): RegistryStatusReport;
+}
+/**
+ * 默认注册表物理位置存储实现。
+ * 直接基于文件系统注册表文件（~/.actiondock/registry.json）读写；
+ * 全部方法均为向 registry.ts 自由函数透传 customHome 的零逻辑转发，
+ * 收敛为单行委托以消除重复样板。
+ */
+export declare class DefaultRegistryStore implements RegistryStore {
+    readonly customHome?: string;
+    constructor(customHome?: string);
+    getFilePath(): string;
+    load(): GlobalRegistryData;
+    loadAsync(): Promise<GlobalRegistryData>;
+    save(data: GlobalRegistryData): Promise<void>;
+    listPackages(): LinkedPackageEntry[];
+    listWorkspaces(): LinkedWorkspaceEntry[];
+    link(path: string, options?: {
+        recursive?: boolean;
+    }): Promise<LinkResult>;
+    unlink(idOrPath: string): Promise<UnlinkResult | null>;
+    prune(): Promise<PruneResult>;
+    getStatus(): RegistryStatusReport;
+}

package/dist/registry/store.js

@@ -0,0 +1,43 @@
+import { getRegistryFilePath, getRegistryStatus, linkPackage, listLinkedPackages, listLinkedWorkspaces, loadRegistry, loadRegistryAsync, pruneRegistry, saveRegistry, unlinkPackage, } from "./registry.js";
+/**
+ * 默认注册表物理位置存储实现。
+ * 直接基于文件系统注册表文件（~/.actiondock/registry.json）读写；
+ * 全部方法均为向 registry.ts 自由函数透传 customHome 的零逻辑转发，
+ * 收敛为单行委托以消除重复样板。
+ */
+export class DefaultRegistryStore {
+    customHome;
+    constructor(customHome) {
+        this.customHome = customHome;
+    }
+    getFilePath() {
+        return getRegistryFilePath(this.customHome);
+    }
+    load() {
+        return loadRegistry(this.customHome);
+    }
+    loadAsync() {
+        return loadRegistryAsync(this.customHome);
+    }
+    save(data) {
+        return saveRegistry(data, this.customHome);
+    }
+    listPackages() {
+        return listLinkedPackages(this.customHome);
+    }
+    listWorkspaces() {
+        return listLinkedWorkspaces(this.customHome);
+    }
+    link(path, options) {
+        return linkPackage(path, this.customHome, options);
+    }
+    unlink(idOrPath) {
+        return unlinkPackage(idOrPath, this.customHome);
+    }
+    prune() {
+        return pruneRegistry(this.customHome);
+    }
+    getStatus() {
+        return getRegistryStatus(this.customHome);
+    }
+}

package/dist/registry/types.d.ts

@@ -91,27 +91,3 @@ export interface PruneResult {
     prunedPackages: LinkedPackageEntry[];
     prunedWorkspaces: LinkedWorkspaceEntry[];
 }
-/**
- * Action 归属项目解析结果。
- */
-export interface ResolvedActionProject {
-    /** 所在项目的根目录绝对路径 */
-    projectRoot: string;
-    /** 所属 Package ID */
-    packageId: string;
-    /** 匹配到的 Action ID */
-    actionId: string;
-}
-/**
- * Playbook 归属项目解析结果。
- */
-export interface ResolvedPlaybookProject {
-    /** 所在项目的根目录绝对路径 */
-    projectRoot: string;
-    /** 所属 Package ID */
-    packageId: string;
-    /** 匹配到的 Playbook ID */
-    playbookId: string;
-    /** Playbook 实体数据 */
-    playbook: import("../project/types.js").PlaybookDefinition;
-}

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

@@ -1,5 +1,5 @@
 import type { ActionDefinition } from "@actiondock/sdk";
-import type { ActionSpec } from "../app/types.js";
+import type { ActionSpec } from "../package/types.js";
 /**
  * 归一化 Action 集合的产物结构。
  */

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

@@ -39,7 +39,3 @@ export declare function findLocalAction(actions: Map<string, ActionDefinition>,
  * 不额外吞异或静默改道，保持边界行为零变化。
  */
 export declare function isActionDefinitionObject(value: unknown): value is ActionDefinition;
-/**
- * 解析 Action 引用或标识符（解析失败抛出原始异常，由调用方分类处理）。
- */
-export declare function parseActionRef(ref: ActionRef | string): ActionRef;

package/dist/runtime/action-registry.js

@@ -1,4 +1,3 @@
-import { ActionResolver } from "../catalog/action-resolver.js";
 /**
  * Action 注册表（单一职责模块）。
  *
@@ -100,9 +99,3 @@ export function isActionDefinitionObject(value) {
         "run" in value &&
         typeof value.run === "function");
 }
-/**
- * 解析 Action 引用或标识符（解析失败抛出原始异常，由调用方分类处理）。
- */
-export function parseActionRef(ref) {
-    return ActionResolver.parseRef(ref);
-}

package/dist/runtime/context.js

@@ -1,6 +1,7 @@
-import { randomUUID } from "node:crypto";
 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";
 /**
  * 生产级配置解析器实现。
  * 严格践行 5 层配置解析优先级链：
@@ -166,14 +167,12 @@ export function createActionContext(options) {
     const state = new RuntimeStateStore(options.storage);
     const log = options.logger || new StderrLogger();
     const signal = options.signal ?? new AbortController().signal;
-    const currentRunId = options.runId || randomUUID();
+    const currentRunId = options.runId || crypto.randomUUID();
     const currentRootRunId = options.rootRunId || options.parentRunId || currentRunId;
     const invoke = async (action, input) => {
         if (typeof action !== "string" &&
             (!action || typeof action !== "object" || typeof action.run === "function" || !("actionId" in action))) {
-            const err = new Error("INVALID_ACTION_REF: ctx.actions.invoke strictly accepts only ActionRef or string, passing ActionDefinition or function is prohibited");
-            err.code = "INVALID_ACTION_REF";
-            throw err;
+            throw new ActionDockError(INVALID_ACTION_REF, "INVALID_ACTION_REF: ctx.actions.invoke strictly accepts only ActionRef or string, passing ActionDefinition or function is prohibited");
         }
         if (options.onActionInvoke) {
             return (await options.onActionInvoke(action, input, currentRunId));
@@ -182,12 +181,7 @@ export function createActionContext(options) {
     };
     const invokerFn = (ref, input) => invoke(ref, input);
     const invoker = Object.assign(invokerFn, { invoke });
-    const defaultOwner = {
-        tenantId: "default",
-        principalId: "default",
-        packageInstanceId: "default",
-        generationId: "default",
-    };
+    const defaultOwner = createDefaultProcessOwner();
     const effectiveOwner = options.owner || defaultOwner;
     // 外部注入的可能是平台级共享 ContextProcessAPI（未绑定 runId），直接复用会让
     // 多个 run 共享同一隔离与回收状态；此处派生 run 级实例保证隔离与自动回收均以 run 为单位

package/dist/runtime/events.js

@@ -1,4 +1,4 @@
-import { EVENT_BACKPRESSURE_LIMIT, EVENT_CURSOR_EXPIRED } from "../errors.js";
+import { ActionDockError, EVENT_BACKPRESSURE_LIMIT, EVENT_CURSOR_EXPIRED } from "../errors.js";
 /**
  * 订阅者通道：封装实时事件队列、监听器与终止状态。
  * 职责：
@@ -409,16 +409,13 @@ export class InMemoryEventSink {
         const earliestSeq = run.earliestRetainedSequence ?? 0;
         if (afterSequence !== undefined && afterSequence >= 0 && afterSequence < earliestSeq - 1) {
             const earliestCursor = run.earliestRetainedEventId ?? String(earliestSeq);
-            const expiredErr = new Error(`Event cursor '${after}' has expired; earliest available cursor is '${earliestCursor}'`);
-            expiredErr.code = EVENT_CURSOR_EXPIRED;
-            expiredErr.details = {
+            throw new ActionDockError(EVENT_CURSOR_EXPIRED, `Event cursor '${after}' has expired; earliest available cursor is '${earliestCursor}'`, {
                 cursor: after,
                 earliestCursor,
                 earliestRetainedCursor: earliestCursor,
                 earliestSequence: earliestSeq,
                 earliestEventId: run.earliestRetainedEventId,
-            };
-            throw expiredErr;
+            });
         }
     }
     /**

package/dist/runtime/identity.d.ts

@@ -0,0 +1,22 @@
+/**
+ * 包唯一物理与快照身份标识值对象（PackageIdentity）。
+ *
+ * 铁律 7：只在 PackageRuntime 创建时生成一次，统一传递给 ExecutionService、
+ * Runner、ProcessOwner、RunRecord 等，禁止内部组件自行 fallback。
+ */
+export interface PackageIdentity {
+    /** 包唯一逻辑标识符 */
+    readonly id: string;
+    /** 包物理实例标识符（单次加载/运行周期的全局唯一物理实例标识） */
+    readonly instanceId: string;
+    /** 快照代次标识符 */
+    readonly generation: string;
+}
+/**
+ * 创建 PackageIdentity 值对象单一事实工厂。
+ */
+export declare function createPackageIdentity(options: {
+    id: string;
+    instanceId?: string;
+    generation?: string;
+}): PackageIdentity;

package/dist/runtime/identity.js

@@ -0,0 +1,10 @@
+/**
+ * 创建 PackageIdentity 值对象单一事实工厂。
+ */
+export function createPackageIdentity(options) {
+    return Object.freeze({
+        id: options.id,
+        instanceId: options.instanceId || options.id,
+        generation: options.generation || "1",
+    });
+}

package/dist/runtime/index.d.ts

@@ -1,10 +1,9 @@
+export * from "./identity.js";
 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";
 export * from "./env.js";
 export * from "./clock.js";