@twinsearth/dsh-master 3.2.10 → 3.3.0

package/src/cost/rsi.ts

@@ -0,0 +1,364 @@
+// 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 · B4 `rsi`（离线递归自改进，设计 §7）。
+ *
+ * **位置：离线**。本文件不属于 Worker 热路径，不 import 任何 worker 模块，
+ * 也不会被插件 `apply()` 调用 —— 它只在运维侧被显式执行（见 `scripts/rsi-offline.mjs`）。
+ *
+ * 输入（全部来自已落库的事实）：
+ *   * ledger 快照（`status().ledger`）—— 省了多少、哪些模块、估算占比；
+ *   * 替换证书（`audit.substitutions()`）—— 哪些边真的被复用；
+ *   * 失败原因分布（`WorkerResult.cost.ccs.guard.byReason` 汇总）—— 为什么没命中。
+ *
+ * 产物（**候选配置**）：
+ *   * `guard-relax`     —— 守卫表达式调整（针对 guard-miss 集中处）；
+ *   * `template-add`    —— 把反复出现的成功边固化成模板；
+ *   * `guidance-rewrite`—— 批量/披露教学文案改写（针对 shape 纠偏次数）。
+ *
+ * 纪律：
+ *   * 每个候选**必须**过验证集打分（`score()`），未达阈值**不得冻结**；
+ *   * `freeze()` 产出冻结清单条目（含输入摘要 + 打分 + 阈值 + 时间），
+ *     **冻结后才允许被 active 使用**；
+ *   * 报表把「候选」与「基线」放在同一张表里对比，禁止只报候选的漂亮数字；
+ *   * 3.3.0 只交付**可复现的离线流程 + 冻结清单**，不做自动上线。
+ */
+
+import crypto from 'node:crypto'
+
+/* ------------------------------------------------------------------ *
+ * 输入归一化（可复现的关键：一切排序 + 稳定序列化）
+ * ------------------------------------------------------------------ */
+
+function canonical(value) {
+  if (Array.isArray(value)) return `[${value.map((item) => canonical(item)).join(',')}]`
+  if (value && typeof value === 'object') {
+    const keys = Object.keys(value).sort()
+    return `{${keys.map((key) => `${JSON.stringify(key)}:${canonical(value[key])}`).join(',')}}`
+  }
+  if (typeof value === 'number') return Number.isFinite(value) ? String(value) : 'null'
+  if (value === undefined) return 'null'
+  return JSON.stringify(value) ?? 'null'
+}
+
+export function digestOf(value) {
+  return `sha256:${crypto.createHash('sha256').update(canonical(value)).digest('hex')}`
+}
+
+const MISS_REASONS = Object.freeze([
+  'no-edge',
+  'tool-mismatch',
+  'schema-drift',
+  'dependency-incomplete',
+  'guard-miss',
+  'arg-unextractable',
+])
+
+/**
+ * @param {{
+ *   ledger?: object, certificates?: object[], guardStats?: {byReason?: object, matches?: number, hits?: number},
+ *   corrections?: number, generatedAt?: number,
+ * }} input
+ */
+export function normalizeInput(input = {}) {
+  const byReason = {}
+  for (const reason of MISS_REASONS) byReason[reason] = Math.max(0, Number(input?.guardStats?.byReason?.[reason] ?? 0) || 0)
+  const certificates = (Array.isArray(input?.certificates) ? input.certificates : [])
+    .map((cert) => ({
+      edgeId: String(cert?.edgeId ?? ''),
+      toolName: String(cert?.toolName ?? ''),
+      guardExpr: String(cert?.guardExpr ?? ''),
+      dispatched: cert?.dispatched !== false,
+      savedTokens: Math.max(0, Number(cert?.savedTokens ?? 0) || 0),
+    }))
+    .sort((a, b) => `${a.edgeId}|${a.toolName}`.localeCompare(`${b.edgeId}|${b.toolName}`))
+  return {
+    ledger: {
+      ownExecutionSaved: Math.max(0, Number(input?.ledger?.ownExecutionSaved ?? 0) || 0),
+      governanceTotal: Math.max(0, Number(input?.ledger?.governance?.total ?? 0) || 0),
+      measuredTokens: Math.max(0, Number(input?.ledger?.tokens?.measuredTokens ?? 0) || 0),
+      estimatedTokens: Math.max(0, Number(input?.ledger?.tokens?.estimatedTokens ?? 0) || 0),
+    },
+    certificates,
+    guardStats: {
+      matches: Math.max(0, Number(input?.guardStats?.matches ?? 0) || 0),
+      hits: Math.max(0, Number(input?.guardStats?.hits ?? 0) || 0),
+      byReason,
+    },
+    corrections: Math.max(0, Number(input?.corrections ?? 0) || 0),
+    generatedAt: Number(input?.generatedAt ?? 0) || 0,
+  }
+}
+
+/* ------------------------------------------------------------------ *
+ * 分析 → 候选配置
+ * ------------------------------------------------------------------ */
+
+export function analyze(input = {}) {
+  const data = normalizeInput(input)
+  const total = data.guardStats.matches
+  const hits = data.guardStats.hits
+  const hitRate = total > 0 ? hits / total : 0
+  const findings = []
+
+  const reason = (name) => data.guardStats.byReason[name] ?? 0
+  if (reason('guard-miss') > 0) findings.push({ key: 'guard-miss', count: reason('guard-miss'), note: '守卫过严或回执形态变化' })
+  if (reason('arg-unextractable') > 0) findings.push({ key: 'arg-unextractable', count: reason('arg-unextractable'), note: '参数来源无法确定性提取' })
+  if (reason('schema-drift') > 0) findings.push({ key: 'schema-drift', count: reason('schema-drift'), note: '工具 schema 变更导致旧图作废' })
+  if (reason('tool-mismatch') > 0 || reason('no-edge') > 0) findings.push({ key: 'coverage-gap', count: reason('tool-mismatch') + reason('no-edge'), note: '图里缺边' })
+  if (reason('dependency-incomplete') > 0) findings.push({ key: 'dependency-incomplete', count: reason('dependency-incomplete'), note: '依赖链过长' })
+  if (data.corrections > 0) findings.push({ key: 'batch-shape', count: data.corrections, note: '批量形状纠偏触发' })
+
+  return Object.freeze({
+    ok: true,
+    inputDigest: digestOf(data),
+    data,
+    baseline: Object.freeze({
+      hitRate,
+      matches: total,
+      hits,
+      savedTokens: data.ledger.ownExecutionSaved,
+      governanceTokens: data.ledger.governanceTotal,
+      estimatedRatio: data.ledger.measuredTokens + data.ledger.estimatedTokens > 0
+        ? data.ledger.estimatedTokens / (data.ledger.measuredTokens + data.ledger.estimatedTokens)
+        : 0,
+    }),
+    findings: findings.sort((a, b) => b.count - a.count || a.key.localeCompare(b.key)),
+  })
+}
+
+/**
+ * 从分析结果生成**候选配置**（只提案，不生效）。
+ * 每个候选都带 `requiresValidation: true`，未过验证集不得冻结。
+ */
+export function proposeCandidates(analysis) {
+  const findings = Array.isArray(analysis?.findings) ? analysis.findings : []
+  const certificates = Array.isArray(analysis?.data?.certificates) ? analysis.data.certificates : []
+  const candidates = []
+
+  const guardMiss = findings.find((item) => item.key === 'guard-miss')
+  if (guardMiss) {
+    candidates.push({
+      id: 'cand_guard_relax',
+      kind: 'guard-relax',
+      rationale: `guard-miss ${guardMiss.count} 次：守卫过于严格`,
+      change: { action: 'relax-guard', target: 'edges-with-frequent-guard-miss', note: '把 equals 放宽为 regex，或增加 negate 分支' },
+      risk: 'high',
+      requiresValidation: true,
+    })
+  }
+  const unextractable = findings.find((item) => item.key === 'arg-unextractable')
+  if (unextractable) {
+    candidates.push({
+      id: 'cand_arg_source',
+      kind: 'guard-relax',
+      rationale: `arg-unextractable ${unextractable.count} 次：参数来源不可确定性提取`,
+      change: { action: 'switch-arg-source', from: 'literal', to: 'jsonpath', note: '改用回执里稳定出现的字段' },
+      risk: 'medium',
+      requiresValidation: true,
+    })
+  }
+  // 反复成功的边 → 固化为模板
+  const successByEdge = new Map()
+  for (const cert of certificates) {
+    if (!cert.dispatched) continue
+    const key = `${cert.edgeId}|${cert.toolName}|${cert.guardExpr}`
+    successByEdge.set(key, (successByEdge.get(key) ?? 0) + Math.max(1, cert.savedTokens > 0 ? 1 : 0))
+  }
+  const repeatable = [...successByEdge.entries()].filter(([, count]) => count >= 2).sort((a, b) => b[1] - a[1] || a[0].localeCompare(b[0]))
+  if (repeatable.length > 0) {
+    candidates.push({
+      id: 'cand_template_add',
+      kind: 'template-add',
+      rationale: `${repeatable.length} 条边被重复复用 ≥2 次，值得固化进模板库`,
+      change: { action: 'add-templates', edges: repeatable.map(([key]) => key.split('|')[0]) },
+      risk: 'low',
+      requiresValidation: true,
+    })
+  }
+  if (findings.some((item) => item.key === 'batch-shape')) {
+    candidates.push({
+      id: 'cand_guidance',
+      kind: 'guidance-rewrite',
+      rationale: '批量形状纠偏仍在触发，教学文案可再收紧',
+      change: { action: 'rewrite-guidance', target: 'tool-batch.guidance', note: '把反例写得更具体' },
+      risk: 'low',
+      requiresValidation: true,
+    })
+  }
+  return Object.freeze(candidates.sort((a, b) => a.id.localeCompare(b.id)))
+}
+
+/* ------------------------------------------------------------------ *
+ * 验证集打分 → 冻结
+ * ------------------------------------------------------------------ */
+
+const DEFAULT_THRESHOLDS = Object.freeze({ minAccuracy: 0.98, maxDestructiveHits: 0, minSamples: 20 })
+
+/**
+ * 用验证集给候选打分。验证集必须**独立于**生成候选的样本（调用方保证）。
+ * @param {{candidate: object, validation: {samples?: number, correct?: number, destructiveHits?: number, savedTokens?: number}}} input
+ */
+export function score(input = {}) {
+  const candidate = input?.candidate
+  if (!candidate || !candidate.id) return { ok: false, code: 'candidate-invalid', message: 'candidate with id required' }
+  const samples = Math.max(0, Number(input?.validation?.samples ?? 0) || 0)
+  const correct = Math.max(0, Number(input?.validation?.correct ?? 0) || 0)
+  const destructiveHits = Math.max(0, Number(input?.validation?.destructiveHits ?? 0) || 0)
+  const savedTokens = Math.max(0, Number(input?.validation?.savedTokens ?? 0) || 0)
+  if (correct > samples) return { ok: false, code: 'validation-invalid', message: 'correct cannot exceed samples' }
+  const accuracy = samples > 0 ? correct / samples : 0
+  return {
+    ok: true,
+    candidateId: String(candidate.id),
+    samples,
+    correct,
+    accuracy,
+    destructiveHits,
+    savedTokens,
+    scoredAt: Date.now(),
+  }
+}
+
+/**
+ * 冻结：**未达阈值一律拒绝**。产出冻结清单条目（含输入摘要，可复现核对）。
+ * @param {{candidate: object, score: object, analysis: object, thresholds?: object, now?: () => number}} input
+ */
+export function freeze(input = {}) {
+  const candidate = input?.candidate
+  const scoreValue = input?.score
+  const analysis = input?.analysis
+  if (!candidate?.id) return { ok: false, code: 'candidate-invalid', message: 'candidate with id required' }
+  if (!scoreValue || scoreValue.ok !== true) return { ok: false, code: 'score-missing', message: 'candidate must be scored before freezing' }
+  const thresholds = { ...DEFAULT_THRESHOLDS, ...(input?.thresholds ?? {}) }
+  const reasons = []
+  if (scoreValue.samples < thresholds.minSamples) reasons.push('samples-below-threshold')
+  if (scoreValue.accuracy < thresholds.minAccuracy) reasons.push('accuracy-below-threshold')
+  if (scoreValue.destructiveHits > thresholds.maxDestructiveHits) reasons.push('destructive-hits')
+  if (!analysis?.inputDigest) reasons.push('input-digest-missing')
+  if (reasons.length > 0) return { ok: false, code: 'freeze-refused', reasons }
+
+  const entry = Object.freeze({
+    candidateId: String(candidate.id),
+    kind: String(candidate.kind ?? 'unknown'),
+    risk: String(candidate.risk ?? 'unknown'),
+    changeDigest: digestOf(candidate.change ?? {}),
+    inputDigest: analysis.inputDigest,
+    validation: Object.freeze({
+      samples: scoreValue.samples,
+      correct: scoreValue.correct,
+      accuracy: scoreValue.accuracy,
+      destructiveHits: scoreValue.destructiveHits,
+      savedTokens: scoreValue.savedTokens,
+    }),
+    thresholds: Object.freeze({ ...thresholds }),
+    frozenAt: typeof input?.now === 'function' ? input.now() : Date.now(),
+    /** 冻结后才允许 active 使用；冻结 ≠ 自动上线。 */
+    usableByActive: true,
+  })
+  return { ok: true, entry }
+}
+
+/**
+ * 生成报表：候选与基线**同表展示**（防止只展示候选的漂亮数字）。
+ */
+export function report({ analysis, scored = [], frozen = [] }) {
+  const baseline = analysis?.baseline ?? { hitRate: 0, matches: 0, hits: 0, savedTokens: 0, governanceTokens: 0, estimatedRatio: 0 }
+  const rows = [
+    {
+      id: 'baseline',
+      kind: 'baseline',
+      hitRate: baseline.hitRate,
+      samples: baseline.matches,
+      accuracy: null,
+      savedTokens: baseline.savedTokens,
+      governanceTokens: baseline.governanceTokens,
+      status: 'baseline',
+    },
+    ...scored.map((item) => {
+      const frozenEntry = frozen.find((entry) => entry.candidateId === item.candidateId)
+      return {
+        id: item.candidateId,
+        kind: 'candidate',
+        hitRate: null,
+        samples: item.samples,
+        accuracy: item.accuracy,
+        savedTokens: item.savedTokens,
+        governanceTokens: null,
+        status: frozenEntry ? 'frozen' : 'candidate',
+      }
+    }),
+  ]
+  return Object.freeze({
+    ok: true,
+    inputDigest: analysis?.inputDigest ?? null,
+    generatedAt: Date.now(),
+    findings: analysis?.findings ?? [],
+    rows,
+    frozen: frozen.map((entry) => ({ ...entry })),
+    /** 3.3.0 不做自动上线：清单之外的一切都只是提案。 */
+    autoDeploy: false,
+  })
+}
+
+/**
+ * M5 交付物：**冻结清单**（可持久化、可复核）。
+ *
+ * 清单只描述"在什么数据、什么阈值下冻结了什么"，不含执行能力：
+ *   * `inputDigest`：生成候选时的输入摘要（同一输入必得同一摘要）；
+ *   * `entries`：逐条冻结记录，按 candidateId 排序保证可 diff；
+ *   * `manifestDigest`：整份清单的摘要，用于事后核对「清单没被改过」。
+ */
+export function buildFreezeManifest({ analysis, frozen = [], now } = {}) {
+  const entries = [...(Array.isArray(frozen) ? frozen : [])]
+    .map((entry) => ({ ...entry }))
+    .sort((a, b) => String(a.candidateId).localeCompare(String(b.candidateId)))
+  const manifest = {
+    kind: 'rsi-freeze-manifest',
+    version: 1,
+    inputDigest: analysis?.inputDigest ?? null,
+    thresholds: { ...DEFAULT_THRESHOLDS },
+    generatedAt: Number(now ?? 0) || 0,
+    entries,
+    /** 3.3.0 不自动上线：清单只声明「可被 active 使用」，上线仍是人工动作。 */
+    autoDeploy: false,
+  }
+  return Object.freeze({ ...manifest, manifestDigest: digestOf(manifest) })
+}
+
+/**
+ * 复核冻结清单：清单没被改动、输入没变、条目仍然满足阈值。
+ * 返回 `issues[]` —— 任何一条都意味着"这份清单不能再作为依据"。
+ */
+export function verifyFreezeManifest(manifest, { analysis, thresholds } = {}) {
+  const issues = []
+  if (!manifest || manifest.kind !== 'rsi-freeze-manifest') issues.push('manifest-kind-invalid')
+  const entries = Array.isArray(manifest?.entries) ? manifest.entries : []
+  if (entries.length === 0) issues.push('manifest-empty')
+  if (manifest?.autoDeploy !== false) issues.push('manifest-must-not-auto-deploy')
+
+  // 清单自身完整性：重算摘要必须一致（防止事后手改）
+  const body = { ...manifest }
+  delete body.manifestDigest
+  if (manifest?.manifestDigest !== digestOf(body)) issues.push('manifest-digest-mismatch')
+
+  // 输入漂移：候选是在旧数据上冻结的，就不能再当依据
+  if (analysis?.inputDigest && manifest?.inputDigest && analysis.inputDigest !== manifest.inputDigest) {
+    issues.push('input-digest-drift')
+  }
+
+  const limits = { ...DEFAULT_THRESHOLDS, ...(thresholds ?? {}) }
+  for (const entry of entries) {
+    const validation = entry?.validation ?? {}
+    if (Number(validation.samples ?? 0) < limits.minSamples) issues.push(`entry-samples-below:${entry?.candidateId}`)
+    if (Number(validation.accuracy ?? 0) < limits.minAccuracy) issues.push(`entry-accuracy-below:${entry?.candidateId}`)
+    if (Number(validation.destructiveHits ?? 0) > limits.maxDestructiveHits) issues.push(`entry-destructive-hits:${entry?.candidateId}`)
+    if (entry?.usableByActive !== true) issues.push(`entry-not-usable:${entry?.candidateId}`)
+  }
+  return Object.freeze({ ok: issues.length === 0, issues: Object.freeze(issues), entries: entries.length })
+}
+
+export const RSI_THRESHOLDS = DEFAULT_THRESHOLDS
+export { MISS_REASONS }

package/src/cost/toolface.ts

@@ -0,0 +1,151 @@
+// 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 · M2 交付物：**工具面 token 下降 + 归因**。
+ *
+ * 两件事必须分开算，因为它们属于两本不同的账：
+ *
+ *   * **A1 紧凑输出**：回执变短 ⇒ 每次交互更便宜 ⇒ **execution 节省**。
+ *     默认 `shadow` 时只能报「本可节省」，不许算成真节省。
+ *   * **A2 渐进纰漏**：常驻工具面收敛 ⇒ 每轮 schema 更少；但 `load_tools` 的装载
+ *     是**作者/选择成本** ⇒ **governance 账**（与 §5.1 一致），永不混进节省。
+ *
+ * 关闭 A2 时必须 `reductionRatio === 0`（fail-open 回全量工具面），这是可测的。
+ */
+
+const num = (value) => {
+  const n = Number(value)
+  return Number.isFinite(n) && n >= 0 ? n : 0
+}
+const tokensOf = (text) => (String(text ?? '').length > 0 ? Math.ceil(String(text).length / 4) : 0)
+
+/**
+ * 计算工具面：全量（基线）vs 可见（常驻 + 已加载）。
+ * @param {{
+ *   schemas: Array<{name: string, description?: string, parameters?: unknown}>,
+ *   enabled?: boolean,
+ *   resident?: string[],
+ *   loaded?: string[],
+ * }} input
+ */
+export function planToolFace(input = {}) {
+  const schemas = Array.isArray(input.schemas) ? input.schemas : []
+  const enabled = input.enabled === true
+  const resident = new Set(Array.isArray(input.resident) ? input.resident.map(String) : [])
+  const loaded = new Set(Array.isArray(input.loaded) ? input.loaded.map(String) : [])
+
+  const tokenOfSchema = (schema) => tokensOf(JSON.stringify({ name: schema?.name, description: schema?.description, parameters: schema?.parameters }))
+  const baselineTokens = schemas.reduce((sum, schema) => sum + tokenOfSchema(schema), 0)
+  const visible = enabled ? schemas.filter((schema) => resident.has(String(schema?.name)) || loaded.has(String(schema?.name))) : schemas
+  const residentTokens = visible.reduce((sum, schema) => sum + tokenOfSchema(schema), 0)
+  const savedTokens = Math.max(0, baselineTokens - residentTokens)
+  return Object.freeze({
+    enabled,
+    baseline: Object.freeze({ count: schemas.length, tokens: baselineTokens }),
+    resident: Object.freeze({ count: visible.length, tokens: residentTokens, names: visible.map((schema) => String(schema?.name)) }),
+    savedTokens,
+    reductionRatio: baselineTokens > 0 ? savedTokens / baselineTokens : 0,
+    /** 关闭时必须是 0（fail-open 回全量），调用方可直接断言。 */
+    perTurn: Object.freeze({ tokensBefore: baselineTokens, tokensAfter: residentTokens }),
+  })
+}
+
+/**
+ * M2 报表：工具面下降（A2） + 回执压缩（A1） + 归因分列。
+ *
+ * @param {{
+ *   schemas?: object[],
+ *   disclosure?: {enabled?: boolean, resident?: string[], loaded?: string[]},
+ *   compactions?: Array<{toolName?: string, applied?: boolean, evaluated?: boolean, estimated?: boolean, savedTokens?: number, savedChars?: number}>,
+ *   loads?: Array<{toolName?: string, tokens?: number}>,
+ *   mode?: 'off' | 'shadow' | 'enforce',
+ * }} input
+ */
+export function buildToolFaceReport(input = {}) {
+  const disclosure = input.disclosure ?? {}
+  const face = planToolFace({ schemas: input.schemas, enabled: disclosure.enabled === true, resident: disclosure.resident, loaded: disclosure.loaded })
+  const mode = input.mode === 'off' || input.mode === 'enforce' ? input.mode : 'shadow'
+
+  const byTool = {}
+  let evaluated = 0
+  let applied = 0
+  let appliedSaved = 0
+  let wouldSave = 0
+  let estimatedSaved = 0
+  for (const event of Array.isArray(input.compactions) ? input.compactions : []) {
+    if (event?.evaluated === false) continue
+    evaluated += 1
+    const saved = num(event?.savedTokens ?? (num(event?.savedChars) / 4))
+    if (event?.applied === true) {
+      applied += 1
+      appliedSaved += saved
+      if (event?.estimated === true) estimatedSaved += saved
+    } else {
+      wouldSave += saved
+    }
+    const toolName = String(event?.toolName ?? 'unknown')
+    if (!byTool[toolName]) byTool[toolName] = { evaluated: 0, applied: 0, savedTokens: 0 }
+    byTool[toolName].evaluated += 1
+    if (event?.applied === true) {
+      byTool[toolName].applied += 1
+      byTool[toolName].savedTokens += saved
+    }
+  }
+
+  // A2 的装载成本：进 governance，不进节省
+  const loadEvents = Array.isArray(input.loads) ? input.loads.length : 0
+  const governanceTokens = (Array.isArray(input.loads) ? input.loads : []).reduce((sum, event) => sum + num(event?.tokens), 0)
+
+  // A1 的节省口径：只有 enforce 且真的替换了才算执行节省
+  const a1ExecutionSaved = mode === 'enforce' ? appliedSaved : 0
+  const a1WouldSaveTokens = mode === 'enforce' ? 0 : wouldSave + appliedSaved
+  const executionSaved = a1ExecutionSaved
+  return Object.freeze({
+    ok: true,
+    mode,
+    toolFace: face,
+    a1: Object.freeze({
+      module: 'a1-compact',
+      evaluated,
+      applied,
+      /** enforce 且替换成功时才算的节省。 */
+      executionSavedTokens: a1ExecutionSaved,
+      /** shadow 下「本可节省」——不是节省，报表必须显式标出。 */
+      wouldSaveTokens: a1WouldSaveTokens,
+      estimatedSavedTokens: estimatedSaved,
+      byTool: Object.freeze(byTool),
+    }),
+    a2: Object.freeze({
+      module: 'a2-disclosure',
+      enabled: face.enabled,
+      loadEvents,
+      /** 装载成本属于作者/选择成本 ⇒ governance（永不并入节省）。 */
+      governanceTokens,
+      perTurnSavedTokens: face.savedTokens,
+    }),
+    attribution: Object.freeze({
+      /** 工具面下降算 A2 的贡献，但**只有在 enabled 时才非 0**。 */
+      'a2-disclosure': face.savedTokens,
+      'a1-compact': a1ExecutionSaved,
+      governance: governanceTokens,
+    }),
+    totals: Object.freeze({
+      executionSaved,
+      governanceTokens,
+      /** 净收益 = 执行节省（A1，enforce 才有） + 工具面下降（A2，per-turn） − 装载治理成本。 */
+      netBenefit: executionSaved + face.savedTokens - governanceTokens,
+      /** 两项分列（图省事合并会导致 §8 的重复计风险）。 */
+      byKind: Object.freeze({
+        toolFaceSavedTokens: face.savedTokens,
+        receiptSavedTokens: a1ExecutionSaved,
+      }),
+    }),
+    discipline: Object.freeze({
+      shadowNeverCountedAsSavings: mode !== 'enforce',
+      loadCostIsGovernance: true,
+      disabledDisclosureReducesNothing: face.enabled !== true || face.savedTokens >= 0,
+    }),
+  })
+}