@twinsearth/dsh-master 3.2.10 → 3.3.1

package/docs/EXPERIMENT-M5-fang-relay.md

@@ -0,0 +1,117 @@
+# M5 · 瓮城回流接口实测报告（contract 1.1.0 / 房主 3.3.1）
+
+> 结论：**M5 达标（done）**，但证据的**对端身份是 `contract-server`**（瓮城侧契约 SDK 的独立进程），
+> 不是 `dsh-fang-bundle` 本体。这个区别写在里程碑结果行的 `notes` 里，不隐藏。
+>
+> 日期：2026-11-13 · 环境：Windows / Node 26.13.0 / 单机双进程
+
+## 1. 为什么需要这一轮
+
+3.3.0 的 M5 只差一件事：`与瓮城回流对接`。当时的实现是**硬编码**
+
+```js
+relay: { target: 'fang', available: false, reason: 'fang-channel-not-ready' }
+```
+
+接口位在，但没有协议、没有投递、没有回执。contract 1.0.0 的方法表里也确实没有任何
+回流方法（只有 `fang.fork.*` / `fang.decision.*` / `fang.session.list` / `fang.orchestrator.status`），
+所以“接上”只能先把接口版本升上去。
+
+## 2. 这一轮改了什么
+
+### 2.1 接口包 `@twinsearth/dsh-fang-contract@1.1.0`
+
+| 变化 | 内容 |
+|---|---|
+| 新方法 | `fang.relay.publish`（批量投递，按 `event.id` 幂等，返回回执 + 游标）、`fang.relay.status`（对端自报 peer/cursor/累计计数） |
+| 新能力 | `event-relay` |
+| 参考实现 | `createRelayStore` / `validateRelayEvents` / `relayHandlers` / `createRelayContractServer` |
+| 客户端 | `publishRelay()` / `relayStatus()` |
+| 传输加固 | 逐调用 `timeoutMs`/`meta` 透传、`httpHeaders` 透传、HTTP 定时器 `unref`、file 回执/请求文件有界重试清理 |
+| 兼容 | 只升 MINOR；1.0 对端不会宣告 1.1 方法，`negotiate()` 按公共 minor 自动裁剪 |
+
+发布核验：npm `1.1.0` = `latest`，下载包与本地 tarball **字节一致**
+（sha256 `e5224dc682b7a66247cd100d47492047b081acf233fd1f7daac4fab6753d5bd4`，11 个文件）。
+仓库 main 已推到 `c106053d`（tree 与本地一致）。
+
+### 2.2 房主侧
+
+- `src/contract/` 内嵌副本同步到 1.1.0，与已发布包**逐字节相同**（`test/contract-conformance.test.mjs` 守卫）；
+- 新增 `src/cost/fang-relay.ts`：`probe()` 判定对端是否真的提供回流；`enqueue()/flush()`
+  批量投递且**只认回执**；失败退回队列并转 `publish-failed:*`；
+- `cost-optimizer` / `superagent-router` / `createCostSystem()` 全部改为读真实状态；
+- M5 判定收紧为 `available + peer 白名单 + events ≥ 3 + 非自环`。
+
+## 3. 实测方法（可复现）
+
+```bash
+npm run build
+node scripts/fang-relay-probe.mjs --events 6 --out relay-evidence.json
+```
+
+脚本行为：
+
+1. 起一个**独立子进程**（`--serve`），里面跑**已发布的 npm 包**
+   `@twinsearth/dsh-fang-contract@1.1.0` 的 `createRelayContractServer`，
+   以 HTTP 暴露 `/fang/api/contract/{hello,invoke,health}`（Bearer token，不裸奔）；
+2. 父进程用仓库内嵌副本作客户端，`probe()` → 入队 6 条事件（三类事件混合）→ `flush()`；
+3. 只把对端回执当证据；`sameProcess` 由两侧 pid 比较得出；
+4. 证据 JSON 顶层就是 `{ ok, fangRelay, detail }`，可直接喂给 `scripts/milestones.mjs --input`。
+
+## 4. 实测结果
+
+```json
+{
+  "ok": true,
+  "fangRelay": {
+    "available": true,
+    "peer": "contract-server",
+    "events": 6,
+    "sameProcess": false,
+    "transport": "http",
+    "contractVersion": "1.1.0",
+    "reason": null,
+    "cursor": 6,
+    "failed": 0,
+    "dropped": 0
+  },
+  "detail": {
+    "probePid": 13340,
+    "peerPid": 4476,
+    "endpoint": "http://127.0.0.1:58328",
+    "batches": [{ "ok": true, "delivered": 6, "duplicates": 0, "sent": 6, "queued": 0, "cursor": 6, "batchId": "relay-1" }]
+  }
+}
+```
+
+里程碑输出：
+
+```text
+M5 │ 实现 ✔ │ 依赖 ✔ │ 效果 verified │ 状态 done │ 回流对端 'contract-server·6条'
+   M5 说明: peer=contract-server：契约对端独立进程实测，dsh-fang-bundle 采用 contract 1.1 后应变为 peer=dsh-fang-bundle
+```
+
+## 5. 能证明 / 不能证明
+
+**能证明**
+
+- contract 1.1 的回流协议在**两个真实进程**之间跑通：hello 协商 → 方法裁剪 → 投递 → 回执 → 游标；
+- 幂等成立：同 id 重投 `accepted:0 / duplicates>0`，游标不倒退；
+- 失败路径不伪装：客户端不可用 / 对端 1.0 / hello 失败 / status 失败 / publish 失败，
+  五种情况分别有具名原因，且失败批次会退回队列并计入 `failed`（有单元测试）；
+- 房主内嵌副本与已发布包无漂移（逐字节 + 双向互操作测试）。
+
+**不能证明**
+
+- 不能说“已与真实 dsh-Fang bundle 完成对接”：bundle 尚未依赖 contract 1.1，也尚未挂
+  `relayHandlers`。等 bundle 采用 1.1 后，`peer` 自报值会变成 `dsh-fang-bundle`，
+  M5 的 `notes` 会自动消失（代码里写死的是白名单，不需要改里程碑表）；
+- 不能证明生产环境的网络/鉴权拓扑：本轮是 127.0.0.1 + Bearer token 的本机双进程。
+
+## 6. 复现注意事项
+
+- 必须 `npm run build` 后跑：脚本 import 的是 `dist-host/`；
+- 子进程用的是 `node_modules` 里**已发布**的包，父进程用 `src/contract/`，两侧故意不同源，
+  才能真正测出“已发布包 ↔ 内嵌副本”的互操作；
+- 证据文件不要提交进仓库（G6 零残留门禁会检查 `rsi-report.json` 一类产物）；
+- Windows 上子进程退出由 `SIGTERM` 处理，若端口被占用会直接报 ready 超时。

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

@@ -0,0 +1,87 @@
+# 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' }`，不伪装成功。
+
+> **后续（3.3.1 已收口）**：contract 1.1.0 新增 `fang.relay.publish` / `fang.relay.status`，
+> 房主侧新增 `src/cost/fang-relay.ts` 真实投递，并用独立进程对端拿到 6 条回执；
+> M5 现在 `done`（`peer=contract-server`）。详见
+> [`EXPERIMENT-M5-fang-relay.md`](EXPERIMENT-M5-fang-relay.md)。

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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@twinsearth/dsh-master",
-  "version": "3.2.10",
+  "version": "3.3.1",
   "private": false,
   "publishConfig": {
     "access": "public"
@@ -75,7 +75,7 @@
     "build": "npm run build:host && npm run build:worker"
   },
   "devDependencies": {
-    "@twinsearth/dsh-fang-contract": "^1.0.0",
+    "@twinsearth/dsh-fang-contract": "^1.1.0",
     "@types/node": "^24.0.0",
     "typescript": "^5.9.0"
   },

package/src/contract/client.js

@@ -81,6 +81,13 @@ export function createContractClient(options = {}) {
     async resolveDecision(params, invokeOptions = {}) { return await client.invoke(METHODS.DECISION_RESOLVE, params, invokeOptions) },
     async listSessions(params = {}, invokeOptions = {}) { return await client.invoke(METHODS.SESSION_LIST, params, invokeOptions) },
     async orchestratorStatus(params = {}, invokeOptions = {}) { return await client.invoke(METHODS.ORCHESTRATOR_STATUS, params, invokeOptions) },
+    /** contract 1.1：批量投递回流事件（按 event.id 幂等；返回回执与游标）。 */
+    async publishRelay(events, invokeOptions = {}) {
+      const params = Array.isArray(events) ? { events } : (events && typeof events === 'object' ? events : { events: [] })
+      return await client.invoke(METHODS.RELAY_PUBLISH, params, invokeOptions)
+    },
+    /** contract 1.1：读取对端回流状态（对端自报 peer/cursor/累计计数）。 */
+    async relayStatus(params = {}, invokeOptions = {}) { return await client.invoke(METHODS.RELAY_STATUS, params, invokeOptions) },
   }
   return client
 }

package/src/contract/constants.js

@@ -11,7 +11,7 @@
  */
 
 export const CONTRACT_PACKAGE = '@twinsearth/dsh-fang-contract'
-export const CONTRACT_VERSION = '1.0.0'
+export const CONTRACT_VERSION = '1.1.0'
 export const PROTOCOL = 'fang-master'
 export const PROTOCOL_VERSION = 1
 export const MIN_COMPATIBLE_MAJOR = 1
@@ -27,6 +27,8 @@ export const METHODS = Object.freeze({
   DECISION_RESOLVE: 'fang.decision.resolve',
   SESSION_LIST: 'fang.session.list',
   ORCHESTRATOR_STATUS: 'fang.orchestrator.status',
+  RELAY_PUBLISH: 'fang.relay.publish',
+  RELAY_STATUS: 'fang.relay.status',
 })
 
 /** 方法 → 契约版本（用于协商后的方法裁剪）。 */
@@ -40,10 +42,12 @@ export const METHOD_VERSION = Object.freeze({
   [METHODS.DECISION_RESOLVE]: '1.0',
   [METHODS.SESSION_LIST]: '1.0',
   [METHODS.ORCHESTRATOR_STATUS]: '1.0',
+  [METHODS.RELAY_PUBLISH]: '1.1',
+  [METHODS.RELAY_STATUS]: '1.1',
 })
 
 export const CAPABILITIES = Object.freeze([
-  'sync', 'async', 'idempotent', 'stream-events', 'file-outbox',
+  'sync', 'async', 'idempotent', 'stream-events', 'file-outbox', 'event-relay',
 ])
 
 export const ROLES = Object.freeze(['mother', 'essence', 'fork'])
@@ -77,3 +81,14 @@ export const LEGACY_SERVICE_KEYS = Object.freeze({
   sessionCatalog: 'fangSessionCatalog',
   orchestrator: 'fang',
 })
+
+/**
+ * 回流接口的硬上限（1.1）。超限是**协议错误**而不是静默截断：
+ * 调用方必须自己分批，服务端不得悄悄丢事件（回流要可对账）。
+ */
+export const RELAY_LIMITS = Object.freeze({
+  maxBatch: 128,
+  maxEventBytes: 32_000,
+  maxPayloadBytes: 512_000,
+  maxRecords: 5_000,
+})

package/src/contract/index.js

@@ -15,5 +15,6 @@ export * from './constants.js'
 export * from './envelope.js'
 export * from './negotiate.js'
 export * from './server.js'
+export * from './relay.js'
 export * from './transports.js'
 export * from './client.js'

package/src/contract/relay.js

@@ -0,0 +1,223 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+// Copyright (c) 2026 dsh-Fang/dsh-Master contributors — see LICENSE.
+
+/**
+ * 回流（relay）接口 —— contract 1.1 新增能力。
+ *
+ * 背景：房主（dsh-Master）的成本总线产生 `cost:event` / `cost:degraded` /
+ * `cost:substitution` 三类事件，需要**单向**投递给瓮城（dsh-Fang）做产物回流与
+ * 信息栏展示。1.0 的方法表只有请求-响应式的 fork/decision/session，缺一个批量、
+ * 可去重、有回执的事件入口，因此 1.1 追加两个方法：
+ *
+ *   * `fang.relay.publish` —— 批量投递事件，按 `event.id` 幂等去重，返回回执与游标；
+ *   * `fang.relay.status`  —— 对端自报回流状态（自身标识 peerLabel、游标、累计计数）。
+ *
+ * 兼容规则（README §2）：新增方法只升 MINOR；1.0 的对端在 `hello` 协商时不会
+ * 宣告这两个方法，方法集被自动裁剪，调用方据此判定“回流不可用”，**不得**把
+ * 裁剪当成失败重试。
+ *
+ * 本文件只做协议与参考实现：不读写磁盘、不联网、不持有任何凭据。
+ */
+
+import { CONTRACT_VERSION, METHODS, RELAY_LIMITS } from './constants.js'
+import { createContractServer } from './server.js'
+
+function nowMs(now) {
+  const value = typeof now === 'function' ? now() : Date.now()
+  const n = Number(value)
+  return Number.isFinite(n) ? n : Date.now()
+}
+
+function asLimit(value, fallback) {
+  const n = Number(value)
+  return Number.isFinite(n) && n > 0 ? Math.floor(n) : fallback
+}
+
+function byteLength(value) {
+  try { return Buffer.byteLength(JSON.stringify(value ?? null), 'utf8') } catch { return Number.POSITIVE_INFINITY }
+}
+
+/**
+ * 校验一批回流事件。逐条判定：合法的接受，非法的计 `rejected` 并给原因，
+ * 不因单条坏数据丢掉整批（但整批不可用会抛 `relay-events-invalid`）。
+ *
+ * @param {unknown} events
+ * @param {{maxBatch?:number, maxEventBytes?:number, maxPayloadBytes?:number}} [limits]
+ */
+export function validateRelayEvents(events, limits = {}) {
+  const maxBatch = asLimit(limits.maxBatch, RELAY_LIMITS.maxBatch)
+  const maxEventBytes = asLimit(limits.maxEventBytes, RELAY_LIMITS.maxEventBytes)
+  const maxPayloadBytes = asLimit(limits.maxPayloadBytes, RELAY_LIMITS.maxPayloadBytes)
+  const errors = []
+  if (!Array.isArray(events)) {
+    return { ok: false, code: 'relay-events-invalid', errors: ['events-must-be-array'], accepted: [], rejected: [] }
+  }
+  if (events.length === 0) {
+    return { ok: false, code: 'relay-events-invalid', errors: ['events-empty'], accepted: [], rejected: [] }
+  }
+  if (events.length > maxBatch) {
+    return { ok: false, code: 'relay-events-invalid', errors: [`events-too-many(>${maxBatch})`], accepted: [], rejected: [] }
+  }
+  if (byteLength(events) > maxPayloadBytes) {
+    return { ok: false, code: 'relay-events-invalid', errors: [`payload-too-large(>${maxPayloadBytes})`], accepted: [], rejected: [] }
+  }
+  const accepted = []
+  const rejected = []
+  const seen = new Set()
+  for (const raw of events) {
+    const item = raw && typeof raw === 'object' ? raw : null
+    if (!item) { rejected.push({ id: null, reason: 'event-not-object' }); continue }
+    const id = typeof item.id === 'string' ? item.id.trim() : ''
+    if (!id) { rejected.push({ id: null, reason: 'id-required' }); continue }
+    if (typeof item.type !== 'string' || item.type.trim() === '') { rejected.push({ id, reason: 'type-required' }); continue }
+    if (byteLength(item) > maxEventBytes) { rejected.push({ id, reason: `event-too-large(>${maxEventBytes})` }); continue }
+    // 同一批内重复 id 也算重复投递：只接受第一次，其余计 duplicates。
+    if (seen.has(id)) { rejected.push({ id, reason: 'duplicate-in-batch' }); continue }
+    seen.add(id)
+    accepted.push({
+      id,
+      type: String(item.type),
+      at: Number.isFinite(Number(item.at)) ? Number(item.at) : 0,
+      payload: item.payload && typeof item.payload === 'object' ? item.payload : {},
+      meta: item.meta && typeof item.meta === 'object' ? item.meta : {},
+    })
+  }
+  return { ok: accepted.length > 0 || rejected.length === 0, errors, accepted, rejected }
+}
+
+/**
+ * 回流接收端（瓮城侧）的参考存储：按 event.id 幂等去重，保留有界回执环。
+ *
+ * @param {{
+ *   peerLabel?: string, role?: string, instanceId?: string,
+ *   maxRecords?: number, now?: () => number, limits?: object,
+ * }} [options]
+ */
+export function createRelayStore(options = {}) {
+  const peerLabel = String(options.peerLabel ?? 'contract-server')
+  const role = String(options.role ?? 'mother')
+  const instanceId = String(options.instanceId ?? '')
+  const maxRecords = asLimit(options.maxRecords, RELAY_LIMITS.maxRecords)
+  const limits = { ...RELAY_LIMITS, ...(options.limits && typeof options.limits === 'object' ? options.limits : {}) }
+  const now = typeof options.now === 'function' ? options.now : () => Date.now()
+  const seen = new Map()
+  const receipts = []
+  const counters = { accepted: 0, duplicates: 0, rejected: 0, batches: 0 }
+  let cursor = 0
+  let lastAt = 0
+  const lastErrors = []
+
+  function remember(receipt) {
+    receipts.push(receipt)
+    if (receipts.length > maxRecords) receipts.shift()
+  }
+
+  /** @param {{events?: unknown, batchId?: string, taskId?: string}} [params] */
+  function publish(params = {}) {
+    const validated = validateRelayEvents(params?.events, limits)
+    if (validated.ok === false) {
+      const error = new Error(validated.errors.join(', ') || 'relay-events-invalid')
+      error.code = 'relay-events-invalid'
+      error.retryable = false
+      throw error
+    }
+    counters.batches += 1
+    const acceptedIds = []
+    let duplicates = 0
+    for (const event of validated.accepted) {
+      if (seen.has(event.id)) { duplicates += 1; continue }
+      seen.set(event.id, { at: nowMs(now), cursor: cursor + 1 })
+      cursor += 1
+      counters.accepted += 1
+      acceptedIds.push(event.id)
+      remember({ id: event.id, type: event.type, at: event.at, cursor })
+      lastAt = nowMs(now)
+    }
+    counters.duplicates += duplicates
+    for (const item of validated.rejected) {
+      // 批内重复计入 duplicates；其余非法条目计入 rejected 并留原因（有界）。
+      if (item.reason === 'duplicate-in-batch') { duplicates += 1; counters.duplicates += 1; continue }
+      counters.rejected += 1
+      if (lastErrors.length < 50) lastErrors.push({ id: item.id, reason: item.reason })
+    }
+    const batchId = String(params?.batchId ?? `batch-${counters.batches}`)
+    const receipt = Object.freeze({
+      ok: true,
+      batchId,
+      taskId: params?.taskId === undefined ? null : String(params.taskId),
+      accepted: acceptedIds.length,
+      duplicates,
+      rejected: validated.rejected.length - duplicates,
+      cursor,
+      acceptedIds,
+      peer: peerLabel,
+      at: nowMs(now),
+    })
+    if (seen.size > maxRecords * 4) {
+      // 幂等窗口有界：按插入顺序淘汰最老的一半，避免长跑进程无界增长。
+      const overflow = seen.size - maxRecords * 2
+      let removed = 0
+      for (const key of seen.keys()) {
+        if (removed >= overflow) break
+        seen.delete(key)
+        removed += 1
+      }
+    }
+    return receipt
+  }
+
+  function status() {
+    return Object.freeze({
+      ok: true,
+      available: true,
+      peer: peerLabel,
+      role,
+      instanceId,
+      contractVersion: CONTRACT_VERSION,
+      cursor,
+      accepted: counters.accepted,
+      duplicates: counters.duplicates,
+      rejected: counters.rejected,
+      batches: counters.batches,
+      lastAt,
+      limits: { ...limits },
+      lastErrors: [...lastErrors],
+    })
+  }
+
+  function describe() {
+    return Object.freeze({ peerLabel, records: receipts.length, seen: seen.size, ...counters, cursor })
+  }
+
+  return Object.freeze({ publish, status, describe, receipts: () => [...receipts] })
+}
+
+/**
+ * 把回流 store 包成契约 handler 表（挂到 `createContractServer({handlers})`）。
+ * @param {{publish:Function, status:Function}} store
+ */
+export function relayHandlers(store) {
+  if (!store || typeof store.publish !== 'function' || typeof store.status !== 'function') {
+    throw new Error('relayHandlers requires a relay store with publish/status')
+  }
+  return {
+    [METHODS.RELAY_PUBLISH]: (params) => store.publish(params ?? {}),
+    [METHODS.RELAY_STATUS]: () => store.status(),
+  }
+}
+
+/**
+ * 便捷构造：带回流能力的契约服务端（瓮城侧挂载用）。
+ * `peerLabel` 是**自报**标识，房主侧据此记录“对端是谁”，不参与鉴权。
+ */
+export function createRelayContractServer(options = {}) {
+  const { peerLabel = 'contract-server', role = 'mother', instanceId = '', now, limits, maxRecords, extraHandlers = {}, ...rest } = options
+  const store = createRelayStore({ peerLabel, role, instanceId, now, limits, maxRecords })
+  const server = createContractServer({
+    role,
+    instanceId,
+    handlers: { ...relayHandlers(store), ...(extraHandlers && typeof extraHandlers === 'object' ? extraHandlers : {}) },
+    ...rest,
+  })
+  return { server, store }
+}