@twinsearth/dsh-master 3.3.0 → 3.3.2

package/src/cost/fang-relay.ts

@@ -0,0 +1,318 @@
+// 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.1 · 瓮城回流出口（设计 §5.6，里程碑 M5）。
+ *
+ * 3.3.0 里这条通道是硬编码的 `{ target:'fang', available:false,
+ * reason:'fang-channel-not-ready' }`：接口位在，但没有实现。3.3.1 把它换成
+ * **真实探测 + 真实投递**：
+ *
+ *   1. `probe()`：用契约 SDK 的 `hello()` 协商，看对端在公共 minor 下是否宣告
+ *      `fang.relay.publish` / `fang.relay.status`（contract 1.1 才有的方法）；
+ *      宣告了再读一次 `fang.relay.status` 确认对端**真的在服务**，不是只挂方法名。
+ *   2. `enqueue()` / `flush()`：把 `cost:event` / `cost:degraded` /
+ *      `cost:substitution` 批量投递，按事件 id 幂等，回执里的 `accepted` /
+ *      `duplicates` / `cursor` 才是“送达”的唯一证据。
+ *   3. `status()`：同步返回**最近一次已知状态**（`probe()` 异步更新）。
+ *
+ * 两条硬约束（与 I1–I8 一致）：
+ *   * 不可用必须显式 `available:false` + 具体原因，**不得**把队列长度当送达；
+ *   * 投递失败不重试成“假成功”：批次退回队列、`failed` 计数、状态转不可用，
+ *     并保留 `lastError`。
+ *
+ * 对端身份（`peer`）由对端在 `fang.relay.status` 里**自报**（如
+ * `dsh-fang-bundle` / `contract-server`），只用于记录“对端是谁”，不参与鉴权，
+ * 也不得被当成“已对接真实瓮城”的证据 —— 那需要 `peer === 'dsh-fang-bundle'`。
+ */
+
+import path from 'node:path'
+
+import { METHODS, createContractClient } from '../contract/index.js'
+
+/** 允许作为 M5 证据的对端标识（自报值白名单）。 */
+export const RELAY_PEERS = Object.freeze(['dsh-fang-bundle', 'contract-server'])
+
+/** 默认值：批量/队列/探测都有界，避免长跑进程无界增长。 */
+export const RELAY_DEFAULTS = Object.freeze({
+  maxBatch: 32,
+  maxQueue: 500,
+  probeTtlMs: 60_000,
+  timeoutMs: 15_000,
+})
+
+function asString(value) { return String(value ?? '').trim() }
+
+function clampInt(value, fallback, min, max) {
+  const n = Number(value)
+  if (!Number.isFinite(n)) return fallback
+  return Math.min(max, Math.max(min, Math.floor(n)))
+}
+
+function describeError(error) {
+  const code = asString(error?.code) || 'relay-error'
+  const message = asString(error?.message ?? error)
+  return message ? `${code}:${message.slice(0, 160)}` : code
+}
+
+/**
+ * 创建回流出口。
+ *
+ * @param {{
+ *   client?: object | null,          // createContractClient() 的返回值；null ⇒ 明确不可用
+ *   target?: string,
+ *   now?: () => number,
+ *   maxBatch?: number, maxQueue?: number, probeTtlMs?: number, timeoutMs?: number,
+ *   logger?: object,
+ * }} [options]
+ */
+export function createFangRelay(options = {}) {
+  const client = options.client && typeof options.client === 'object' ? options.client : null
+  const target = asString(options.target) || 'fang'
+  const now = typeof options.now === 'function' ? options.now : () => Date.now()
+  const maxBatch = clampInt(options.maxBatch, RELAY_DEFAULTS.maxBatch, 1, 128)
+  const maxQueue = clampInt(options.maxQueue, RELAY_DEFAULTS.maxQueue, 1, 5_000)
+  const probeTtlMs = clampInt(options.probeTtlMs, RELAY_DEFAULTS.probeTtlMs, 1_000, 600_000)
+  const timeoutMs = clampInt(options.timeoutMs, RELAY_DEFAULTS.timeoutMs, 1_000, 300_000)
+  const logger = options.logger ?? null
+
+  const queue = []
+  const counters = { enqueued: 0, delivered: 0, duplicates: 0, failed: 0, dropped: 0, batches: 0, roundTrips: 0 }
+  let sequence = 0
+  let batchSequence = 0
+  let cursor = null
+  let lastError = null
+  let lastDeliveredAt = 0
+  let probing = null
+  // 没有客户端时开局即知不可用（不需要“探测中”这种灰色状态去掩盖）。
+  let state = Object.freeze({
+    available: false,
+    reason: client ? 'probe-pending' : 'relay-client-absent',
+    peer: null,
+    peerContractVersion: null,
+    transport: null,
+    probedAt: 0,
+  })
+
+  function setState(next) {
+    state = Object.freeze({ ...state, probedAt: now(), ...next })
+  }
+
+  function status() {
+    return Object.freeze({
+      target,
+      available: state.available === true,
+      reason: state.reason ?? null,
+      peer: state.peer ?? null,
+      peerContractVersion: state.peerContractVersion ?? null,
+      transport: state.transport ?? null,
+      delivered: counters.delivered,
+      failed: counters.failed,
+      queued: queue.length,
+      dropped: counters.dropped,
+      duplicates: counters.duplicates,
+      batches: counters.batches,
+      cursor,
+      lastError,
+      lastDeliveredAt,
+      probedAt: state.probedAt,
+      limits: { maxBatch, maxQueue, probeTtlMs, timeoutMs },
+    })
+  }
+
+  /** 探测对端：hello 协商 → 方法裁剪判定 → 读一次 relay 状态确认真的可用。 */
+  async function probe({ force = false } = {}) {
+    if (!client) {
+      setState({ available: false, reason: 'relay-client-absent', peer: null })
+      return status()
+    }
+    if (!force && state.probedAt > 0 && now() - state.probedAt < probeTtlMs) return status()
+    if (probing) return probing
+    probing = (async () => {
+      try {
+        const hello = await client.hello(true)
+        if (!hello || hello.ok !== true) {
+          setState({ available: false, reason: `hello-failed:${asString(hello?.code) || 'unknown'}`, peer: null })
+          return status()
+        }
+        const methods = Array.isArray(hello.negotiation?.methods) ? hello.negotiation.methods : []
+        const peerContractVersion = asString(hello.hello?.contractVersion) || null
+        const offersRelay = methods.includes(METHODS.RELAY_PUBLISH) && methods.includes(METHODS.RELAY_STATUS)
+        if (!offersRelay) {
+          // 1.0 对端不会宣告 1.1 方法；这是“协议层没有回流”，不是传输故障。
+          setState({
+            available: false,
+            reason: `peer-contract-without-relay:${peerContractVersion ?? 'unknown'}`,
+            peer: null,
+            peerContractVersion,
+            transport: asString(hello.transport) || null,
+          })
+          return status()
+        }
+        const remote = await client.relayStatus({}, { timeoutMs })
+        if (!remote || remote.ok !== true) {
+          setState({
+            available: false,
+            reason: `relay-status-failed:${asString(remote?.code) || 'unknown'}`,
+            peer: null,
+            peerContractVersion,
+            transport: asString(hello.transport) || null,
+          })
+          return status()
+        }
+        const result = remote.response?.result ?? {}
+        cursor = Number.isFinite(Number(result.cursor)) ? Number(result.cursor) : cursor
+        setState({
+          available: true,
+          reason: null,
+          peer: asString(result.peer) || null,
+          peerContractVersion: asString(result.contractVersion) || peerContractVersion,
+          transport: asString(remote.transport ?? hello.transport) || null,
+        })
+        return status()
+      } catch (error) {
+        setState({ available: false, reason: `probe-threw:${describeError(error)}`, peer: null })
+        try { logger?.warn?.(`[cost-relay] probe failed: ${describeError(error)}`) } catch { /* ignore */ }
+        return status()
+      }
+    })()
+    try { return await probing } finally { probing = null }
+  }
+
+  /** 入队一条总线事件；不可用时不假装收下（记 dropped 并返回原因）。 */
+  function enqueue(event = {}) {
+    if (state.available !== true) {
+      counters.dropped += 1
+      return { ok: false, code: 'relay-unavailable', reason: state.reason ?? 'unknown' }
+    }
+    const type = asString(event.type) || 'cost:event'
+    sequence += 1
+    const item = Object.freeze({
+      // id 稳定且唯一：重投同一批时对端按 id 去重，不会重复记账。
+      id: `cost-${type}-${sequence}-${Math.max(0, Math.floor(Number(event.at ?? now()) || 0))}`,
+      type,
+      at: Math.max(0, Math.floor(Number(event.at ?? now()) || 0)),
+      payload: event.payload && typeof event.payload === 'object' ? { ...event.payload } : {},
+    })
+    if (queue.length >= maxQueue) {
+      queue.shift()
+      counters.dropped += 1
+    }
+    queue.push(item)
+    counters.enqueued += 1
+    return { ok: true, id: item.id, queued: queue.length }
+  }
+
+  /** 投递一个批次；失败时批次退回队列并把状态转不可用（不吞错）。 */
+  async function flush() {
+    if (!client) return { ok: false, code: 'relay-client-absent', ...status() }
+    if (state.available !== true) return { ok: false, code: 'relay-unavailable', reason: state.reason ?? 'unknown', ...status() }
+    if (queue.length === 0) return { ok: true, delivered: 0, sent: 0, queued: 0 }
+    const batch = queue.slice(0, maxBatch)
+    batchSequence += 1
+    const batchId = `relay-${batchSequence}`
+    let outcome = null
+    try {
+      outcome = await client.publishRelay({ batchId, events: batch }, { timeoutMs })
+    } catch (error) {
+      outcome = { ok: false, code: 'relay-threw', error: describeError(error) }
+    }
+    counters.roundTrips += 1
+    if (outcome && outcome.ok === true) {
+      const result = outcome.response?.result ?? {}
+      const accepted = Math.max(0, Number(result.accepted ?? 0) || 0)
+      const duplicates = Math.max(0, Number(result.duplicates ?? 0) || 0)
+      // 只有对端回执才算送达：从队列头移除本次实际发送的批次。
+      queue.splice(0, batch.length)
+      counters.batches += 1
+      counters.delivered += accepted + duplicates
+      counters.duplicates += duplicates
+      if (Number.isFinite(Number(result.cursor))) cursor = Number(result.cursor)
+      lastDeliveredAt = now()
+      lastError = null
+      return { ok: true, delivered: accepted, duplicates, sent: batch.length, queued: queue.length, cursor, batchId }
+    }
+    const code = asString(outcome?.code) || 'publish-failed'
+    const detail = asString(outcome?.failures?.[0]?.code) || asString(outcome?.error)
+    lastError = detail && !detail.startsWith(code) ? `${code}:${detail}`.slice(0, 200) : (detail || code)
+    counters.failed += batch.length
+    setState({ available: false, reason: `publish-failed:${lastError}` })
+    try { logger?.warn?.(`[cost-relay] publish failed: ${lastError}`) } catch { /* ignore */ }
+    return { ok: false, code, error: lastError, sent: batch.length, queued: queue.length }
+  }
+
+  /** 挂到事件总线上：订阅者异常与投递异常都不影响主流程。 */
+  function attach(bus) {
+    if (!bus || typeof bus.subscribe !== 'function') return () => {}
+    return bus.subscribe((event) => {
+      try { enqueue(event) } catch { /* 回流不得影响主流程 */ }
+    })
+  }
+
+  function reset() {
+    queue.length = 0
+    lastError = null
+    setState({ available: false, reason: 'probe-pending', peer: null })
+    return status()
+  }
+
+  return Object.freeze({ target, probe, enqueue, flush, attach, status, reset, describe: status })
+}
+
+/**
+ * 从插件配置/环境装配契约客户端。
+ *
+ * 未配置任何传输时返回 null（**不**创建空客户端去假装探测过）。
+ *
+ * @param {object} ctx
+ * @param {{relay?: object, dispatch?: object}} [config]
+ * @param {{fetchImpl?: typeof fetch, env?: object}} [options]
+ */
+export function createRelayClient(ctx, config = {}, options = {}) {
+  const raw = config.relay && typeof config.relay === 'object' ? config.relay : {}
+  const dispatch = config.dispatch && typeof config.dispatch === 'object' ? config.dispatch : {}
+  const env = options.env ?? process.env
+  const fetchImpl = options.fetchImpl ?? fetch
+  const httpBaseUrl = asString(raw.httpBaseUrl) || asString(dispatch.motherUrl) || asString(env.DSH_FANG_CONTRACT_URL) || asString(env.DSH_MASTER_MOTHER_URL)
+  const httpToken = asString(raw.httpToken) || asString(dispatch.motherToken) || asString(env.DSH_FANG_CONTRACT_TOKEN)
+  const motherDataDir = asString(env.DSH_FANG_MOTHER)
+  const fileDir = asString(raw.fileDir) || asString(dispatch.contractFileDir) || (motherDataDir ? path.join(motherDataDir, 'contract-outbox') : '')
+  const localService = (() => {
+    try { return ctx && typeof ctx.get === 'function' ? ctx.get('fangContract') : null } catch { return null }
+  })()
+  const enabled = raw.enabled === true || Boolean(httpBaseUrl) || Boolean(fileDir) || Boolean(localService)
+  if (!enabled) return null
+  if (raw.enabled === false) return null
+  return createContractClient({
+    ctx,
+    config: {
+      httpBaseUrl,
+      httpToken,
+      httpHeaders: raw.httpHeaders && typeof raw.httpHeaders === 'object' ? raw.httpHeaders : undefined,
+      fileDir,
+      timeoutMs: clampInt(raw.timeoutMs, RELAY_DEFAULTS.timeoutMs, 1_000, 300_000),
+      fileTimeoutMs: clampInt(raw.fileTimeoutMs, 30_000, 1_000, 300_000),
+      order: Array.isArray(raw.order) ? raw.order : undefined,
+    },
+    fetchImpl,
+  })
+}
+
+/**
+ * 一次性装配：配置 → 客户端 → 出口。返回的 `client` 为 null 表示没有任何
+ * 可用传输（此时出口状态是 `relay-client-absent`，不是“探测中”）。
+ */
+export function createFangRelayFromContext(ctx, config = {}, options = {}) {
+  const client = createRelayClient(ctx, config, options)
+  const relay = createFangRelay({
+    client,
+    now: options.now,
+    maxBatch: config.relay?.maxBatch,
+    maxQueue: config.relay?.maxQueue,
+    probeTtlMs: config.relay?.probeTtlMs,
+    timeoutMs: config.relay?.timeoutMs,
+    logger: options.logger,
+  })
+  return { client, relay }
+}

package/src/cost/index.ts

@@ -17,6 +17,7 @@ import { createAuditChain } from './audit.ts'
 import { createAttribution } from './attribution.ts'
 import { createCostBus } from './bus.ts'
 import { createHostSurfaceAdapter } from './host-surface.ts'
+import { createFangRelay } from './fang-relay.ts'
 import { buildSavingsReport, classifyEntry } from './report.ts'
 import { buildMetricsReport, METRIC_KEYS, SUCCESS_REGRESSION_PP } from './metrics.ts'
 import { MODULE_MANIFESTS, MODULE_IDS, validateManifests } from './modules/manifests.ts'
@@ -24,8 +25,9 @@ import { buildLedgerReport, formatLedgerReport, parseLedgerJsonl } from './ledge
 import { buildToolFaceReport, planToolFace } from './toolface.ts'
 import { buildReuseReport, formatReuseReport } from './reuse-report.ts'
 
-export { createLedger, createBudget, createPolicy, createAuditChain, createAttribution, createCostBus, createHostSurfaceAdapter, buildSavingsReport, classifyEntry, buildMetricsReport, METRIC_KEYS, SUCCESS_REGRESSION_PP, MODULE_MANIFESTS, MODULE_IDS, validateManifests, buildLedgerReport, formatLedgerReport, parseLedgerJsonl, buildToolFaceReport, planToolFace, buildReuseReport, formatReuseReport }
+export { createLedger, createBudget, createPolicy, createAuditChain, createAttribution, createCostBus, createHostSurfaceAdapter, createFangRelay, buildSavingsReport, classifyEntry, buildMetricsReport, METRIC_KEYS, SUCCESS_REGRESSION_PP, MODULE_MANIFESTS, MODULE_IDS, validateManifests, buildLedgerReport, formatLedgerReport, parseLedgerJsonl, buildToolFaceReport, planToolFace, buildReuseReport, formatReuseReport }
 export * from './types.ts'
+export { RELAY_PEERS, RELAY_DEFAULTS, createFangRelayFromContext, createRelayClient } from './fang-relay.ts'
 
 /**
  * @param {{
@@ -34,6 +36,7 @@ export * from './types.ts'
  *   budgetLimits?: Array<{unit:string, limitTokens?:number, limitCost?:number, onExhaust?:string, degradeTo?:string}>,
  *   degradeModels?: string[],
  *   now?: () => number, maxEntries?: number, maxRecords?: number,
+ *   relay?: object, relayClient?: object|null, relayOptions?: object, relayAutoAttach?: boolean,
  * }} [options]
  */
 export function createCostSystem(options = {}) {
@@ -50,6 +53,18 @@ export function createCostSystem(options = {}) {
   })
   const attribution = createAttribution({ ledger, now })
   const bus = createCostBus({ now, maxEvents: options.maxBusEvents, relays: options.relays })
+  /**
+   * §5.6 / M5：瓮城回流出口。
+   * 传入 `relay`（已有适配器）则复用；否则用 `relayClient` 现造一个。
+   * 没有客户端时出口状态是 `relay-client-absent` —— 显式不可用，不是“探测中”。
+   */
+  const relay = options.relay && typeof options.relay.status === 'function'
+    ? options.relay
+    : createFangRelay({ client: options.relayClient ?? null, now, ...(options.relayOptions && typeof options.relayOptions === 'object' ? options.relayOptions : {}), logger: options.logger })
+  // 默认把出口挂到总线；测试可关掉自动挂载，手动投递。
+  if (options.relayAutoAttach !== false && typeof relay.attach === 'function') {
+    try { relay.attach(bus) } catch { /* 回流挂载失败不影响记账 */ }
+  }
   /** 宿主会话工具面适配器（可选；默认关闭，不依赖任何第三方插件）。 */
   const hostSurface = createHostSurfaceAdapter({
     ledger,
@@ -270,6 +285,21 @@ export function createCostSystem(options = {}) {
     return bus.subscribe(listener)
   }
 
+  /** §5.6：探测回流对端（hello 协商 + relay 状态），结果并入 `status().relay`。 */
+  async function relayProbe(input = {}) {
+    return await relay.probe({ force: input.force === true })
+  }
+
+  /** §5.6：投递当前队列里的回流事件；返回回执摘要（不吞错，不谎报送达）。 */
+  async function relayFlush() {
+    if (typeof relay.flush !== 'function') return { ok: false, code: 'relay-flush-unsupported' }
+    return await relay.flush()
+  }
+
+  function relayStatus() {
+    return relay.status()
+  }
+
   function status() {
     const ledgerSnapshot = ledger.snapshot()
     const auditVerify = audit.verify()
@@ -293,6 +323,8 @@ export function createCostSystem(options = {}) {
         unattributedProjectedTotal: attributionSnapshot.unattributedProjectedTotal,
       },
       bus: { count: busSnapshot.count, dropped: busSnapshot.dropped, subscribers: busSnapshot.subscribers, relays: busSnapshot.relays },
+      /** §5.6 / M5：瓮城回流出口的真实状态（可达则 available:true + 对端自报 peer）。 */
+      relay: relay.status(),
       degraded: {
         modules: [...degradedByModule.values()].map((item) => ({ ...item, phases: { ...item.phases } })),
         occurrences: [...degradedByModule.values()].reduce((sum, item) => sum + item.occurrences, 0),
@@ -312,5 +344,5 @@ export function createCostSystem(options = {}) {
     })
   }
 
-  return Object.freeze({ ledger, budget, policy, audit, attribution, bus, hostSurface, recordUsage, authorize, attribute, attributeTotal, substitute, trace, degraded, query, replay, savingsReport, metrics, ledgerReport, subscribe, status })
+  return Object.freeze({ ledger, budget, policy, audit, attribution, bus, hostSurface, relay, recordUsage, authorize, attribute, attributeTotal, substitute, trace, degraded, query, replay, savingsReport, metrics, ledgerReport, subscribe, status, relayProbe, relayFlush, relayStatus })
 }

package/src/cost/milestones.ts

@@ -28,6 +28,13 @@ export const M3_MIN_SAMPLES = 20
 /** M4 放行前要求的最小守卫准确率（与 ENFORCE_GATE.minAccuracy 一致）。 */
 export const M3_MIN_ACCURACY = 0.98
 
+/**
+ * M5 回流放行条件：至少 3 条事件拿到对端回执，且对端自报身份在白名单内。
+ * 自环（同一进程里服务端+客户端）与未知 peer 一律不算达标。
+ */
+export const M5_MIN_RELAY_EVENTS = 3
+export const M5_RELAY_PEERS = Object.freeze(['dsh-fang-bundle', 'contract-server'])
+
 export const MILESTONES = Object.freeze([
   Object.freeze({
     id: 'M1',
@@ -79,13 +86,16 @@ export const MILESTONES = Object.freeze([
  *   files?: string[],                       // 仓库里实际存在的文件（相对路径）
  *   guard?: {samples?: number, accuracy?: number},   // M3 的守卫准确率数据（来自 shadow 报告）
  *   forkExperiment?: {ok?: boolean},        // M4 的成功率对照（来自 gate 的 G5）
- *   fangRelay?: {available?: boolean},      // 瓮城回流通道（本会话范围内恒为不可用）
+ *   fangRelay?: {available?: boolean, peer?: string, events?: number,
+ *                sameProcess?: boolean, transport?: string, contractVersion?: string,
+ *                reason?: string},          // M5 的回流对端证据（独立进程实测）
  * }} evidence
  */
 export function evaluateMilestones(evidence = {}) {
   const files = new Set(Array.isArray(evidence.files) ? evidence.files : [])
   const rows = []
   const done = new Set()
+  let relayEvidence = null
 
   for (const milestone of MILESTONES) {
     const missingImplementation = milestone.implementation.filter((file) => !files.has(file))
@@ -118,10 +128,30 @@ export function evaluateMilestones(evidence = {}) {
         if (evidence?.forkExperiment?.ok === true) effect = 'verified'
         else reasons.push('effect-needs-fork-success-comparison')
       } else if (milestone.id === 'M5') {
-        // 面板 + 冻结清单可测；瓮城回流在本会话范围内明确不可用（不伪装）
-        const relayOk = evidence?.fangRelay?.available === true
-        effect = relayOk ? 'verified' : 'unmeasured'
-        if (!relayOk) reasons.push('fang-relay-out-of-scope')
+        // 回流必须有**对端回执**才算达标：可用 + 非自环 + 对端自报身份在白名单 + 至少 3 条事件。
+        const relay = evidence?.fangRelay && typeof evidence.fangRelay === 'object' ? evidence.fangRelay : null
+        const available = relay?.available === true
+        const peer = String(relay?.peer ?? '')
+        const events = Math.max(0, Number(relay?.events ?? 0) || 0)
+        if (!available) {
+          reasons.push(`fang-relay-unavailable:${String(relay?.reason ?? 'not-provided')}`)
+        } else if (relay?.sameProcess === true) {
+          reasons.push('fang-relay-self-loop')
+        } else if (!M5_RELAY_PEERS.includes(peer)) {
+          reasons.push(`fang-relay-peer-invalid:${peer || 'missing'}`)
+        } else if (events < M5_MIN_RELAY_EVENTS) {
+          reasons.push(`fang-relay-no-receipts(events=${events})`)
+        } else {
+          effect = 'verified'
+        }
+        relayEvidence = Object.freeze({
+          available,
+          peer: peer || null,
+          events,
+          sameProcess: relay?.sameProcess === true,
+          transport: relay?.transport ?? null,
+          contractVersion: relay?.contractVersion ?? relay?.peerContractVersion ?? null,
+        })
       }
     }
 
@@ -141,6 +171,12 @@ export function evaluateMilestones(evidence = {}) {
       effect,
       status,
       reasons,
+      /** M5：回流对端证据（peer 自报 + 事件数 + 是否自环）；其它阶段为 null。 */
+      relay: relayEvidence,
+      /** 剩余缺口说明（不隐藏）。 */
+      notes: milestone.id === 'M5' && relayEvidence?.peer === 'contract-server'
+        ? ['peer=contract-server：契约对端独立进程实测，dsh-fang-bundle 采用 contract 1.1 后应变为 peer=dsh-fang-bundle']
+        : [],
     }))
     if (status === 'done') done.add(milestone.id)
   }

package/src/kernel.ts

@@ -10,7 +10,7 @@
 
 import crypto from 'node:crypto'
 
-export const MASTER_VERSION = '3.3.0'
+export const MASTER_VERSION = '3.3.2'
 export const FANG_CONTRACT_MIN = '3.1.14'
 
 export const SERVICE = Object.freeze({

package/src/plugins/cost-optimizer.ts

@@ -28,7 +28,7 @@ import {
   roleAllowed,
   safeGet,
 } from '../kernel.ts'
-import { createCostSystem, DEFAULT_BUDGET_LIMITS } from '../cost/index.ts'
+import { createCostSystem, createFangRelayFromContext, DEFAULT_BUDGET_LIMITS } from '../cost/index.ts'
 
 export const name = 'dsh-master-cost-optimizer'
 export const inject = ['dshMaster']
@@ -53,6 +53,10 @@ function finiteNonNegative(value) {
  *   enabled?: boolean, mode?: string, targetSavingsRatio?: number,
  *   budget?: Array<{unit: string, limitTokens: number, onExhaust?: string}>,
  *   enforceAllowlist?: string[],
+ *   relay?: {enabled?: boolean, httpBaseUrl?: string, httpToken?: string, fileDir?: string,
+ *            timeoutMs?: number, maxBatch?: number, maxQueue?: number, probeTtlMs?: number,
+ *            autoFlushMs?: number},
+ *   dispatch?: {motherUrl?: string, motherToken?: string, contractFileDir?: string},
  * }} [config]
  */
 export function apply(ctx, config = {}) {
@@ -70,6 +74,12 @@ export function apply(ctx, config = {}) {
   }
 
   const targetSavingsRatio = finiteNonNegative(config.targetSavingsRatio)
+  /**
+   * §5.6 / M5：瓮城回流出口。
+   * 传输按「插件配置 relay → dispatch 配置 → 环境变量 DSH_FANG_*」装配；
+   * 一个都没有时不造客户端，出口状态显式 `relay-client-absent`。
+   */
+  const relayWiring = createFangRelayFromContext(ctx, config, { logger: ctx?.logger })
   const system = createCostSystem({
     mode: config.mode,
     allowlist: config.enforceAllowlist ?? config.allowlist,
@@ -80,9 +90,21 @@ export function apply(ctx, config = {}) {
     hostSurface: config.hostSurface && typeof config.hostSurface === 'object'
       ? { enabled: config.hostSurface.enabled === true, source: config.hostSurface.source }
       : undefined,
+    relay: relayWiring.relay,
+    logger: ctx?.logger,
   })
   const policy = system.policy.describe()
 
+  // M5：加载后异步探测一次回流对端（不阻塞 apply；没有客户端时立即返回 absent）。
+  try { void Promise.resolve(system.relayProbe()).catch(() => {}) } catch { /* 探测失败不影响主流程 */ }
+  /** M5：回流自动投递；没有客户端或 autoFlushMs=0 时不开定时器。 */
+  const autoFlushMs = Math.max(0, Number(config.relay?.autoFlushMs ?? 2_000) || 0)
+  let relayTimer = null
+  if (relayWiring.client && autoFlushMs > 0) {
+    relayTimer = setInterval(() => { try { void system.relayFlush().catch(() => {}) } catch { /* ignore */ } }, autoFlushMs)
+    try { relayTimer.unref?.() } catch { /* ignore */ }
+  }
+
   // 3.2.x 兼容计数器（任务级实测汇总；系统层另有账本，两者口径不同、互不覆盖）。
   const metrics = {
     tasks: 0,
@@ -95,7 +117,7 @@ export function apply(ctx, config = {}) {
 
   const service = {
     id: SERVICE.cost,
-    version: '3.3.0',
+    version: '3.3.2',
     role,
     get mode() {
       return system.policy.describe().mode
@@ -315,12 +337,24 @@ export function apply(ctx, config = {}) {
     substitutions(filter = {}) {
       return system.audit.substitutions(filter)
     },
+    /** M5：瓮城回流出口状态（只读；不可用时必须带具体原因）。 */
+    relayStatus() {
+      return system.relayStatus()
+    },
+    /** M5：立即探测回流对端（hello 协商 + relay 状态），返回最新状态。 */
+    async relayProbe(input = {}) {
+      return await system.relayProbe(input)
+    },
+    /** M5：立即投递队列中的回流事件；回执里的数字才是送达证据。 */
+    async relayFlush() {
+      return await system.relayFlush()
+    },
     status() {
       const current = system.policy.describe()
       return {
         ok: true,
         id: 'cost-optimizer',
-        version: '3.3.0',
+        version: '3.3.2',
         role,
         mode: current.mode,
         requestedMode: current.requestedMode,
@@ -340,8 +374,10 @@ export function apply(ctx, config = {}) {
         attribution: system.attribution.snapshot(),
         attributionSummary: system.status().attributionSummary,
         bus: system.bus.snapshot(1),
-    /** §5.6：内部事件类型（冒号命名）与对外出口状态（fang 未就绪 ⇒ unavailable）。 */
-    events: { types: ['cost:event', 'cost:degraded', 'cost:substitution'], relays: system.bus.snapshot(1).relays },
+        /** §5.6 / M5：瓮城回流出口（可达 ⇒ available:true + 对端自报 peer；否则带原因）。 */
+        relay: system.relayStatus(),
+        /** §5.6：内部事件类型（冒号命名）与对外出口状态。 */
+        events: { types: ['cost:event', 'cost:degraded', 'cost:substitution'], relays: system.bus.snapshot(1).relays },
         degraded: system.status().degraded,
         surfaces: system.status().surfaces,
         hostSurface: system.hostSurface.status(),
@@ -360,12 +396,18 @@ export function apply(ctx, config = {}) {
             doubleCountGuard: report.doubleCountGuard,
           }
         })(),
-        note: '3.3.0 M1+M2：系统层记账/预算/灰度/审计 + A1 工具输出紧凑化（默认 shadow）；工具面 A2–A3 与决策复用 B1–B4 在 M3–M4 接入。',
+        note: '3.3.2：系统层记账/预算/灰度/审计 + A1 工具输出紧凑化（默认 shadow）+ 瓮城回流出口（contract 1.1.1 真实投递，回执计数修复）；工具面 A2–A3 与决策复用 B1–B4 已接入（shadow 默认）。',
       }
     },
   }
 
   try { ctx.effect(() => ctx.provide(SERVICE.cost, service)) } catch { /* fake ctx */ }
+  try {
+    ctx.effect(() => () => {
+      if (relayTimer) clearInterval(relayTimer)
+      relayTimer = null
+    })
+  } catch { /* fake ctx */ }
   // 3.3.0 §11：可选子服务（主服务形态不变；消费方必须探测，不能假定存在）。
   const optionalFaces = {
     [OPTIONAL_SERVICE.costLedger]: Object.freeze({

package/src/plugins/superagent-router.ts

@@ -312,6 +312,20 @@ export function apply(ctx, config = {}) {
       } catch { return null }
     })()
     const tickets = id === null ? [...workerEvents.keys()] : [id]
+    /**
+     * §5.6 / M5：回流出口状态来自成本服务（3.3.1 起是真实探测，不再是硬编码）。
+     * 没有成本服务时如实给 `cost-service-unavailable`，不编造“未就绪”原因。
+     */
+    const relayBlock = (() => {
+      try {
+        const cost = safeGet(ctx, SERVICE.cost)
+        if (cost && typeof cost.relayStatus === 'function') {
+          const relay = cost.relayStatus()
+          if (relay && typeof relay === 'object') return relay
+        }
+      } catch { /* 回流状态读取失败不阻塞成本摘要 */ }
+      return { target: 'fang', available: false, reason: 'cost-service-unavailable' }
+    })()
     const rows = []
     const totals = { events: 0, degraded: 0, substitutions: 0, estimated: 0, savedTokens: 0 }
     for (const key of tickets) {
@@ -345,8 +359,8 @@ export function apply(ctx, config = {}) {
       totals,
       /* §11：只读成本块（A 单价项 / B 跳过调用项分列 + 命中率），面板只读消费。 */
       service: serviceBlock,
-      /* §5.6：瓮城「产物回流」尚未就绪 —— 显式 unavailable，不假装成功、不阻塞主线。 */
-      relay: { target: 'fang', available: false, reason: 'fang-channel-not-ready' },
+      /* §5.6 / M5：瓮城回流出口真实状态（不可用必须显式带原因）。 */
+      relay: relayBlock,
     }
   }