@actiondock/core 2.10.0 → 2.11.0

package/dist/storage/types.d.ts

@@ -200,7 +200,16 @@ export interface RuntimeStorage {
         actionId?: string;
         status?: string;
         limit?: number;
+        offset?: number;
     }): RunRecord[];
+    /** 统计符合条件的运行记录总数 */
+    countRuns?(options?: {
+        actionId?: string;
+        status?: string;
+        requestIds?: string[];
+    }): number;
+    /** 查询单条运行记录并补齐幂等请求标识关联（详情路径专用） */
+    getRunWithRequestId?(id: string): RunRecord | null;
     clearRuns(options?: {
         actionId?: string;
         status?: string;
@@ -210,14 +219,38 @@ export interface RuntimeStorage {
     /** 按保留策略清理过期及超额的终态运行记录（基于时间与数量策略） */
     cleanExpiredRuns?(policy?: RunsRetentionPolicy): number;
     /**
-     * 收敛死亡会话遗留的非终态运行任务（含无会话标识的遗留非终态记录），
+     * 收敛死亡宿主遗留的非终态运行任务（含无会话标识的遗留非终态记录），
      * 统一收敛为 interrupted。历史别名 recoverRunningRuns 已合并至本方法。
+     *
+     * 判定依据是宿主存活而不是会话归属：仅收割进程探测失败或心跳过期的记录，
+     * 无法确认死亡时保守保留，避免误杀并发进程的在途任务。
      */
-    recoverDeadSessionRuns?(currentHostSessionId?: string): number | Promise<number>;
+    recoverDeadSessionRuns?(currentHostSessionId?: string, options?: {
+        probe?: import("./run-liveness.js").ProcessLivenessProbe;
+    }): number | Promise<number>;
+    /** 刷新在途运行记录的心跳时间戳（供执行宿主周期性调用，支撑存活判定） */
+    touchRunHeartbeat?(runIds: string[]): number;
     /** 确保底层存储与 Schema 初始化完成 */
     ensureInitialized?(): Promise<void>;
     checkAndRecordIdempotency?(record: IdempotencyRecord): IdempotencyCheckResult;
     getIdempotencyRecord?(ownerId: string, actionRef: string, requestId: string): IdempotencyRecord | undefined;
+    /**
+     * 按客户端幂等请求标识批量反查运行记录（仅限当前包范围）。
+     *
+     * 不按 ownerId 隔离：查询方（CLI 旁观视图）与写入方（后台派工进程）分属
+     * 不同宿主会话，ownerId 天然不一致；requestId 本身即跨进程全局唯一的外部
+     * 事实源，包维度隔离已提供足够边界。
+     */
+    listRunsByRequestIds?(requestIds: string[]): RunRecord[];
+    /** 按客户端幂等请求标识反查关联运行记录总数 */
+    countRunsByRequestIds?(requestIds: string[], options?: {
+        actionId?: string;
+        status?: string;
+    }): number;
+    /** 反查运行记录关联的幂等请求标识映射（仅限当前包范围，无关联时不含对应键） */
+    getRunRequestIds?(runIds: string[]): Record<string, string>;
+    appendEvent?(eventType: string, payload: unknown): void;
+    queryEvents?(eventType?: string): any[];
     /** 关闭底层 SQLite 数据库连接并释放句柄 */
     close(): void | Promise<void>;
 }

package/dist/utils/index.d.ts

@@ -1,20 +1,23 @@
-export { isLoopbackHost } from "./net.js";
-export { isProcessAlive } from "./process.js";
 /**
- * 语义化版本元数据结构。
+ * 检查指定的主机地址是否为本地回环接口（Loopback Host）。
+ * 支持 127.0.0.1, localhost, ::1 等形式。
+ *
+ * @param host 主机名或 IP 字符串
  */
-export interface SemVer {
-    major: number;
-    minor: number;
-    patch: number;
-    prerelease?: string;
-}
+export declare function isLoopbackHost(host: string): boolean;
 /**
- * 解析基础 SemVer 版本字符串（单一事实源）。
- * 仅接受可选 v/= 前缀的严格三段式语义化版本，可携带预发布后缀；
- * 其余形态（两段式、非数值等）返回 null，由调用方自行兜底。
+ * 检查目标进程是否处于存活状态（跨域通用谓词单一事实源）。
+ *
+ * 基于 process.kill(pid, 0) 探测：无异常视为存活；ESRCH（进程不存在）
+ * 视为已死；其他异常（如 EPERM，权限不足但进程存在）保守视为存活，
+ * 避免权限受限环境下误判他人持有进程死亡而抢占其锁。
+ *
+ * @param pid 待检测的进程标识符
  */
-export declare function parseSemVer(v: string): SemVer | null;
+export declare function isProcessAlive(pid: number): boolean;
+/** 转引独立的语义化版本纯函数，保持既有公共导出面。 */
+export type { SemVer } from "./semver.js";
+export { parseSemVer } from "./semver.js";
 /**
  * 目录遍历条目描述。
  */
@@ -53,7 +56,7 @@ export interface TraverseDirectoryOptions {
  */
 export declare function traverseDirectory(root: string, options?: TraverseDirectoryOptions): TraverseDirectoryEntry[];
 /**
- * 跨运行时安全查找可执行文件绝对物理路径。
+ * 安全查找可执行文件绝对物理路径。
  *
  * 注意：本函数为同步实现，内部同步遍历 PATH 逐个探测物理文件存在性；
  * 当前全部调用方（doctor 体检与测试 CLI 桥）均为同步链路，serve 链路未使用本函数，
@@ -101,3 +104,4 @@ export declare function assertPathWithinRoot(rootDir: string, targetPath: string
  * Backwards-compatible alias for assertPathWithinRoot targeting project roots.
  */
 export declare function assertWithinProjectRoot(projectRoot: string, subDir: string, fieldName: string): void;
+export { suppressExperimentalWarnings } from "./warning.js";

package/dist/utils/index.js

@@ -1,25 +1,42 @@
 import { existsSync, readdirSync, realpathSync, statSync } from "node:fs";
 import { homedir } from "node:os";
 import { basename, delimiter, dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
-import { ActionDockError, INVALID_PACKAGE_ID, PATH_TRAVERSAL } from "../errors.js";
-export { isLoopbackHost } from "./net.js";
-export { isProcessAlive } from "./process.js";
+import { ActionDockError, INVALID_ARGUMENT, INVALID_PACKAGE_ID, PATH_TRAVERSAL } from "../errors.js";
 /**
- * 解析基础 SemVer 版本字符串（单一事实源）。
- * 仅接受可选 v/= 前缀的严格三段式语义化版本，可携带预发布后缀；
- * 其余形态（两段式、非数值等）返回 null，由调用方自行兜底。
+ * 检查指定的主机地址是否为本地回环接口（Loopback Host）。
+ * 支持 127.0.0.1, localhost, ::1 等形式。
+ *
+ * @param host 主机名或 IP 字符串
  */
-export function parseSemVer(v) {
-    const match = v.trim().replace(/^[v=]/, "").match(/^(\d+)\.(\d+)\.(\d+)(?:-([0-9A-Za-z.-]+))?$/);
-    if (!match)
-        return null;
-    return {
-        major: parseInt(match[1], 10),
-        minor: parseInt(match[2], 10),
-        patch: parseInt(match[3], 10),
-        prerelease: match[4],
-    };
+export function isLoopbackHost(host) {
+    const trimmed = host.trim().toLowerCase().replace(/^\[|\]$/g, "");
+    return (trimmed === "127.0.0.1" ||
+        trimmed === "::1" ||
+        trimmed === "localhost" ||
+        trimmed === "0:0:0:0:0:0:0:1");
+}
+/**
+ * 检查目标进程是否处于存活状态（跨域通用谓词单一事实源）。
+ *
+ * 基于 process.kill(pid, 0) 探测：无异常视为存活；ESRCH（进程不存在）
+ * 视为已死；其他异常（如 EPERM，权限不足但进程存在）保守视为存活，
+ * 避免权限受限环境下误判他人持有进程死亡而抢占其锁。
+ *
+ * @param pid 待检测的进程标识符
+ */
+export function isProcessAlive(pid) {
+    if (typeof pid !== "number" || !Number.isInteger(pid) || pid <= 0) {
+        return false;
+    }
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (err) {
+        return err?.code !== "ESRCH";
+    }
 }
+export { parseSemVer } from "./semver.js";
 /**
  * 递归遍历目录的单一事实源实现（同步）。
  *
@@ -98,23 +115,13 @@ export function traverseDirectory(root, options = {}) {
     return results;
 }
 /**
- * 跨运行时安全查找可执行文件绝对物理路径。
+ * 安全查找可执行文件绝对物理路径。
  *
  * 注意：本函数为同步实现，内部同步遍历 PATH 逐个探测物理文件存在性；
  * 当前全部调用方（doctor 体检与测试 CLI 桥）均为同步链路，serve 链路未使用本函数，
  * 因此暂不提供异步版本。若后续异步链路需要，应另行新增异步实现而非改造本函数。
  */
 export function findExecutable(command) {
-    if (typeof globalThis.Bun !== "undefined" && typeof globalThis.Bun.which === "function") {
-        try {
-            const bPath = globalThis.Bun.which(command);
-            if (bPath)
-                return bPath;
-        }
-        catch {
-            // ignore
-        }
-    }
     const hasPathSep = command.includes("/") || command.includes("\\");
     if (hasPathSep) {
         return existsSync(command) ? command : null;
@@ -150,7 +157,7 @@ export function parseDuration(input) {
     }
     const match = str.match(/^(\d+(?:\.\d+)?)\s*(ms|s|m|h|d)$/i);
     if (!match) {
-        throw new Error(`Invalid duration format: '${input}'. Supported formats: 500ms, 30s, 5m, 1h`);
+        throw new ActionDockError(INVALID_ARGUMENT, `Invalid duration format: '${input}'. Supported formats: 500ms, 30s, 5m, 1h`);
     }
     const val = parseFloat(match[1]);
     const unit = match[2].toLowerCase();
@@ -270,7 +277,8 @@ export function assertPathWithinRoot(rootDir, targetPath, fieldName = "path") {
  */
 export function assertWithinProjectRoot(projectRoot, subDir, fieldName) {
     if (isAbsolute(subDir)) {
-        throw new Error(`'${fieldName}' cannot be an absolute path: ${subDir}`);
+        throw new ActionDockError(INVALID_ARGUMENT, `'${fieldName}' cannot be an absolute path: ${subDir}`);
     }
     assertPathWithinRoot(projectRoot, subDir, fieldName);
 }
+export { suppressExperimentalWarnings } from "./warning.js";

package/dist/utils/semver.d.ts

@@ -0,0 +1,18 @@
+/**
+ * 语义化版本元数据结构。
+ */
+export interface SemVer {
+    major: number;
+    minor: number;
+    patch: number;
+    prerelease?: string;
+}
+/**
+ * 解析基础 SemVer 版本字符串（单一事实源）。
+ * 仅接受可选 v/= 前缀的严格三段式语义化版本，可携带预发布后缀；
+ * 其余形态（两段式、非数值等）返回 null，由调用方自行兜底。
+ *
+ * 本模块不依赖任何 Node 内建与 core 领域模块，可在无 loader 的原生
+ * Node 直接以 .ts 形态导入（工程脚本域复用此处单一事实源）。
+ */
+export declare function parseSemVer(v: string): SemVer | null;

package/dist/utils/semver.js

@@ -0,0 +1,19 @@
+/**
+ * 解析基础 SemVer 版本字符串（单一事实源）。
+ * 仅接受可选 v/= 前缀的严格三段式语义化版本，可携带预发布后缀；
+ * 其余形态（两段式、非数值等）返回 null，由调用方自行兜底。
+ *
+ * 本模块不依赖任何 Node 内建与 core 领域模块，可在无 loader 的原生
+ * Node 直接以 .ts 形态导入（工程脚本域复用此处单一事实源）。
+ */
+export function parseSemVer(v) {
+    const match = v.trim().replace(/^[v=]/, "").match(/^(\d+)\.(\d+)\.(\d+)(?:-([0-9A-Za-z.-]+))?$/);
+    if (!match)
+        return null;
+    return {
+        major: parseInt(match[1], 10),
+        minor: parseInt(match[2], 10),
+        patch: parseInt(match[3], 10),
+        prerelease: match[4],
+    };
+}

package/dist/utils/warning.d.ts

@@ -0,0 +1 @@
+export declare function suppressExperimentalWarnings(): void;

package/dist/utils/warning.js

@@ -0,0 +1,52 @@
+/**
+ * 全局禁用 Node.js 所有的 ExperimentalWarning 实验性特性警告。
+ * 跨所有 Node.js 运行版本，不区分具体特性（如 SQLite、类型擦除等），
+ * 在进程级别统一静默全部实验性警告，同时完整保留废弃警告与运行期异常。
+ *
+ * 逃生通道：当环境变量 ACTIONDOCK_SILENCE_WARNINGS 显式设置为 "0" 时，放弃静默以供深度调试排查。
+ */
+const kExperimentalWarningSuppressed = Symbol.for("actiondock.experimental_warning_suppressed");
+export function suppressExperimentalWarnings() {
+    // 逃生通道：支持开发者显式禁用静默逻辑，确保排障透明度
+    if (process.env.ACTIONDOCK_SILENCE_WARNINGS === "0") {
+        return;
+    }
+    const globalObj = globalThis;
+    if (globalObj[kExperimentalWarningSuppressed]) {
+        return;
+    }
+    globalObj[kExperimentalWarningSuppressed] = true;
+    // 1. 拦截 process.emitWarning 源头
+    const originalEmitWarning = process.emitWarning;
+    if (typeof originalEmitWarning === "function") {
+        process.emitWarning = function (warning, ...args) {
+            if (typeof warning === "string") {
+                const type = typeof args[0] === "string" ? args[0] : args[0]?.type || args[1];
+                if (type === "ExperimentalWarning") {
+                    return;
+                }
+            }
+            else if (warning) {
+                const warnObj = warning;
+                if (warnObj.name === "ExperimentalWarning" || warnObj.type === "ExperimentalWarning") {
+                    return;
+                }
+            }
+            return Reflect.apply(originalEmitWarning, process, [warning, ...args]);
+        };
+    }
+    // 2. 包装进程级 warning 事件分发器，作为双层防护
+    const originalListeners = process.listeners("warning");
+    process.removeAllListeners("warning");
+    process.on("warning", (warning) => {
+        const warnObj = warning;
+        if (warnObj.name === "ExperimentalWarning" || warnObj.type === "ExperimentalWarning") {
+            return;
+        }
+        for (const listener of originalListeners) {
+            listener.call(process, warning);
+        }
+    });
+}
+// 模块被引入时立即自执行
+suppressExperimentalWarnings();

package/dist/{json/value-validator.d.ts → value-validator.d.ts}

@@ -79,6 +79,15 @@ export declare function validateJsonValue(value: unknown, options?: ValidateJson
  * @returns 校验结果对象
  */
 export declare function validateActionInputValue(value: unknown, options?: ValidateActionInputOptions): ActionInputValidationResult;
+/**
+ * 递归检查数据中是否包含危险的原型污染属性键名（__proto__、constructor、prototype）。
+ * 针对环路对象与有向无环图（DAG）保证安全遍历且具有深度上限防御。
+ *
+ * @param data 待检查的目标数据
+ * @param maxDepth 最大允许嵌套深度（默认 256）
+ * @returns 若存在危险键名则返回 true，否则返回 false
+ */
+export declare function hasDangerousKeys(data: unknown, maxDepth?: number): boolean;
 /**
  * 断言值必须为合法的 Canonical JSON 兼容结构，若非法则抛出 TypeError。
  *

package/dist/value-validator.js

@@ -0,0 +1,330 @@
+import { isForbiddenActionInputPropertyName } from "./input/flat-predicates.js";
+/** 默认 JSON 最大嵌套深度限制（防止恶意超深结构） */
+export const DEFAULT_MAX_JSON_DEPTH = 256;
+/** 最大安全递归调用栈深度，防止超大自定义 maxDepth 导致栈溢出 */
+const MAX_SAFE_RECURSION_DEPTH = 2048;
+/**
+ * 按照 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)}`;
+}
+function walkJsonValue(val, depth, path, maxDepth, ancestors, checkForbidden) {
+    if (val === null || typeof val === "boolean" || typeof val === "string") {
+        return { valid: true };
+    }
+    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,
+            };
+        }
+        return { valid: true };
+    }
+    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") {
+        if (depth > maxDepth || depth > MAX_SAFE_RECURSION_DEPTH) {
+            return {
+                valid: false,
+                kind: "json-value",
+                code: "MAX_JSON_DEPTH",
+                reason: `Max JSON depth limit (${maxDepth}) exceeded`,
+                path,
+            };
+        }
+        if (ancestors.has(val)) {
+            return {
+                valid: false,
+                kind: "json-value",
+                code: "CIRCULAR_REFERENCE",
+                reason: "Circular reference detected in object structure",
+                path,
+            };
+        }
+        try {
+            if (Array.isArray(val)) {
+                if (Object.getPrototypeOf(val) !== Array.prototype) {
+                    return {
+                        valid: false,
+                        kind: "json-value",
+                        code: "INVALID_JSON_OBJECT",
+                        reason: "Array prototype must be Array.prototype",
+                        path,
+                    };
+                }
+                // 稀疏数组（存在 hole）不是合法 JSON 结构
+                for (let i = 0; i < val.length; i++) {
+                    if (!(i in val)) {
+                        return {
+                            valid: false,
+                            kind: "json-value",
+                            code: "INVALID_JSON_OBJECT",
+                            reason: `Sparse array (hole at index ${i}) is not allowed in JSON`,
+                            path: appendJsonPointer(path, i),
+                        };
+                    }
+                }
+                // 数组只允许索引元素，拒绝额外字符串属性或 Symbol 属性（忽略不可枚举的内建属性如 length）
+                const extraKeys = Reflect.ownKeys(val).filter((k) => {
+                    if (typeof k === "symbol")
+                        return true;
+                    if (!/^\d+$/.test(k) || Number(k) >= val.length) {
+                        const desc = Object.getOwnPropertyDescriptor(val, k);
+                        // 不可枚举属性（如数组内建 length）不视为额外属性
+                        return desc?.enumerable === true;
+                    }
+                    return false;
+                });
+                if (extraKeys.length > 0) {
+                    return {
+                        valid: false,
+                        kind: "json-value",
+                        code: "INVALID_JSON_OBJECT",
+                        reason: "Arrays must not carry extra properties beyond indexed elements",
+                        path,
+                    };
+                }
+                ancestors.add(val);
+                try {
+                    for (let i = 0; i < val.length; i++) {
+                        const res = walkJsonValue(val[i], depth + 1, appendJsonPointer(path, i), maxDepth, ancestors, checkForbidden);
+                        if (!res.valid)
+                            return res;
+                    }
+                }
+                finally {
+                    ancestors.delete(val);
+                }
+                return { valid: true };
+            }
+            const proto = Object.getPrototypeOf(val);
+            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);
+            if (checkForbidden) {
+                for (let i = 0; i < ownKeys.length; i++) {
+                    const key = ownKeys[i];
+                    if (typeof key === "string" && isForbiddenActionInputPropertyName(key)) {
+                        return {
+                            valid: false,
+                            kind: "input-policy",
+                            code: "FORBIDDEN_PROPERTY",
+                            property: key,
+                            path: appendJsonPointer(path, key),
+                            reason: `Forbidden property "${key}" is not allowed in Action input`,
+                        };
+                    }
+                }
+            }
+            ancestors.add(val);
+            try {
+                for (let i = 0; i < ownKeys.length; 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);
+                    const desc = Object.getOwnPropertyDescriptor(val, key);
+                    if (!desc)
+                        continue;
+                    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,
+                        };
+                    }
+                    const res = walkJsonValue(desc.value, depth + 1, propPath, maxDepth, ancestors, checkForbidden);
+                    if (!res.valid)
+                        return res;
+                }
+            }
+            finally {
+                ancestors.delete(val);
+            }
+            return { valid: true };
+        }
+        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 maxDepth = options?.maxDepth ?? DEFAULT_MAX_JSON_DEPTH;
+    const res = walkJsonValue(value, 0, "", maxDepth, new Set(), false);
+    if (res.valid) {
+        return { valid: true };
+    }
+    if (res.kind !== "input-policy") {
+        return {
+            valid: false,
+            code: res.code,
+            reason: res.reason,
+            path: res.path,
+        };
+    }
+    return {
+        valid: false,
+        code: "INVALID_JSON_OBJECT",
+        reason: res.reason,
+        path: res.path,
+    };
+}
+/**
+ * 校验 Action 输入值是否满足 Canonical JsonValue 规范且符合 ActionDock 安全策略。
+ * 在遍历过程中递归检查是否存在禁止属性（__proto__、constructor、prototype）。
+ *
+ * @param value 待校验的 Action 输入值
+ * @param options 校验配置选项
+ * @returns 校验结果对象
+ */
+export function validateActionInputValue(value, options) {
+    const maxDepth = options?.maxDepth ?? DEFAULT_MAX_JSON_DEPTH;
+    return walkJsonValue(value, 0, "", maxDepth, new Set(), true);
+}
+/**
+ * 递归检查数据中是否包含危险的原型污染属性键名（__proto__、constructor、prototype）。
+ * 针对环路对象与有向无环图（DAG）保证安全遍历且具有深度上限防御。
+ *
+ * @param data 待检查的目标数据
+ * @param maxDepth 最大允许嵌套深度（默认 256）
+ * @returns 若存在危险键名则返回 true，否则返回 false
+ */
+export function hasDangerousKeys(data, maxDepth = DEFAULT_MAX_JSON_DEPTH) {
+    const visited = new Set();
+    function scan(val, depth) {
+        if (!val || typeof val !== "object" || depth > maxDepth) {
+            return false;
+        }
+        if (visited.has(val)) {
+            return false;
+        }
+        visited.add(val);
+        try {
+            if (Array.isArray(val)) {
+                for (let i = 0; i < val.length; i++) {
+                    if (scan(val[i], depth + 1))
+                        return true;
+                }
+                return false;
+            }
+            const keys = Reflect.ownKeys(val);
+            for (let i = 0; i < keys.length; i++) {
+                const k = keys[i];
+                if (typeof k === "string" && isForbiddenActionInputPropertyName(k)) {
+                    return true;
+                }
+            }
+            for (let i = 0; i < keys.length; i++) {
+                const k = keys[i];
+                if (typeof k === "string") {
+                    const desc = Object.getOwnPropertyDescriptor(val, k);
+                    if (desc && desc.value !== undefined) {
+                        if (scan(desc.value, depth + 1))
+                            return true;
+                    }
+                }
+            }
+        }
+        catch {
+            return false;
+        }
+        return false;
+    }
+    return scan(data, 0);
+}
+/**
+ * 断言值必须为合法的 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/version.d.ts

@@ -1,4 +1,4 @@
 /**
  * ActionDock 核心版本号单一事实源。
  */
-export declare const ACTIONDOCK_VERSION = "2.10.0";
+export declare const ACTIONDOCK_VERSION = "2.11.0";

package/dist/version.js

@@ -1,4 +1,4 @@
 /**
  * ActionDock 核心版本号单一事实源。
  */
-export const ACTIONDOCK_VERSION = "2.10.0";
+export const ACTIONDOCK_VERSION = "2.11.0";