@twinsearth/w2m-dsh-plugin 3.1.0 → 3.2.2

package/src/interop/contract/PROVENANCE.md

@@ -0,0 +1,26 @@
+# 契约 SDK 副本来源（PROVENANCE）
+
+本目录是 `@twinsearth/dsh-fang-contract@1.1.1` 的**逐字节副本**，来源是 npm 上已发布的包，
+不是对 dsh-fang / dsh-master 仓库的改动。按 w2m 会话守则（`E:/GPT/w2m/AGENTS.md`），
+三个项目相互独立：w2m 只经由发布出来的版本化契约 SDK 互联，不 import 对方内部代码。
+
+- 包名：`@twinsearth/dsh-fang-contract`
+- 版本：`1.1.1`（`CONTRACT_VERSION` 常量与 package.json 一致）
+- 来源：npm registry，`npm pack @twinsearth/dsh-fang-contract@1.1.1`
+- 许可证：AGPL-3.0-or-later（见本目录 `LICENSE`）
+- 语义不改：w2m 自己的方法放进 `w2m.*` 命名空间，不改 `fang.*` 任何语义。
+
+| 文件 | 字节 | sha256 |
+|---|---|---|
+| LICENSE | 34523 | 0d96a4ff68ad6d4b6f1f30f713b18d5184912ba8dd389f86aa7710db079abcb0 |
+| client.js | 4021 | b1c48a56c64e7058f40a6f1e3239f9e81619381c121fc3d2e1f5418b6e8c6b26 |
+| constants.js | 3404 | 6ce1d813a6a61cfc991c4888f813e7baeff828802ba03f375c6b49e6b0329979 |
+| envelope.js | 3164 | 68e8725a4b7d5c01e49b1364a201121278d3d45dac6e99dc0ee53f98232d380a |
+| index.js | 780 | 67b5d687d4f8c47fd4d573fe5540362014ed0617e7df3533936e613a439b655c |
+| negotiate.js | 3993 | 8a699b287b740a7d478c40981c0ae7915a6522ff856f3bc0b19f0cc077587c43 |
+| relay.js | 9499 | 9f7150aaa026ea4ca629b749a2bc691579b72836af053e05228070a009f5b5b2 |
+| server.js | 3255 | 5e7c884639fc365833f6fdca91f276c34db2b1d1a6938790c7e9b71c127e6c17 |
+| transports.js | 16872 | 6712aabbe702ae559ff50027a3469c0ce031092e6b0a61fec51cfe80b69d0a6c |
+
+升级流程：`npm pack` 取新版本 → 覆盖本目录 → 重跑生成脚本更新上表 →
+`node scripts/check-contract-vendor.mjs`（本仓库的 pre-flight 会跑它）。

package/src/interop/contract/client.js

@@ -0,0 +1,93 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+// Copyright (c) 2026 dsh-Fang/dsh-Master contributors — see LICENSE.
+
+import { DEFAULT_TRANSPORT_ORDER, METHODS } from './constants.js'
+import {
+  createFileTransport,
+  createHttpTransport,
+  createLegacyTransport,
+  createLocalTransport,
+  createTransportRouter,
+} from './transports.js'
+
+/**
+ * 客户端门面：一次配置，按 local → http → file → legacy 自动降级。
+ *
+ * @param {{
+ *  ctx?: object,
+ *  config?: {httpBaseUrl?:string, httpToken?:string, fileDir?:string, order?:string[], timeoutMs?:number},
+ *  fetchImpl?: typeof fetch,
+ *  logger?: object,
+ *  instanceId?: string,
+ * }} options
+ */
+export function createContractClient(options = {}) {
+  const { ctx = null, config = {}, fetchImpl = fetch, logger = null, instanceId = 'contract-client' } = options
+  const transports = []
+  if (ctx) transports.push(createLocalTransport({ ctx }))
+  if (config.httpBaseUrl) transports.push(createHttpTransport({
+    baseUrl: config.httpBaseUrl,
+    token: config.httpToken,
+    headers: config.httpHeaders,
+    fetchImpl,
+    timeoutMs: config.timeoutMs,
+    pathPrefix: config.pathPrefix,
+  }))
+  if (config.fileDir) transports.push(createFileTransport({
+    dir: config.fileDir,
+    pollMs: config.filePollMs,
+    timeoutMs: config.fileTimeoutMs,
+  }))
+  if (ctx) transports.push(createLegacyTransport({ ctx }))
+
+  const order = Array.isArray(config.order) && config.order.length > 0 ? config.order : DEFAULT_TRANSPORT_ORDER
+  const router = createTransportRouter({
+    transports,
+    order,
+    localHello: null,
+    logger,
+  })
+  let lastHello = null
+  let helloPromise = null
+
+  const client = {
+    instanceId,
+    transports: () => router.transports(),
+    describe: () => ({
+      instanceId,
+      routes: router.describe(),
+      hello: lastHello,
+    }),
+    attempts: () => router.attempts(),
+    async hello(force = false) {
+      if (!force && lastHello) return lastHello
+      if (!force && helloPromise) return helloPromise
+      helloPromise = (async () => {
+        const result = await router.hello()
+        lastHello = result
+        return result
+      })().finally(() => { helloPromise = null })
+      return helloPromise
+    },
+    async invoke(method, params, invokeOptions = {}) {
+      const result = await router.invoke(method, params, { timeoutMs: config.timeoutMs, ...invokeOptions })
+      return result
+    },
+    async health() { return await client.invoke(METHODS.HEALTH, null) },
+    async spawnFork(params, invokeOptions = {}) { return await client.invoke(METHODS.FORK_SPAWN, params, invokeOptions) },
+    async stopFork(params, invokeOptions = {}) { return await client.invoke(METHODS.FORK_STOP, params, invokeOptions) },
+    async listForks(params = {}, invokeOptions = {}) { return await client.invoke(METHODS.FORK_LIST, params, invokeOptions) },
+    async createDecision(params, invokeOptions = {}) { return await client.invoke(METHODS.DECISION_CREATE, params, invokeOptions) },
+    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/interop/contract/constants.js

@@ -0,0 +1,94 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+// Copyright (c) 2026 dsh-Fang/dsh-Master contributors — see LICENSE.
+
+/**
+ * 契约常量与兼容规则（contract SDK 1.x）。
+ *
+ * 稳定承诺：
+ *   * MAJOR 相同的版本保证“旧字段可读、旧方法可调、未知字段忽略”；
+ *   * 新增能力只通过 METHODS/CAPABILITIES 扩展，不改变既有方法语义；
+ *   * 删除/改义必须升 MAJOR，并保留至少一个 MINOR 周期的双写（method@1 与 method@2）。
+ */
+
+export const CONTRACT_PACKAGE = '@twinsearth/dsh-fang-contract'
+export const CONTRACT_VERSION = '1.1.1'
+export const PROTOCOL = 'fang-master'
+export const PROTOCOL_VERSION = 1
+export const MIN_COMPATIBLE_MAJOR = 1
+
+/** 稳定方法名（新方法只能追加）。 */
+export const METHODS = Object.freeze({
+  HELLO: 'contract.hello',
+  HEALTH: 'contract.health',
+  FORK_SPAWN: 'fang.fork.spawn',
+  FORK_STOP: 'fang.fork.stop',
+  FORK_LIST: 'fang.fork.list',
+  DECISION_CREATE: 'fang.decision.create',
+  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',
+})
+
+/** 方法 → 契约版本（用于协商后的方法裁剪）。 */
+export const METHOD_VERSION = Object.freeze({
+  [METHODS.HELLO]: '1.0',
+  [METHODS.HEALTH]: '1.0',
+  [METHODS.FORK_SPAWN]: '1.0',
+  [METHODS.FORK_STOP]: '1.0',
+  [METHODS.FORK_LIST]: '1.0',
+  [METHODS.DECISION_CREATE]: '1.0',
+  [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', 'event-relay',
+])
+
+export const ROLES = Object.freeze(['mother', 'essence', 'fork'])
+
+export const ERROR_CODES = Object.freeze({
+  INVALID_ENVELOPE: 'invalid-envelope',
+  UNSUPPORTED_METHOD: 'unsupported-method',
+  UNSUPPORTED_VERSION: 'unsupported-version',
+  INCOMPATIBLE: 'contract-incompatible',
+  TRANSPORT_UNAVAILABLE: 'transport-unavailable',
+  TRANSPORT_TIMEOUT: 'transport-timeout',
+  TRANSPORT_HTTP_ERROR: 'transport-http-error',
+  REMOTE_ERROR: 'remote-error',
+  ALL_TRANSPORTS_FAILED: 'all-transports-failed',
+  HANDLER_THREW: 'handler-threw',
+})
+
+/**
+ * 兜底顺序（从快到慢）：
+ *   local  —— 同一 Host 的 DSH 服务（零网络、首选）
+ *   http   —— 母体/原身 HTTP 契约端点
+ *   file   —— 同一文件系统的 outbox/inbox（HTTP 不可用/被防火墙拦）
+ *   legacy —— 直接调用 3.1.x 的旧 DSH 服务键（接口包被替换/新端点不存在时）
+ */
+export const DEFAULT_TRANSPORT_ORDER = Object.freeze(['local', 'http', 'file', 'legacy'])
+
+/** 3.1.x 及更早的旧服务键（只读兼容；不新增语义）。 */
+export const LEGACY_SERVICE_KEYS = Object.freeze({
+  forker: 'fangForker',
+  decisionCenter: 'fangDecisionCenter',
+  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/interop/contract/envelope.js

@@ -0,0 +1,83 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+// Copyright (c) 2026 dsh-Fang/dsh-Master contributors — see LICENSE.
+
+import crypto from 'node:crypto'
+
+import { ERROR_CODES, PROTOCOL, PROTOCOL_VERSION } from './constants.js'
+
+export function newId(prefix = 'msg') {
+  return `${prefix}_${crypto.randomUUID()}`
+}
+
+/** 创建请求信封；未知字段由接收方忽略（兼容规则）。 */
+export function createEnvelope({ method, params = null, id, source = '', instanceId = '', timeoutMs = 30_000, meta = {} } = {}) {
+  if (!method || typeof method !== 'string') throw new Error('method is required')
+  return {
+    protocol: PROTOCOL,
+    protocolVersion: PROTOCOL_VERSION,
+    id: String(id ?? newId('req')),
+    method: String(method),
+    params: params ?? null,
+    meta: {
+      at: Date.now(),
+      deadline: Date.now() + Math.max(1, Number(timeoutMs) || 30_000),
+      source: String(source ?? ''),
+      instanceId: String(instanceId ?? ''),
+      ...(meta && typeof meta === 'object' ? meta : {}),
+    },
+  }
+}
+
+/** 校验请求/响应信封；返回 {ok, errors, envelope}。 */
+export function validateEnvelope(value, { response = false } = {}) {
+  const errors = []
+  const raw = value && typeof value === 'object' ? value : {}
+  if (raw.protocol !== PROTOCOL) errors.push(`protocol-invalid:${String(raw.protocol)}`)
+  if (raw.protocolVersion !== PROTOCOL_VERSION) errors.push(`protocol-version-invalid:${String(raw.protocolVersion)}`)
+  if (!raw.id) errors.push('id-required')
+  if (response) {
+    if (typeof raw.ok !== 'boolean') errors.push('ok-required')
+    if (raw.ok === false && !raw.error?.code) errors.push('error-code-required')
+  } else if (!raw.method) {
+    errors.push('method-required')
+  }
+  return { ok: errors.length === 0, errors, envelope: raw }
+}
+
+export function createResponse({ id, result, error, meta = {} } = {}) {
+  const base = {
+    protocol: PROTOCOL,
+    protocolVersion: PROTOCOL_VERSION,
+    id: String(id ?? newId('res')),
+    ok: !error,
+    meta: { at: Date.now(), ...(meta && typeof meta === 'object' ? meta : {}) },
+  }
+  if (error) return { ...base, error: normalizeError(error) }
+  return { ...base, result: result ?? null }
+}
+
+export function normalizeError(error, fallbackCode = ERROR_CODES.REMOTE_ERROR) {
+  if (!error) return { code: fallbackCode, message: String(fallbackCode), retryable: false }
+  if (typeof error === 'string') return { code: fallbackCode, message: error, retryable: false }
+  return {
+    code: String(error.code ?? fallbackCode),
+    message: String(error.message ?? error.error ?? fallbackCode),
+    retryable: error.retryable === true,
+    ...(error.detail === undefined ? {} : { detail: error.detail }),
+  }
+}
+
+export class ContractTransportError extends Error {
+  constructor(code, message, { transport = '', detail = null, retryable = false } = {}) {
+    super(String(message ?? code))
+    this.name = 'ContractTransportError'
+    this.code = String(code)
+    this.transport = String(transport)
+    this.detail = detail
+    this.retryable = retryable === true
+  }
+}
+
+export function isCompatibleResponse(value) {
+  return validateEnvelope(value, { response: true }).ok
+}

package/src/interop/contract/index.js

@@ -0,0 +1,20 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+// Copyright (c) 2026 dsh-Fang/dsh-Master contributors — see LICENSE.
+
+/**
+ * @twinsearth/dsh-fang-contract
+ *
+ * 瓮城（dsh-Fang）↔ 房主（dsh-Master）的独立版本化互联 SDK。
+ * 设计目标：
+ *   1. 双方独立升级：语义化版本 + hello 协商 + 未知字段忽略 + 方法版本裁剪；
+ *   2. 互联互通保底：local → http → file → legacy 四级传输自动降级；
+ *   3. 接口包可独立替换：更新本包即升级接口架构，旧方法在 MAJOR 内保持可调用。
+ */
+
+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/interop/contract/negotiate.js

@@ -0,0 +1,106 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+// Copyright (c) 2026 dsh-Fang/dsh-Master contributors — see LICENSE.
+
+import {
+  CAPABILITIES,
+  CONTRACT_VERSION,
+  ERROR_CODES,
+  METHOD_VERSION,
+  METHODS,
+  MIN_COMPATIBLE_MAJOR,
+  PROTOCOL,
+  ROLES,
+} from './constants.js'
+
+export function parseVersion(value) {
+  const text = String(value ?? '').trim()
+  const match = /^(\d+)\.(\d+)(?:\.(\d+))?/.exec(text)
+  if (!match) return null
+  return {
+    major: Number(match[1]), minor: Number(match[2]), patch: Number(match[3] ?? 0), text,
+  }
+}
+
+export function compareVersions(a, b) {
+  const pa = parseVersion(a)
+  const pb = parseVersion(b)
+  if (!pa || !pb) return 0
+  if (pa.major !== pb.major) return pa.major - pb.major
+  if (pa.minor !== pb.minor) return pa.minor - pb.minor
+  return pa.patch - pb.patch
+}
+
+/** 标准 hello payload（服务端暴露；客户端据此协商）。 */
+export function helloPayload({
+  role = 'mother',
+  instanceId = '',
+  version = CONTRACT_VERSION,
+  methods = Object.values(METHODS),
+  capabilities = CAPABILITIES,
+  transports = [],
+  startedAt = Date.now(),
+} = {}) {
+  return {
+    protocol: PROTOCOL,
+    contractVersion: String(version),
+    role: ROLES.includes(String(role)) ? String(role) : 'fork',
+    instanceId: String(instanceId ?? ''),
+    startedAt: Number(startedAt) || Date.now(),
+    methods: [...new Set(methods.map(String))],
+    capabilities: [...new Set(capabilities.map(String))],
+    transports: [...new Set(transports.map(String))],
+    features: {
+      idempotency: true,
+      envelopes: true,
+      fileOutbox: true,
+      versionNegotiation: true,
+    },
+  }
+}
+
+/**
+ * 双向版本协商。
+ * @param {object} local 本端 helloPayload
+ * @param {object} remote 对端 helloPayload
+ * @returns {{ok:boolean, compatible:boolean, fallback:'legacy'|null, reason?:string, version?:string, methods:string[], capabilities:string[], features:object}}
+ */
+export function negotiate(local, remote) {
+  const lv = parseVersion(local?.contractVersion)
+  const rv = parseVersion(remote?.contractVersion)
+  if (local?.protocol !== PROTOCOL || remote?.protocol !== PROTOCOL) {
+    return { ok: false, compatible: false, fallback: 'legacy', reason: 'protocol-mismatch', methods: [], capabilities: [], features: {} }
+  }
+  if (!lv || !rv) {
+    return { ok: false, compatible: false, fallback: 'legacy', reason: 'version-invalid', methods: [], capabilities: [], features: {} }
+  }
+  if (rv.major < MIN_COMPATIBLE_MAJOR) {
+    return { ok: false, compatible: false, fallback: 'legacy', reason: 'remote-too-old', methods: [], capabilities: [], features: {} }
+  }
+  if (rv.major > lv.major) {
+    return { ok: false, compatible: false, fallback: 'legacy', reason: 'remote-too-new', methods: [], capabilities: [], features: {} }
+  }
+  const localMethods = new Set(Array.isArray(local.methods) ? local.methods : [])
+  const methods = (Array.isArray(remote.methods) ? remote.methods : []).filter((method) => localMethods.has(method))
+  // 裁剪：方法所需契约 minor 不能高于双方共同支持的 minor。
+  const commonMinor = Math.min(lv.minor, rv.minor)
+  const supported = methods.filter((method) => {
+    const methodVersion = parseVersion(METHOD_VERSION[method] ?? '1.0')
+    return !methodVersion || methodVersion.minor <= commonMinor || methodVersion.major < lv.major
+  })
+  const localCaps = new Set(Array.isArray(local.capabilities) ? local.capabilities : [])
+  const capabilities = (Array.isArray(remote.capabilities) ? remote.capabilities : []).filter((cap) => localCaps.has(cap))
+  const version = `${Math.min(lv.major, rv.major)}.${commonMinor}.0`
+  return {
+    ok: true,
+    compatible: true,
+    fallback: null,
+    version,
+    methods: supported,
+    capabilities,
+    features: { ...(local.features ?? {}), ...(remote.features ?? {}) },
+  }
+}
+
+export function unsupportedMethodError(method) {
+  return { code: ERROR_CODES.UNSUPPORTED_METHOD, message: `unsupported method: ${String(method)}`, retryable: false }
+}

package/src/interop/contract/relay.js

@@ -0,0 +1,229 @@
+// 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 alreadySeen = 0
+    let inBatchDuplicates = 0
+    let rejectedCount = 0
+    for (const event of validated.accepted) {
+      if (seen.has(event.id)) { alreadySeen += 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)
+    }
+    for (const item of validated.rejected) {
+      // 批内重复计入 duplicates；其余非法条目计入 rejected 并留原因（有界）。
+      if (item.reason === 'duplicate-in-batch') { inBatchDuplicates += 1; continue }
+      rejectedCount += 1
+      if (lastErrors.length < 50) lastErrors.push({ id: item.id, reason: item.reason })
+    }
+    // 两个计数分开累计：duplicates = 已存在 + 批内重复；rejected 只数真正非法的条目。
+    // （1.1.0 曾用 `validated.rejected.length - duplicates` 计算 rejected，重投时会得到负数。）
+    const duplicates = alreadySeen + inBatchDuplicates
+    counters.duplicates += duplicates
+    counters.rejected += rejectedCount
+    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: rejectedCount,
+      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 }
+}