@feng0531/dsh-execution-bus 0.2.1 → 0.2.2

package/README.md

@@ -2,7 +2,7 @@
 
 **让模型发出一次执行请求，由程序负责排队、等待和收取结果。**
 
-DSH 独立插件：`@feng0531/dsh-execution-bus` · 当前版本 **0.2.1**
+DSH 独立插件：`@feng0531/dsh-execution-bus` · 当前版本 **0.2.2**
 
 > 当前是早期可运行版本，不是完整生产验收版。已验证真实 DSH 组件和脚本模型驱动的内存会话；真实模型、桌面界面和 PTC 完整链路尚未验收。**不支持重启后恢复任务。**
 
@@ -100,7 +100,7 @@ flowchart TD
 2. 在你选定的隔离 DSH 配置依赖目录安装固定版本，不要在 DSH 程序安装目录执行：
 
    ```powershell
-   npm install --ignore-scripts @feng0531/dsh-execution-bus@0.2.1
+   npm install --ignore-scripts @feng0531/dsh-execution-bus@0.2.2
    ```
 
    这是 npm 目录示例。若目标配置使用 pnpm，应沿用其包管理器，不混用锁文件。遇到宿主 peer 版本冲突就停止，不用强制安装绕过。
@@ -229,7 +229,7 @@ npm run test:install    # 临时目录安装，不操作日常 DSH
 
 - [协议和投递语义](<docs/protocol.md>)：字段、状态、重复处理与取消规则。
 - [宿主兼容性与源码调用链](<docs/host-compatibility.md>)：为什么可以等待，为什么不能跨重启恢复。
-- [验证记录](<docs/validation.md>)、[0.2.1 发布说明](<docs/releases/0.2.1.md>)：已验证与未验证范围。
+- [验证记录](<docs/validation.md>)、[0.2.2 发布说明](<docs/releases/0.2.2.md>)：已验证与未验证范围。
 - [维护者发布流程](<docs/RELEASING.md>)：标签 CI、安装包校验与正式发布门禁。
 
 ## 许可

package/dist/bus.js

@@ -1,4 +1,5 @@
 import { randomUUID, createHash } from "node:crypto";
+import { assertJson } from "./json.js";
 export function object(v) {
     if (!v || typeof v !== "object" || Array.isArray(v))
         throw Error("INVALID_OBJECT");
@@ -19,6 +20,7 @@ function canonical(v) {
         "}");
 }
 export function parse(raw) {
+    assertJson(raw);
     const m = object(raw);
     if (Object.keys(m).some((k) => ![
         "protocolVersion",
@@ -220,8 +222,13 @@ export class ExecutionBus {
         if (previous && previous !== fingerprint)
             throw Error("MESSAGE_CONFLICT");
         if (!previous) {
-            if (e.messages.size >= 128)
-                throw Error("MESSAGE_LIMIT");
+            // Keep one emergency control slot: read traffic must never prevent cancellation.
+            if (e.messages.size >= 128) {
+                if (m.type !== "cancel")
+                    throw Error("MESSAGE_LIMIT");
+                if (e.view.cancelRequested || terminal(e.view.state))
+                    return this.view(e);
+            }
             e.messages.set(m.messageId, fingerprint);
             if (m.type === "cancel")
                 this.cancel(e);
@@ -242,14 +249,32 @@ export class ExecutionBus {
     finish(e, state, result, error) {
         if (terminal(e.view.state))
             return;
-        e.created = Date.now();
-        e.view.state = state;
+        // Prepare the delivery snapshot BEFORE committing an irreversible terminal state.
+        let next = { ...e.view, state, sequence: e.view.sequence + 1 };
         if (result !== undefined)
-            e.view.result = result;
+            next.result = result;
         if (error)
-            e.view.error = error;
+            next.error = error;
+        let snapshot;
+        try {
+            snapshot = freezeJson(structuredClone(next));
+        }
+        catch {
+            state = "unknown";
+            next = {
+                requestId: e.view.requestId,
+                state,
+                sequence: e.view.sequence + 1,
+                cancelRequested: e.view.cancelRequested,
+                delivery: e.view.delivery,
+                error: "RESULT_NOT_RETAINED",
+            };
+            snapshot = freezeJson({ ...next });
+        }
+        e.created = Date.now();
+        e.view = { ...next, sequence: next.sequence - 1 };
         this.emit(e, state, { state });
-        e.resolve(freezeJson(this.view(e)));
+        e.resolve(snapshot);
         e.listeners.clear();
     }
     pump() {
@@ -289,6 +314,7 @@ export class ExecutionBus {
             });
             let json;
             try {
+                assertJson(result);
                 json = JSON.stringify(result);
             }
             catch {

package/dist/json.d.ts

@@ -0,0 +1,4 @@
+/** Strict JSON tree validation before serialization, cloning or recursive freezing. */
+export declare function assertJson(value: unknown, depth?: number, active?: Set<object>, budget?: {
+    left: number;
+}): void;

package/dist/json.js

@@ -0,0 +1,42 @@
+/** Strict JSON tree validation before serialization, cloning or recursive freezing. */
+export function assertJson(value, depth = 0, active = new Set(), budget = { left: 65536 }) {
+    if (--budget.left < 0 || depth > 64)
+        throw Error("JSON_LIMIT");
+    if (value === null || typeof value === "string" || typeof value === "boolean")
+        return;
+    if (typeof value === "number" &&
+        Number.isFinite(value) &&
+        !Object.is(value, -0))
+        return;
+    if (typeof value !== "object" || value === null)
+        throw Error("INVALID_JSON");
+    if (active.has(value))
+        throw Error("CYCLIC_JSON");
+    const array = Array.isArray(value);
+    if (!array &&
+        Object.getPrototypeOf(value) !== Object.prototype &&
+        Object.getPrototypeOf(value) !== null)
+        throw Error("INVALID_JSON_OBJECT");
+    active.add(value);
+    try {
+        const keys = Reflect.ownKeys(value);
+        if (array && keys.length !== value.length + 1)
+            throw Error("INVALID_JSON_ARRAY");
+        for (const key of keys) {
+            if (array && key === "length")
+                continue;
+            if (typeof key !== "string")
+                throw Error("INVALID_JSON_KEY");
+            if (array &&
+                (!/^(0|[1-9][0-9]*)$/.test(key) || Number(key) >= value.length))
+                throw Error("INVALID_JSON_ARRAY");
+            const descriptor = Object.getOwnPropertyDescriptor(value, key);
+            if (!descriptor.enumerable || !("value" in descriptor))
+                throw Error("INVALID_JSON_PROPERTY");
+            assertJson(descriptor.value, depth + 1, active, budget);
+        }
+    }
+    finally {
+        active.delete(value);
+    }
+}

package/docs/protocol.md

@@ -2,12 +2,12 @@
 
 ## 输入
 
-严格 JSON，最大 16 KiB，不接受额外顶层字段。messageId / requestId 为 1–128 位字母、数字、下划线、点、冒号或短横线。
+严格无损 JSON，最大 16 KiB，不接受额外顶层字段。JSON 值最大深度 64、访问节点最多 65536；拒绝非有限数字、负零、undefined、函数、符号、稀疏数组、访问器属性、特殊对象和循环引用。messageId / requestId 为 1–128 位字母、数字、下划线、点、冒号或短横线。
 
 
 type 为 request 时 payload 为 {handler,input}；type 为 status / result / cancel 时 payload 必须为 {}。不支持其他类型或版本。sessionId、权限、工作目录不能出现在输入中，可信归属只能由宿主工具上下文绑定。
 
-- messageId 标识一条消息；同请求内同 messageId 不同内容拒绝。消息记账最多 128 条，超过拒绝新消息，不自动遗忘取消记账。
+- messageId 标识一条消息；同请求内同 messageId 不同内容拒绝。普通消息记账最多 128 条，超过拒绝普通新消息。首次有效取消可使用额外一个保留槽，最多 129 条；之后的新取消不再增加记账，已记录消息 ID 的冲突检查仍生效，不会因查询耗尽额度而丧失取消路径。
 - requestId 是一次逻辑操作的稳定幂等键；作用域为当前插件实例 + 宿主 session。相同 requestId 不同 handler/input 拒绝冲突，相同输入使用新 requestId 仍是新操作。
 - 输入规范排序后的摘要仅用于同 requestId 冲突比较，不作永久参数去重。保存期后旧键会失效，调用者不得因此盲目重跑有副作用操作。
 - callId / rootCallId / Agent / parent token 来自宿主；通过工具原本的 Promise 关联结果，不依赖模型提供的身份。
@@ -27,13 +27,13 @@ queued → cancelled。终态不可变；取消终态任务只返回原状态。
 
 运行中取消先置 cancelRequested 并触发 AbortSignal，不立即声称 cancelled。Handler 用 AbortError 确认取消后才 cancelled；收到取消仍成功返回则 success 获胜；取消后其他异常为 unknown。Handler 必须合作取消并等待自身资源停止，不能把部分副作用当作已撤销。初版内置 Handler 仅为受控测试和只读宿主 read，没有非幂等写操作。
 
-异常是固定错误码，不将异常堆栈/原文写日志。过大或不可保存的结果进入 unknown / RESULT_NOT_RETAINED，不因结果传输失败自动执行一次。执行结束不等于交付，delivery 单独记录 pending / returned；returned 仅代表插件已走到工具返回路径，**不是会话持久化提交确认**。done 快照保留当时的 pending，后续查询可见 returned。宿主可能因取消/后置策略改变最终工具结果，插件不声称已确认模型收到。
+异常是固定错误码，不将异常堆栈/原文写日志。结果遵守同样的严格 JSON 深度/节点与值约束；过大、会丢失信息或不可保存的结果进入 unknown / RESULT_NOT_RETAINED，不因结果传输失败自动执行一次。执行结束不等于交付，delivery 单独记录 pending / returned；returned 仅代表插件已走到工具返回路径，**不是会话持久化提交确认**。done 快照保留当时的 pending，后续查询可见 returned。宿主可能因取消/后置策略改变最终工具结果，插件不声称已确认模型收到。
 
 ## 容量和清理
 
 默认并发 2，待分发队列 32，记录 256，单结果 JSON 64 KiB；所有请求先经上限检查，满则 BACKPRESSURE，不自动重试。Job 仍受宿主自己的每 owner 容量限制。队列不提供公平性 SLA，单会话可占满实例。
 
-终态自完成后保存一小时；新受理时惰性清理，可通过 core.sweep 主动清理。无定时器常驻、无磁盘结果存储、无日志输出。插件关闭先停止受理，取消队列与运行任务，等待合作 Handler，清理内存；不合作的 Handler 会阻碍关闭，插件无法安全硬杀同进程代码。
+终态自完成后保存一小时；新受理及控制消息查询时惰性清理，可通过 core.sweep 主动清理。无定时器常驻、无磁盘结果存储、无日志输出。插件关闭先停止受理，取消队列与运行任务，等待合作 Handler，清理内存；不合作的 Handler 会阻碍关闭，插件无法安全硬杀同进程代码。
 
 敏感文件结果仍可能进入宿主原有工具会话日志，本插件不具备任意文本秘密识别能力。只请求确实需要的内容；不将敏感内容放入请求标识。结果长度检查发生在 Handler 返回后，扩展 Handler 自身也必须限制分配，不可把此检查当成防止超大对象构造的内存沙箱。
 

package/docs/releases/0.2.2.md

@@ -0,0 +1,15 @@
+# 执行总线 0.2.2
+
+## BUG 修复
+
+- 终态提交先准备返回快照再更新状态；深层结果或快照构造失败会明确结算为 unknown / RESULT_NOT_RETAINED，避免原工具调用和关闭流程永久等待。
+- 普通消息额度耗尽后为首次取消保留一个额外槽；最多 129 条记账，重复取消不增加内存，不绕过已记录消息 ID 的冲突检查。
+- 输入和结果采用严格无损 JSON 校验，拒绝 NaN、Infinity、负零、undefined、函数、稀疏数组、循环和特殊对象，避免静默改写成成功结果。JSON 深度最多 64，访问节点最多 65536；不自动重跑保存失败任务。
+
+## 验证
+
+新增 5 项回归，覆盖 1800 层结果、注入快照克隆故障、消息额度耗尽取消、无损返回值和不执行 getter 的输入拒绝。本地全量 31/31 测试通过；仍须标签 Windows/Ubuntu × Node 22/24 四矩阵 CI、候选一致性、隔离安装及公开包核验通过才能发布。
+
+## 安装与边界
+
+固定版本 @feng0531/dsh-execution-bus@0.2.2，DSH 0.2.0-rc.2。只修复审核确认问题，本版不混入待实施的“萧何”显示名称调整。非商业源码公开许可证。真实模型/GUI/PTC 完整链路未验收，不支持跨重启恢复；发布不自动安装或重启 DSH。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@feng0531/dsh-execution-bus",
-  "version": "0.2.1",
+  "version": "0.2.2",
   "type": "module",
   "private": false,
   "license": "SEE LICENSE IN LICENSE",