@twinsearth/dsh-master 3.2.10 → 3.3.0

package/src/cost/budget.ts

@@ -0,0 +1,226 @@
+// 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 系统层 · budget（预算闸，设计 §5.2）。
+ *
+ * 规格要点：
+ *   * 规则：`unit(task|fork|day) + limitTokens? + limitCost? + onExhaust(hard-stop|degrade)`；
+ *   * **检查点只在 ① beforeModelCall**（`authorize()` 即该检查点，其它地方不得自行扣减）；
+ *   * 超限返回 `masterError('budget-exhausted', …)` 形状 + 结构化 `remaining`；
+ *   * **fail-closed**：额度不足不得「先跑着看」——拒绝时**不扣额度**、不放行；
+ *   * `degrade` 档只允许降级到**已在白名单**的廉价模型，绝不引入新 provider。
+ *
+ * 成本维度（`limitCost`）需要调用方给出本次预估成本（`cost` 字段）；
+ * 未提供成本时成本维度不可判定，会显式标 `costTracked: false`，而不是假装达标。
+ */
+
+import { DEFAULT_BUDGET_LIMITS } from './types.ts'
+
+const UNITS = ['task', 'fork', 'day']
+const EXHAUST_ACTIONS = ['hard-stop', 'degrade']
+
+/** 与 kernel.masterError 同形状（host 侧不反向依赖 kernel，避免子系统耦合）。 */
+function masterError(code, message, detail) {
+  const out = { ok: false, code: String(code), error: String(message ?? code) }
+  if (detail !== undefined) out.detail = detail
+  return out
+}
+
+function positiveLimit(value) {
+  const n = Number(value)
+  return Number.isFinite(n) && n > 0 ? Math.floor(n) : null
+}
+
+function keyOf(unit, key) {
+  return `${unit}:${String(key ?? 'default')}`
+}
+
+/**
+ * @param {{
+ *   limits?: Array<{unit:string, limitTokens?:number, limitCost?:number, onExhaust?:string, degradeTo?:string}>,
+ *   degradeModels?: string[],   // degrade 允许的廉价模型白名单（不在此列表 ⇒ 一律 hard-stop）
+ *   now?: () => number,
+ * }} [options]
+ */
+export function createBudget(options = {}) {
+  const now = typeof options.now === 'function' ? options.now : () => Date.now()
+  const source = Array.isArray(options.limits) && options.limits.length > 0 ? options.limits : DEFAULT_BUDGET_LIMITS
+  const degradeModels = Object.freeze(
+    (Array.isArray(options.degradeModels) ? options.degradeModels : [])
+      .map((item) => String(item ?? '').trim())
+      .filter(Boolean),
+  )
+  const limits = []
+  const invalid = []
+  for (const item of source) {
+    const unit = String(item?.unit ?? '')
+    const limitTokens = item?.limitTokens === undefined ? null : positiveLimit(item.limitTokens)
+    const limitCost = item?.limitCost === undefined ? null : positiveLimit(item.limitCost)
+    if (!UNITS.includes(unit) || (limitTokens === null && limitCost === null)) {
+      // 既无 token 上限也无成本上限的规则没有意义：配置错误必须显式暴露（fail-closed）。
+      invalid.push({ unit, limitTokens: item?.limitTokens, limitCost: item?.limitCost })
+      continue
+    }
+    if (limits.some((rule) => rule.unit === unit)) {
+      // 同一 unit 只能有一条规则（先注册先得），否则判定口径不确定。
+      invalid.push({ unit, reason: 'duplicate-unit' })
+      continue
+    }
+    const onExhaust = EXHAUST_ACTIONS.includes(String(item?.onExhaust)) ? String(item.onExhaust) : 'hard-stop'
+    const degradeTo = item?.degradeTo === undefined ? null : String(item.degradeTo)
+    // degrade 档必须在白名单内，否则等于开了个后门：降级为 hard-stop。
+    const effective = onExhaust === 'degrade' && degradeTo !== null && degradeModels.includes(degradeTo)
+      ? 'degrade'
+      : 'hard-stop'
+    if (onExhaust === 'degrade' && effective !== 'degrade') {
+      invalid.push({ unit, degradeTo, reason: 'degrade-model-not-allowlisted' })
+    }
+    limits.push(Object.freeze({
+      unit,
+      limitTokens,
+      limitCost,
+      onExhaust: effective,
+      degradeTo: effective === 'degrade' ? degradeTo : null,
+    }))
+  }
+  const limitOf = (unit) => limits.find((item) => item.unit === unit) ?? null
+  const consumed = new Map()
+  const used = (unit, key) => consumed.get(keyOf(unit, key)) ?? { tokens: 0, cost: 0 }
+
+  /**
+   * ① beforeModelCall 的唯一检查点。
+   * @param {{unit: string, key?: string, tokens?: number, cost?: number}} input
+   */
+  function authorize(input = {}) {
+    const unit = String(input.unit)
+    const key = String(input.key ?? 'default')
+    const requested = Number(input.tokens ?? 0)
+    const requestedCost = Number(input.cost ?? 0)
+    if (!Number.isFinite(requested) || requested < 0) {
+      return masterError('tokens-invalid', 'tokens must be a non-negative number')
+    }
+    if (!Number.isFinite(requestedCost) || requestedCost < 0) {
+      return masterError('cost-invalid', 'cost must be a non-negative number')
+    }
+    const limit = limitOf(unit)
+    if (!limit) {
+      return { ok: true, unlimited: true, unit, key, requested, remaining: null, costTracked: false, at: now() }
+    }
+
+    const current = used(unit, key)
+    const remainingTokens = limit.limitTokens === null ? null : Math.max(0, limit.limitTokens - current.tokens)
+    const remainingCost = limit.limitCost === null ? null : Math.max(0, limit.limitCost - current.cost)
+    const tokenExhausted = limit.limitTokens !== null && requested > remainingTokens
+    const costExhausted = limit.limitCost !== null && requestedCost > remainingCost
+    const costTracked = limit.limitCost === null ? false : Number(input.cost) > 0
+
+    if (tokenExhausted || costExhausted) {
+      const reason = tokenExhausted ? 'tokens' : 'cost'
+      // degrade 档：只降级到白名单里的廉价模型；否则一律 fail-closed。
+      if (limit.onExhaust === 'degrade' && limit.degradeTo && degradeModels.includes(limit.degradeTo)) {
+        return {
+          ok: true,
+          degraded: true,
+          action: 'degrade',
+          unit,
+          key,
+          model: limit.degradeTo,
+          reason,
+          limitTokens: limit.limitTokens,
+          limitCost: limit.limitCost,
+          consumedTokens: current.tokens,
+          consumedCost: current.cost,
+          remainingTokens,
+          remainingCost,
+          requested,
+          requestedCost,
+          costTracked,
+          onExhaust: 'degrade',
+          at: now(),
+        }
+      }
+      // fail-closed：拒绝且**不扣额度**，绝不「先跑着看」。
+      return masterError('budget-exhausted', `预算不足：${unit}/${key} 剩余 ${remainingTokens ?? '∞'} token`, {
+        unit,
+        key,
+        reason,
+        limitTokens: limit.limitTokens,
+        limitCost: limit.limitCost,
+        consumedTokens: current.tokens,
+        consumedCost: current.cost,
+        remainingTokens,
+        remainingCost,
+        requested,
+        requestedCost,
+        costTracked,
+        onExhaust: limit.onExhaust,
+        /** 剩余信息同时平铺在顶层，便于调用方不需解 detail。 */
+        remaining: { tokens: remainingTokens, cost: remainingCost },
+        at: now(),
+      })
+    }
+
+    const nextTokens = current.tokens + Math.floor(requested)
+    const nextCost = current.cost + requestedCost
+    consumed.set(keyOf(unit, key), { tokens: nextTokens, cost: nextCost })
+    return {
+      ok: true,
+      unit,
+      key,
+      requested,
+      requestedCost,
+      consumedTokens: nextTokens,
+      consumedCost: nextCost,
+      limitTokens: limit.limitTokens,
+      limitCost: limit.limitCost,
+      remainingTokens: limit.limitTokens === null ? null : limit.limitTokens - nextTokens,
+      remainingCost: limit.limitCost === null ? null : limit.limitCost - nextCost,
+      costTracked,
+      at: now(),
+    }
+  }
+
+  function refund({ unit, key = 'default', tokens = 0, cost = 0 } = {}) {
+    const n = Number(tokens)
+    const c = Number(cost)
+    if (!Number.isFinite(n) || n < 0 || !Number.isFinite(c) || c < 0 || (n === 0 && c === 0)) {
+      return masterError('refund-invalid', 'refund requires positive tokens and/or cost')
+    }
+    const k = keyOf(String(unit), key)
+    const current = consumed.get(k) ?? { tokens: 0, cost: 0 }
+    const next = { tokens: Math.max(0, current.tokens - Math.floor(n)), cost: Math.max(0, current.cost - c) }
+    consumed.set(k, next)
+    return { ok: true, unit: String(unit), key: String(key), consumedTokens: next.tokens, consumedCost: next.cost, at: now() }
+  }
+
+  function state() {
+    const rows = []
+    for (const limit of limits) {
+      for (const [k, value] of consumed.entries()) {
+        const prefix = `${limit.unit}:`
+        if (!k.startsWith(prefix)) continue
+        rows.push(Object.freeze({
+          unit: limit.unit,
+          key: k.slice(prefix.length),
+          consumedTokens: value.tokens,
+          consumedCost: value.cost,
+          limitTokens: limit.limitTokens,
+          limitCost: limit.limitCost,
+          remainingTokens: limit.limitTokens === null ? null : Math.max(0, limit.limitTokens - value.tokens),
+          remainingCost: limit.limitCost === null ? null : Math.max(0, limit.limitCost - value.cost),
+          onExhaust: limit.onExhaust,
+        }))
+      }
+    }
+    return Object.freeze({ ok: true, limits, invalid, degradeModels: degradeModels.slice(), rows, at: now() })
+  }
+
+  function reset() {
+    consumed.clear()
+    return { ok: true }
+  }
+
+  return Object.freeze({ authorize, refund, state, reset, limits: () => limits.slice(), degradeModels: () => degradeModels.slice() })
+}

package/src/cost/bus.ts

@@ -0,0 +1,97 @@
+// 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 系统层 · bus（事件总线与回流出口，设计 §5.6）。
+ *
+ * 对外只暴露三种内部事件（冒号命名，与 Router 事件通道一致）：
+ *   * `cost:event`         —— 账本/归因/预算等一般成本事件（payload.kind 区分）；
+ *   * `cost:degraded`      —— 模块降级（不伪装成节省）；
+ *   * `cost:substitution`  —— 替换证书（与审计链同源）。
+ *
+ * 可选对外出口（3.3.0 不阻塞主线）：
+ *   * `web`  —— Worker→Router 既有事件通道（Router 落库后供状态页/分身信息栏读取）；
+ *   * `fang` —— 瓮城「产物回流」；未就绪时状态里必须显式 `available: false` + 原因，
+ *               **不得**静默丢弃或假装成功。
+ */
+
+export const COST_EVENT_TYPES = Object.freeze(['cost:event', 'cost:degraded', 'cost:substitution'])
+
+/**
+ * @param {{maxEvents?: number, now?: () => number, relays?: Array<{name:string, publish?:Function, available?:boolean, reason?:string}>}} [options]
+ */
+export function createCostBus(options = {}) {
+  const now = typeof options.now === 'function' ? options.now : () => Date.now()
+  const maxEvents = Math.max(1, Number(options.maxEvents ?? 200) || 200)
+  const events = []
+  const subscribers = new Set()
+  /** 外部出口（web / fang）；available=false 的出口只记录状态，不投递。 */
+  const relays = (Array.isArray(options.relays) ? options.relays : [])
+    .filter((relay) => relay && typeof relay === 'object' && relay.name)
+    .map((relay) => ({
+      name: String(relay.name),
+      publish: typeof relay.publish === 'function' ? relay.publish : null,
+      available: relay.available === true && typeof relay.publish === 'function',
+      reason: String(relay.reason ?? ''),
+      delivered: 0,
+      failed: 0,
+    }))
+  let dropped = 0
+
+  function publish(type, payload = {}) {
+    const event = Object.freeze({ type: String(type ?? 'unknown'), at: now(), payload: Object.freeze({ ...payload }) })
+    events.push(event)
+    if (events.length > maxEvents) {
+      events.shift()
+      dropped += 1
+    }
+    for (const listener of [...subscribers]) {
+      try { listener(event) } catch { /* 订阅者异常不影响成本链路 */ }
+    }
+    for (const relay of relays) {
+      if (!relay.available || !relay.publish) continue
+      try {
+        relay.publish(event)
+        relay.delivered += 1
+      } catch {
+        relay.failed += 1
+        // 出口失败不得影响主流程，但必须留痕（failed 计数），不静默吞掉。
+      }
+    }
+    return event
+  }
+
+  function subscribe(listener) {
+    if (typeof listener !== 'function') return () => {}
+    subscribers.add(listener)
+    return () => { subscribers.delete(listener) }
+  }
+
+  function snapshot(limit = 50) {
+    const n = Math.max(1, Number(limit) || 50)
+    return Object.freeze({
+      ok: true,
+      count: events.length,
+      dropped,
+      subscribers: subscribers.size,
+      events: events.slice(-n),
+      /** §5.6 出口状态：不可用必须显式说明原因，不假装成功。 */
+      relays: relays.map((relay) => Object.freeze({
+        name: relay.name,
+        available: relay.available,
+        reason: relay.reason,
+        delivered: relay.delivered,
+        failed: relay.failed,
+      })),
+    })
+  }
+
+  function reset() {
+    events.length = 0
+    dropped = 0
+    return { ok: true }
+  }
+
+  return Object.freeze({ publish, subscribe, snapshot, reset })
+}

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