@twinsearth/dsh-master 3.2.10 → 3.3.0

package/src/cost/policy.ts

@@ -0,0 +1,276 @@
+// 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 系统层 · policy（灰度与回滚，设计 §5.3）。
+ *
+ * 三档语义：
+ *   * `observe`  —— 只计量、只计算命中，**绝不替换**（3.2.x 现状，默认档）；
+ *   * `shadow`   —— 决策层真实计算守卫结果并落证书，但**仍调用慢模型**（可对比「本可节省」）；
+ *   * `enforce`  —— 守卫命中才真正替换，且受白名单（forkId / task 标签 / 工具集）限制。
+ *
+ * 粒度：`global → forkId → taskId`，取**最严格**档（observe 最严格，enforce 最宽松）。
+ * 默认 observe；enforce 只能由显式配置或用户指令开启（过门禁，不自动升级）。
+ * 任何时刻都可降级（回滚优先）。
+ */
+
+import { ENFORCE_GATE, POLICY_MODES } from './types.ts'
+
+/** 越靠前越严格（限制越少自动化）。 */
+const STRICTNESS = Object.freeze(['observe', 'shadow', 'enforce'])
+
+function mostRestrictive(modes) {
+  const valid = modes.filter((mode) => POLICY_MODES.includes(mode))
+  if (valid.length === 0) return 'observe'
+  return valid.reduce((strict, current) => (STRICTNESS.indexOf(current) < STRICTNESS.indexOf(strict) ? current : strict))
+}
+
+function normalizeList(input) {
+  const list = Array.isArray(input) ? input : []
+  return Object.freeze([...new Set(list.map((item) => String(item ?? '').trim()).filter(Boolean))])
+}
+
+/**
+ * 归一化白名单：兼容 3.3.0 早期的扁平数组（等价于「forkId 或标签命中」），
+ * 也接受显式四维对象 `{forks, tasks, tags, tools}`。空维度 = 该维度不限制。
+ */
+function normalizeAllowlist(input) {
+  if (Array.isArray(input)) {
+    const flat = normalizeList(input)
+    return Object.freeze({ legacy: true, forks: flat, tasks: Object.freeze([]), tags: flat, tools: Object.freeze([]) })
+  }
+  const source = input && typeof input === 'object' ? input : {}
+  return Object.freeze({
+    legacy: false,
+    forks: normalizeList(source.forks),
+    tasks: normalizeList(source.tasks),
+    tags: normalizeList(source.tags),
+    tools: normalizeList(source.tools),
+  })
+}
+
+/**
+ * @param {{
+ *   mode?: string,
+ *   scopes?: { global?: string, forks?: Record<string,string>, tasks?: Record<string,string> },
+ *   allowlist?: string[] | { forks?: string[], tasks?: string[], tags?: string[], tools?: string[] },
+ *   audit?: { append?: Function },
+ *   now?: () => number,
+ * }} [options]
+ */
+export function createPolicy(options = {}) {
+  const now = typeof options.now === 'function' ? options.now : () => Date.now()
+  const audit = options.audit && typeof options.audit.append === 'function' ? options.audit : null
+  const allowlist = normalizeAllowlist(options.allowlist)
+  const requestedMode = String(options.mode ?? 'observe')
+  let mode = POLICY_MODES.includes(requestedMode) ? requestedMode : 'observe'
+  let lastRefusal = null
+
+  const scopes = options.scopes && typeof options.scopes === 'object' ? options.scopes : {}
+  const forkScopes = scopes.forks && typeof scopes.forks === 'object' ? { ...scopes.forks } : {}
+  const taskScopes = scopes.tasks && typeof scopes.tasks === 'object' ? { ...scopes.tasks } : {}
+
+  /** 命中计数（observe 也要算，不然「灰度」无从判断）。 */
+  const hits = new Map()
+  const CERTIFICATE_LIMIT = 200
+  const certificates = []
+
+  const record = (type, payload) => {
+    try { audit?.append({ type, actor: 'cost-policy', payload }) } catch { /* 审计失败不改变策略行为 */ }
+  }
+
+  /** 解析当前上下文的生效档：global → fork → task，取最严格。 */
+  function resolve(context = {}) {
+    const forkId = String(context.forkId ?? '')
+    const taskId = String(context.taskId ?? '')
+    const layers = [{ scope: 'global', mode }]
+    if (forkId && POLICY_MODES.includes(String(forkScopes[forkId]))) {
+      layers.push({ scope: 'fork', mode: String(forkScopes[forkId]) })
+    }
+    if (taskId && POLICY_MODES.includes(String(taskScopes[taskId]))) {
+      layers.push({ scope: 'task', mode: String(taskScopes[taskId]) })
+    }
+    const effective = mostRestrictive(layers.map((layer) => layer.mode))
+    return Object.freeze({
+      mode: effective,
+      decidedBy: layers.find((layer) => layer.mode === effective)?.scope ?? 'global',
+      layers,
+    })
+  }
+
+  /** enforce 是否被白名单放行（forkId / taskId / tags / toolName 四个维度，非空维度必须命中）。 */
+  function allowlisted(context = {}) {
+    const forkId = String(context.forkId ?? '')
+    const taskId = String(context.taskId ?? '')
+    const tags = Array.isArray(context.tags) ? context.tags.map((tag) => String(tag)) : []
+    const toolName = String(context.toolName ?? '')
+    if (allowlist.legacy) {
+      if (allowlist.forks.length === 0) return { ok: false, reason: 'allowlist-empty' }
+      const matched = (forkId !== '' && allowlist.forks.includes(forkId)) || tags.some((tag) => allowlist.tags.includes(tag))
+      return matched ? { ok: true, reason: null } : { ok: false, reason: 'allowlist-miss' }
+    }
+    if (allowlist.forks.length === 0 && allowlist.tasks.length === 0 && allowlist.tags.length === 0 && allowlist.tools.length === 0) {
+      return { ok: false, reason: 'allowlist-empty' }
+    }
+    if (allowlist.forks.length > 0 && !(forkId !== '' && allowlist.forks.includes(forkId))) return { ok: false, reason: 'fork-not-allowlisted' }
+    if (allowlist.tasks.length > 0 && !(taskId !== '' && allowlist.tasks.includes(taskId))) return { ok: false, reason: 'task-not-allowlisted' }
+    if (allowlist.tags.length > 0 && !tags.some((tag) => allowlist.tags.includes(tag))) return { ok: false, reason: 'tag-not-allowlisted' }
+    if (allowlist.tools.length > 0 && !(toolName !== '' && allowlist.tools.includes(toolName))) return { ok: false, reason: 'tool-not-allowlisted' }
+    return { ok: true, reason: null }
+  }
+
+  /**
+   * 决策复用模块在守卫「命中」时调用（B1/B2/B3 都会经过这里）。
+   *   observe —— 只计数；
+   *   shadow  —— 计数 + 落证书（记录本可节省），**不替换**；
+   *   enforce —— 计数 + 落证书 + 允许替换（还需白名单命中）。
+   */
+  function recordHit(input = {}) {
+    const context = { forkId: input.forkId, taskId: input.taskId, tags: input.tags, toolName: input.toolName }
+    const resolved = resolve(context)
+    const key = `${resolved.mode}:${String(input.module ?? 'unattributed')}`
+    const row = hits.get(key) ?? { mode: resolved.mode, module: String(input.module ?? 'unattributed'), hits: 0, wouldSaveTokens: 0, substituted: 0 }
+    row.hits += 1
+    row.wouldSaveTokens += Math.max(0, Number(input.wouldSaveTokens ?? 0) || 0)
+    hits.set(key, row)
+
+    let certificate = null
+    if (resolved.mode === 'observe') {
+      return Object.freeze({ ok: true, mode: 'observe', substituted: false, counted: true, certificate: null, resolved })
+    }
+    const allowed = resolved.mode === 'enforce' ? allowlisted(context) : { ok: false, reason: 'shadow-does-not-substitute' }
+    const substituted = resolved.mode === 'enforce' && allowed.ok
+    if (substituted) row.substituted += 1
+    certificate = Object.freeze({
+      at: now(),
+      module: String(input.module ?? 'unattributed'),
+      guardId: input.guardId === undefined ? null : String(input.guardId),
+      edgeId: input.edgeId === undefined ? null : String(input.edgeId),
+      receiptHash: input.receiptHash === undefined ? null : String(input.receiptHash),
+      mode: resolved.mode,
+      substituted,
+      wouldSaveTokens: Math.max(0, Number(input.wouldSaveTokens ?? 0) || 0),
+      allowlist: allowed.ok ? 'matched' : allowed.reason,
+    })
+    certificates.push(certificate)
+    if (certificates.length > CERTIFICATE_LIMIT) certificates.shift()
+    record('policy.hit', { ...certificate })
+    return Object.freeze({
+      ok: true,
+      mode: resolved.mode,
+      substituted,
+      counted: true,
+      certificate,
+      resolved,
+      allowlist: allowed,
+    })
+  }
+
+  function describe() {
+    return Object.freeze({
+      mode,
+      requestedMode,
+      scopes: Object.freeze({ global: mode, forks: Object.freeze({ ...forkScopes }), tasks: Object.freeze({ ...taskScopes }) }),
+      allowlist: Object.freeze({
+        legacy: allowlist.legacy,
+        forks: allowlist.forks.slice(),
+        tasks: allowlist.tasks.slice(),
+        tags: allowlist.tags.slice(),
+        tools: allowlist.tools.slice(),
+      }),
+      gate: { minAccuracy: ENFORCE_GATE.minAccuracy, minSamples: ENFORCE_GATE.minSamples, allowlistRequired: true },
+      lastRefusal,
+    })
+  }
+
+  function canEnforce(context = {}) {
+    if (resolve(context).mode !== 'enforce') return false
+    return allowlisted(context).ok
+  }
+
+  function requestMode(next, evidence = {}) {
+    const target = String(next)
+    if (!POLICY_MODES.includes(target)) {
+      return { ok: false, code: 'mode-invalid', message: `mode must be one of ${POLICY_MODES.join('/')}` }
+    }
+    if (target === mode) return { ok: true, mode, unchanged: true, at: now() }
+    const from = mode
+
+    if (target === 'enforce') {
+      const reasons = []
+      if (from === 'observe' && evidence.force !== true) reasons.push('shadow-required')
+      const accuracy = Number(evidence.accuracy)
+      if (!Number.isFinite(accuracy) || accuracy < ENFORCE_GATE.minAccuracy) reasons.push('accuracy-below-threshold')
+      const samples = Number(evidence.samples)
+      if (!Number.isFinite(samples) || samples < ENFORCE_GATE.minSamples) reasons.push('samples-below-threshold')
+      const destructiveHits = Number(evidence.destructiveHits ?? 0)
+      if (!Number.isFinite(destructiveHits) || destructiveHits > 0) reasons.push('destructive-hits')
+      const allowlistEmpty = allowlist.legacy
+        ? allowlist.forks.length === 0
+        : allowlist.forks.length === 0 && allowlist.tasks.length === 0 && allowlist.tags.length === 0 && allowlist.tools.length === 0
+      if (allowlistEmpty) reasons.push('allowlist-empty')
+      if (reasons.length > 0) {
+        lastRefusal = Object.freeze({ at: now(), next: target, reasons })
+        record('policy.refused', { from, to: target, reasons })
+        return { ok: false, code: 'enforce-gate-failed', reasons, mode, at: lastRefusal.at }
+      }
+    }
+
+    mode = target
+    lastRefusal = null
+    record('policy.mode', { from, to: target, evidence: { ...evidence } })
+    return { ok: true, mode, from, at: now() }
+  }
+
+  function setMode(next) {
+    const target = String(next)
+    if (!POLICY_MODES.includes(target)) {
+      return { ok: false, code: 'mode-invalid', message: `mode must be one of ${POLICY_MODES.join('/')}` }
+    }
+    if (target === mode) return { ok: true, mode, unchanged: true }
+    const from = mode
+    mode = target
+    record('policy.rollback', { from, to: target })
+    return { ok: true, mode, from }
+  }
+
+  /** 设置某个 fork / task 的档位（只能更严格或经 enforce 门禁前先下沉）。 */
+  function setScope(scope, id, next) {
+    const target = String(next)
+    if (!POLICY_MODES.includes(target)) {
+      return { ok: false, code: 'mode-invalid', message: `mode must be one of ${POLICY_MODES.join('/')}` }
+    }
+    const key = String(id ?? '').trim()
+    if (!key) return { ok: false, code: 'scope-id-invalid', message: 'scope id must be a non-empty string' }
+    if (scope === 'fork') forkScopes[key] = target
+    else if (scope === 'task') taskScopes[key] = target
+    else return { ok: false, code: 'scope-invalid', message: 'scope must be fork or task' }
+    record('policy.scope', { scope, id: key, to: target })
+    return { ok: true, scope, id: key, mode: target }
+  }
+
+  function stats() {
+    return Object.freeze({
+      ok: true,
+      rows: [...hits.values()].map((row) => Object.freeze({ ...row })),
+      totalHits: [...hits.values()].reduce((sum, row) => sum + row.hits, 0),
+      totalWouldSaveTokens: [...hits.values()].reduce((sum, row) => sum + row.wouldSaveTokens, 0),
+      totalSubstituted: [...hits.values()].reduce((sum, row) => sum + row.substituted, 0),
+      certificates: certificates.slice(-50),
+    })
+  }
+
+  return Object.freeze({
+    describe,
+    resolve,
+    allowlisted,
+    recordHit,
+    stats,
+    canEnforce,
+    requestMode,
+    setMode,
+    setScope,
+    isEnforce: (context = {}) => resolve(context).mode === 'enforce',
+  })
+}

package/src/cost/report.ts

@@ -0,0 +1,158 @@
+// 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 系统层 · report（两条链路联动报表，设计 §8）。
+ *
+ * 两条链路的节省**必须分列、且不重复计**：
+ *
+ *   * **单价项（A）**：A1 压缩回执 → 每次交互更便宜。来源 = execution 账里 `phase:'tool'`
+ *     的压缩归因条目（`meta.kind` 为 attribution）。
+ *   * **次数项（B）**：B2/B3 命中 → 少调一次模型。来源 = **替换证书**（不是账本），
+ *     每个 dispatched 证书代表一次被跳过的回调，金额 = 该证书的 `savedTokens`（基线单价）。
+ *
+ * 总节省 = Σ(跳过的调用数 × 该步基线单价) + Σ(每次交互的单价下降)，两项分列。
+ *
+ * 作者的代价必须摊进去：EDG 编写与 RSI 离线成本都在 governance 账；
+ * 若某任务 `execution 节省 < governance 摊销`，该任务记为**净亏**并显式列出，不隐藏。
+ */
+
+function num(value) {
+  const n = Number(value)
+  return Number.isFinite(n) ? n : 0
+}
+
+const nonNegative = (value) => Math.max(0, num(value))
+
+/**
+ * 判定某条账本事件属于哪一列（互斥）：
+ *   * B 列**只认证书**：替换产生的账本事件（`meta.kind === 'substitution'`）单列出来，
+ *     既不进 A 也不进 B —— 否则同一次节省会被证书与账本各算一遍；
+ *   * A 列只认 execution + tool 相位 + 非外部（external 是宿主面插件收益，单列）。
+ */
+export function classifyEntry(entry) {
+  if (!entry || entry.account !== 'execution') return 'governance'
+  if (entry.external === true) return 'external'
+  if (entry.meta?.kind === 'substitution') return 'skipped-call-ledger'
+  if (entry.phase === 'tool' && entry.savedTokens > 0) return 'unit-price'
+  if (entry.savedTokens > 0) return 'other-execution'
+  return 'consumption'
+}
+
+/**
+ * @param {{
+ *   entries?: object[],
+ *   certificates?: object[],
+ *   amortize?: 'even' | 'per-task',
+ *   moduleOf?: (entry: object) => string,
+ * }} input
+ */
+export function buildSavingsReport(input = {}) {
+  const entries = Array.isArray(input.entries) ? input.entries : []
+  const certificates = Array.isArray(input.certificates) ? input.certificates : []
+  const amortize = input.amortize === 'per-task' ? 'per-task' : 'even'
+
+  // ---- 列 A：单价下降（A1 回执压缩） ----
+  const unitPrice = { savedTokens: 0, interactions: 0, byModule: {}, byTask: {} }
+  // ---- 列 B：跳过调用（B2/B3 复用） ----
+  const skippedCalls = { savedTokens: 0, calls: 0, byTool: {}, byTask: {} }
+  // ---- 治理成本（作者 + 离线） ----
+  const governance = { totalTokens: 0, byKind: {}, byTask: {} }
+  // ---- 其它（消耗、外部）----
+  const consumption = { tokens: 0, entries: 0 }
+  const externalSaved = 0
+
+  for (const entry of entries) {
+    const bucket = classifyEntry(entry)
+    if (bucket === 'governance') {
+      const tokens = nonNegative(entry.total)
+      governance.totalTokens += tokens
+      const kind = String(entry.meta?.kind ?? entry.source ?? 'governance')
+      governance.byKind[kind] = (governance.byKind[kind] ?? 0) + tokens
+      const taskKey = entry.taskId ?? 'unattributed'
+      governance.byTask[taskKey] = (governance.byTask[taskKey] ?? 0) + tokens
+      continue
+    }
+    if (bucket === 'unit-price') {
+      const saved = nonNegative(entry.savedTokens)
+      unitPrice.savedTokens += saved
+      unitPrice.interactions += 1
+      const moduleKey = String(entry.module ?? 'unattributed')
+      unitPrice.byModule[moduleKey] = (unitPrice.byModule[moduleKey] ?? 0) + saved
+      const taskKey = entry.taskId ?? 'unattributed'
+      unitPrice.byTask[taskKey] = (unitPrice.byTask[taskKey] ?? 0) + saved
+      continue
+    }
+    if (bucket === 'consumption') {
+      consumption.tokens += nonNegative(entry.total)
+      consumption.entries += 1
+    }
+  }
+
+  // B 列：只来自证书，且只算真正派发成功的
+  for (const cert of certificates) {
+    if (cert?.dispatched === false) continue
+    const saved = nonNegative(cert?.savedTokens)
+    skippedCalls.calls += 1
+    skippedCalls.savedTokens += saved
+    const tool = String(cert?.toolName ?? 'unknown')
+    skippedCalls.byTool[tool] = (skippedCalls.byTool[tool] ?? 0) + saved
+    const taskKey = cert?.taskId ?? 'unattributed'
+    skippedCalls.byTask[taskKey] = (skippedCalls.byTask[taskKey] ?? 0) + saved
+  }
+
+  // ---- 任务级净额：execution 节省（A+B） − governance 摊销 ----
+  const taskIds = [...new Set([
+    ...Object.keys(unitPrice.byTask),
+    ...Object.keys(skippedCalls.byTask),
+    ...Object.keys(governance.byTask),
+  ])].filter((taskId) => taskId !== 'unattributed').sort()
+  const amortized = {}
+  if (amortize === 'even') {
+    // RSI/离线等无法落到具体任务的成本，按任务数均摊（显式声明策略）。
+    const shared = governance.byTask.unattributed ?? 0
+    const perTask = taskIds.length > 0 ? shared / taskIds.length : 0
+    for (const taskId of taskIds) amortized[taskId] = (governance.byTask[taskId] ?? 0) + perTask
+  } else {
+    for (const taskId of taskIds) amortized[taskId] = governance.byTask[taskId] ?? 0
+  }
+
+  const tasks = taskIds.map((taskId) => {
+    const executionSaved = (unitPrice.byTask[taskId] ?? 0) + (skippedCalls.byTask[taskId] ?? 0)
+    const governanceAmortized = amortized[taskId] ?? 0
+    const net = executionSaved - governanceAmortized
+    return {
+      taskId,
+      executionSaved,
+      unitPriceSaved: unitPrice.byTask[taskId] ?? 0,
+      skippedCallSaved: skippedCalls.byTask[taskId] ?? 0,
+      governanceAmortized,
+      net,
+      /** §8：净亏任务必须显示，不隐藏。 */
+      netLoss: net < 0,
+    }
+  })
+  const netLossTasks = tasks.filter((task) => task.netLoss)
+
+  const totalSavedTokens = unitPrice.savedTokens + skippedCalls.savedTokens
+  return Object.freeze({
+    ok: true,
+    amortize,
+    /** 两项分列——报表必须分别展示，禁止只报合计。 */
+    columns: Object.freeze({
+      unitPrice: Object.freeze({ ...unitPrice, byModule: { ...unitPrice.byModule }, byTask: { ...unitPrice.byTask } }),
+      skippedCalls: Object.freeze({ ...skippedCalls, byTool: { ...skippedCalls.byTool }, byTask: { ...skippedCalls.byTask } }),
+    }),
+    totalSavedTokens,
+    governance: Object.freeze({ ...governance, byKind: { ...governance.byKind }, byTask: { ...governance.byTask } }),
+    consumption: Object.freeze({ ...consumption }),
+    /** 宿主面外部插件自报收益：只展示，永不并入总节省。 */
+    externalSaved,
+    /** A/B 两列来源互斥（A=账本、B=证书），结构上不可能重复计。 */
+    doubleCountGuard: true,
+    tasks: Object.freeze(tasks.map((task) => Object.freeze(task))),
+    netLossTasks: Object.freeze(netLossTasks.map((task) => Object.freeze(task))),
+    netSaved: totalSavedTokens - governance.totalTokens,
+  })
+}

package/src/cost/reuse-report.ts

@@ -0,0 +1,131 @@
+// 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 · M3 交付物：**命中率与「本可节省」报表**（B1 EDG + B2 GDR，shadow 只算不替换）。
+ *
+ * 口径纪律（M3 最关键的一条）：
+ *
+ *   * **shadow 的节省是「本可节省」，不是节省**。报表字段名就叫 `wouldSaveTokens`，
+ *     并且 `actualSavedTokens` 在 shadow 下恒为 0；
+ *   * **分母是「每次复用尝试」**，不是每次工具调用、也不是每个任务；
+ *   * 未命中必须给原因分布（`schema-drift` / `guard-miss` / `arg-unextractable` …），
+ *     这是 RSI（B4）唯一能拿来做改进的输入；
+ *   * shadow 证书**不进审计链**（它们没有派发，没有 native dispatcher 证据）。
+ */
+
+export const GDR_REASONS = Object.freeze([
+  'no-edge',
+  'tool-mismatch',
+  'schema-drift',
+  'dependency-incomplete',
+  'guard-miss',
+  'arg-unextractable',
+])
+
+const num = (value) => {
+  const n = Number(value)
+  return Number.isFinite(n) && n >= 0 ? n : 0
+}
+
+/**
+ * M3 报表。
+ *
+ * @param {{
+ *   attempts?: Array<{toolName?: string, hit?: boolean, reason?: string | null, stage?: string | null, edgeId?: string | null, wouldSaveTokens?: number}>,
+ *   shadowCertificates?: Array<object>,
+ *   substitutions?: Array<object>,
+ *   mode?: 'off' | 'shadow' | 'enforce',
+ * }} input
+ */
+export function buildReuseReport(input = {}) {
+  const attempts = Array.isArray(input.attempts) ? input.attempts : []
+  const shadowCertificates = Array.isArray(input.shadowCertificates) ? input.shadowCertificates : []
+  const substitutions = Array.isArray(input.substitutions) ? input.substitutions : []
+  const mode = input.mode === 'enforce' ? 'enforce' : input.mode === 'off' ? 'off' : 'shadow'
+
+  const byReason = Object.fromEntries(GDR_REASONS.map((reason) => [reason, 0]))
+  const byTool = {}
+  const byStage = {}
+  let hits = 0
+  let wouldSaveTokens = 0
+
+  for (const attempt of attempts) {
+    const toolName = String(attempt?.toolName ?? 'unknown')
+    if (!byTool[toolName]) byTool[toolName] = { attempts: 0, hits: 0, wouldSaveTokens: 0 }
+    const row = byTool[toolName]
+    row.attempts += 1
+    if (attempt?.hit === true) {
+      hits += 1
+      row.hits += 1
+      const wouldSave = num(attempt?.wouldSaveTokens)
+      wouldSaveTokens += wouldSave
+      row.wouldSaveTokens += wouldSave
+    } else {
+      const reason = String(attempt?.reason ?? 'guard-miss')
+      if (reason in byReason) byReason[reason] += 1
+      else byReason['guard-miss'] += 1
+      const stage = String(attempt?.stage ?? 'unknown')
+      byStage[stage] = (byStage[stage] ?? 0) + 1
+    }
+  }
+
+  const total = attempts.length
+  const hitRate = total > 0 ? hits / total : 0
+  // shadow 与 enforce 的节省口径必须分开：shadow 的命中只是「本可替换」
+  const dispatchedSubstitutions = substitutions.filter((cert) => cert?.dispatched === true)
+  const actualSavedTokens = mode === 'enforce'
+    ? dispatchedSubstitutions.reduce((sum, cert) => sum + num(cert?.savedTokens), 0)
+    : 0
+
+  return Object.freeze({
+    ok: true,
+    mode,
+    attempts: total,
+    hits,
+    hitRate,
+    /** 分母口径写进报表，避免被误读成「每次工具调用的命中率」。 */
+    denominator: 'reuse-attempts',
+    byReason: Object.freeze({ ...byReason }),
+    byStage: Object.freeze({ ...byStage }),
+    byTool: Object.freeze(Object.fromEntries(Object.entries(byTool).map(([key, row]) => [key, Object.freeze({ ...row })]))),
+    /** M3 的核心数字：shadow 下的「本可节省」。 */
+    wouldSaveTokens,
+    /** 真正派发成功的替换节省；shadow 恒为 0，绝不会把「本可」写成「已省」。 */
+    actualSavedTokens,
+    shadowCertificates: shadowCertificates.length,
+    shadowCertificateDispatched: shadowCertificates.filter((cert) => cert?.dispatched === true).length,
+    substitutions: dispatchedSubstitutions.length,
+    /** 三档语义：shadow 只算不替换；enforce 才可能真的替换成功。 */
+    discipline: Object.freeze({
+      shadowNeverBooksSavings: mode === 'shadow' ? actualSavedTokens === 0 : true,
+      shadowCertificatesNotAudited: shadowCertificates.every((cert) => cert?.dispatched !== true),
+      denominatorIsAttempts: true,
+    }),
+    /** 数据不足时的诚实提示（样本太小不能下结论）。 */
+    sufficiency: Object.freeze({
+      samples: total,
+      enoughForConclusion: total >= 20,
+      note: total >= 20 ? null : '样本不足 20：命中率尚不足以下结论',
+    }),
+  })
+}
+
+/** 人读行（CLI / 面板共用）。 */
+export function formatReuseReport(report) {
+  const lines = []
+  lines.push(`复用报表（${report.mode}）  尝试 ${report.attempts} · 命中 ${report.hits} · 命中率 ${(report.hitRate * 100).toFixed(1)}%`)
+  lines.push(`本可节省 ${report.wouldSaveTokens} tokens · 实际节省 ${report.actualSavedTokens} tokens`)
+  lines.push(`shadow 证书 ${report.shadowCertificates}（未派发 ${report.shadowCertificates - report.shadowCertificateDispatched}）· 真实替换 ${report.substitutions}`)
+  lines.push('')
+  lines.push('未命中原因分布')
+  for (const [reason, count] of Object.entries(report.byReason)) lines.push(`  ${reason.padEnd(22)} ${count}`)
+  lines.push('')
+  lines.push('按工具')
+  for (const [tool, row] of Object.entries(report.byTool)) {
+    lines.push(`  ${tool.padEnd(20)} 尝试 ${row.attempts} · 命中 ${row.hits} · 本可节省 ${row.wouldSaveTokens}`)
+  }
+  if (report.sufficiency.note) lines.push(`\n注意：${report.sufficiency.note}`)
+  return lines.join('\n')
+}