@twinsearth/dsh-master 3.2.9 → 3.3.0

package/README.md

@@ -1,9 +1,12 @@
 # dsh-Master（房主）
 
 > 与瓮城 **dsh-Fang** 并行的主 Agent 插件。  
-> 当前版本：`3.2.9`（面板交互修复线；tag / GitHub Release / NPM public）。
+> 当前版本：`3.2.10`（角色矩阵放宽线；tag / GitHub Release / NPM public）。
 > 仓库：https://github.com/TwinsEarth/dsh-Master
 
+[![CI](https://github.com/TwinsEarth/dsh-Master/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/TwinsEarth/dsh-Master/actions/workflows/ci.yml)
+[![npm](https://img.shields.io/npm/v/@twinsearth/dsh-master?style=flat&label=npm&color=4D6BFE)](https://www.npmjs.com/package/@twinsearth/dsh-master)
+[![license](https://img.shields.io/badge/license-AGPL--3.0--or--later-4D6BFE?style=flat)](https://github.com/TwinsEarth/dsh-Master/blob/main/LICENSE)
 [![DSH 0.2.2-rc.1](https://img.shields.io/badge/DSH-0.2.2--rc.1-4D6BFE?style=flat)](https://github.com/deepseek-ai/deepseek-harness)
 [![](https://img.shields.io/badge/powered_by-dsh-4D6BFE?style=flat-square&logo=deepseek&logoColor=white)](https://github.com/deepseek-ai/deepseek-harness)
 
@@ -16,8 +19,8 @@ dsh-Master 不接管瓮城的「母体 / 原身 / 分身」生命周期；它是
 DSH Host
 ├── 瓮城 bundle (dsh-Fang)                    房主 bundle (dsh-Master)
 │   mirror / essence / derived                core（主 Agent 控制面）
-│   fangForker / fangDecisionCenter  ◄──────  ├── superagent-router   （essence）
-│   fangSessionCatalog                       ├── superagent-worker   （fork）
+│   fangForker / fangDecisionCenter  ◄──────  ├── superagent-router   （essence/mother）
+│   fangSessionCatalog                       ├── superagent-worker   （fork/essence）
 │                                            ├── cost-optimizer       （fork）
 │                                            └── dual-manager         （mother/essence）
 └── 协作只走服务键；任一方向失败一律 fail-closed，不本地降级执行
@@ -27,9 +30,9 @@ DSH Host
 
 | 子插件 | 行 id | 允许角色 | 路线图 | 已交付 |
 |---|---|---|---|---|
-| SuperAgent Router | `master-superagent-router` | **essence only** | 3.2.1/3.2.3 | Webhook/Ticket/Mandate、渐进信任、本地或母体桥派发、Worker 实时事件、回写 |
-| SuperAgent Worker | `master-superagent-worker` | **fork only** | 3.2.1 | Ticket 上下文、Mandate 守卫 |
-| Worker Agent Loop | `master-superagent-loop` | **fork only** | 3.2.3 | tsc 编译 preset；有 Ticket 自动跑多轮工具循环并流式回传 |
+| SuperAgent Router | `master-superagent-router` | **essence / mother** | 3.2.1/3.2.3 | Webhook/Ticket/Mandate、渐进信任、本地或母体桥派发、Worker 实时事件、回写 |
+| SuperAgent Worker | `master-superagent-worker` | **fork / essence** | 3.2.1 | Ticket 上下文、Mandate 守卫 |
+| Worker Agent Loop | `master-superagent-loop` | **fork / essence** | 3.2.3 | tsc 编译 preset；有 Ticket 自动跑多轮工具循环并流式回传 |
 | 成本优化 HarnessMM | `master-cost-optimizer` | **fork only** | 3.3.0 | observe 层：token 估算、实测记录 |
 | 双主管 PM + PJM | `master-dual-manager` | **mother / essence** | 3.4.0 | PRD/计划/调度/决策中心澄清 |
 
@@ -81,14 +84,44 @@ dsh plugin add <package>  # 加载 dist-host/dist-worker
 - [Worker Agent Loop](docs/WORKER-AGENT-LOOP.md)
 - [SuperAgent v3.2.1 设计与契约](docs/SUPERAGENT.md)
 - [架构设计](docs/ARCHITECTURE.md)
+- [3.3.0 成本优化架构（总体架构 / 实施进度）](docs/DESIGN-v3.3.0-cost-optimization.md)
+- [第三方参考实现与移植边界](docs/THIRD-PARTY.md)
 - [路线图（3.2.0–3.4.0）](docs/ROADMAP.md)
 - [安全边界](docs/SECURITY.md)
 - [变更记录](docs/CHANGELOG.md)
 
 ## 状态
 
+- 3.3.0 M1+M2（dev，未发布）：成本优化系统层（ledger / budget / policy / audit）+ Worker 四个成本切点（observe-only）+ A1 工具输出紧凑化（默认 shadow，enforce 需白名单）；A2–A3 与决策复用 B1–B4 在 M3–M4 接入，详见 [3.3.0 架构设计](docs/DESIGN-v3.3.0-cost-optimization.md)。
+- 3.2.10 发布线：角色矩阵放宽——Router 进入母体（essence/mother），Worker 与 Worker Agent Loop 进入原身（fork/essence）；母体仍不接纳执行体，fork 仍不注册 Router。
 - 3.2.9 发布线：房主面板改注册到 `shell.overlay` 常驻浮层——点击面板之外不收起、侧栏「房主」按钮二次点击收起、正文独立滚动；新增无浏览器 hook 运行时行为测试（开关、无 outside-click 监听、滚动容器、SSE 失败不卸载面板）。
 - 3.2.8 发布线：与瓮城通过 fang-master contract 1.0 互联（local/http/file/legacy 四级保底）；GitHub Release + NPM public。
 - 当前工作树完成新一轮审计修复：工具名/死循环阈值、Router 鉴权与生命周期、真实路由分流、契约幂等与超时、PR 护栏与交付、飞书加密、长 Shell 后台作业、成本实测接线、PJM 派生契约。
 - 验收：`npm run check` / `npm run build` / `npm test` 全绿（188/188）；真实双 Host/fork 落库、工具写读、SSE、回写、配额与桥清理断言通过。详见复盘文档。
 - 发布不等于安装：本流程不修改任何用户 profile（当前 desktop profile 仍为 3.2.8，升级需另行授权）。
+
+## 依赖、权限与兼容
+
+- **外部依赖**：与瓮城 **dsh-Fang ≥ 3.1.14** 同宿主协作，通过 `fangForker` / `fangDecisionCenter` / `fangSessionCatalog` / `fangSessionBridge` 服务键派发与回收；瓮城不在线时子插件 **fail-closed**，不在本地降级执行。
+- **安装产物**：npm 运行时依赖为空；无 `preinstall` / `install` / `postinstall` / `prepare` 生命周期脚本；安装只写目标 profile 的 bundle 层。
+- **权限与边界**：Host 侧只注册受控 HTTP 路由（status / stream-token / worker-events / stream / session / webhook），worker-events POST 需要 ticket 匹配的 worker token；Worker 工具受 Mandate 作用域、Shell 白名单与工作区 jail 约束；Web Client 只读（面板不写宿主状态）。
+- **默认状态**：SuperAgent 默认 **observe**，不会自动接单；Router 仅 essence、Worker/成本仅 fork、双主管仅 mother/essence，角色不匹配时该行明确报 `role-not-allowed`。
+- **兼容**：`engines.dsh: >=0.2.2-rc.1 <0.3.0-0`（实测基线 DSH 0.2.2-rc.1、Node.js 26）。
+
+## CI
+
+`.github/workflows/ci.yml` 在 `push main`、Pull Request 与手动触发时运行：
+
+```text
+npm ci
+npm run check        # client.js 语法 + host/worker 类型检查
+npm run build        # dist-host + dist-worker
+npm test             # 全量测试
+```
+
+矩阵：Node 24 / 26（ubuntu），另加 Node 26（windows，覆盖平台相关用例）。
+
+## 许可证
+
+本项目以 [GNU Affero General Public License v3.0 or later](LICENSE) 发布。
+`LICENSE-CORE` 是同一许可文本的副本，随核心源码一起分发。

package/client.js

@@ -241,6 +241,55 @@ window.__ModuleLoader__.load({
       )
     }
 
+    /**
+     * §11：成本（只读）块。
+     *
+     * 只消费 `/dsh-master/api/superagent/cost` 的 `service` 段，**不写任何业务状态**、
+     * 不触发任何成本动作；A（单价项）与 B（跳过调用项）分列展示，绝不合并成一个数字。
+     */
+    function CostCard() {
+      const [cost, setCost] = React.useState(null)
+      const [failed, setFailed] = React.useState(false)
+
+      React.useEffect(() => {
+        let alive = true
+        const load = async () => {
+          try {
+            const response = await fetch('/dsh-master/api/superagent/cost', { headers: { accept: 'application/json' } })
+            const body = await response.json().catch(() => null)
+            if (!alive) return
+            setCost(response.ok && body ? body : null)
+            setFailed(!response.ok)
+          } catch { if (alive) setFailed(true) }
+        }
+        void load()
+        const timer = setInterval(load, 5000)
+        return () => { alive = false; clearInterval(timer) }
+      }, [])
+
+      const block = cost && cost.service ? cost.service : null
+      const columns = block && block.columns ? block.columns : null
+      const savings = block && block.savings ? block.savings : null
+      const fmt = (value) => (value === null || value === undefined ? '—' : Number(value).toLocaleString())
+
+      return h('div', { style: S.card, 'data-dsh-master': 'cost-block' },
+        h('div', { style: S.row },
+          h('span', { style: S.name }, '成本（只读）'),
+          tag(block ? '3.3.0' : '未启用', block ? undefined : '#B45309')),
+        failed ? h('div', { style: S.error }, '成本接口不可达') : null,
+        !block && !failed ? h('div', { style: S.desc }, '成本系统未装配（cost-optimizer 未启用或角色不匹配）') : null,
+        columns ? h('div', { style: S.desc },
+          '单价项 A：' + fmt(columns.unitPriceSaved) + ' · ',
+          '跳过调用 B：' + fmt(columns.skippedCallSaved) + '（' + fmt(columns.skippedCalls) + ' 次）') : null,
+        columns ? h('div', { style: S.desc },
+          'governance：' + fmt(columns.governanceTotal) + ' · 净节省：' + fmt(columns.netSaved)) : null,
+        columns && columns.netLossTasks && columns.netLossTasks.length > 0
+          ? h('div', { style: S.off }, '净亏任务：' + columns.netLossTasks.slice(0, 3).join(', '))
+          : null,
+        savings ? h('div', { style: S.desc }, '命中率：' + (block.hitRate === undefined || block.hitRate === null ? '—' : (Number(block.hitRate) * 100).toFixed(1) + '%')) : null,
+      )
+    }
+
     function MasterPanel() {
       const [status, setStatus] = React.useState(null)
       const [error, setError] = React.useState('')
@@ -283,9 +332,10 @@ window.__ModuleLoader__.load({
             h('div', { style: S.desc }, '运行：' + Math.max(1, Math.round((status.uptimeMs || 0) / 60000)) + ' 分钟'),
           ) : null,
           ...items.map((item) => h(SubpluginCard, { key: item.id, item })),
+          h(CostCard),
           h(FangCard, { cooperation: status && status.cooperation }),
           h(LiveFeed),
-          h('div', { style: S.desc }, '3.2.9：面板常驻（点面板外不收起、按钮二次点击收起、长内容可滚动）；实时流（SSE）+ token 轮换/审计 + Worker 并发配额。'),
+          h('div', { style: S.desc }, '3.2.10：角色矩阵放宽（Router→essence/mother，Worker/Loop→fork/essence）；面板常驻、按钮二次点击收起、正文可滚动；实时流（SSE）+ token 轮换/审计。'),
         ))
     }
 

package/dist-host/cost/attribution.js

@@ -0,0 +1,183 @@
+// 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.js";
+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 });
+}

package/dist-host/cost/audit.js

@@ -0,0 +1,163 @@
+// 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 系统层 · audit（哈希链审计，设计 §5.5）。
+ *
+ * 结构约束：
+ *   * **只追加**：没有 update/delete/rewrite API，记录 `Object.freeze`；
+ *   * 每条记录含 `prevHash` 与自身 `hash`，任何篡改或截断都会在 `verify()` 断链；
+ *   * 每次替换写一条 `SubstitutionCert`（edgeId / toolName / schemaHash / guardExpr /
+ *     receiptDigest / replacedCallbackId / viaNativeDispatcher: true），
+ *     并与 ledger 事件用同一 `taskId + step` 关联 —— 报表可回放「这一省是怎么来的」。
+ */
+import crypto from 'node:crypto';
+/** SubstitutionCert 必填字段；缺任何一项都不得落链（否则证书无法复核）。 */
+const CERT_REQUIRED = Object.freeze([
+    'edgeId',
+    'toolName',
+    'schemaHash',
+    'guardExpr',
+    'receiptDigest',
+    'replacedCallbackId',
+    'taskId',
+]);
+function canonical(value) {
+    if (Array.isArray(value))
+        return `[${value.map((item) => canonical(item)).join(',')}]`;
+    if (value && typeof value === 'object') {
+        const keys = Object.keys(value).sort();
+        return `{${keys.map((key) => `${JSON.stringify(key)}:${canonical(value[key])}`).join(',')}}`;
+    }
+    if (typeof value === 'number')
+        return Number.isFinite(value) ? String(value) : 'null';
+    if (value === undefined)
+        return 'null';
+    return JSON.stringify(value) ?? 'null';
+}
+function hashOf(seq, at, type, actor, payload, prevHash) {
+    const body = canonical([seq, at, type, actor, payload, prevHash]);
+    return `sha256:${crypto.createHash('sha256').update(body).digest('hex')}`;
+}
+/**
+ * @param {{now?: () => number, maxRecords?: number}} [options]
+ */
+export function createAuditChain(options = {}) {
+    const now = typeof options.now === 'function' ? options.now : () => Date.now();
+    const maxRecords = Math.max(1, Number(options.maxRecords ?? 2000) || 2000);
+    const records = [];
+    let seq = 0;
+    let dropped = 0;
+    function append({ type, actor = 'cost-system', payload = {} } = {}) {
+        seq += 1;
+        const at = now();
+        const prevHash = records.length > 0 ? records[records.length - 1].hash : '';
+        const record = Object.freeze({
+            seq,
+            at,
+            type: String(type ?? 'unknown'),
+            actor: String(actor ?? 'cost-system'),
+            payload: Object.freeze({ ...payload }),
+            prevHash,
+            hash: hashOf(seq, at, String(type ?? 'unknown'), String(actor ?? 'cost-system'), payload, prevHash),
+        });
+        records.push(record);
+        if (records.length > maxRecords) {
+            records.shift();
+            dropped += 1;
+        }
+        return record;
+    }
+    /**
+     * 写一条 SubstitutionCert（§5.5）。fail-closed：
+     *   * 必填字段缺失/空白 ⇒ 拒绝；
+     *   * `viaNativeDispatcher` 必须严格为 `true`（非原生派发不得替换）；
+     *   * `taskId + step` 是回放键，step 必须是非负整数。
+     */
+    function appendSubstitution(cert = {}) {
+        const missing = CERT_REQUIRED.filter((key) => {
+            const value = cert?.[key];
+            return value === undefined || value === null || String(value).trim() === '';
+        });
+        if (missing.length > 0) {
+            return { ok: false, code: 'cert-invalid', message: `substitution cert missing ${missing.join(',')}`, missing };
+        }
+        if (cert.viaNativeDispatcher !== true) {
+            return { ok: false, code: 'cert-not-native', message: 'substitution must be executed via the native dispatcher' };
+        }
+        const step = Number(cert.step);
+        if (!Number.isInteger(step) || step < 0) {
+            return { ok: false, code: 'cert-step-invalid', message: 'step must be a non-negative integer' };
+        }
+        const savedTokens = Number(cert.savedTokens ?? 0);
+        if (!Number.isFinite(savedTokens) || savedTokens < 0) {
+            return { ok: false, code: 'cert-saved-invalid', message: 'savedTokens must be a non-negative number' };
+        }
+        const payload = Object.freeze({
+            kind: 'substitution-cert',
+            edgeId: String(cert.edgeId),
+            toolName: String(cert.toolName),
+            schemaHash: String(cert.schemaHash),
+            guardExpr: String(cert.guardExpr),
+            receiptDigest: String(cert.receiptDigest),
+            replacedCallbackId: String(cert.replacedCallbackId),
+            /** M4：落链即代表「已经过原生派发器真的派发」；证书链核对直接读这一位。 */
+            dispatched: true,
+            viaNativeDispatcher: true,
+            taskId: String(cert.taskId),
+            step,
+            forkId: cert.forkId === undefined ? null : String(cert.forkId),
+            sessionId: cert.sessionId === undefined ? null : String(cert.sessionId),
+            ticketId: cert.ticketId === undefined ? null : String(cert.ticketId),
+            moduleId: cert.moduleId === undefined ? null : String(cert.moduleId),
+            savedTokens,
+        });
+        const record = append({ type: 'cost.substitution', actor: 'cost-ccs', payload });
+        return { ok: true, cert: payload, record };
+    }
+    function verify(source) {
+        const list = Array.isArray(source) ? source : records;
+        let prevHash = '';
+        let expectedSeq = 1;
+        for (const record of list) {
+            if (record.seq !== expectedSeq)
+                return { ok: false, count: list.length, brokenAt: record.seq, reason: 'seq-gap' };
+            if (record.prevHash !== prevHash)
+                return { ok: false, count: list.length, brokenAt: record.seq, reason: 'prev-hash-mismatch' };
+            const expected = hashOf(record.seq, record.at, record.type, record.actor, record.payload, record.prevHash);
+            if (record.hash !== expected)
+                return { ok: false, count: list.length, brokenAt: record.seq, reason: 'hash-mismatch' };
+            prevHash = record.hash;
+            expectedSeq += 1;
+        }
+        return { ok: true, count: list.length, brokenAt: null, reason: null };
+    }
+    function snapshot(limit = 50) {
+        const n = Math.max(1, Number(limit) || 50);
+        return Object.freeze({
+            ok: true,
+            count: records.length,
+            dropped,
+            verified: verify(),
+            records: records.slice(-n),
+        });
+    }
+    function reset() {
+        records.length = 0;
+        seq = 0;
+        dropped = 0;
+        return { ok: true };
+    }
+    /** 取某任务/步骤的证书（回放用；不改链）。 */
+    function substitutions(filter = {}) {
+        const taskId = filter.taskId === undefined ? null : String(filter.taskId);
+        const step = filter.step === undefined ? null : Number(filter.step);
+        const rows = records
+            .filter((record) => record.type === 'cost.substitution')
+            .filter((record) => (taskId === null ? true : record.payload.taskId === taskId))
+            .filter((record) => (step === null ? true : record.payload.step === step));
+        return Object.freeze(rows.map((record) => Object.freeze({ ...record.payload, seq: record.seq, at: record.at, hash: record.hash })));
+    }
+    // 只追加：对外**不暴露**任何修改/删除入口（records() 返回副本）。
+    return Object.freeze({ append, appendSubstitution, verify, snapshot, reset, records: () => records.slice(), substitutions });
+}