@actiondock/core 2.10.0 → 2.12.0

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

@@ -0,0 +1,64 @@
+import { type Clock } from "./clock.js";
+export declare const DEFAULT_FILE_LOCK_STALE_MS = 10000;
+export declare const DEFAULT_FILE_LOCK_ACQUIRE_TIMEOUT_MS = 15000;
+export declare const DEFAULT_FILE_LOCK_RETRY_DELAY_MS = 25;
+export declare const DEFAULT_FILE_LOCK_HEARTBEAT_MS = 3000;
+export declare const LOCK_METADATA_FILE = "metadata.json";
+export interface FileLockMetadata {
+    pid: number;
+    token: string;
+    createdAt: string;
+    sessionToken?: string;
+    lockToken?: string;
+    [key: string]: unknown;
+}
+export interface FileLockOptions {
+    staleMs?: number;
+    acquireTimeoutMs?: number;
+    retryDelayMs?: number;
+    heartbeatMs?: number;
+    metadata?: Record<string, unknown>;
+    mtimeFirst?: boolean;
+    createLockError?: (message: string) => Error;
+    assertHolderReclaimable?: (metadata: FileLockMetadata) => void;
+    clock?: Clock;
+}
+export interface FileLockHandle {
+    lockPath: string;
+    metadata: FileLockMetadata;
+    release(): void | Promise<void>;
+}
+export interface LockDriver<T> {
+    mkdir(path: string, options?: {
+        mode?: number;
+        recursive?: boolean;
+    }): T;
+    rmdir(path: string, options?: {
+        recursive?: boolean;
+        force?: boolean;
+    }): T;
+    readFile(path: string, encoding: "utf-8"): T;
+    writeFile(path: string, data: string, options?: {
+        mode?: number;
+    }): T;
+    rename(oldPath: string, newPath: string): T;
+    stat(path: string): T;
+    unlink(path: string): T;
+    delay(ms: number): T;
+    timeExceeded(deadline: number): boolean;
+    setInterval?(fn: () => void, ms: number): NodeJS.Timeout;
+}
+export declare const syncLockDriver: LockDriver<any>;
+export declare const asyncLockDriver: LockDriver<Promise<any>>;
+export declare function runSync<T>(driver: LockDriver<any>, machine: Generator<any, T, any>): T;
+export declare function runAsync<T>(driver: LockDriver<Promise<any>>, machine: Generator<any, T, any>): Promise<T>;
+export declare function readLockMetadata(lockPath: string): Promise<FileLockMetadata | undefined>;
+export declare function readLockMetadataSync(lockPath: string): FileLockMetadata | undefined;
+export declare function isStaleLock(lockPath: string, staleMs?: number, options?: FileLockOptions, clock?: Clock): Promise<boolean>;
+export declare function isStaleLockSync(lockPath: string, staleMs?: number, options?: FileLockOptions, clock?: Clock): boolean;
+export declare function isLockHeld(lockPath: string, excludeSelf?: boolean, clock?: Clock): boolean;
+export declare function safeReleaseFileLock(lockPath: string, expectedToken?: string, expectedSessionToken?: string): Promise<void>;
+export declare function safeReleaseFileLockSync(lockPath: string, expectedToken?: string, expectedSessionToken?: string): void;
+export declare function acquireFileLockSync(lockPath: string, options?: FileLockOptions): FileLockHandle;
+export declare function acquireFileLock(lockPath: string, options?: FileLockOptions): Promise<FileLockHandle>;
+export declare function withFileLock<T>(lockPath: string, fn: () => T | Promise<T>, options?: FileLockOptions): Promise<T>;

package/dist/storage/file-lock.js

@@ -0,0 +1,447 @@
+import { randomUUID } from "node:crypto";
+import { existsSync, mkdirSync, readFileSync, renameSync, rmSync, statSync, writeFileSync, } from "node:fs";
+import { mkdir, readFile, rename, rm, stat, utimes, writeFile } from "node:fs/promises";
+import { dirname, join, resolve } from "node:path";
+import { isProcessAlive } from "../utils/index.js";
+import { SystemClock } from "./clock.js";
+import { ActionDockError, STORAGE_BUSY, TIMEOUT } from "../errors.js";
+const defaultClock = new SystemClock();
+export const DEFAULT_FILE_LOCK_STALE_MS = 10000;
+export const DEFAULT_FILE_LOCK_ACQUIRE_TIMEOUT_MS = 15000;
+export const DEFAULT_FILE_LOCK_RETRY_DELAY_MS = 25;
+export const DEFAULT_FILE_LOCK_HEARTBEAT_MS = 3000;
+export const LOCK_METADATA_FILE = "metadata.json";
+const activeLockPaths = new Set();
+export const syncLockDriver = {
+    mkdir: (path, opts) => mkdirSync(path, opts),
+    rmdir: (path, opts) => rmSync(path, opts),
+    readFile: (path, enc) => readFileSync(path, enc),
+    writeFile: (path, data, opts) => writeFileSync(path, data, opts),
+    rename: (oldPath, newPath) => renameSync(oldPath, newPath),
+    stat: (path) => statSync(path),
+    unlink: (path) => rmSync(path, { force: true }),
+    delay: () => { },
+    timeExceeded: () => false,
+};
+export const asyncLockDriver = {
+    mkdir: (path, opts) => mkdir(path, opts),
+    rmdir: (path, opts) => rm(path, opts),
+    readFile: (path, enc) => readFile(path, enc),
+    writeFile: (path, data, opts) => writeFile(path, data, opts),
+    rename: (oldPath, newPath) => rename(oldPath, newPath),
+    stat: (path) => stat(path),
+    unlink: (path) => rm(path, { force: true }),
+    delay: (ms) => new Promise(resolve => setTimeout(resolve, ms)),
+    timeExceeded: (deadline) => Date.now() >= deadline,
+    setInterval: (fn, ms) => setInterval(fn, ms),
+};
+export function runSync(driver, machine) {
+    let result = machine.next();
+    while (!result.done) {
+        try {
+            const value = result.value(driver);
+            result = machine.next(value);
+        }
+        catch (err) {
+            result = machine.throw(err);
+        }
+    }
+    return result.value;
+}
+export async function runAsync(driver, machine) {
+    let result = machine.next();
+    while (!result.done) {
+        try {
+            const value = await result.value(driver);
+            result = machine.next(value);
+        }
+        catch (err) {
+            result = machine.throw(err);
+        }
+    }
+    return result.value;
+}
+function* readLockMetadataMachine(lockPath) {
+    let isDir = false;
+    try {
+        const s = yield (d) => d.stat(lockPath);
+        isDir = s.isDirectory();
+    }
+    catch {
+        return undefined;
+    }
+    const targetFile = isDir ? join(lockPath, LOCK_METADATA_FILE) : lockPath;
+    try {
+        const raw = yield (d) => d.readFile(targetFile, "utf-8");
+        const parsed = JSON.parse(raw);
+        if (parsed && typeof parsed === "object") {
+            return parsed;
+        }
+    }
+    catch {
+        // 忽略异常
+    }
+    return undefined;
+}
+export async function readLockMetadata(lockPath) {
+    return runAsync(asyncLockDriver, readLockMetadataMachine(lockPath));
+}
+export function readLockMetadataSync(lockPath) {
+    return runSync(syncLockDriver, readLockMetadataMachine(lockPath));
+}
+function* checkIsStaleLock(lockPath, staleMs, options, clock) {
+    const effectiveClock = options?.clock ?? clock;
+    let lockAgeMs;
+    try {
+        const s = yield (d) => d.stat(lockPath);
+        lockAgeMs = effectiveClock.now().getTime() - s.mtimeMs;
+    }
+    catch (err) {
+        throw err;
+    }
+    if (options?.mtimeFirst && lockAgeMs <= staleMs) {
+        return false;
+    }
+    const metadata = yield* readLockMetadataMachine(lockPath);
+    if (options?.assertHolderReclaimable && metadata) {
+        options.assertHolderReclaimable(metadata);
+    }
+    if (metadata === undefined) {
+        if (lockAgeMs <= staleMs) {
+            return false;
+        }
+        return true;
+    }
+    if (typeof metadata.pid === "number") {
+        if (metadata.pid === process.pid) {
+            return !activeLockPaths.has(resolve(lockPath));
+        }
+        return !isProcessAlive(metadata.pid);
+    }
+    return lockAgeMs > staleMs;
+}
+export async function isStaleLock(lockPath, staleMs = DEFAULT_FILE_LOCK_STALE_MS, options, clock) {
+    return runAsync(asyncLockDriver, checkIsStaleLock(lockPath, staleMs, options, clock ?? defaultClock));
+}
+export function isStaleLockSync(lockPath, staleMs = DEFAULT_FILE_LOCK_STALE_MS, options, clock) {
+    return runSync(syncLockDriver, checkIsStaleLock(lockPath, staleMs, options, clock ?? defaultClock));
+}
+export function isLockHeld(lockPath, excludeSelf = true, clock) {
+    if (!existsSync(lockPath))
+        return false;
+    const effectiveClock = clock ?? defaultClock;
+    try {
+        const meta = readLockMetadataSync(lockPath);
+        if (meta && typeof meta.pid === "number") {
+            if (excludeSelf && meta.pid === process.pid) {
+                return false;
+            }
+            return isProcessAlive(meta.pid);
+        }
+        const stat = statSync(lockPath);
+        return effectiveClock.now().getTime() - stat.mtimeMs < DEFAULT_FILE_LOCK_STALE_MS;
+    }
+    catch {
+        return false;
+    }
+}
+function* safeReleaseMachine(lockPath, expectedToken, expectedSessionToken) {
+    try {
+        const meta = yield* readLockMetadataMachine(lockPath);
+        if (meta) {
+            if (expectedSessionToken && meta.sessionToken && meta.sessionToken !== expectedSessionToken)
+                return;
+            if (expectedToken && meta.token && meta.token !== expectedToken)
+                return;
+        }
+        yield (d) => d.rmdir(lockPath, { recursive: true, force: true });
+    }
+    catch {
+        // 忽略释放异常
+    }
+}
+export async function safeReleaseFileLock(lockPath, expectedToken, expectedSessionToken) {
+    return runAsync(asyncLockDriver, safeReleaseMachine(lockPath, expectedToken, expectedSessionToken));
+}
+export function safeReleaseFileLockSync(lockPath, expectedToken, expectedSessionToken) {
+    return runSync(syncLockDriver, safeReleaseMachine(lockPath, expectedToken, expectedSessionToken));
+}
+function* checkIsReclaimGuardActive(reclaimPath, staleMs, clock) {
+    try {
+        const raw = yield (d) => d.readFile(join(reclaimPath, "reclaim.json"), "utf-8");
+        const meta = JSON.parse(raw);
+        if (typeof meta.pid === "number") {
+            const age = clock.now().getTime() - (meta.createdAt ?? 0);
+            if (age < staleMs && isProcessAlive(meta.pid))
+                return true;
+        }
+    }
+    catch { }
+    try {
+        const s = yield (d) => d.stat(reclaimPath);
+        return clock.now().getTime() - s.mtimeMs < staleMs;
+    }
+    catch {
+        return false;
+    }
+}
+function* tryAcquireReclaimGuard(reclaimPath, staleMs, clock) {
+    try {
+        yield (d) => d.mkdir(reclaimPath, { mode: 0o700 });
+        yield (d) => d.writeFile(join(reclaimPath, "reclaim.json"), JSON.stringify({ pid: process.pid, createdAt: clock.now().getTime() }), { mode: 0o600 });
+        return true;
+    }
+    catch (err) {
+        if (err.code !== "EEXIST")
+            throw err;
+    }
+    const active = yield* checkIsReclaimGuardActive(reclaimPath, staleMs, clock);
+    if (!active) {
+        try {
+            yield (d) => d.rmdir(reclaimPath, { recursive: true, force: true });
+            yield (d) => d.mkdir(reclaimPath, { mode: 0o700 });
+            yield (d) => d.writeFile(join(reclaimPath, "reclaim.json"), JSON.stringify({ pid: process.pid, createdAt: clock.now().getTime() }), { mode: 0o600 });
+            return true;
+        }
+        catch {
+            return false;
+        }
+    }
+    return false;
+}
+function* acquireLockMachine(lockPath, options, isAsync) {
+    const clock = options?.clock ?? defaultClock;
+    const staleMs = options?.staleMs ?? DEFAULT_FILE_LOCK_STALE_MS;
+    const acquireTimeoutMs = options?.acquireTimeoutMs ?? DEFAULT_FILE_LOCK_ACQUIRE_TIMEOUT_MS;
+    const retryDelayMs = options?.retryDelayMs ?? DEFAULT_FILE_LOCK_RETRY_DELAY_MS;
+    const heartbeatMs = options?.heartbeatMs ?? DEFAULT_FILE_LOCK_HEARTBEAT_MS;
+    const deadline = clock.monotonic() + acquireTimeoutMs;
+    const resolvedPath = resolve(lockPath);
+    const reclaimPath = `${lockPath}.reclaim`;
+    const parentDir = dirname(lockPath);
+    try {
+        yield (d) => d.mkdir(parentDir, { recursive: true });
+    }
+    catch { }
+    let token = "";
+    let metadata;
+    let reclaimMetadataWritten = false;
+    let acquired = false;
+    while (!acquired) {
+        const guardActive = yield* checkIsReclaimGuardActive(reclaimPath, staleMs, clock);
+        if (guardActive) {
+            if (!isAsync) {
+                if (options?.createLockError) {
+                    throw options.createLockError(`Lock '${lockPath}' is currently being reclaimed by another active process`);
+                }
+                throw new ActionDockError(STORAGE_BUSY, `Lock '${lockPath}' is currently being reclaimed by another active process`);
+            }
+        }
+        else {
+            try {
+                yield (d) => d.mkdir(lockPath, { mode: 0o700 });
+                activeLockPaths.add(resolvedPath);
+                acquired = true;
+            }
+            catch (err) {
+                if (err.code !== "EEXIST") {
+                    throw err;
+                }
+            }
+        }
+        if (!acquired) {
+            let stale = false;
+            try {
+                stale = yield* checkIsStaleLock(lockPath, staleMs, options, clock);
+            }
+            catch (err) {
+                if (err.code !== "ENOENT")
+                    throw err;
+            }
+            if (stale) {
+                const guardAcquired = yield* tryAcquireReclaimGuard(reclaimPath, staleMs, clock);
+                if (!guardAcquired) {
+                    if (!isAsync) {
+                        if (options?.createLockError) {
+                            throw options.createLockError(`Lock '${lockPath}' is currently held by another active process`);
+                        }
+                        throw new ActionDockError(STORAGE_BUSY, `Lock '${lockPath}' is currently held by another active process`);
+                    }
+                }
+                else {
+                    try {
+                        let stillStale = false;
+                        try {
+                            stillStale = yield* checkIsStaleLock(lockPath, staleMs, options, clock);
+                        }
+                        catch (err) {
+                            if (err.code === "ENOENT")
+                                stillStale = true;
+                            else
+                                throw err;
+                        }
+                        if (!stillStale) {
+                            if (options?.createLockError) {
+                                throw options.createLockError(`Lock '${lockPath}' is currently held by another active process`);
+                            }
+                            throw new ActionDockError(STORAGE_BUSY, `Lock '${lockPath}' is currently held by another active process`);
+                        }
+                        let isDir = false;
+                        try {
+                            const s = yield (d) => d.stat(lockPath);
+                            isDir = s.isDirectory();
+                        }
+                        catch { }
+                        if (!isDir) {
+                            try {
+                                yield (d) => d.unlink(lockPath);
+                            }
+                            catch { }
+                            try {
+                                yield (d) => d.mkdir(lockPath, { mode: 0o700 });
+                            }
+                            catch (err) {
+                                if (err.code !== "EEXIST")
+                                    throw err;
+                            }
+                        }
+                        // 在接管守卫独占保护下写入并核验元数据，杜绝外部并发读取到残余陈旧元数据
+                        token = randomUUID();
+                        metadata = {
+                            pid: process.pid,
+                            createdAt: clock.now().toISOString(),
+                            ...options?.metadata,
+                            token,
+                        };
+                        const metaPath = join(lockPath, LOCK_METADATA_FILE);
+                        const tmpPath = join(lockPath, `meta.tmp.${process.pid}.${randomUUID().slice(0, 8)}`);
+                        yield (d) => d.writeFile(tmpPath, JSON.stringify(metadata, null, 2), { mode: 0o600 });
+                        yield (d) => d.rename(tmpPath, metaPath);
+                        const raw = yield (d) => d.readFile(metaPath, "utf-8");
+                        const verify = JSON.parse(raw);
+                        if (verify?.token !== token) {
+                            if (options?.createLockError) {
+                                throw options.createLockError(`Failed to verify acquired lock ownership in '${lockPath}'`);
+                            }
+                            throw new ActionDockError(STORAGE_BUSY, `Failed to verify acquired lock ownership in '${lockPath}'`);
+                        }
+                        activeLockPaths.add(resolvedPath);
+                        acquired = true;
+                        reclaimMetadataWritten = true;
+                    }
+                    finally {
+                        try {
+                            yield (d) => d.rmdir(reclaimPath, { recursive: true, force: true });
+                        }
+                        catch { }
+                    }
+                }
+            }
+        }
+        if (!acquired) {
+            if (isAsync) {
+                const exceeded = clock.monotonic() >= deadline;
+                if (exceeded) {
+                    if (options?.createLockError) {
+                        throw options.createLockError(`Failed to acquire lock '${lockPath}' within ${acquireTimeoutMs}ms`);
+                    }
+                    throw new ActionDockError(TIMEOUT, `Failed to acquire lock '${lockPath}' within ${acquireTimeoutMs}ms`);
+                }
+                yield () => clock.sleep(retryDelayMs);
+            }
+            else {
+                if (options?.createLockError) {
+                    throw options.createLockError(`Lock '${lockPath}' is currently held by another active process`);
+                }
+                throw new ActionDockError(STORAGE_BUSY, `Lock '${lockPath}' is currently held by another active process`);
+            }
+        }
+    }
+    if (!reclaimMetadataWritten) {
+        token = randomUUID();
+        metadata = {
+            pid: process.pid,
+            createdAt: clock.now().toISOString(),
+            ...options?.metadata,
+            token,
+        };
+        const metaPath = join(lockPath, LOCK_METADATA_FILE);
+        const tmpPath = join(lockPath, `meta.tmp.${process.pid}.${randomUUID().slice(0, 8)}`);
+        try {
+            yield (d) => d.writeFile(tmpPath, JSON.stringify(metadata, null, 2), { mode: 0o600 });
+            yield (d) => d.rename(tmpPath, metaPath);
+            const raw = yield (d) => d.readFile(metaPath, "utf-8");
+            const verify = JSON.parse(raw);
+            if (verify?.token !== token) {
+                throw new Error("Lock metadata verification failed");
+            }
+        }
+        catch (err) {
+            activeLockPaths.delete(resolvedPath);
+            try {
+                yield (d) => d.rmdir(lockPath, { recursive: true, force: true });
+            }
+            catch { }
+            if (options?.createLockError) {
+                throw options.createLockError(`Failed to write or verify lock metadata for '${lockPath}'`);
+            }
+            throw new ActionDockError(STORAGE_BUSY, `Failed to write or verify lock metadata for '${lockPath}'`);
+        }
+    }
+    let timer;
+    if (isAsync && heartbeatMs > 0) {
+        timer = yield (d) => {
+            if (d.setInterval) {
+                return d.setInterval(() => {
+                    const now = clock.now();
+                    utimes(lockPath, now, now).catch(() => { });
+                }, heartbeatMs);
+            }
+        };
+        if (timer?.unref) {
+            timer.unref();
+        }
+    }
+    let released = false;
+    const release = () => {
+        if (released)
+            return;
+        released = true;
+        if (timer) {
+            clearInterval(timer);
+        }
+        activeLockPaths.delete(resolvedPath);
+    };
+    return {
+        lockPath,
+        metadata: metadata,
+        release,
+    };
+}
+export function acquireFileLockSync(lockPath, options) {
+    const handle = runSync(syncLockDriver, acquireLockMachine(lockPath, options, false));
+    const origRelease = handle.release;
+    handle.release = () => {
+        origRelease();
+        safeReleaseFileLockSync(lockPath, handle.metadata.token, handle.metadata.sessionToken);
+    };
+    return handle;
+}
+export async function acquireFileLock(lockPath, options) {
+    const handle = await runAsync(asyncLockDriver, acquireLockMachine(lockPath, options, true));
+    const origRelease = handle.release;
+    handle.release = async () => {
+        origRelease();
+        await safeReleaseFileLock(lockPath, handle.metadata.token, handle.metadata.sessionToken);
+    };
+    return handle;
+}
+export async function withFileLock(lockPath, fn, options) {
+    const lock = await acquireFileLock(lockPath, options);
+    try {
+        return await fn();
+    }
+    finally {
+        await lock.release();
+    }
+}

package/dist/storage/index.d.ts

@@ -1,9 +1,9 @@
 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 { NodeSqliteDriver } from "./sqlite-driver.js";
+export { normalizeSqliteParams } from "./params.js";
 export * from "./sqlite-driver.js";
-export * from "./lazy.js";
 export * from "./mask.js";
 export * from "./params.js";
 export * from "./sqlite.js";

package/dist/storage/index.js

@@ -1,11 +1,12 @@
 import { join, relative, resolve } from "node:path";
 import { assertValidPackageId, getActionDockHome, isPathOutsideBoundary } from "../utils/index.js";
+import { ActionDockError, PATH_TRAVERSAL } from "../errors.js";
 import { SqliteRuntimeStorage } from "./sqlite.js";
 export { DataDirLock, isProcessAlive, } from "./data-dir-lock.js";
 export * from "./clock.js";
-export * from "./driver.js";
+export { NodeSqliteDriver } from "./sqlite-driver.js";
+export { normalizeSqliteParams } from "./params.js";
 export * from "./sqlite-driver.js";
-export * from "./lazy.js";
 export * from "./mask.js";
 export * from "./params.js";
 export * from "./sqlite.js";
@@ -34,7 +35,7 @@ export function resolveDatabasePath(packageId, options = {}) {
         const dbPath = resolve(rootDir, safePkgPath, "runtime.db");
         const rel = relative(rootDir, dbPath);
         if (isPathOutsideBoundary(rel)) {
-            throw new Error(`'database dataDir path' escapes boundary '${rootDir}': ${dbPath}`);
+            throw new ActionDockError(PATH_TRAVERSAL, `'database dataDir path' escapes boundary '${rootDir}': ${dbPath}`);
         }
         return dbPath;
     }
@@ -43,7 +44,7 @@ export function resolveDatabasePath(packageId, options = {}) {
     const dbPath = resolve(rootDir, safePkgPath, "runtime.db");
     const rel = relative(rootDir, dbPath);
     if (isPathOutsideBoundary(rel)) {
-        throw new Error(`'database storage path' escapes boundary '${rootDir}': ${dbPath}`);
+        throw new ActionDockError(PATH_TRAVERSAL, `'database storage path' escapes boundary '${rootDir}': ${dbPath}`);
     }
     return dbPath;
 }

package/dist/storage/run-liveness.d.ts

@@ -0,0 +1,48 @@
+import type { Clock } from "./clock.js";
+/**
+ * 无进程标识的遗留记录心跳过期阈值（毫秒）。
+ *
+ * 遗留记录（未落库宿主进程标识的旧版本写入）无法做进程存活探测，只能依赖
+ * 心跳时间戳兜底判定。阈值必须显著大于执行服务的心跳刷新间隔
+ * （RUN_HEARTBEAT_INTERVAL_MS），保证心跳正常的宿主绝不被误判过期；
+ * 同时保持足够小，使真正崩溃后的遗留记录能在下次打开时被及时收敛。
+ */
+export declare const RUN_LIVENESS_GRACE_MS = 90000;
+/**
+ * 候选收割记录的最小判定输入。
+ *
+ * 只取判定所需字段，避免收割判定逻辑耦合完整运行记录投影。
+ */
+export interface LivenessCandidate {
+    /** 运行标识 */
+    id: string;
+    /** 运行生命周期状态（可选，终态记录不属于宿主死亡异常） */
+    status?: string;
+    /** 写入方宿主进程标识（遗留记录可能缺失） */
+    hostPid?: number | null;
+    /** 最后一次心跳刷新时间（ISO 8601） */
+    heartbeatAt?: string | null;
+    /** 运行开始时间（ISO 8601） */
+    startedAt?: string | null;
+}
+/**
+ * 进程存活探测函数契约（便于测试注入确定性替身）。
+ */
+export type ProcessLivenessProbe = (pid: number) => boolean;
+/**
+ * 判定单条运行记录的执行宿主是否确认死亡。
+ *
+ * 存活判断核心准则：
+ * - 终态记录不属于「宿主死亡」的在途异常，返回 false；
+ * - 携带合法 hostPid 时以进程探测（process.kill(pid, 0)）为准，进程明确不存在（ESRCH）才判死；
+ * - 无 hostPid 时仅在存在显式 heartbeatAt 且超时超过宽限期才判死；
+ * - 缺少可靠存活依据时，严禁凭「开始时间超过九十秒」认定死亡，保守返回 false。
+ *
+ * @param candidate 候选记录
+ * @param options 可选注入：进程探测替身、时钟替身与心跳宽限期
+ */
+export declare function isRunHostDead(candidate: LivenessCandidate, options?: {
+    probe?: ProcessLivenessProbe;
+    clock?: Clock;
+    graceMs?: number;
+}): boolean;

package/dist/storage/run-liveness.js

@@ -0,0 +1,44 @@
+import { isProcessAlive } from "../utils/index.js";
+import { isTerminalRunStatus } from "./types.js";
+/**
+ * 无进程标识的遗留记录心跳过期阈值（毫秒）。
+ *
+ * 遗留记录（未落库宿主进程标识的旧版本写入）无法做进程存活探测，只能依赖
+ * 心跳时间戳兜底判定。阈值必须显著大于执行服务的心跳刷新间隔
+ * （RUN_HEARTBEAT_INTERVAL_MS），保证心跳正常的宿主绝不被误判过期；
+ * 同时保持足够小，使真正崩溃后的遗留记录能在下次打开时被及时收敛。
+ */
+export const RUN_LIVENESS_GRACE_MS = 90_000;
+/**
+ * 判定单条运行记录的执行宿主是否确认死亡。
+ *
+ * 存活判断核心准则：
+ * - 终态记录不属于「宿主死亡」的在途异常，返回 false；
+ * - 携带合法 hostPid 时以进程探测（process.kill(pid, 0)）为准，进程明确不存在（ESRCH）才判死；
+ * - 无 hostPid 时仅在存在显式 heartbeatAt 且超时超过宽限期才判死；
+ * - 缺少可靠存活依据时，严禁凭「开始时间超过九十秒」认定死亡，保守返回 false。
+ *
+ * @param candidate 候选记录
+ * @param options 可选注入：进程探测替身、时钟替身与心跳宽限期
+ */
+export function isRunHostDead(candidate, options) {
+    if (candidate.status && isTerminalRunStatus(candidate.status)) {
+        return false;
+    }
+    const pid = candidate.hostPid;
+    if (typeof pid === "number" && Number.isInteger(pid) && pid > 0) {
+        const probe = options?.probe ?? isProcessAlive;
+        // 存活（含权限受限的 EPERM 保守存活）一律保留；仅明确的进程不存在才判死
+        return !probe(pid);
+    }
+    if (candidate.heartbeatAt) {
+        const heartbeatMs = Date.parse(candidate.heartbeatAt);
+        if (!Number.isNaN(heartbeatMs)) {
+            const graceMs = options?.graceMs ?? RUN_LIVENESS_GRACE_MS;
+            const nowMs = options?.clock ? options.clock.now().getTime() : Date.now();
+            return nowMs - heartbeatMs > graceMs;
+        }
+    }
+    // 缺少可靠依据（既无有效 hostPid 也无有效 heartbeatAt）：绝不凭 startedAt 认定死亡
+    return false;
+}

package/dist/storage/sqlite-config.d.ts

@@ -0,0 +1,16 @@
+import type { SqliteDriver } from "./types.js";
+import type { Clock } from "./clock.js";
+export declare class SqliteConfigStore {
+    private statementCache;
+    private driver;
+    private packageId;
+    private dbPath;
+    private clock;
+    constructor(driver: SqliteDriver, packageId: string, dbPath: string, clock: Clock);
+    private getStatement;
+    getConfig<T = unknown>(key: string): T | undefined;
+    listConfig(): Record<string, unknown>;
+    setConfig(key: string, value: unknown): void;
+    deleteConfig(key: string): boolean;
+    close(): void;
+}