@twinsearth/dsh-master 3.2.10 → 3.3.1

package/src/cost/cert-chain.ts

@@ -0,0 +1,102 @@
+// 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 · M4 交付物：**证书链核对报告**（真实替换 → 证书 → 审计链 → 账本）。
+ *
+ * 一张证书要说清楚三件事，缺一件就不算"可回放"：
+ *
+ *   1. **派发证据**：`viaNativeDispatcher === true` 且 `dispatched === true`（真的走了原生派发器）；
+ *   2. **审计落链**：能在审计链里按 `taskId + step + edgeId` 找到对应记录，且 `verify()` 不断链；
+ *   3. **账本对账**：同一 `taskId + step` 的替换账本事件金额与证书金额一致。
+ *
+ * 任何一项不成立 ⇒ 该证书 `ok:false` 并给出 `issue`，报表整体 `ok:false`。
+ * 失败替换（`dispatched:false`）单列：它们是**自动回退的证据**，不是节省。
+ */
+
+const num = (value) => {
+  const n = Number(value)
+  return Number.isFinite(n) && n >= 0 ? n : 0
+}
+
+/**
+ * @param {{
+ *   certificates?: Array<object>,
+ *   entries?: Array<object>,
+ *   audit?: {ok?: boolean, count?: number, records?: Array<object>},
+ * }} input
+ */
+export function buildCertChainReport(input = {}) {
+  const certificates = Array.isArray(input.certificates) ? input.certificates : []
+  const entries = Array.isArray(input.entries) ? input.entries : []
+  const auditOk = input?.audit?.ok !== false
+  const auditRecords = Array.isArray(input?.audit?.records) ? input.audit.records : []
+
+  // 替换账本事件：按 taskId+step 索引（同一步可能有多条，取合计）
+  const ledgerByKey = new Map()
+  for (const entry of entries) {
+    if (entry?.meta?.kind !== 'substitution') continue
+    const key = `${String(entry.taskId)}|${Number(entry.step)}`
+    ledgerByKey.set(key, (ledgerByKey.get(key) ?? 0) + num(entry.savedTokens))
+  }
+
+  const rows = certificates.map((cert) => {
+    const taskId = String(cert?.taskId ?? '')
+    const step = Number(cert?.step ?? -1)
+    const key = `${taskId}|${step}`
+    // 审计链只接受已派发的证书；因此 dispatched 缺省视为 true，显式 false 才是失败替换。
+    const dispatched = cert?.dispatched !== false
+    const native = cert?.viaNativeDispatcher === true
+    const ledgerSaved = ledgerByKey.get(key) ?? null
+    const certSaved = num(cert?.savedTokens)
+    const audited = auditRecords.some((record) => String(record?.payload?.edgeId ?? '') === String(cert?.edgeId ?? '')
+      && String(record?.payload?.taskId ?? '') === taskId
+      && Number(record?.payload?.step ?? -1) === step)
+
+    const issues = []
+    if (!native) issues.push('not-native-dispatcher')
+    if (dispatched && ledgerSaved === null) issues.push('missing-ledger-entry')
+    if (dispatched && ledgerSaved !== null && ledgerSaved !== certSaved) issues.push('ledger-mismatch')
+    if (dispatched && !audited && auditRecords.length > 0) issues.push('missing-audit-record')
+    if (dispatched && !auditOk) issues.push('audit-chain-broken')
+
+    return Object.freeze({
+      edgeId: String(cert?.edgeId ?? ''),
+      toolName: String(cert?.toolName ?? ''),
+      replacedCallbackId: String(cert?.replacedCallbackId ?? ''),
+      taskId,
+      step,
+      dispatched,
+      viaNativeDispatcher: native,
+      certificateSavedTokens: certSaved,
+      ledgerSavedTokens: ledgerSaved,
+      audited,
+      issue: issues.length > 0 ? issues.join(',') : null,
+      /** 失败替换是「自动回退」的证据，不是缺陷也不是节省。 */
+      fallback: !dispatched,
+      ok: issues.length === 0,
+    })
+  })
+
+  const dispatchedRows = rows.filter((row) => row.dispatched)
+  const fallbackRows = rows.filter((row) => row.fallback)
+  return Object.freeze({
+    ok: rows.every((row) => row.ok),
+    certificates: rows.length,
+    dispatched: dispatchedRows.length,
+    fallbacks: fallbackRows.length,
+    /** 证书声明的节省总额（只算派发成功的）。 */
+    savedTokens: dispatchedRows.reduce((sum, row) => sum + num(row.certificateSavedTokens), 0),
+    audit: Object.freeze({ ok: auditOk, records: Number(input?.audit?.count ?? auditRecords.length) }),
+    /** 自动回退证据：每条失败替换的原因。 */
+    fallbackReasons: Object.freeze(fallbackRows.map((row) => Object.freeze({ edgeId: row.edgeId, reason: String(row.issue ?? 'not-dispatched') }))),
+    rows: Object.freeze(rows),
+    discipline: Object.freeze({
+      /** 失败替换不计节省、不算替换成功。 */
+      fallbacksNeverCountAsSavings: fallbackRows.every((row) => num(row.certificateSavedTokens) === 0 || row.dispatched === false),
+      everyDispatchHasLedgerEntry: dispatchedRows.every((row) => row.ledgerSavedTokens !== null),
+      nativeDispatcherOnly: rows.every((row) => row.viaNativeDispatcher === true),
+    }),
+  })
+}

package/src/cost/experiment.ts

@@ -0,0 +1,136 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+// Copyright (c) 2026 dsh-Master contributors — see LICENSE-CORE.
+// @ts-nocheck — host JS→TS 迁移阶段：运行时行为优先，类型注解逐步补齐（worker/ 仍严格检查）。
+
+/**
+ * M5 实验台：**A/B 对照执行器**（control = ccs off / enforce = ccs enforce）。
+ *
+ * 设计原则（决定它能不能当证据）：
+ *   * 走**真实 Worker 代码路径**（工具注册表、A1 紧凑、A3 批量、B1/B2/B3 全都在）；
+ *   * 每组 ≥10 任务，**同一 corpus 同一顺序**，control 与 enforce 只差一个开关；
+ *   * 输出**同表**：tokens/task 与成功率并列，绝不只报实验组；
+ *   * **自报口径**：`harness:'local-dry-run'` 与 `runner` 字段写进结果 ——
+ *     用脚本化 LLM 跑的 dry run 不能冒充「真实 fork 实机」证据（G5 会因此继续被挡住）。
+ */
+
+export const EXPERIMENT_HARNESS = Object.freeze({
+  dryRun: 'local-dry-run',
+  /** 真实 provider + 真实 Worker 代码路径（票据可以是合成的，但模型与工具是真的）。 */
+  realProvider: 'real-provider-real-worker',
+  realFork: 'real-fork',
+})
+
+const num = (value) => {
+  const n = Number(value)
+  return Number.isFinite(n) ? n : 0
+}
+
+/**
+ * 单组执行：把 corpus 逐个跑完，收集指标。
+ *
+ * @param {{
+ *   tasks: Array<{taskId: string, run: (task: object) => Promise<object>}>,
+ *   group: 'control' | 'enforce',
+ * }} input
+ */
+export async function runGroup(input = {}) {
+  const tasks = Array.isArray(input.tasks) ? input.tasks : []
+  const rows = []
+  for (const task of tasks) {
+    const startedAt = Date.now()
+    let result
+    try {
+      result = await task.run(task)
+    } catch (error) {
+      result = { ok: false, error: { code: 'harness-error', message: error instanceof Error ? error.message : String(error) } }
+    }
+    const elapsedMs = Date.now() - startedAt
+    const cost = result?.cost ?? {}
+    rows.push({
+      taskId: String(task.taskId),
+      ok: result?.ok === true,
+      tokens: num(result?.tokenUsage),
+      elapsedMs: num(result?.elapsedMs) || elapsedMs,
+      steps: Array.isArray(result?.steps) ? result.steps.length : 0,
+      a1: cost.compaction
+        ? {
+          mode: cost.compaction.mode,
+          applied: cost.compaction.applied === true,
+          savedChars: num(cost.compaction.savedChars),
+          estimatedTokens: num(cost.compaction.estimatedTokens),
+        }
+        : null,
+      a3: cost.batch ? { taught: cost.batch.taught === true, corrections: num(cost.batch.corrections) } : null,
+      reuse: cost.ccs
+        ? {
+          mode: cost.ccs.mode,
+          attempts: Array.isArray(cost.ccs.attempts) ? cost.ccs.attempts.length : 0,
+          hits: Array.isArray(cost.ccs.attempts) ? cost.ccs.attempts.filter((item) => item.hit === true).length : 0,
+          wouldSaveTokens: Array.isArray(cost.ccs.attempts) ? cost.ccs.attempts.reduce((sum, item) => sum + num(item.wouldSaveTokens), 0) : 0,
+          skippedModelCalls: num(cost.ccs.skippedModelCalls),
+          substitutions: Array.isArray(cost.ccs.substitutions) ? cost.ccs.substitutions.length : 0,
+          dispatched: Array.isArray(cost.ccs.substitutions) ? cost.ccs.substitutions.filter((cert) => cert.dispatched === true).length : 0,
+          failures: Array.isArray(cost.ccs.substitutions) ? cost.ccs.substitutions.filter((cert) => cert.dispatched === false).length : 0,
+          shadowCertificates: Array.isArray(cost.ccs.shadowCertificates) ? cost.ccs.shadowCertificates.length : 0,
+        }
+        : null,
+    })
+  }
+  return { group: String(input.group ?? 'unknown'), tasks: rows }
+}
+
+/** 两组同表对比（成功率差值按 §10.1 的 2pp 门禁）。 */
+export function compareGroups({ control, enforce, harness = EXPERIMENT_HARNESS.dryRun, runner = 'scripted-llm' } = {}) {
+  const avg = (rows) => (rows.length > 0 ? rows.reduce((sum, row) => sum + num(row.tokens), 0) / rows.length : null)
+  const rate = (rows) => (rows.length > 0 ? rows.filter((row) => row.ok === true).length / rows.length : null)
+  const ctl = Array.isArray(control?.tasks) ? control.tasks : []
+  const trt = Array.isArray(enforce?.tasks) ? enforce.tasks : []
+  const controlTokens = avg(ctl)
+  const enforceTokens = avg(trt)
+  const controlSuccess = rate(ctl)
+  const enforceSuccess = rate(trt)
+  const tokenDeltaPct = controlTokens !== null && enforceTokens !== null && controlTokens > 0
+    ? (enforceTokens - controlTokens) / controlTokens
+    : null
+  const successDelta = controlSuccess !== null && enforceSuccess !== null ? enforceSuccess - controlSuccess : null
+  const reuse = trt.map((row) => row.reuse).filter(Boolean)
+  const a1 = trt.map((row) => row.a1).filter(Boolean)
+  return Object.freeze({
+    harness,
+    runner,
+    /** 这条是给 G5 用的：dry-run 永远不足以当证据；真实 provider + 真实 worker 才算测量有效。 */
+    qualifiesForGate: harness === EXPERIMENT_HARNESS.realFork || harness === EXPERIMENT_HARNESS.realProvider,
+    table: [
+      { group: 'control', samples: ctl.length, tokensPerTask: controlTokens, successRate: controlSuccess, elapsedMsMedian: median(ctl.map((row) => num(row.elapsedMs))) },
+      { group: 'enforce', samples: trt.length, tokensPerTask: enforceTokens, successRate: enforceSuccess, elapsedMsMedian: median(trt.map((row) => num(row.elapsedMs))) },
+    ],
+    delta: { tokensPerTask: controlTokens !== null && enforceTokens !== null ? enforceTokens - controlTokens : null, tokensPerTaskPct: tokenDeltaPct, successRate: successDelta },
+    a1: {
+      tasks: a1.length,
+      /** pplied 只反映**最后一次**压缩事件；真正判断贡献要看是否产生了估算节省。 */
+      tasksWithSavings: a1.filter((row) => num(row.estimatedTokens) > 0).length,
+      applied: a1.filter((row) => row.applied === true).length,
+      estimatedTokens: a1.reduce((sum, row) => sum + num(row.estimatedTokens), 0),
+    },
+    reuse: {
+      attempts: reuse.reduce((sum, row) => sum + num(row.attempts), 0),
+      hits: reuse.reduce((sum, row) => sum + num(row.hits), 0),
+      wouldSaveTokens: reuse.reduce((sum, row) => sum + num(row.wouldSaveTokens), 0),
+      skippedModelCalls: reuse.reduce((sum, row) => sum + num(row.skippedModelCalls), 0),
+      dispatched: reuse.reduce((sum, row) => sum + num(row.dispatched), 0),
+      failures: reuse.reduce((sum, row) => sum + num(row.failures), 0),
+      shadowCertificates: reuse.reduce((sum, row) => sum + num(row.shadowCertificates), 0),
+    },
+    /** 与 gate G5 同形，便于直接喂 `evaluateForkExperiment`。 */
+    gateShape: Object.freeze({
+      control: { tasks: ctl.map((row) => ({ taskId: row.taskId, tokens: row.tokens, success: row.ok })) },
+      enforce: { tasks: trt.map((row) => ({ taskId: row.taskId, tokens: row.tokens, success: row.ok })) },
+    }),
+  })
+}
+
+function median(values) {
+  const sorted = [...values].sort((a, b) => a - b)
+  if (sorted.length === 0) return null
+  return sorted[Math.min(sorted.length - 1, Math.ceil(0.5 * sorted.length) - 1)]
+}

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 }
+}