@feng0531/dsh-execution-bus 0.5.1 → 0.7.0

package/README.md

@@ -4,7 +4,7 @@
 
 “萧何”是产品与模式显示名，执行总线是其技术功能；不新增人物 Agent，不进行角色扮演。仓库 dsh-execution-bus、npm 包名、execution_bus 工具名及 execution-bus-test 预设 ID 保持不变。历史版本发布说明保留当时名称。
 
-DSH 独立插件：`@feng0531/dsh-execution-bus` · 当前版本 **0.5.1**
+DSH 独立插件：`@feng0531/dsh-execution-bus` · 当前版本 **0.7.0**
 
 > 萧何模式从宿主已声明的 PTC 组合派生，保留日常工具，再叠加可选执行总线。已验证隔离的真实 Node PTC → 原 read + 总线调用，以及脚本模型内存会话；真实模型、桌面界面与实际沙箱仍未验收。**不支持重启后恢复任务。**
 
@@ -85,8 +85,10 @@ flowchart TD
 |---|---|---|
 | `test`（诊断，非业务） | 仅在明确诊断时检查延迟、进度、成功、失败和取消 | `delayMs`：0–30000；`fail`：布尔值 |
 | `host.read` | 经由 DSH 现有 `read` 工具读取文本 | `file_path`；可选 `offset` 和 `limit`，最多 100 行 |
+| `host.edit` | 经由 DSH 现有 `edit` 工具替换文本（有副作用） | `file_path`、`old_string`、`new_string`；可选 `replace_all` |
+| `host.write` | 经由 DSH 现有 `write` 工具写入文本（有副作用） | `file_path`、`content` |
 
-`host.read` 在出队时重新进入宿主工具管线，沿用宿主当前权限、会话工作目录及输出限制。插件不自行启动命令、不提供任意远程执行服务。它也不会强制将现有工具改成总线调用。
+`host.read`、`host.edit` 与 `host.write` 在出队时重新进入宿主工具管线，沿用宿主当前权限、会话工作目录及输出限制。`host.edit`/`host.write` 有副作用，显式声明非幂等：同一 requestId 的终态结果不可复用，重复提交返回 `MUTATING_REUSE_DENIED`。插件不自行启动命令、不提供任意远程执行服务，也不会强制将现有工具改成总线调用。
 
 ## 选择“萧何”预设
 
@@ -103,7 +105,7 @@ flowchart TD
 
 **0.3.0 起不再是只读验证模式。** 加载时读取宿主 `ptc` 预设的组合声明快照，保留原工具、平台表达式、禁用项和配置，只追加萧何总线与说明。不再强制 native 呈现或添加只读白名单；终端、写入、搜索、技能等能力是否可用，取决于原 PTC 配置和宿主服务。其他预设和默认模式不被修改，原 PTC 会话看不到新增总线。
 
-普通任务仍通过 `run_code` 调用原工具；**总线目前只支持 test 和 host.read，不接管任意命令、安装或全部工具**。例如更新插件应使用原终端能力并遵守宿主授权；专用插件管理工具若在源 PTC 中禁用，萧何不会擅自启用。命令受理、返回 Job ID 不等于执行完成。
+普通任务仍通过 `run_code` 调用原工具；**总线目前只支持 test、host.read、host.edit 和 host.write，不接管任意命令、安装或全部工具**。例如更新插件应使用原终端能力并遵守宿主授权；专用插件管理工具若在源 PTC 中禁用，萧何不会擅自启用。命令受理、返回 Job ID 不等于执行完成。
 
 升级提示：预设 ID 保持兼容，但从旧版只读模式升级后能力范围扩大，使用者须审阅后加载；本次不自动升级日常配置。它不是进程沙箱，同一预设会话共享总线容量，结果按会话隔离。派生是加载时快照，不自动跟随源预设热编辑；源 PTC 更新后应按宿主正常流程重新加载派生行，旧会话遵循宿主版本保留规则。
 
@@ -124,7 +126,7 @@ flowchart TD
 2. 在你选定的隔离 DSH 配置依赖目录安装固定版本，不要在 DSH 程序安装目录执行：
 
    ```powershell
-   npm install --ignore-scripts @feng0531/dsh-execution-bus@0.5.1
+   npm install --ignore-scripts @feng0531/dsh-execution-bus@0.7.0
    ```
 
    这是 npm 目录示例。若目标配置使用 pnpm，应沿用其包管理器，不混用锁文件。遇到宿主 peer 版本冲突就停止，不用强制安装绕过。
@@ -267,7 +269,7 @@ npm run test:install    # 临时目录安装，不操作日常 DSH
 
 - [协议和投递语义](<docs/protocol.md>)：字段、状态、重复处理与取消规则。
 - [宿主兼容性与源码调用链](<docs/host-compatibility.md>)：为什么可以等待，为什么不能跨重启恢复。
-- [验证记录](<docs/validation.md>)、[0.5.1 发布说明](<docs/releases/0.5.1.md>)：已验证与未验证范围。
+- [验证记录](<docs/validation.md>)、[0.7.0 发布说明](<docs/releases/0.7.0.md>)：已验证与未验证范围。
 - [同类项目源码整合](<docs/INTEGRATION.md>)：固定来源、采用范围、许可与验证边界。
 - [维护者发布流程](<docs/RELEASING.md>)：标签 CI、安装包校验与正式发布门禁。
 

package/dist/bus.d.ts

@@ -1,50 +1,11 @@
+import { object, parse } from "./protocol.js";
+import type { Capability, Event, Handler, Message, Owner, RecordView, State } from "./protocol.js";
+export { object, parse };
+export type { Capability, Event, Handler, Message, Owner, RecordView, State };
 export interface AdmissionPolicy {
     sessionQueueLimit?: number;
     maxQueueWaitMs?: number;
 }
-export type State = "queued" | "running" | "succeeded" | "failed" | "cancelled" | "unknown";
-export type Owner = {
-    sessionId: string;
-    callId: string;
-};
-export type Message = {
-    protocolVersion: 1;
-    messageId: string;
-    requestId: string;
-    type: "request" | "status" | "result" | "cancel";
-    payload: Record<string, unknown>;
-};
-export type Event = {
-    protocolVersion: 1;
-    messageId: string;
-    requestId: string;
-    correlationId: string;
-    sequence: number;
-    type: string;
-    payload: Record<string, unknown>;
-};
-export type Capability = (input: Record<string, unknown>, signal: AbortSignal) => Promise<unknown>;
-export interface Handler {
-    validate(input: Record<string, unknown>): void;
-    run(input: Record<string, unknown>, ctx: {
-        signal: AbortSignal;
-        progress: (sequence: number, percent: number) => void;
-        requestId: string;
-        invoke?: Capability;
-    }): Promise<unknown>;
-}
-export interface RecordView {
-    requestId: string;
-    state: State;
-    sequence: number;
-    cancelRequested: boolean;
-    delivery: "pending" | "returned";
-    result?: unknown;
-    error?: string;
-    progress?: number;
-}
-export declare function object(v: unknown): Record<string, unknown>;
-export declare function parse(raw: unknown): Message;
 /** Volatile single-process bus; no acceptance durability or automatic execution retry. */
 export declare class ExecutionBus {
     readonly options: {
@@ -108,6 +69,14 @@ export declare class ExecutionBus {
         detach: () => void;
         returned: () => void;
     };
+    /** 校验并拆解 request 的 payload，返回 handler 名、入参与原文。 */
+    private requestParts;
+    /** 同一 requestId 的重复提交：校验一致性后复用执行或结果。 */
+    private reuseInvocation;
+    /** 受理全新请求：校验 Handler、检查容量、构建记录并入队。 */
+    private admitInvocation;
+    /** 若启用了排队期限，登记到期结算为 QUEUE_WAIT_TIMEOUT 的计时器。 */
+    private scheduleQueueDeadline;
     private attachment;
     command(owner: Owner, raw: unknown): RecordView;
     private removeQueued;
@@ -140,6 +109,8 @@ export declare class ExecutionBus {
     };
     private cancel;
     private finish;
+    /** 按会话轮转挑选下一个出队项：各会话内部 FIFO，跨会话公平。 */
+    private nextQueuedIndex;
     private pump;
     private run;
     close(): Promise<void>;

package/dist/bus.js

@@ -1,60 +1,17 @@
-import { randomUUID, createHash } from "node:crypto";
-import { assertJson } from "./json.js";
-import { Diagnostics } from "./diagnostics.js";
+import { createHash, randomUUID } from "node:crypto";
 import { performance } from "node:perf_hooks";
+import { Diagnostics } from "./diagnostics.js";
+import { ERRORS } from "./error-codes.js";
+import { assertJson } from "./json.js";
+import { LIMITS } from "./limits.js";
 import { CORE_DEFAULTS } from "./product.js";
-export function object(v) {
-    if (!v || typeof v !== "object" || Array.isArray(v))
-        throw Error("INVALID_OBJECT");
-    return v;
-}
-function canonical(v) {
-    if (v === null || typeof v !== "object")
-        return JSON.stringify(v);
-    if (Array.isArray(v))
-        return "[" + v.map(canonical).join(",") + "]";
-    return ("{" +
-        Object.keys(v)
-            .sort()
-            .map((k) => JSON.stringify(k) +
-            ":" +
-            canonical(v[k]))
-            .join(",") +
-        "}");
+import { canonical, freezeJson, object, parse } from "./protocol.js";
+export { object, parse };
+const isTerminal = (s) => !["queued", "running"].includes(s);
+/** 对 payload 做规范排序后的 SHA-256 摘要，仅用于同 requestId 的冲突比较。 */
+function hashPayload(payload) {
+    return createHash("sha256").update(canonical(payload)).digest("hex");
 }
-export function parse(raw) {
-    assertJson(raw);
-    const m = object(raw);
-    if (Object.keys(m).some((k) => ![
-        "protocolVersion",
-        "messageId",
-        "requestId",
-        "type",
-        "payload",
-    ].includes(k)))
-        throw Error("UNKNOWN_FIELD");
-    if (m.protocolVersion !== 1)
-        throw Error("UNSUPPORTED_VERSION");
-    for (const k of ["messageId", "requestId"])
-        if (typeof m[k] !== "string" ||
-            !/^[a-zA-Z0-9_.:-]{1,128}$/.test(m[k]))
-            throw Error("INVALID_ID");
-    if (!["request", "status", "result", "cancel"].includes(m.type))
-        throw Error("UNSUPPORTED_TYPE");
-    object(m.payload);
-    if (Buffer.byteLength(JSON.stringify(m)) > 16384)
-        throw Error("MESSAGE_TOO_LARGE");
-    return structuredClone(m);
-}
-function freezeJson(value) {
-    if (value && typeof value === "object") {
-        for (const child of Object.values(value))
-            freezeJson(child);
-        Object.freeze(value);
-    }
-    return value;
-}
-const terminal = (s) => !["queued", "running"].includes(s);
 /** Volatile single-process bus; no acceptance durability or automatic execution retry. */
 export class ExecutionBus {
     options;
@@ -87,7 +44,7 @@ export class ExecutionBus {
             typeof admission !== "object" ||
             Array.isArray(admission) ||
             Reflect.ownKeys(admission).some((key) => typeof key !== "string" || !allowed.includes(key)))
-            throw Error("INVALID_ADMISSION_POLICY");
+            throw Error(ERRORS.INVALID_ADMISSION_POLICY);
         for (const key of Reflect.ownKeys(admission)) {
             const descriptor = Object.getOwnPropertyDescriptor(admission, key);
             if (!("value" in descriptor) ||
@@ -95,7 +52,7 @@ export class ExecutionBus {
                 !Number.isSafeInteger(descriptor.value) ||
                 descriptor.value < 1 ||
                 descriptor.value > 2147483647)
-                throw Error("INVALID_ADMISSION_POLICY");
+                throw Error(ERRORS.INVALID_ADMISSION_POLICY);
         }
         this.admission = Object.freeze({ ...admission });
         const keys = [
@@ -113,15 +70,15 @@ export class ExecutionBus {
                 const descriptor = Object.getOwnPropertyDescriptor(options, key);
                 return (!descriptor || !("value" in descriptor) || !descriptor.enumerable);
             }))
-            throw Error("INVALID_OPTIONS");
+            throw Error(ERRORS.INVALID_OPTIONS);
         this.options = Object.freeze({ ...options });
         for (const v of Object.values(this.options))
             if (!Number.isSafeInteger(v) || v < 1)
-                throw Error("INVALID_OPTIONS");
+                throw Error(ERRORS.INVALID_OPTIONS);
     }
     register(name, handler) {
         if (this.handlers.has(name))
-            throw Error("DUPLICATE_HANDLER");
+            throw Error(ERRORS.DUPLICATE_HANDLER);
         const registration = { handler, token: Symbol(name) };
         this.handlers.set(name, registration);
         let disposed = false;
@@ -135,7 +92,7 @@ export class ExecutionBus {
     }
     key(o, id) {
         if (!o.sessionId || !o.callId)
-            throw Error("UNTRUSTED_CONTEXT");
+            throw Error(ERRORS.UNTRUSTED_CONTEXT);
         return JSON.stringify([o.sessionId, id]);
     }
     emit(e, type, payload, correlationId = "") {
@@ -149,8 +106,7 @@ export class ExecutionBus {
             type,
             payload,
         });
-        // Snapshot and enqueue before invoking user code: nested cancellation cannot
-        // overtake the current event for later observers. Removed listeners are skipped.
+        // 在调用用户代码前快照并排队：嵌套取消无法抢到当前事件。
         e.notifications.push({ event, listeners: [...e.listeners] });
         if (e.dispatching)
             return;
@@ -170,7 +126,7 @@ export class ExecutionBus {
         }
         finally {
             e.dispatching = false;
-            if (terminal(e.view.state))
+            if (isTerminal(e.view.state))
                 e.listeners.clear();
         }
     }
@@ -180,68 +136,87 @@ export class ExecutionBus {
     get(o, id) {
         const e = this.entries.get(this.key(o, id));
         if (!e)
-            throw Error("NOT_FOUND");
+            throw Error(ERRORS.NOT_FOUND);
         return e;
     }
     sweep(now = Date.now()) {
         for (const [k, e] of this.entries)
-            if (terminal(e.view.state) &&
-                now - e.created > this.options.retentionMs) {
+            if (isTerminal(e.view.state) && now - e.created > this.options.retentionMs) {
                 this.retainedResultBytes -= e.resultBytes;
                 this.entries.delete(k);
             }
     }
     submit(owner, raw, onEvent, invoke) {
         if (this.closed)
-            throw Error("CLOSED");
+            throw Error(ERRORS.CLOSED);
         const m = parse(raw);
         if (m.type !== "request")
-            throw Error("EXPECTED_REQUEST");
+            throw Error(ERRORS.EXPECTED_REQUEST);
+        const parts = this.requestParts(m);
+        const key = this.key(owner, m.requestId);
+        const fingerprint = hashPayload(parts.payload);
+        this.sweep();
+        const existing = this.entries.get(key);
+        return existing
+            ? this.reuseInvocation(existing, m, fingerprint, onEvent)
+            : this.admitInvocation(owner, m, parts, key, fingerprint, invoke, onEvent);
+    }
+    /** 校验并拆解 request 的 payload，返回 handler 名、入参与原文。 */
+    requestParts(m) {
         const p = m.payload;
         if (Object.keys(p).some((k) => !["handler", "input"].includes(k)) ||
             typeof p.handler !== "string")
-            throw Error("INVALID_REQUEST");
-        const input = object(p.input);
-        const key = this.key(owner, m.requestId), fp = createHash("sha256").update(canonical(p)).digest("hex");
-        this.sweep();
-        let e = this.entries.get(key);
-        if (e) {
-            if (e.fingerprint !== fp)
-                throw Error("REQUEST_CONFLICT");
-            const previous = e.messages.get(m.messageId);
-            if (previous && previous !== canonical(m))
-                throw Error("MESSAGE_CONFLICT");
-            if (!previous && e.messages.size >= 128)
-                throw Error("MESSAGE_LIMIT");
-            // Acquire the attachment before committing its message identity. Rejection is side-effect free.
-            const attached = this.attachment(e, onEvent, m.messageId);
-            if (!previous)
-                e.messages.set(m.messageId, canonical(m));
-            this.telemetry.record(e.trace, "reused");
-            return attached;
-        }
-        const handler = this.handlers.get(p.handler)?.handler;
+            throw Error(ERRORS.INVALID_REQUEST);
+        return {
+            handler: p.handler,
+            input: object(p.input),
+            payload: p,
+        };
+    }
+    /** 同一 requestId 的重复提交：校验一致性后复用执行或结果。 */
+    reuseInvocation(e, m, fingerprint, onEvent) {
+        if (e.fingerprint !== fingerprint)
+            throw Error(ERRORS.REQUEST_CONFLICT);
+        // 仅显式声明非幂等（idempotent:false）的 handler，终态结果才不可复用：
+        // 返回"已执行"会掩盖副作用状态。运行中的重复 attach 仍放行，不会二次执行。
+        if (e.handler.idempotent === false && isTerminal(e.view.state))
+            throw Error(ERRORS.MUTATING_REUSE_DENIED);
+        const previous = e.messages.get(m.messageId);
+        if (previous && previous !== canonical(m))
+            throw Error(ERRORS.MESSAGE_CONFLICT);
+        if (!previous && e.messages.size >= LIMITS.messageAccountLimit)
+            throw Error(ERRORS.MESSAGE_LIMIT);
+        // 先取得附着，再提交消息身份：附着被拒（WAITER_LIMIT）时无副作用。
+        const attached = this.attachment(e, onEvent, m.messageId);
+        if (!previous)
+            e.messages.set(m.messageId, canonical(m));
+        this.telemetry.record(e.trace, "reused");
+        return attached;
+    }
+    /** 受理全新请求：校验 Handler、检查容量、构建记录并入队。 */
+    admitInvocation(owner, m, parts, key, fingerprint, invoke, onEvent) {
+        const handler = this.handlers.get(parts.handler)?.handler;
         if (!handler)
-            throw Error("UNKNOWN_HANDLER");
-        handler.validate(input);
+            throw Error(ERRORS.UNKNOWN_HANDLER);
+        handler.validate(parts.input);
         if (this.entries.size >= this.options.recordLimit ||
             this.queue.length >= this.options.queueLimit)
-            throw Error("BACKPRESSURE");
+            throw Error(ERRORS.BACKPRESSURE);
         if (this.admission.sessionQueueLimit !== undefined &&
             this.queue.filter((entry) => entry.owner === owner.sessionId).length >=
                 this.admission.sessionQueueLimit)
-            throw Error("SESSION_BACKPRESSURE");
+            throw Error(ERRORS.SESSION_BACKPRESSURE);
         let resolve;
         const done = new Promise((r) => (resolve = r));
-        e = {
+        const e = {
             trace: this.telemetry.begin(),
             resultBytes: 0,
             invoke,
             correlationId: m.messageId,
             owner: owner.sessionId,
-            fingerprint: fp,
+            fingerprint,
             handler,
-            input: structuredClone(input),
+            input: structuredClone(parts.input),
             view: {
                 requestId: m.requestId,
                 state: "queued",
@@ -263,33 +238,36 @@ export class ExecutionBus {
         this.telemetry.record(e.trace, "accepted");
         const attached = this.attachment(e, onEvent, m.messageId);
         this.queue.push(e);
-        if (this.admission.maxQueueWaitMs !== undefined) {
-            e.deadline = performance.now() + this.admission.maxQueueWaitMs;
-            const entry = e;
-            const expire = () => {
-                if (entry.view.state !== "queued")
-                    return;
-                const remaining = entry.deadline - performance.now();
-                if (remaining > 0) {
-                    entry.queueTimer = setTimeout(expire, Math.ceil(remaining));
-                    return;
-                }
-                this.removeQueued(entry);
-                this.finish(entry, "failed", undefined, "QUEUE_WAIT_TIMEOUT");
-            };
-            e.queueTimer = setTimeout(expire, this.admission.maxQueueWaitMs);
-        }
+        this.scheduleQueueDeadline(e);
         if (!this.readyOwners.includes(e.owner))
             this.readyOwners.push(e.owner);
         queueMicrotask(() => this.pump());
         return attached;
     }
+    /** 若启用了排队期限，登记到期结算为 QUEUE_WAIT_TIMEOUT 的计时器。 */
+    scheduleQueueDeadline(e) {
+        if (this.admission.maxQueueWaitMs === undefined)
+            return;
+        e.deadline = performance.now() + this.admission.maxQueueWaitMs;
+        const expire = () => {
+            if (e.view.state !== "queued")
+                return;
+            const remaining = e.deadline - performance.now();
+            if (remaining > 0) {
+                e.queueTimer = setTimeout(expire, Math.ceil(remaining));
+                return;
+            }
+            this.removeQueued(e);
+            this.finish(e, "failed", undefined, "QUEUE_WAIT_TIMEOUT");
+        };
+        e.queueTimer = setTimeout(expire, this.admission.maxQueueWaitMs);
+    }
     attachment(e, onEvent, id) {
-        // Each attachment owns its registration, even when callers reuse one function.
+        // 每次附着独立占配额，即使调用方复用同一个回调。
         const listener = onEvent ? (event) => onEvent(event) : undefined;
-        if (listener && !terminal(e.view.state)) {
-            if (e.listeners.size >= 32)
-                throw Error("WAITER_LIMIT");
+        if (listener && !isTerminal(e.view.state)) {
+            if (e.listeners.size >= LIMITS.waiterLimit)
+                throw Error(ERRORS.WAITER_LIMIT);
             e.listeners.add(listener);
         }
         const accepted = {
@@ -319,20 +297,20 @@ export class ExecutionBus {
     command(owner, raw) {
         const m = parse(raw);
         if (m.type === "request")
-            throw Error("EXPECTED_CONTROL");
+            throw Error(ERRORS.EXPECTED_CONTROL);
         if (Object.keys(m.payload).length)
-            throw Error("INVALID_CONTROL");
+            throw Error(ERRORS.INVALID_CONTROL);
         this.sweep();
         const e = this.get(owner, m.requestId);
         const previous = e.messages.get(m.messageId), fingerprint = canonical(m);
         if (previous && previous !== fingerprint)
-            throw Error("MESSAGE_CONFLICT");
+            throw Error(ERRORS.MESSAGE_CONFLICT);
         if (!previous) {
-            // Keep one emergency control slot: read traffic must never prevent cancellation.
-            if (e.messages.size >= 128) {
+            // 保留一个应急控制槽：读流量绝不能阻塞取消。
+            if (e.messages.size >= LIMITS.messageAccountLimit) {
                 if (m.type !== "cancel")
-                    throw Error("MESSAGE_LIMIT");
-                if (e.view.cancelRequested || terminal(e.view.state))
+                    throw Error(ERRORS.MESSAGE_LIMIT);
+                if (e.view.cancelRequested || isTerminal(e.view.state))
                     return this.view(e);
             }
             e.messages.set(m.messageId, fingerprint);
@@ -349,14 +327,14 @@ export class ExecutionBus {
     /** Trusted host owner required. Never exposes other sessions or business payloads. */
     inspect(owner) {
         if (!owner || typeof owner.sessionId !== "string" || !owner.sessionId)
-            throw Error("OWNING_SESSION_REQUIRED");
+            throw Error(ERRORS.OWNING_SESSION_REQUIRED);
         this.sweep();
         const now = performance.now();
         const records = [...this.entries.values()].filter((e) => e.owner === owner.sessionId);
-        // Active work must not disappear behind newer terminal history.
-        const active = records.filter((e) => !terminal(e.view.state));
-        const history = records.filter((e) => terminal(e.view.state)).reverse();
-        const selected = [...active, ...history].slice(0, 50);
+        // 活跃任务不得被更新的终态历史挤到列表之外。
+        const active = records.filter((e) => !isTerminal(e.view.state));
+        const history = records.filter((e) => isTerminal(e.view.state)).reverse();
+        const selected = [...active, ...history].slice(0, LIMITS.inspectTaskLimit);
         const tasks = selected.map((e) => ({
             requestId: e.view.requestId,
             state: e.view.state,
@@ -369,7 +347,7 @@ export class ExecutionBus {
                     ? "concurrency"
                     : "dispatch"
                 : null,
-            phase: terminal(e.view.state)
+            phase: isTerminal(e.view.state)
                 ? e.view.delivery === "returned"
                     ? "returned"
                     : "terminal"
@@ -390,14 +368,14 @@ export class ExecutionBus {
             counts: {
                 queued: records.filter((e) => e.view.state === "queued").length,
                 running: records.filter((e) => e.view.state === "running").length,
-                terminal: records.filter((e) => terminal(e.view.state)).length,
+                terminal: records.filter((e) => isTerminal(e.view.state)).length,
             },
             tasks,
-            truncated: records.length > 50,
+            truncated: records.length > LIMITS.inspectTaskLimit,
         });
     }
     cancel(e) {
-        if (terminal(e.view.state) || e.view.cancelRequested)
+        if (isTerminal(e.view.state) || e.view.cancelRequested)
             return;
         e.view.cancelRequested = true;
         this.telemetry.record(e.trace, "cancel_requested");
@@ -409,15 +387,16 @@ export class ExecutionBus {
         }
     }
     finish(e, state, result, error, resultBytes = 0) {
-        if (terminal(e.view.state))
+        if (isTerminal(e.view.state))
             return;
         if (e.queueTimer !== undefined) {
             clearTimeout(e.queueTimer);
             e.queueTimer = undefined;
         }
         e.finishedAt = performance.now();
-        // Prepare the delivery snapshot BEFORE committing an irreversible terminal state.
-        let next = { ...e.view, state, sequence: e.view.sequence + 1 };
+        // 终态事件是下一个序号；先用它构建快照，避免把不可逆终态提交到视图之外。
+        const terminalSequence = e.view.sequence + 1;
+        let next = { ...e.view, state, sequence: terminalSequence };
         if (result !== undefined)
             next.result = result;
         if (error)
@@ -432,7 +411,7 @@ export class ExecutionBus {
             next = {
                 requestId: e.view.requestId,
                 state,
-                sequence: e.view.sequence + 1,
+                sequence: terminalSequence,
                 cancelRequested: e.view.cancelRequested,
                 delivery: e.view.delivery,
                 error: "RESULT_NOT_RETAINED",
@@ -442,28 +421,36 @@ export class ExecutionBus {
         e.resultBytes = resultBytes;
         this.retainedResultBytes += resultBytes;
         e.created = Date.now();
-        e.view = { ...next, sequence: next.sequence - 1 };
+        // emit() 会再自增序号；先整体回退一档，使终态事件恰好落在 terminalSequence，
+        // 与上面交付给等待者的快照序号完全一致。
+        e.view = { ...next, sequence: terminalSequence - 1 };
         this.telemetry.record(e.trace, "terminal");
         e.resolve(snapshot);
         this.emit(e, state, { state });
-        // A reentrant terminal notification may still be queued behind this batch.
+        // 重入的终态通知可能仍排在本批之后。
         if (!e.dispatching)
             e.listeners.clear();
     }
+    /** 按会话轮转挑选下一个出队项：各会话内部 FIFO，跨会话公平。 */
+    nextQueuedIndex() {
+        let index = -1;
+        while (this.readyOwners.length && index < 0) {
+            const owner = this.readyOwners.shift();
+            const i = this.queue.findIndex((entry) => entry.owner === owner);
+            if (i >= 0) {
+                index = i;
+                // 找到后，若该会话仍有其它排队任务，保留其轮次避免单个会话饥饿。
+                if (this.queue.some((entry, j) => j !== i && entry.owner === owner))
+                    this.readyOwners.push(owner);
+            }
+        }
+        return index < 0 ? 0 : index;
+    }
     pump() {
         while (!this.closed &&
             this.running < this.options.concurrency &&
             this.queue.length) {
-            let index = -1;
-            while (this.readyOwners.length && index < 0) {
-                const owner = this.readyOwners.shift();
-                index = this.queue.findIndex((entry) => entry.owner === owner);
-                if (index >= 0 &&
-                    this.queue.some((entry, i) => i !== index && entry.owner === owner))
-                    this.readyOwners.push(owner);
-            }
-            if (index < 0)
-                index = 0;
+            const index = this.nextQueuedIndex();
             const e = this.queue.splice(index, 1)[0];
             if (e.view.state !== "queued")
                 continue;

package/dist/diagnostics.js

@@ -1,8 +1,9 @@
 import { performance } from "node:perf_hooks";
+import { LIMITS } from "./limits.js";
 /** In-memory numeric metadata only: never accepts request/session strings, input, output or error text. */
 export class Diagnostics {
     next = 0;
-    events = new Array(128);
+    events = new Array(LIMITS.traceRingSize);
     cursor = 0;
     size = 0;
     counts = {};
@@ -16,14 +17,15 @@ export class Diagnostics {
             stage,
             elapsedMs: Math.max(0, performance.now() - context.at),
         };
-        this.cursor = (this.cursor + 1) % 128;
-        this.size = Math.min(this.size + 1, 128);
+        this.cursor = (this.cursor + 1) % LIMITS.traceRingSize;
+        this.size = Math.min(this.size + 1, LIMITS.traceRingSize);
     }
     snapshot() {
         return {
             counts: { ...this.counts },
             traces: Array.from({ length: this.size }, (_, index) => ({
-                ...this.events[(this.cursor - this.size + 128 + index) % 128],
+                ...this.events[(this.cursor - this.size + LIMITS.traceRingSize + index) %
+                    LIMITS.traceRingSize],
             })),
         };
     }