@twinsearth/dsh-master 3.3.0 → 3.3.1

package/README.md

@@ -92,7 +92,8 @@ dsh plugin add <package>  # 加载 dist-host/dist-worker
 
 ## 状态
 
-- 3.3.0 M1+M2（dev，未发布）：成本优化系统层（ledger / budget / policy / audit）+ Worker 四个成本切点（observe-only）+ A1 工具输出紧凑化（默认 shadow，enforce 需白名单）；A2–A3 与决策复用 B1–B4 在 M3–M4 接入，详见 [3.3.0 架构设计](docs/DESIGN-v3.3.0-cost-optimization.md)。
+- **3.3.1 发布线**：M5 收口 —— 瓮城回流接口升级到 `@twinsearth/dsh-fang-contract` **1.1.0**（`fang.relay.publish` / `fang.relay.status`），房主侧 `src/cost/fang-relay.ts` 做真实探测与投递（只有对端回执才算送达，不可用给具名原因）；里程碑 **M1–M5 全部 done**。详见 [M5 回流实测](docs/EXPERIMENT-M5-fang-relay.md)。
+- **3.3.0 发布线**：成本优化系统层（ledger / budget / policy / audit）+ Worker 四个成本切点 + A1 紧凑化（默认 shadow）+ A2–A3 / B1–B4；真实 A/B 实测 tokens/task 6263 → 3906.75（−37.6%），成功率 0pp 差，详见 [3.3.0 架构设计](docs/DESIGN-v3.3.0-cost-optimization.md)。
 - 3.2.10 发布线：角色矩阵放宽——Router 进入母体（essence/mother），Worker 与 Worker Agent Loop 进入原身（fork/essence）；母体仍不接纳执行体，fork 仍不注册 Router。
 - 3.2.9 发布线：房主面板改注册到 `shell.overlay` 常驻浮层——点击面板之外不收起、侧栏「房主」按钮二次点击收起、正文独立滚动；新增无浏览器 hook 运行时行为测试（开关、无 outside-click 监听、滚动容器、SSE 失败不卸载面板）。
 - 3.2.8 发布线：与瓮城通过 fang-master contract 1.0 互联（local/http/file/legacy 四级保底）；GitHub Release + NPM public。

package/client.js

@@ -275,7 +275,7 @@ window.__ModuleLoader__.load({
       return h('div', { style: S.card, 'data-dsh-master': 'cost-block' },
         h('div', { style: S.row },
           h('span', { style: S.name }, '成本（只读）'),
-          tag(block ? '3.3.0' : '未启用', block ? undefined : '#B45309')),
+          tag(block ? '3.3.1' : '未启用', block ? undefined : '#B45309')),
         failed ? h('div', { style: S.error }, '成本接口不可达') : null,
         !block && !failed ? h('div', { style: S.desc }, '成本系统未装配（cost-optimizer 未启用或角色不匹配）') : null,
         columns ? h('div', { style: S.desc },

package/dist-host/contract/client.js

@@ -77,6 +77,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/dist-host/contract/constants.js

@@ -9,7 +9,7 @@
  *   * 删除/改义必须升 MAJOR，并保留至少一个 MINOR 周期的双写（method@1 与 method@2）。
  */
 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;
@@ -24,6 +24,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',
 });
 /** 方法 → 契约版本（用于协商后的方法裁剪）。 */
 export const METHOD_VERSION = Object.freeze({
@@ -36,9 +38,11 @@ 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']);
 export const ERROR_CODES = Object.freeze({
@@ -68,3 +72,13 @@ 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/dist-host/contract/index.js

@@ -13,5 +13,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/dist-host/contract/relay.js

@@ -0,0 +1,239 @@
+// 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 };
+}

package/dist-host/cost/fang-relay.js

@@ -0,0 +1,329 @@
+// 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 };
+}