@twinsearth/dsh-master 3.2.10 → 3.3.1

package/src/cost/gate.ts

@@ -0,0 +1,191 @@
+// 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 · gate（发布门禁，设计 §10.2）。
+ *
+ * **3.3.0 不通过不发布**。六道门：
+ *
+ * | # | 门禁 | 判定 |
+ * |---|---|---|
+ * | G1 | `npm run check` 0 error | 退出码 |
+ * | G2 | `npm run build` 0 error | 退出码 |
+ * | G3 | `npm test` 全绿（含新增模块测试） | 退出码 + 用例数 |
+ * | G4 | 新增测试至少覆盖：I1–I8 各一条、守卫命中/未命中、schema 漂移、证书回放、归因不重复计 | 覆盖清单逐项核验 |
+ * | G5 | 真实 fork 实机：≥10 任务的对照组 vs enforce 组，tokens/task 与成功率同表 | 样本量 + 同表 + 成功率不退化 |
+ * | G6 | 零残留：临时 profile / 工作区清理证据 | 路径扫描 |
+ * | G7 | 发布需用户明确授权 | 默认 **未授权**（设计不含发布动作） |
+ *
+ * 门禁的价值在于**敢说不**：任一门不满足即 `ok:false` 并列出 `blockers`，
+ * 不允许"部分通过"。
+ */
+
+/** 必须被测试覆盖的能力（G4），每项给出识别标记。 */
+export const REQUIRED_COVERAGE = Object.freeze([
+  { id: 'I1', label: '预算不足不启动模型调用', patterns: [/I1:.*budget/u] },
+  { id: 'I2', label: 'CCS 只经原生派发器 / 无派发器拒绝', patterns: [/I2:.*native dispatcher/u, /I2:.*non-native/u] },
+  { id: 'I3', label: '破坏性工具默认不入池', patterns: [/I3:.*destructive/u] },
+  { id: 'I4', label: 'schema 漂移整图作废', patterns: [/I4:.*schema drift/u] },
+  { id: 'I5', label: '守卫不匹配回落慢模型', patterns: [/I5:.*guard miss/u] },
+  { id: 'I6', label: '模块异常 degraded 且任务继续', patterns: [/I6:.*throwing module/u] },
+  { id: 'I7', label: '压缩回执可回读原文（spill）', patterns: [/I7:.*read back/u] },
+  { id: 'I8', label: '取消信号阻断替换', patterns: [/I8:.*aborted signal/u] },
+  { id: 'guard-hit', label: '守卫命中', patterns: [/all five gates must pass/u] },
+  { id: 'guard-miss', label: '守卫未命中', patterns: [/each gate has its own miss reason/u] },
+  { id: 'schema-drift', label: 'schema 漂移（B2 层）', patterns: [/schema drift archives the whole graph/u, /schemaHash/u] },
+  { id: 'cert-replay', label: '证书回放', patterns: [/100% replayable/u] },
+  { id: 'no-double-count', label: '归因不重复计', patterns: [/doubleCountGuard/u, /mutually exclusive/u] },
+])
+
+/** G5：对照组 vs enforce 组的最小样本量。 */
+export const MIN_FORK_TASKS = 10
+/** G5：成功率允许的最大下降（与 §10.1 的 2pp 门禁一致）。 */
+export const MAX_SUCCESS_DROP_PP = 0.02
+
+const num = (value) => {
+  const n = Number(value)
+  return Number.isFinite(n) ? n : 0
+}
+
+/**
+ * G4：扫描测试源码，逐项确认覆盖（找不到标记即报缺）。
+ * @param {Record<string, string>} sources 文件名 → 源码
+ */
+export function checkCoverage(sources = {}) {
+  const haystack = Object.values(sources).join('\n')
+  const missing = []
+  const covered = []
+  for (const item of REQUIRED_COVERAGE) {
+    const found = item.patterns.some((pattern) => pattern.test(haystack))
+    if (found) covered.push(item.id)
+    else missing.push({ id: item.id, label: item.label })
+  }
+  return { ok: missing.length === 0, covered, missing }
+}
+
+/**
+ * G5：评估真实 fork 实机对照实验。
+ * @param {{control?: {tasks: Array<{taskId: string, tokens: number, success: boolean}>}, enforce?: {tasks: Array<{taskId: string, tokens: number, success: boolean}>}}} input
+ */
+export function evaluateForkExperiment(input = {}) {
+  const control = Array.isArray(input?.control?.tasks) ? input.control.tasks : []
+  const enforce = Array.isArray(input?.enforce?.tasks) ? input.enforce.tasks : []
+  const problems = []
+  // 证据来源必须真实：dry-run（合成语料 + 脚本化模型）不能冒充 G5。
+  const harness = input?.harness === undefined ? 'real-fork' : String(input.harness)
+  if (harness === 'local-dry-run') problems.push('harness-not-real')
+  if (control.length < MIN_FORK_TASKS) problems.push(`control-tasks<${MIN_FORK_TASKS}`)
+  if (enforce.length < MIN_FORK_TASKS) problems.push(`enforce-tasks<${MIN_FORK_TASKS}`)
+
+  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?.success === true).length / rows.length : null)
+
+  const controlTokensPerTask = avg(control)
+  const enforceTokensPerTask = avg(enforce)
+  const controlSuccess = rate(control)
+  const enforceSuccess = rate(enforce)
+  const tokenDelta = controlTokensPerTask !== null && enforceTokensPerTask !== null
+    ? Math.round((enforceTokensPerTask - controlTokensPerTask) * 100) / 100
+    : null
+  const successDelta = controlSuccess !== null && enforceSuccess !== null
+    ? Math.round((enforceSuccess - controlSuccess) * 10000) / 10000
+    : null
+  if (successDelta !== null && successDelta <= -MAX_SUCCESS_DROP_PP) problems.push('success-regression>=2pp')
+  // 同表：两组必须都在同一份报告里给出 tokens/task 与成功率
+  const sameTable = controlTokensPerTask !== null && enforceTokensPerTask !== null && controlSuccess !== null && enforceSuccess !== null
+  if (!sameTable) problems.push('groups-not-in-same-table')
+
+  return {
+    ok: problems.length === 0,
+    problems,
+    samples: { control: control.length, enforce: enforce.length },
+    table: [
+      { group: 'control', samples: control.length, tokensPerTask: controlTokensPerTask, successRate: controlSuccess },
+      { group: 'enforce', samples: enforce.length, tokensPerTask: enforceTokensPerTask, successRate: enforceSuccess },
+    ],
+    delta: { tokensPerTask: tokenDelta, successRate: successDelta },
+    /** token 变好且成功率不退化，才算"通过且有效"。 */
+    improvement: tokenDelta !== null && tokenDelta < 0 && (successDelta === null || successDelta > -MAX_SUCCESS_DROP_PP),
+  }
+}
+
+/**
+ * G6：零残留——给出的路径里不允许还有临时 profile / 工作区。
+ * @param {Array<{path: string, exists: boolean, kind?: string}>} checks
+ */
+export function checkResidue(checks = []) {
+  const leftovers = checks.filter((entry) => entry?.exists === true).map((entry) => ({ path: String(entry.path), kind: String(entry.kind ?? 'unknown') }))
+  return {
+    ok: leftovers.length === 0,
+    checked: checks.length,
+    leftovers,
+    /** 没有检查项等于没有证据，不算通过。 */
+    evidence: checks.length > 0 ? '<results>' : null,
+  }
+}
+
+/**
+ * 汇总门禁。
+ * @param {{
+ *   commands?: Array<{id: string, exitCode: number, note?: string}>,
+ *   coverage?: ReturnType<typeof checkCoverage>,
+ *   forkExperiment?: ReturnType<typeof evaluateForkExperiment>,
+ *   residue?: ReturnType<typeof checkResidue>,
+ *   releaseAuthorized?: boolean,
+ * }} input
+ */
+export function evaluateGate(input = {}) {
+  const items = []
+  const blockers = []
+
+  for (const command of Array.isArray(input.commands) ? input.commands : []) {
+    const id = String(command?.id ?? 'unknown')
+    const passed = num(command?.exitCode) === 0
+    items.push({ gate: id, ok: passed, detail: `exit=${num(command?.exitCode)}${command?.note ? ` ${command.note}` : ''}` })
+    if (!passed) blockers.push(`${id}:exit-code`)
+  }
+
+  const coverage = input.coverage
+  if (!coverage) {
+    blockers.push('G4:coverage-not-checked')
+    items.push({ gate: 'G4', ok: false, detail: '未执行覆盖核验' })
+  } else {
+    items.push({ gate: 'G4', ok: coverage.ok === true, detail: coverage.ok ? `${coverage.covered.length} 项全中` : `缺 ${coverage.missing.map((item) => item.id).join(',')}` })
+    if (coverage.ok !== true) blockers.push(`G4:missing:${coverage.missing.map((item) => item.id).join(',')}`)
+  }
+
+  const fork = input.forkExperiment
+  if (!fork) {
+    blockers.push('G5:fork-experiment-missing')
+    items.push({ gate: 'G5', ok: false, detail: '尚无真实 fork 对照数据（≥10 任务/组）' })
+  } else {
+    items.push({ gate: 'G5', ok: fork.ok === true, detail: fork.ok ? `control ${fork.table[0].tokensPerTask} → enforce ${fork.table[1].tokensPerTask} tokens/task` : fork.problems.join(',') })
+    if (fork.ok !== true) blockers.push(`G5:${fork.problems.join(',')}`)
+  }
+
+  const residue = input.residue
+  if (!residue) {
+    blockers.push('G6:residue-not-checked')
+    items.push({ gate: 'G6', ok: false, detail: '未提供清理证据' })
+  } else {
+    items.push({ gate: 'G6', ok: residue.ok === true, detail: residue.ok ? `${residue.checked} 个路径均无残留` : `残留: ${residue.leftovers.map((item) => item.path).join(',')}` })
+    if (residue.ok !== true) blockers.push('G6:residue')
+  }
+
+  // G7：默认未授权。设计本身不含发布动作；授权是人工显式行为。
+  const authorized = input.releaseAuthorized === true
+  items.push({ gate: 'G7', ok: authorized, detail: authorized ? '用户已明确授权' : '未授权（发布需用户明确授权）' })
+  if (!authorized) blockers.push('G7:release-not-authorized')
+
+  const hardGates = ['G1', 'G2', 'G3', 'G4', 'G5', 'G6']
+  const hardOk = items.filter((item) => hardGates.includes(item.gate)).every((item) => item.ok)
+  return {
+    ok: hardOk && authorized,
+    /** 不发布 ≠ 代码不可用：G1–G4 + G6 全绿时，代码质量门禁是过了的。 */
+    bootstrapOk: hardOk,
+    blockers,
+    items,
+    releaseAuthorized: authorized,
+  }
+}

package/src/cost/host-surface.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 · 宿主会话工具面适配器（可选）。
+ *
+ * 设计 §3.3：`dsh-ops` 这类宿主插件作用于**宿主会话工具面**（DSH 原生工具准入/
+ * 执行器接口），而本项目 A1–A3 作用于**master Worker 自有工具面**（`worker/tools.ts`）。
+ * 两者作用面不同，不能合并统计，也不能互相替代。
+ *
+ * 因此本文件**不重写、不依赖、不冒领**任何宿主插件：
+ *   * 它只提供一个「外部收益登记」入口，由宿主侧（或用户脚本）把某个宿主插件的
+ *     自报收益按 `surface: 'host', external: true` 写入账本；
+ *   * 这些条目永远不进入 `ownExecutionSaved` / `netSaved`，只作为对照展示；
+ *   * 未安装宿主插件时，本适配器完全空转（无网络、无副作用、零依赖）。
+ *
+ * 这是「双管齐下」的第二半：**协议等价实现（Worker 面自研）+ 可选适配器（宿主面归因）**。
+ */
+
+import { createCostBus } from './bus.ts'
+
+const SOURCES = new Set(['dsh-ops', 'other'])
+
+function finiteNonNegative(value) {
+  const n = Number(value)
+  return Number.isFinite(n) && n >= 0 ? Math.floor(n) : null
+}
+
+/**
+ * @param {{
+ *   ledger: {append: Function},
+ *   enabled?: boolean,
+ *   source?: string,
+ *   bus?: ReturnType<typeof createCostBus>,
+ *   now?: () => number,
+ * }} options
+ */
+export function createHostSurfaceAdapter(options = {}) {
+  const ledger = options.ledger
+  if (!ledger || typeof ledger.append !== 'function') throw new Error('host-surface adapter requires a ledger')
+  const enabled = options.enabled === true
+  const source = SOURCES.has(String(options.source ?? 'dsh-ops')) ? String(options.source ?? 'dsh-ops') : 'other'
+  const bus = options.bus && typeof options.bus.publish === 'function' ? options.bus : null
+  const now = typeof options.now === 'function' ? options.now : () => Date.now()
+  let recorded = 0
+  let tokensClaimed = 0
+
+  /**
+   * 登记一次宿主面外部收益（只展示，不计入本项目节省）。
+   * @param {{taskId?: string, savedTokens: number, baselineTokens?: number, meta?: object}} input
+   */
+  function record(input = {}) {
+    if (!enabled) return { ok: false, code: 'host-adapter-disabled', message: 'host surface adapter is opt-in; enable it in config' }
+    const saved = finiteNonNegative(input.savedTokens)
+    if (saved === null) return { ok: false, code: 'saved-tokens-invalid', message: 'savedTokens must be a non-negative number' }
+    const appended = ledger.append({
+      account: 'execution',
+      surface: 'host',
+      external: true,
+      module: 'a1-compact',
+      source: 'tool',
+      phase: 'tool',
+      taskId: input.taskId,
+      totalTokens: 0,
+      savedTokens: saved,
+      meta: {
+        ...(input.meta && typeof input.meta === 'object' ? input.meta : {}),
+        adapter: source,
+        external: true,
+        note: 'third-party host-surface saving; shown for comparison only',
+      },
+    })
+    if (!appended.ok) return { ok: false, code: appended.code, message: appended.message }
+    recorded += 1
+    tokensClaimed += saved
+    try { bus?.publish?.('cost.host-surface', { adapter: source, savedTokens: saved, taskId: input.taskId ?? null }) } catch { /* ignore */ }
+    return { ok: true, adapter: source, external: true, savedTokens: saved, ledger: { id: appended.entry.id }, at: now() }
+  }
+
+  function status() {
+    return Object.freeze({
+      ok: true,
+      enabled,
+      adapter: source,
+      /** 明确声明：本适配器不产生本项目收益。 */
+      contributesToOwnSavings: false,
+      recorded,
+      savedTokens: tokensClaimed,
+      note: enabled
+        ? '外部宿主面收益只做对照展示，不计入 executionSaved / netSaved'
+        : '未启用：本设计不依赖任何第三方宿主插件',
+    })
+  }
+
+  return Object.freeze({ record, status })
+}

package/src/cost/index.ts

@@ -0,0 +1,348 @@
+// 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 系统层入口：把 ledger / budget / policy / audit 组装成一个系统。
+ *
+ * `cost-optimizer` 插件通过它拿到统一的记账、预算、灰度与审计口径；
+ * M1 只做 observe（不接入任何替换路径），所以这些组件只被读取与记账，
+ * 不改变 Worker/模型调用行为。
+ */
+
+import { createLedger } from './ledger.ts'
+import { createBudget } from './budget.ts'
+import { createPolicy } from './policy.ts'
+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'
+import { buildLedgerReport, formatLedgerReport, parseLedgerJsonl } from './ledger-report.ts'
+import { buildToolFaceReport, planToolFace } from './toolface.ts'
+import { buildReuseReport, formatReuseReport } from './reuse-report.ts'
+
+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 {{
+ *   mode?: string, allowlist?: string[] | {forks?:string[],tasks?:string[],tags?:string[],tools?:string[]},
+ *   policyScopes?: {global?:string, forks?:Record<string,string>, tasks?:Record<string,string>},
+ *   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 = {}) {
+  const now = typeof options.now === 'function' ? options.now : () => Date.now()
+  const audit = createAuditChain({ now, maxRecords: options.maxRecords })
+  const policy = createPolicy({ mode: options.mode, allowlist: options.allowlist, scopes: options.policyScopes, audit, now })
+  const budget = createBudget({ limits: options.budgetLimits, degradeModels: options.degradeModels, now })
+  const ledger = createLedger({
+    now,
+    maxEntries: options.maxEntries,
+    dataDir: options.dataDir,
+    persist: options.persist === true,
+    logger: options.logger,
+  })
+  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,
+    bus,
+    enabled: options.hostSurface?.enabled === true,
+    source: options.hostSurface?.source,
+    now,
+  })
+  /** 模块降级累计（按模块聚合；不参与节省计算）。 */
+  const degradedByModule = new Map()
+
+  function recordUsage(input = {}) {
+    const out = ledger.append({
+      account: input.account ?? 'execution',
+      module: input.module,
+      source: input.source ?? 'model',
+      phase: input.phase,
+      surface: input.surface,
+      external: input.external,
+      taskId: input.taskId,
+      forkId: input.forkId,
+      sessionId: input.sessionId,
+      ticketId: input.ticketId,
+      turn: input.turn,
+      step: input.step,
+      provider: input.provider,
+      model: input.model,
+      toolName: input.toolName,
+      inputTokens: input.inputTokens,
+      outputTokens: input.outputTokens,
+      cachedTokens: input.cachedTokens,
+      totalTokens: input.totalTokens,
+      baselineTokens: input.baselineTokens,
+      savedTokens: input.savedTokens,
+      estimated: input.estimated,
+      meta: input.meta,
+    })
+    if (out.ok) {
+      bus.publish('cost:event', { kind: 'ledger',
+        id: out.entry.id,
+        account: out.entry.account,
+        module: out.entry.module,
+        phase: out.entry.phase,
+        surface: out.entry.surface,
+        total: out.entry.total,
+        savedTokens: out.entry.savedTokens,
+        taskId: out.entry.taskId,
+        estimated: out.entry.estimated,
+      })
+    }
+    return out
+  }
+
+  /** 按维度查询账本（task/fork/session/module/account/phase/时间窗）。 */
+  function query(filter = {}) {
+    return ledger.query(filter)
+  }
+
+  /** 从 JSONL 回放（进程重启后恢复报表）。 */
+  function replay(direction = 'forward') {
+    return ledger.replay(direction)
+  }
+
+  /**
+   * §8 联动报表：A（单价下降）与 B（跳过调用）分列，governance 摊销后逐任务算净额，
+   * 净亏任务显式列出（不隐藏）。
+   */
+  function savingsReport(input = {}) {
+    const from = input.from === undefined ? undefined : Number(input.from)
+    const to = input.to === undefined ? undefined : Number(input.to)
+    const entries = ledger.query({ limit: Math.max(1, Number(input.limit ?? 5000) || 5000), ...(from === undefined ? {} : { from }), ...(to === undefined ? {} : { to }) }).entries
+    const certificates = audit.substitutions({})
+    return buildSavingsReport({ entries, certificates, amortize: input.amortize })
+  }
+
+  function authorize(input = {}) {
+    const out = budget.authorize(input)
+    if (!out.ok) {
+      try { audit.append({ type: 'budget.denied', actor: 'cost-budget', payload: { ...out } }) } catch { /* ignore */ }
+      bus.publish('cost:event', { kind: 'budget.denied', ...out })
+    } else if (out.degraded) {
+      try { audit.append({ type: 'budget.degraded', actor: 'cost-budget', payload: { ...out } }) } catch { /* ignore */ }
+      bus.publish('cost:event', { kind: 'budget.degraded', ...out })
+    } else {
+      bus.publish('cost:event', { kind: 'budget.authorized', unit: out.unit, key: out.key, consumedTokens: out.consumedTokens, remainingTokens: out.remainingTokens })
+    }
+    return out
+  }
+
+  /** 归因入口：enforce 写账本；shadow 只累计「本可节省」。 */
+  function attribute(input = {}) {
+    const out = attribution.attribute(input)
+    if (out.ok) bus.publish('cost:event', { kind: 'attribution', mode: out.mode, module: out.module, savedTokens: out.savedTokens ?? 0, projectedTokens: out.projectedTokens ?? 0 })
+    return out
+  }
+
+  /** §5.4：总额 − 各模块之和，差额进 unattributed（报表单列）。 */
+  function attributeTotal(input = {}) {
+    const out = attribution.attributeTotal(input)
+    if (out.ok) bus.publish('cost:event', { kind: 'attribution.total', totalSavedTokens: out.totalSavedTokens, attributedTokens: out.attributedTokens, unattributedTokens: out.unattributedTokens })
+    return out
+  }
+
+  /**
+   * §5.5：一次真实替换 = 证书 + 账本事件，两者共用 `taskId + step`。
+   * 任何一步失败都 fail-closed（不写半套）。
+   */
+  function substitute(cert = {}) {
+    const recorded = audit.appendSubstitution(cert)
+    if (!recorded.ok) {
+      bus.publish('cost:event', { kind: 'substitution.rejected', code: recorded.code, taskId: cert?.taskId ?? null })
+      return recorded
+    }
+    let attributed = null
+    if (Number(recorded.cert.savedTokens) > 0) {
+      attributed = attribution.attribute({
+        taskId: recorded.cert.taskId,
+        module: cert.moduleId ?? 'b3-ccs',
+        savedTokens: recorded.cert.savedTokens,
+        mode: 'enforce',
+        forkId: recorded.cert.forkId ?? undefined,
+        sessionId: recorded.cert.sessionId ?? undefined,
+        step: recorded.cert.step,
+        meta: { kind: 'substitution', step: recorded.cert.step, edgeId: recorded.cert.edgeId, replacedCallbackId: recorded.cert.replacedCallbackId },
+      })
+      if (!attributed.ok) return attributed
+    }
+    bus.publish('cost:substitution', {
+      taskId: recorded.cert.taskId,
+      step: recorded.cert.step,
+      edgeId: recorded.cert.edgeId,
+      toolName: recorded.cert.toolName,
+      savedTokens: recorded.cert.savedTokens,
+    })
+    return { ok: true, cert: recorded.cert, attribution: attributed, hash: recorded.record.hash }
+  }
+
+  /**
+   * §5.5：回放「这一省是怎么来的」——按 `taskId + step` 取出证书与账本事件。
+   */
+  function trace({ taskId, step } = {}) {
+    if (taskId === undefined || String(taskId).trim() === '') {
+      return { ok: false, code: 'task-missing', message: 'trace requires taskId' }
+    }
+    const filter = { taskId }
+    if (step !== undefined) filter.step = step
+    const certificates = audit.substitutions(filter)
+    const entries = ledger.query({ taskId, limit: 500 }).entries
+      .filter((entry) => (step === undefined ? true : entry.step === Number(step)))
+    const savedFromCerts = certificates.reduce((sum, cert) => sum + Number(cert.savedTokens ?? 0), 0)
+    // 对账只比「替换产生的账本事件」：其它节省（A1 压缩等）不属于证书口径。
+    const substitutionEntries = entries.filter((entry) => entry.meta?.kind === 'substitution')
+    const savedFromLedger = substitutionEntries.reduce((sum, entry) => sum + entry.savedTokens, 0)
+    const savedFromLedgerAll = entries.reduce((sum, entry) => sum + entry.savedTokens, 0)
+    return Object.freeze({
+      ok: true,
+      taskId: String(taskId),
+      step: step === undefined ? null : Number(step),
+      certificates,
+      entries,
+      /** 两边对账：证书声明的节省应等于**替换账本**记到的节省。 */
+      savedFromCertificates: savedFromCerts,
+      savedFromLedger,
+      /** 任务全部节省（含 A1 等非替换来源），仅展示，不参与对账。 */
+      savedFromLedgerAll,
+      reconciled: savedFromCerts === savedFromLedger,
+    })
+  }
+
+  /**
+   * 降级留痕（目标 2.1-5）：模块异常 → 审计链 + 事件总线 + 计数。
+   * 降级**不计入任何节省**，只用于让报表能区分「真的省了」与「模块挂了」。
+   */
+  function degraded(input = {}) {
+    const module = String(input.module ?? 'unknown')
+    const phase = String(input.phase ?? 'transform')
+    const message = String(input.message ?? '')
+    const count = Math.max(1, Number(input.count ?? 1) || 1)
+    const at = now()
+    const totals = degradedByModule.get(module) ?? { module, events: 0, occurrences: 0, lastAt: 0, phases: {} }
+    totals.events += 1
+    totals.occurrences += count
+    totals.lastAt = at
+    totals.phases[phase] = (totals.phases[phase] ?? 0) + count
+    degradedByModule.set(module, totals)
+    try { audit.append({ type: 'cost.degraded', actor: 'cost-system', payload: { module, phase, message, count, taskId: input.taskId ?? null } }) } catch { /* ignore */ }
+    bus.publish('cost:degraded', { module, phase, message, count, taskId: input.taskId ?? null })
+    return { ok: true, module, phase, count, total: { ...totals, phases: { ...totals.phases } }, at }
+  }
+
+  /**
+   * §10.1 验收指标：七项必须给全；缺项显式报 `complete:false + missing[]`。
+   * 传入 `tasks` / `control` / `guard` / `traceCheck` 才能算出对照与回放检查。
+   */
+  function metrics(input = {}) {
+    const entries = ledger.query({ limit: Math.max(1, Number(input.limit ?? 5000) || 5000) }).entries
+    const certificates = audit.substitutions({})
+    return buildMetricsReport({
+      entries,
+      certificates,
+      tasks: input.tasks,
+      control: input.control,
+      guard: input.guard,
+      audit: { ok: audit.verify().ok },
+      traceCheck: typeof input.traceCheck === 'function' ? input.traceCheck : (taskId) => trace({ taskId }),
+    })
+  }
+
+  /**
+   * M1 交付物：记账报表（估算/实测分列、两本账不合并、外部面单列、unattributed 留位）。
+   */
+  function ledgerReport(input = {}) {
+    const entries = ledger.query({ limit: Math.max(1, Number(input.limit ?? 5000) || 5000), ...(input.from === undefined ? {} : { from: Number(input.from) }), ...(input.to === undefined ? {} : { to: Number(input.to) }) }).entries
+    return buildLedgerReport({ entries, from: input.from, to: input.to, bucketMs: input.bucketMs })
+  }
+
+  function subscribe(listener) {
+    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()
+    const attributionSnapshot = attribution.snapshot()
+    const busSnapshot = bus.snapshot(1)
+    return Object.freeze({
+      ok: true,
+      mode: policy.describe().mode,
+      policy: policy.describe(),
+      /** 三档命中统计（observe 也计数；shadow 落证书；enforce 才替换）。 */
+      policyStats: policy.stats(),
+      ledger: ledgerSnapshot,
+      budget: budget.state(),
+      audit: { ok: auditVerify.ok, count: auditVerify.count, brokenAt: auditVerify.brokenAt },
+      attribution: attributionSnapshot,
+      /* §5.4：模块收益与未归因收益**分开列**，未归因永不算模块业绩。 */
+      attributionSummary: {
+        attributedSavedTotal: attributionSnapshot.attributedSavedTotal,
+        unattributedSavedTotal: attributionSnapshot.unattributedSavedTotal,
+        attributedProjectedTotal: attributionSnapshot.attributedProjectedTotal,
+        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),
+      },
+      /* 报表口径：只把本项目 worker 面的 execution.saved 当节省；governance 与外部适配器并列。 */
+      savings: {
+        executionSaved: ledgerSnapshot.ownExecutionSaved,
+        governanceCost: ledgerSnapshot.governance.total,
+        netSaved: ledgerSnapshot.netSaved,
+        /** 外部（宿主面）插件自报：仅对照，不计入上面的任何数字。 */
+        externalSaved: ledgerSnapshot.externalSaved,
+      },
+      /** 估算 token 与实测 token 分列（不混算）。 */
+      tokens: ledgerSnapshot.tokens,
+      surfaces: ledgerSnapshot.bySurface,
+      hostSurface: hostSurface.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 })
+}