@actiondock/core 2.5.1 → 2.7.0

package/dist/json/value-validator.js

@@ -0,0 +1,330 @@
+import { isForbiddenActionInputPropertyName } from "../input/flat-predicates.js";
+/** 默认 JSON 最大嵌套深度限制（防止恶意超深结构） */
+export const DEFAULT_MAX_JSON_DEPTH = 256;
+/**
+ * 按照 RFC 6901 转义单个 JSON Pointer 路径段。
+ *
+ * @param segment 路径段（属性名或数组索引）
+ * @returns 转义后的路径段
+ */
+export function escapeJsonPointerSegment(segment) {
+    return String(segment).replace(/~/g, "~0").replace(/\//g, "~1");
+}
+/**
+ * 将路径段追加到基础 RFC 6901 JSON Pointer 路径后。
+ *
+ * @param basePath 基础路径
+ * @param segment 待追加的路径段
+ * @returns 拼接后的 JSON Pointer
+ */
+export function appendJsonPointer(basePath, segment) {
+    return `${basePath}/${escapeJsonPointerSegment(segment)}`;
+}
+/**
+ * 内部统一 JSON 值与输入策略遍历校验引擎。
+ *
+ * 遍历规范：
+ * - 迭代式显式栈遍历：模拟调用栈，杜绝深层结构造成的堆栈溢出。
+ * - 严格数值有限性：全链路检查所有数值满足 Number.isFinite，拦截 NaN 与 Infinity。
+ * - 活跃祖先集合环路检测：仅在当前子树遍历期间在祖先集合中保留，完美放行有向无环（DAG）共享子结构。
+ * - 严格对象与原型校验：仅允许 Object.prototype 与 null 原型，拒绝 Date、Map、Set 等非纯数据对象与类实例。
+ * - 严格数组紧凑性：校验 0..length-1 全部存在，拒绝稀疏数组、额外属性与访问器元素。
+ * - Proxy 异常防御：对所有反射与属性检查执行防护拦截，杜绝未分类异常泄漏。
+ * - RFC 6901 路径追踪：全链路维护转义标准 JSON Pointer 路径。
+ */
+function walkJsonValue(value, options, checkForbiddenProperties = false) {
+    const maxDepth = options?.maxDepth ?? DEFAULT_MAX_JSON_DEPTH;
+    const ancestors = new Set();
+    const stack = [{ type: "ENTER", value, depth: 0, path: "" }];
+    while (stack.length > 0) {
+        const frame = stack.pop();
+        if (frame.type === "EXIT") {
+            ancestors.delete(frame.target);
+            continue;
+        }
+        const { value: val, depth, path } = frame;
+        if (val === null || typeof val === "boolean" || typeof val === "string") {
+            continue;
+        }
+        if (typeof val === "number") {
+            if (!Number.isFinite(val) || Number.isNaN(val)) {
+                return {
+                    valid: false,
+                    kind: "json-value",
+                    code: "NON_FINITE_NUMBER",
+                    reason: `Number is non-finite or NaN (${val})`,
+                    path,
+                };
+            }
+            continue;
+        }
+        if (typeof val === "undefined") {
+            return {
+                valid: false,
+                kind: "json-value",
+                code: "UNDEFINED_JSON_VALUE",
+                reason: "Undefined value is not allowed in JSON",
+                path,
+            };
+        }
+        if (typeof val === "function" ||
+            typeof val === "symbol" ||
+            typeof val === "bigint") {
+            return {
+                valid: false,
+                kind: "json-value",
+                code: "UNSUPPORTED_JSON_TYPE",
+                reason: `Unsupported JSON type '${typeof val}'`,
+                path,
+            };
+        }
+        if (typeof val === "object") {
+            try {
+                if (ancestors.has(val)) {
+                    return {
+                        valid: false,
+                        kind: "json-value",
+                        code: "CIRCULAR_REFERENCE",
+                        reason: "Circular reference detected in object structure",
+                        path,
+                    };
+                }
+                if (depth > maxDepth) {
+                    return {
+                        valid: false,
+                        kind: "json-value",
+                        code: "MAX_JSON_DEPTH",
+                        reason: `Max JSON depth limit (${maxDepth}) exceeded`,
+                        path,
+                    };
+                }
+                const proto = Object.getPrototypeOf(val);
+                const isArr = Array.isArray(val);
+                if (isArr) {
+                    if (proto !== Array.prototype) {
+                        return {
+                            valid: false,
+                            kind: "json-value",
+                            code: "INVALID_JSON_OBJECT",
+                            reason: "Array prototype must be Array.prototype",
+                            path,
+                        };
+                    }
+                    const len = val.length;
+                    if (typeof len !== "number" ||
+                        !Number.isInteger(len) ||
+                        len < 0 ||
+                        len > Number.MAX_SAFE_INTEGER) {
+                        return {
+                            valid: false,
+                            kind: "json-value",
+                            code: "INVALID_JSON_OBJECT",
+                            reason: "Array length is invalid",
+                            path,
+                        };
+                    }
+                    const ownKeys = Reflect.ownKeys(val);
+                    if (ownKeys.length !== len + 1) {
+                        return {
+                            valid: false,
+                            kind: "json-value",
+                            code: "INVALID_JSON_OBJECT",
+                            reason: "Array must be dense without extra properties or holes",
+                            path,
+                        };
+                    }
+                    ancestors.add(val);
+                    stack.push({ type: "EXIT", target: val });
+                    for (let i = len - 1; i >= 0; i--) {
+                        const keyStr = String(i);
+                        const desc = Object.getOwnPropertyDescriptor(val, keyStr);
+                        const elemPath = appendJsonPointer(path, i);
+                        if (!desc) {
+                            return {
+                                valid: false,
+                                kind: "json-value",
+                                code: "INVALID_JSON_OBJECT",
+                                reason: `Sparse array (missing element at index ${i})`,
+                                path: elemPath,
+                            };
+                        }
+                        if (desc.get !== undefined || desc.set !== undefined) {
+                            return {
+                                valid: false,
+                                kind: "json-value",
+                                code: "INVALID_JSON_OBJECT",
+                                reason: `Accessor property not allowed at array index ${i}`,
+                                path: elemPath,
+                            };
+                        }
+                        if (!desc.enumerable) {
+                            return {
+                                valid: false,
+                                kind: "json-value",
+                                code: "INVALID_JSON_OBJECT",
+                                reason: `Non-enumerable property not allowed at array index ${i}`,
+                                path: elemPath,
+                            };
+                        }
+                        if (desc.value === undefined) {
+                            return {
+                                valid: false,
+                                kind: "json-value",
+                                code: "UNDEFINED_JSON_VALUE",
+                                reason: `Undefined value is not allowed at array index ${i}`,
+                                path: elemPath,
+                            };
+                        }
+                        stack.push({
+                            type: "ENTER",
+                            value: desc.value,
+                            depth: depth + 1,
+                            path: elemPath,
+                        });
+                    }
+                }
+                else {
+                    if (proto !== Object.prototype && proto !== null) {
+                        return {
+                            valid: false,
+                            kind: "json-value",
+                            code: "INVALID_JSON_OBJECT",
+                            reason: "Object prototype must be Object.prototype or null",
+                            path,
+                        };
+                    }
+                    const ownKeys = Reflect.ownKeys(val);
+                    ancestors.add(val);
+                    stack.push({ type: "EXIT", target: val });
+                    for (let i = ownKeys.length - 1; i >= 0; i--) {
+                        const key = ownKeys[i];
+                        if (typeof key !== "string") {
+                            return {
+                                valid: false,
+                                kind: "json-value",
+                                code: "INVALID_JSON_OBJECT",
+                                reason: "Symbol-keyed properties are not allowed in JSON object",
+                                path: appendJsonPointer(path, String(key)),
+                            };
+                        }
+                        const propPath = appendJsonPointer(path, key);
+                        if (checkForbiddenProperties &&
+                            isForbiddenActionInputPropertyName(key)) {
+                            return {
+                                valid: false,
+                                kind: "input-policy",
+                                code: "FORBIDDEN_PROPERTY",
+                                property: key,
+                                path: propPath,
+                                reason: `Forbidden property "${key}" is not allowed in Action input`,
+                            };
+                        }
+                        const desc = Object.getOwnPropertyDescriptor(val, key);
+                        if (!desc) {
+                            return {
+                                valid: false,
+                                kind: "json-value",
+                                code: "INVALID_JSON_OBJECT",
+                                reason: `Property descriptor missing for key "${key}"`,
+                                path: propPath,
+                            };
+                        }
+                        if (desc.get !== undefined || desc.set !== undefined) {
+                            return {
+                                valid: false,
+                                kind: "json-value",
+                                code: "INVALID_JSON_OBJECT",
+                                reason: `Accessor properties (getters/setters) are not allowed for key "${key}"`,
+                                path: propPath,
+                            };
+                        }
+                        if (!desc.enumerable) {
+                            return {
+                                valid: false,
+                                kind: "json-value",
+                                code: "INVALID_JSON_OBJECT",
+                                reason: `Non-enumerable properties are not allowed for key "${key}"`,
+                                path: propPath,
+                            };
+                        }
+                        if (desc.value === undefined) {
+                            return {
+                                valid: false,
+                                kind: "json-value",
+                                code: "UNDEFINED_JSON_VALUE",
+                                reason: `Undefined value is not allowed for key "${key}"`,
+                                path: propPath,
+                            };
+                        }
+                        stack.push({
+                            type: "ENTER",
+                            value: desc.value,
+                            depth: depth + 1,
+                            path: propPath,
+                        });
+                    }
+                }
+            }
+            catch (err) {
+                return {
+                    valid: false,
+                    kind: "json-value",
+                    code: "INVALID_JSON_OBJECT",
+                    reason: `Failed to inspect object: ${err instanceof Error ? err.message : String(err)}`,
+                    path,
+                };
+            }
+        }
+    }
+    return { valid: true };
+}
+/**
+ * 校验值是否为合法的 Canonical JSON 兼容结构。
+ *
+ * @param value 待校验的目标值
+ * @param options 校验配置选项
+ * @returns 校验结果对象
+ */
+export function validateJsonValue(value, options) {
+    const res = walkJsonValue(value, options, false);
+    if (res.valid) {
+        return { valid: true };
+    }
+    if (res.kind === "input-policy") {
+        return {
+            valid: false,
+            code: "INVALID_JSON_OBJECT",
+            reason: res.reason,
+            path: res.path,
+        };
+    }
+    return {
+        valid: false,
+        code: res.code,
+        reason: res.reason,
+        path: res.path,
+    };
+}
+/**
+ * 校验 Action 输入值是否满足 Canonical JsonValue 规范且符合 ActionDock 安全策略。
+ * 在遍历过程中递归检查是否存在禁止属性（__proto__、constructor、prototype）。
+ *
+ * @param value 待校验的 Action 输入值
+ * @param options 校验配置选项
+ * @returns 校验结果对象
+ */
+export function validateActionInputValue(value, options) {
+    return walkJsonValue(value, options, true);
+}
+/**
+ * 断言值必须为合法的 Canonical JSON 兼容结构，若非法则抛出 TypeError。
+ *
+ * @param value 待断言的目标值
+ * @param options 校验配置选项
+ */
+export function assertJsonValue(value, options) {
+    const result = validateJsonValue(value, options);
+    if (!result.valid) {
+        throw new TypeError(`Invalid JSON value: ${result.reason}`);
+    }
+}

package/dist/platform/types.d.ts

@@ -53,6 +53,11 @@ export interface StorageFactoryOptions {
     dataDir?: string;
     inMemory?: boolean;
     customHome?: string;
+    /**
+     * 是否以数据目录持有者身份打开：true 时构造阶段收割死亡会话遗留的非终态运行记录。
+     * 默认 false（旁观查询打开，不触碰在途记录），供 CLI 查询命令与执行宿主并发共存。
+     */
+    recoverOrphans?: boolean;
 }
 /**
  * 跨运行时全局存储工厂配置选项。
@@ -61,6 +66,8 @@ export interface GlobalStorageFactoryOptions {
     dataDir?: string;
     inMemory?: boolean;
     customHome?: string;
+    /** 是否以持有者身份打开并收割遗留非终态运行记录（默认 false，旁观语义） */
+    recoverOrphans?: boolean;
 }
 /**
  * 跨运行时持久化存储工厂契约。

package/dist/process/control-arbiter.d.ts

@@ -0,0 +1,107 @@
+import type { ControlGrant } from "@actiondock/sdk";
+import type { ManagedProcessRecord, ProcessOwner } from "./managed-record.js";
+import type { StoredProcessRecord } from "./metadata-store.js";
+/**
+ * 控制权仲裁器宿主协作回调集合。
+ *
+ * 持有者始终为 ProcessManager：仲裁器仅经回调透传副作用，不反向依赖管理器。
+ */
+export interface ControlArbiterHost {
+    /** 控制权状态落盘（异步尽力而为） */
+    persistState(processId: string, patch: Partial<StoredProcessRecord>): unknown;
+    /** 排队路径授予成功时的凭据落盘（异步尽力而为） */
+    persistGrantReceipt(grant: ControlGrant, wait: {
+        requestId: string;
+        waitMs: number;
+        ttlMs: number;
+    }, proc: ManagedProcessRecord): unknown;
+    /** 控制权事件后的空闲定时器刷新（授予、续租与成功输入均触发） */
+    refreshIdleTimer(proc: ManagedProcessRecord): void;
+    /** 到期复核通过后的隔离处置（隔离而非释放） */
+    quarantineProcess(owner: ProcessOwner, processId: string, token?: string, reason?: string): unknown;
+    /** 宿主级等待者配额统计（含全部进程的排队等待者） */
+    countHostAcquireWaiters(): number;
+    /** 宿主等待者配额上限 */
+    readonly maxWaitersPerProcess: number;
+    /** 单进程等待者配额上限 */
+    readonly maxWaitersPerHost: number;
+}
+/**
+ * 控制权仲裁器。
+ *
+ * 单一职责：独占控制权状态机的全部推进路径——
+ * - 直接授予与 FIFO 等待队列（唯一唤醒）
+ * - TTL 定时器生命周期（设置、续租换新、清理）
+ * - 到期复核（复合控制态与凭据双重校验，转隔离而非释放）
+ * - 操作授权校验（write/control 提交前与调度复核共用）
+ * - 终态等待者单一拒绝入口
+ */
+export declare class ControlArbiter {
+    private readonly host;
+    constructor(host: ControlArbiterHost);
+    /**
+     * 尝试立即授予控制权：控制权空闲且无等待者时直接授予，
+     * 否则按 FIFO 进入等待队列并返回等待 Promise。
+     *
+     * 调用方（原 acquire 请求）在排队路径 resolve 后负责预约结算；
+     * 唤醒方负责凭据落盘，保持两阶段时序不变。
+     */
+    tryAcquire(proc: ManagedProcessRecord, input: {
+        requestId: string;
+        waitMs: number;
+        ttlMs: number;
+    }, call?: {
+        signal?: AbortSignal;
+    }, runId?: string): {
+        granted: boolean;
+        waiter?: Promise<ControlGrant>;
+    };
+    /**
+     * FIFO 入队单个等待者：注册超时定时器、中止监听与自清理钩子。
+     */
+    private enqueueWaiter;
+    /**
+     * 授予指定受管进程控制令牌：递增控制纪元、登记凭据并设置 TTL 定时器。
+     */
+    grantControl(proc: ManagedProcessRecord, requestId: string, ttlMs: number, runId?: string): ControlGrant;
+    /**
+     * 续租当前有效控制令牌：先清理旧 TTL 定时器再设置新定时器，
+     * 刷新到期时刻并联动空闲定时器。
+     */
+    renewGrant(proc: ManagedProcessRecord, ttlMs: number): ControlGrant;
+    /**
+     * 显式释放控制令牌：清理 TTL 定时器、凭据置空并唤醒下一个等待者。
+     */
+    releaseGrant(proc: ManagedProcessRecord): void;
+    /**
+     * 唤醒排队等待控制权的下一个调用者（唯一唤醒入口）：
+     * 授予令牌、由唤醒方落盘排队凭据并 resolve 原等待 Promise。
+     */
+    private wakeNextAcquireWaiter;
+    /**
+     * 控制权到期未释放时的复核：仍处于 held 且凭据有效时转隔离（隔离而非释放）。
+     */
+    handleGrantTtlExpired(proc: ManagedProcessRecord): void;
+    /**
+     * 操作提交前校验持有者令牌与授权（write/control 入队前与调度链路共用）。
+     */
+    validateOperation(proc: ManagedProcessRecord, token: string): void;
+    /**
+     * 校验当前持有凭据有效性（token 匹配且未过期），供 renew/release 提交前判定。
+     */
+    validateHeldGrant(proc: ManagedProcessRecord, token: string): void;
+    /**
+     * 终态等待者单一拒绝入口：按 FIFO 拒绝全部排队等待者。
+     *
+     * 终态转移（exit/error/stop/quarantine）必须经由此方法清空等待队列，
+     * 禁止直接操作 acquireWaiters 数组。
+     */
+    revokeAllWaiters(proc: ManagedProcessRecord, reason: {
+        code: string;
+        message: string;
+    }): void;
+    /**
+     * 清理进程全部控制权相关定时器与等待队列（stop/退出/故障路径统一入口）。
+     */
+    disposeProcess(proc: ManagedProcessRecord): void;
+}