@twinsearth/dsh-master 3.2.9 → 3.3.0

package/docs/EXPERIMENT-M5-real-ab.md

@@ -0,0 +1,82 @@
+# M5 真实对照实验报告（3.3.0-dev）
+
+> 生成时间：2026-11-13 08:5x（Asia/Shanghai）
+> 运行命令：`node scripts/fork-experiment.mjs --real --tasks 20 --model deepseek-chat`
+> 原始结果：`E:\GPT\.tmp\real-ab.json`（本地，不入库）
+
+## 1. 这次跑的是什么
+
+| 项 | 值 |
+|---|---|
+| provider | DeepSeek 官方 API（`https://api.deepseek.com`，模型 `deepseek-chat`） |
+| Worker | **本仓库 `worker/` 的真实代码路径**：真实工具注册表、真实 A1 紧凑化、真实 A3 批量、真实 B1/B2/B3 |
+| 对照分组 | `control` = 3.2.x 行为（`compactMode:'off'`、无复用）；`enforce` = `compactMode:'enforce'` + `ccs.mode:'enforce'`（白名单） |
+| 样本量 | 每组 **20** 个任务（G5 要求 ≥10） |
+| 票据来源 | **合成**（脚本生成的任务描述与工作区，不是飞书/GitHub 真 ticket） |
+| harness 标签 | `real-provider-real-worker`（`qualifiesForGate: true`） |
+| 是否安装到任何 profile | **否**（未安装、未升级、未改 profile 配置） |
+
+## 2. 结果（同表，两组并列）
+
+| 组 | 样本 | tokens/task | 成功率 | 耗时中位数 |
+|---|---|---|---|---|
+| control | 20 | **6263** | 100% | 3200 ms |
+| enforce | 20 | **3906.75** | 100% | 3274 ms |
+
+- **tokens/task 下降 −2356.25（−37.6%）**
+- **成功率差值 0pp**（两组均 20/20 成功，未触及 §10.1 的 2pp 降级红线）
+
+## 3. 拆开看这两项省在哪
+
+| 链路 | 实测 |
+|---|---|
+| **A1 回执压缩**（单价项） | 20/20 任务发生压缩，估算节省 **53,549 tokens** |
+| **B2/B3 决策复用**（次数项） | 复用尝试 **20** · 命中 **20**（100%）· 跳过模型调用 **20** · 真实派发 **20** · 失败回落 **0** |
+
+口径说明：
+- A1 的 token 是**估算值**（`chars/4`），报表里与实测分开列；
+- B 的节省按「跳过 1 次模型回调 × 该步基线下单」计，与 A1 的单价下降**分列不合并**（§8 口径）。
+
+## 4. 这些数字能证明什么、不能证明什么
+
+**能证明**
+- 在真实 provider + 真实 Worker 代码路径下，A1+B 组合让 tokens/task 下降约 **37.6%**；
+- 复用命中不会牺牲成功率（两组都是 100%）；
+- 派发失败自动回退路径没有被触发（0 次），说明白名单内的边在这批语料上是稳定的。
+
+**不能证明**
+- **不代表真实 ticket 上的收益**：任务描述与工作区是合成的，真实工单的规模/形态差异可能显著改变比例；
+- **不是安装态实测**：本次未安装到任何 profile，也没有在 18000 端口那个 DSH 实例里跑——该实例的 profile（`E:\DSH\.dsh\profiles\desktop`）**没有安装 dsh-master**（我核对过：`node_modules\@twinsearth\dsh-master` 不存在，`/dsh-master/api/*` 一律 404）；
+- **不含 §8 的净亏检查**：governance 成本（EDG 作者步骤是模板来源、作者成本 0）在这批任务里没有真实开销。
+
+## 5. 复现步骤
+
+```bash
+# 需要真实 provider 凭据（本文件不记录、不入库）
+export DSH_MASTER_LLM_BASE_URL=https://api.deepseek.com
+export DSH_MASTER_LLM_API_KEY=<your-key>
+export DSH_MASTER_LLM_MODEL=deepseek-chat
+
+node scripts/fork-experiment.mjs --real --tasks 20 --out /tmp/real-ab.json --json
+```
+
+`--real` 与默认 dry-run 的区别写在脚本头部；dry-run 的 `harness=local-dry-run` 会被
+`evaluateForkExperiment()` 判 `harness-not-real` —— **dry-run 数据无法冒充 G5 证据**。
+
+## 6. 门禁与里程碑
+
+```
+[gate] ✔ G1 check / ✔ G2 build / ✔ G3 test / ✔ G4 覆盖 13/13
+       ✔ G5 control 6263 → enforce 3906.75 tokens/task（20/20 组）
+       ✔ G6 零残留        ✖ G7 未授权
+       bootstrapOk=true   ok=false（只剩发布授权）
+```
+
+```
+[milestones] 实现 5/5 · 达标 4/5
+  M1 done · M2 done · M3 done · M4 done
+  M5 implemented-effect-unmeasured（原因：fang-relay-out-of-scope）
+```
+
+M5 唯一未达标项是「与瓮城回流对接」—— 该通道按本会话守则（§二）不可用，
+接口位显式返回 `{ available:false, reason:'fang-channel-not-ready' }`，不伪装成功。

package/docs/RELEASE-v3.2.10.md

@@ -0,0 +1,32 @@
+# dsh-Master v3.2.10 发布门禁
+
+日期：2026-11-12。
+
+## 内容
+
+本版按实机反馈放宽角色矩阵：`master-superagent-router` 由 essence-only 改为 **essence / mother**；`master-superagent-worker` 与 `master-superagent-loop` 由 fork-only 改为 **fork / essence**；`master-cost-optimizer` 仍 fork-only，`master-dual-manager` 仍 mother / essence。
+
+母体仍不接纳 Worker/Loop 执行体，fork 仍不注册 Router；面板、子插件描述与角色文档同步。测试按新矩阵逐角色断言。
+
+## 发布前实测
+
+```text
+npm run check       0 error
+npm run build       0 error（dist-host + dist-worker）
+npm test            188 / 188 pass / 0 fail
+npm run test:clean  188 / 188 pass / 0 fail（不使用 --test-force-exit）
+```
+
+## 三方发布目标
+
+- `main`：发布提交；
+- `v3.2.10`：annotated tag；
+- GitHub Release：tarball + sha256 + manifest；
+- NPM：`@twinsearth/dsh-master@3.2.10`，`access=public`。
+
+发布不等同于安装：本流程不修改任何用户 profile（desktop / 瓮城运行态仍停在旧版，升级需另行授权）。
+
+## 已知限制
+
+- 瓮城分身的 profile 未安装本 bundle（forker 的 `forkSeed` 不含 `@twinsearth/dsh-master`），因此“分身 web 里 Worker/Loop 自动激活”仍需把包加进 `forkSeed`（activate）或装进分身 profile——属瓮城配置。
+- 矩阵放宽只改变激活范围，不改变各自的安全边界：Router 仍只派发不执行，执行体仍在 Mandate 作用域内运行。

package/docs/ROADMAP.md

@@ -1,14 +1,14 @@
 # 路线图：3.2.0 → 3.4.0
 
-> 版本线：`3.2.0 – 3.2.9`（1 个大版本 + 9 个小版本），随后 3.3.0、3.4.0。  
-> 本文保留版本演进记录；当前基线为 `3.2.9`。
+> 版本线：`3.2.0 – 3.2.10`（1 个大版本 + 10 个小版本），随后 3.3.0、3.4.0。  
+> 本文保留版本演进记录；当前基线为 `3.2.10`。
 > 最新测试/实机状态与尚未完成的范围见 `REVIEW-v3.2.7.md`，下列旧版本待办不得再理解为当前状态。
 
 ## 三条主线
 
 | 版本 | 主题 | 核心组件 | 定位 |
 |---|---|---|---|
-| **3.2.0–3.2.9** | 主动性：从被动响应到主动巡航 | SuperAgent（Router/Worker） | 原身控制面 + 分身执行体的双层结构 |
+| **3.2.0–3.2.10** | 主动性：从被动响应到主动巡航 | SuperAgent（Router/Worker） | 原身控制面 + 分身执行体的双层结构 |
 | **3.3.0** | 经济性：车间成本控制器 | HarnessMM | 分身的 Token 效率优化器；EGD/GDR/CCS |
 | **3.4.0** | 组织性：人机协同制度化 | PM + PJM | 母体/元主内的元 Agent，调度分身集群 |
 

package/docs/SECURITY.md

@@ -1,4 +1,4 @@
-# 安全边界（3.2.9）
+# 安全边界（3.2.10）
 
 > 最新变化：worker-events 读取需 UI/匹配 worker token；旧 token 轮换 fail-closed；契约与 PR 网络调用全部有超时；DSH 同路径路由合并分流；飞书加密事件支持 AES-256-CBC。实机证据见 `REVIEW-v3.2.7.md`。
 
@@ -59,14 +59,14 @@
 
 | 子插件 | 允许角色 | 强制位置 |
 |---|---|---|
-| SuperAgent Router | **essence only** | `superagent-router.mjs` apply 开头 `roleAllowed(ROW_ID, role)`；母体/fork 不注册服务 |
-| SuperAgent Worker | **fork only** | `superagent-worker.mjs` 同上；母体/元主不注册 |
-| 成本优化 | **fork only** | `cost-optimizer.mjs` 同上 |
-| 双主管 | **mother / essence** | `dual-manager.mjs` 同上 |
-
-- 母体（mother）不接纳任何 SuperAgent 行；
-- Router 是控制面：不读文件、不跑命令、不改代码；所有执行体必须在 fork Worker 中；
-- Worker 是官方研究原型：物理隔离是底线，**绝不**在母体/元主启用；
+| SuperAgent Router | **essence / mother** | `superagent-router.ts` apply 开头 `roleAllowed(ROW_ID, role)`；fork 不注册服务 |
+| SuperAgent Worker | **fork / essence** | `superagent-worker.ts` 同上；母体不注册 |
+| 成本优化 | **fork only** | `cost-optimizer.ts` 同上 |
+| 双主管 | **mother / essence** | `dual-manager.ts` 同上 |
+
+- 母体（mother）只接纳 Router 与双主管，不接纳 Worker/Loop 执行体；
+- Router 是控制面：不读文件、不跑命令、不改代码；执行体在 fork Worker 或原身（3.2.10 起）中运行；
+- Worker 的物理隔离仍是默认执行路径，**绝不**在母体启用；
 - 测试逐角色断言（mother/essence/fork）服务是否存在。
 
 ## 2. 外部输入不可信

package/docs/SUPERAGENT.md

@@ -1,8 +1,8 @@
-# SuperAgent（v3.2.9）
+# SuperAgent（v3.2.10）
 
 > 把“用户从多窗口注意力调度中解放出来”的架构跃迁：**Router（常驻控制面）** 与
 > **Worker（隔离执行体）** 分离，Ticket/Mandate 约束授权，渐进式信任控制自动接单。
-> 3.2.9 为面板交互修复发布线。历史限制与实机证据见 `REVIEW-v3.2.7.md`。
+> 3.2.10 为角色矩阵放宽线（Router 进入母体、Worker/Loop 进入原身）。历史限制与实机证据见 `REVIEW-v3.2.7.md`。
 
 ## 1. 双层结构
 
@@ -27,8 +27,8 @@
 | 层 | 瓮城物理层 | 本仓库实现 | 角色 |
 |---|---|---|---|
 | 事件源 | 外部环境 | `src/superagent/github.mjs`、`feishu.mjs` | 被动入口 |
-| Router | 原身（安全盘） | `src/plugins/superagent-router.mjs` + `src/superagent/router.mjs` | **essence only** |
-| Worker | 分身（隔离 VM） | `src/plugins/superagent-worker.mjs` + `worker.mjs` | **fork only** |
+| Router | 原身（安全盘）/ 母体 | `src/plugins/superagent-router.ts` + `src/superagent/router.ts` | **essence / mother** |
+| Worker | 分身（隔离 VM）/ 原身 | `src/plugins/superagent-worker.ts` + `worker/` | **fork / essence** |
 | 持久化 | 会话仓 | `ticket-store.mjs`（`<dataDir>/superagent-tickets.json`） | Router 侧 |
 | 派发 | DerivedManager | `dispatch.mjs` → `fangForker.spawn({env})` | Router 侧 |
 
@@ -117,7 +117,7 @@ fangForker.spawn({
 |---|---|
 | 外部输入不可信 | 验签/Token → 归一化 → Gate；payload 永远当不可信文本 |
 | Mandate 防越权 | 不可变 Ticket；Worker 精确 scope 校验，越权退回 Router |
-| 物理隔离 | Worker 只在 fork；Router essence-only；母体不接纳任何 SuperAgent 行 |
+| 物理隔离 | Worker 默认在 fork；3.2.10 起也可在 essence；Router 在 essence/mother；母体不接纳执行体 |
 | 长任务不阻塞 | `exec_shell_in_vm` 超过 5s 返回后台 job id，`vm_job_result` 查询真实终态与输出 |
 | 失败不假装成功 | dispatch 失败 → Ticket= failed、decision=unavailable，错误码原样返回 |
 | 去重 | 事件 id 最近 500 条 FIFO（重复事件不刷新顺序）；契约幂等键随 envelope 传递 |

package/docs/THIRD-PARTY.md

@@ -0,0 +1,87 @@
+# 第三方参考实现与移植边界
+
+> 适用范围：整个 `dsh-Master` 仓库（含 `src/`、`worker/`、`client.js`、`docs/`）。
+> 本文件是**约束文件**，不是致谢清单：它规定我们「可以借鉴什么、不可以复制什么」，
+> 并由 `test/license-provenance.test.mjs` 自动守卫。
+
+---
+
+## 1. 参考项目
+
+| 项目 | 许可证 | 层次 | 在本设计中的角色 |
+|---|---|---|---|
+| [`T-Auto/dsh-ops`](https://github.com/T-Auto/dsh-ops) | MIT | 工具层（I/O 单价） | **方法参考**：紧凑工具输出、按需披露工具、批量调用可以降低单次交互 Token |
+| [`YuhuaJiang2002/HarnessMM`](https://github.com/YuhuaJiang2002/HarnessMM) | Apache-2.0 | 决策层（推理次数） | **方法参考**：EDG / GDR / CCS / RSI 可在模型—工具边界跳过冗余推理；两本账（执行节省 vs 治理成本）分开核算 |
+
+论文：HarnessMM，arXiv[:2610.32813](https://arxiv.org/abs/2610.32813)。
+
+两者解决同一问题的不同侧面：`dsh-ops` 让**每次工具调用更便宜**，`HarnessMM` 让**需要发生的推理次数更少**。
+本项目的 3.3.0 把两者拆成 A（工具面）/ B（决策复用）两条链路，用一套计量与治理系统联合起来。
+
+---
+
+## 2. 移植边界（硬性）
+
+> **只移植协议语义与问题分解方式；实现全部自研；不复制第三方代码。**
+
+| 允许 | 禁止 |
+|---|---|
+| 阅读论文/文档，提炼**问题分解**（如「单价 vs 次数」）与**协议语义**（如「守卫命中则复用已解决决策」） | 复制源码、函数体、注释、常量表、正则字面量集合、数据结构布局 |
+| 重新设计并**自研实现**同等能力，接口与命名按本项目风格 | 引入第三方包作为运行时依赖来「代劳」 |
+| 在文档/代码注释中**引用**项目名、论文号、许可证名 | 在源码里带上第三方版权头 / 许可证正文 / 出处不明的大段代码 |
+| 使用公开可用的**实测数字**做对标（标注来源） | 把第三方基准数字当作本项目实测结果对外宣称 |
+
+**判定标准**：如果删掉参考项目的仓库，我们的实现应当仍能独立读懂、独立测试、独立演进——
+不能存在「只有对照原项目才看得懂」的代码。
+
+---
+
+## 3. 当前实现来源核对
+
+| 模块 | 来源 | 说明 |
+|---|---|---|
+| 系统层 `ledger` / `budget` / `policy` / `audit` / `attribution` / `bus` | **自研** | 通用工程结构（计量、闸门、灰度、哈希链、归因、事件）。“两本账”这一核算口径来自 HarnessMM 论文的**原则**，实现与数据结构均为本项目自写。 |
+| A1 `tool-compact` | **自研** | 只针对本项目自有工具（`fs_read_file` / `fs_list_dir` / `fs_write_file` / `exec_shell_in_vm`）的输出形状做无损压缩；与 `dsh-ops` 的 Rust 工具、`ops_*` 命名、PTC 预设**无代码关系**。 |
+| A2 / A3 | 未实现 | 将来按同一 SPI 自研；**不引入** `dsh-ops` 的 `tools_addition` 运行时与 Rust 二进制。 |
+| B1–B4 | 未实现（仅 SPI 类型） | 将来按 EDG/GDR/CCS/RSI 的**语义**自研；**不复制**其图结构定义、证书格式或 RSI 训练脚本。 |
+| 四切点 `cost-hooks` + 模块 SPI | **自研** | 本项目 Agent Loop 的既有边界，非第三方 API。 |
+
+**基准数字**（`HARNESSMM_BENCHMARK`）是论文公开数值，仅用于对标与单测断言常量，
+不参与任何对外「我们省了多少」的宣称；本项目实测值由 `ledger` 产生并与基准并列展示。
+
+---
+
+## 4. 编写 B1–B4 时的检查清单
+
+新增决策复用能力前，逐条确认：
+
+1. [ ] 结构体/状态机是从**问题**出发设计，而不是照抄参考项目的字段名与层级？
+2. [ ] 守卫条件、证书、图的序列化格式均为本项目自定义（不兼容、不消费第三方产物）？
+3. [ ] 没有新增运行时依赖；没有 vendored 代码目录；没有 Rust/二进制产物？
+4. [ ] 每个新文件带 `SPDX-License-Identifier: AGPL-3.0-or-later` 头？
+5. [ ] 若某段实现确实**必须**基于第三方代码（当前无此情况），先在 PR 中单独说明：
+   来源 URL、许可证、复制的具体范围，并在 `NOTICE`/`THIRD-PARTY` 与文件头保留原始声明——
+   **未经此步骤不得合入**。
+
+---
+
+## 5. 许可证
+
+- 本项目：`AGPL-3.0-or-later`（见 `LICENSE`、`LICENSE-CORE`）。
+- MIT 与 Apache-2.0 均为宽松许可证，与本项目兼容；但由于我们**未复制**其代码，当前无需附带其许可证正文。
+- 引用论文结论属学术引用，不构成代码衍生。
+- 若将来引入任何第三方代码，必须在此文件登记并同步 `LICENSE`/`NOTICE`。
+
+---
+
+## 6. 自动守卫
+
+`test/license-provenance.test.mjs` 会在每次 `npm test` 时校验：
+
+- `src/**`、`worker/**`、`client.js` 的每个文件都以本项目 SPDX 头开始；
+- 不存在第三方版权头或许可证正文（MIT/Apache 样板文本）；
+- 不存在 `*.rs`、`Cargo.toml`、`vendor/`、`third_party/` 等 vendored 痕迹；
+- `package.json` 无运行时/peer/optional 依赖（无法把参考实现当依赖拉进来）；
+- 源码不 `import`/`require` `dsh-ops`、`harnessmm` 等第三方包。
+
+守卫失败即视为违反本节约束。

package/docs/WORKER-AGENT-LOOP.md

@@ -131,7 +131,7 @@ apply(ctx) // 监听 superagent:worker:start；也可直接 runWorker(ticket, de
 - **PR**：`create_pr` 工具可接真实 GitHub 客户端（`DSH_MASTER_GITHUB_TOKEN/REPO`），需要先把分支 push 到远端；
 - 回写默认关闭，失败只告警，不改变 Ticket 终态；token 不入日志/状态。
 
-- Worker preset 已用 tsc 构建到 `dist-worker/` 并接入 bundle 行 `master-superagent-loop`（fork only）；
+- Worker preset 已用 tsc 构建到 `dist-worker/` 并接入 bundle 行 `master-superagent-loop`（fork/essence）；
 - Router 生成的 per-ticket token 通过 HTTP POST 把事件实时回传 Router；前端 SSE/WS 转发待 3.2.4；
 - 回写（webhook / GitHub Issue 评论）默认关闭，按宿主配置启用；失败只告警；
 - 跨进程派发桥需要宿主配置 `bridgeToken`（母体）与 `motherUrl/motherToken`（原身），默认关闭；

package/package.json

@@ -1,11 +1,23 @@
 {
   "name": "@twinsearth/dsh-master",
-  "version": "3.2.9",
+  "version": "3.3.0",
   "private": false,
   "publishConfig": {
     "access": "public"
   },
   "type": "module",
+  "license": "AGPL-3.0-or-later",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/TwinsEarth/dsh-Master.git"
+  },
+  "homepage": "https://github.com/TwinsEarth/dsh-Master#readme",
+  "bugs": {
+    "url": "https://github.com/TwinsEarth/dsh-Master/issues"
+  },
+  "engines": {
+    "dsh": ">=0.2.2-rc.1 <0.3.0-0"
+  },
   "description": "Dsh-Master（房主）：与瓮城 dsh-Fang 并行的主 Agent 插件，托管 SuperAgent Router/Worker、HarnessMM、PM+PJM。",
   "keywords": [
     "dsh",
@@ -51,8 +63,8 @@
     "README.md"
   ],
   "scripts": {
-    "test": "node --test --test-force-exit test/",
-    "test:clean": "node --test --test-concurrency=1 test/",
+    "test": "node --test --test-force-exit \"test/**/*.test.mjs\" \"test/**/*.test.ts\"",
+    "test:clean": "node --test --test-concurrency=1 \"test/**/*.test.mjs\" \"test/**/*.test.ts\"",
     "test:worker": "node --test --test-force-exit test/worker-agent-loop.test.ts test/worker-tools.test.ts test/worker-llm-http.test.ts test/worker-sink-http.test.ts",
     "typecheck:worker": "tsc -p tsconfig.worker.json",
     "build:worker": "tsc -p tsconfig.worker.build.json",

package/src/cost/attribution.ts

@@ -0,0 +1,186 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+// Copyright (c) 2026 dsh-Master contributors — see LICENSE-CORE.
+// @ts-nocheck — host JS→TS 迁移阶段：运行时行为优先，类型注解逐步补齐（worker/ 仍严格检查）。
+
+/**
+ * 3.3.0 系统层 · attribution（归因，设计 §5.4）。
+ *
+ * 三条硬规则：
+ *   1. **每条 savedTokens 必须带 moduleId**（缺失 ⇒ `module-missing`，不猜、不默认）；
+ *   2. 差额进 `unattributed`，报表**单列**——未归因收益不得算作任何模块收益；
+ *   3. 归因算法（工具面）：`baselineOutputTokens(toolName, 长度) − actualOutputTokens`，
+ *      baseline 由 A1 固定拟合式给出（`worker/baseline-fit.ts`，参数在 docs §5.4.1 冻结）。
+ *
+ * 另守 §5.3 口径：`shadow` 只累计「本可节省」，`enforce` 才写入 execution 账本且
+ * `totalTokens=0`（不重复计入已消耗 token）。
+ */
+
+import { COST_MODULES } from './types.ts'
+
+function finiteNonNegative(value) {
+  const n = Number(value)
+  return Number.isFinite(n) && n >= 0 ? Math.floor(n) : null
+}
+
+/**
+ * @param {{ledger: {append: Function}, now?: () => number}} options
+ */
+export function createAttribution(options = {}) {
+  const ledger = options.ledger
+  if (!ledger || typeof ledger.append !== 'function') throw new Error('attribution requires a ledger')
+  const now = typeof options.now === 'function' ? options.now : () => Date.now()
+  const allowed = new Set(COST_MODULES)
+  const modules = new Map()
+  const tasks = new Map()
+
+  const moduleRow = (module) => {
+    if (!modules.has(module)) modules.set(module, { module, events: 0, projectedTokens: 0, enforceSavedTokens: 0 })
+    return modules.get(module)
+  }
+  const taskRow = (taskId, module) => {
+    const key = `${taskId ?? ''}|${module}`
+    if (!tasks.has(key)) tasks.set(key, { key, taskId: taskId === undefined ? null : String(taskId), module, events: 0, projectedTokens: 0, enforceSavedTokens: 0 })
+    return tasks.get(key)
+  }
+
+  /**
+   * @param {{taskId?: string, module: string, savedTokens: number, mode?: string, meta?: object,
+   *          forkId?: string, sessionId?: string}} input
+   */
+  function attribute(input = {}) {
+    const saved = finiteNonNegative(input.savedTokens)
+    if (saved === null) return { ok: false, code: 'saved-tokens-invalid', message: 'savedTokens must be a non-negative number' }
+    // §5.4-1：moduleId 必填，缺失不猜默认值。
+    if (input.module === undefined || input.module === null || String(input.module).trim() === '') {
+      return { ok: false, code: 'module-missing', message: 'every savedTokens must carry a moduleId' }
+    }
+    const module = String(input.module)
+    if (!allowed.has(module)) return { ok: false, code: 'module-invalid', message: `module must be one of ${COST_MODULES.join('/')}` }
+    const enforce = String(input.mode ?? 'shadow') === 'enforce'
+    const row = moduleRow(module)
+    const perTask = taskRow(input.taskId, module)
+
+    if (!enforce) {
+      row.events += 1
+      row.projectedTokens += saved
+      perTask.events += 1
+      perTask.projectedTokens += saved
+      return {
+        ok: true,
+        mode: 'shadow',
+        module,
+        projectedTokens: saved,
+        shadow: { events: row.events, projectedTokens: row.projectedTokens, appliedTokens: row.enforceSavedTokens },
+        at: now(),
+      }
+    }
+
+    const appended = ledger.append({
+      account: 'execution',
+      module,
+      source: 'tool',
+      phase: 'tool',
+      taskId: input.taskId === undefined ? null : String(input.taskId),
+      forkId: input.forkId,
+      sessionId: input.sessionId,
+      step: input.step,
+      turn: input.turn,
+      totalTokens: 0,
+      savedTokens: saved,
+      meta: { kind: 'attribution', ...(input.meta && typeof input.meta === 'object' ? input.meta : {}), mode: 'enforce' },
+    })
+    if (!appended.ok) return { ok: false, code: appended.code, message: appended.message }
+    row.events += 1
+    row.enforceSavedTokens += saved
+    perTask.events += 1
+    perTask.enforceSavedTokens += saved
+    return {
+      ok: true,
+      mode: 'enforce',
+      module,
+      savedTokens: saved,
+      ledger: { id: appended.entry.id },
+      shadow: { events: row.events, projectedTokens: row.projectedTokens, appliedTokens: row.enforceSavedTokens },
+      at: now(),
+    }
+  }
+
+  /**
+   * §5.4-2：按「总额 − 各模块之和」结算，差额自动进 `unattributed`。
+   * 任何未提供 moduleId 的条目都会被拒绝（模块收益不得凭空出现）。
+   *
+   * @param {{taskId?: string, totalSavedTokens: number, items?: Array<{module: string, savedTokens: number}>,
+   *          mode?: string, forkId?: string, sessionId?: string}} input
+   */
+  function attributeTotal(input = {}) {
+    const total = finiteNonNegative(input.totalSavedTokens)
+    if (total === null) return { ok: false, code: 'saved-tokens-invalid', message: 'totalSavedTokens must be a non-negative number' }
+    const items = Array.isArray(input.items) ? input.items : []
+    let attributed = 0
+    const applied = []
+    for (const item of items) {
+      const out = attribute({
+        taskId: input.taskId,
+        module: item?.module,
+        savedTokens: item?.savedTokens,
+        mode: input.mode,
+        forkId: input.forkId,
+        sessionId: input.sessionId,
+        meta: { kind: 'module-share' },
+      })
+      if (!out.ok) return out
+      attributed += finiteNonNegative(item?.savedTokens) ?? 0
+      applied.push({ module: String(item.module), savedTokens: finiteNonNegative(item?.savedTokens) ?? 0 })
+    }
+    if (attributed > total) {
+      return { ok: false, code: 'attribution-overflow', message: `attributed ${attributed} exceeds total ${total}` }
+    }
+    const residual = total - attributed
+    if (residual > 0) {
+      const out = attribute({
+        taskId: input.taskId,
+        module: 'unattributed',
+        savedTokens: residual,
+        mode: input.mode,
+        forkId: input.forkId,
+        sessionId: input.sessionId,
+        meta: { kind: 'residual' },
+      })
+      if (!out.ok) return out
+    }
+    return { ok: true, totalSavedTokens: total, attributedTokens: attributed, unattributedTokens: residual, items: applied, at: now() }
+  }
+
+  function snapshot() {
+    const moduleRows = [...modules.values()]
+      .map((item) => Object.freeze({ ...item }))
+      .sort((a, b) => b.projectedTokens + b.enforceSavedTokens - (a.projectedTokens + a.enforceSavedTokens))
+    const taskRows = [...tasks.values()]
+      .map((item) => Object.freeze({ ...item }))
+      .sort((a, b) => b.projectedTokens + b.enforceSavedTokens - (a.projectedTokens + a.enforceSavedTokens))
+    const named = moduleRows.filter((row) => row.module !== 'unattributed')
+    const unattributed = moduleRows.filter((row) => row.module === 'unattributed')
+    const sum = (rows, key) => rows.reduce((total, row) => total + row[key], 0)
+    return Object.freeze({
+      ok: true,
+      modules: moduleRows,
+      tasks: taskRows,
+      /** 模块收益（不含 unattributed）——报表只能把这一项当「模块业绩」。 */
+      attributedSavedTotal: sum(named, 'enforceSavedTokens'),
+      attributedProjectedTotal: sum(named, 'projectedTokens'),
+      /** 未归因收益：单列，永不并入上面的模块业绩。 */
+      unattributedSavedTotal: sum(unattributed, 'enforceSavedTokens'),
+      unattributedProjectedTotal: sum(unattributed, 'projectedTokens'),
+      projectedTotal: sum(moduleRows, 'projectedTokens'),
+      enforceSavedTotal: sum(moduleRows, 'enforceSavedTokens'),
+    })
+  }
+
+  function reset() {
+    modules.clear()
+    tasks.clear()
+    return { ok: true }
+  }
+
+  return Object.freeze({ attribute, attributeTotal, snapshot, reset })
+}