@twinsearth/dsh-master 3.3.0 → 3.3.1

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.1'
 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.1',
     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.1',
         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.1：系统层记账/预算/灰度/审计 + A1 工具输出紧凑化（默认 shadow）+ 瓮城回流出口（contract 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,
     }
   }