@twinsearth/dsh-master 3.2.10 → 3.3.1

package/src/cost/metrics.ts

@@ -0,0 +1,193 @@
+// 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 · metrics（验收指标，设计 §10.1）。
+ *
+ * **每份报告必须给全**七项指标；缺任何一项都必须显式报 `complete: false` + `missing[]`，
+ * 不允许"报一半也算报告"。
+ *
+ * | 指标 | 口径 |
+ * |---|---|
+ * | tokens/task | 完整任务输入+输出，含重试/回退/失败执行 |
+ * | 成功率 | 与对照组同 scorer；差值 ≥2pp 下降即触发降级审查 |
+ * | GDR 命中率 / 未命中分布 | 每次复用尝试为分母 |
+ * | CCS 替换数 / 证书完整率 | 证书必须 100% 可回放 |
+ * | 节省归因 | A1/A2/A3/B1–B4 分列 + unattributed |
+ * | governance 成本 | 作者步骤、RSI 离线、选择/验证 |
+ * | 耗时 | wall-clock 中位数与 p95 |
+ */
+
+export const METRIC_KEYS = Object.freeze([
+  'tokensPerTask',
+  'success',
+  'gdr',
+  'ccs',
+  'attribution',
+  'governance',
+  'latency',
+])
+
+/** 成功率相对对照组下降 ≥2pp ⇒ 触发降级审查（§10.1）。 */
+export const SUCCESS_REGRESSION_PP = 0.02
+
+const MODULES = Object.freeze(['a1-compact', 'a2-disclosure', 'a3-batch', 'b1-edg', 'b2-gdr', 'b3-ccs', 'b4-rsi', 'unattributed'])
+
+function num(value) {
+  const n = Number(value)
+  return Number.isFinite(n) ? n : 0
+}
+
+function percentile(sorted, ratio) {
+  if (sorted.length === 0) return null
+  if (sorted.length === 1) return sorted[0]
+  const index = Math.min(sorted.length - 1, Math.max(0, Math.ceil(ratio * sorted.length) - 1))
+  return sorted[index]
+}
+
+function median(values) {
+  const sorted = [...values].sort((a, b) => a - b)
+  return percentile(sorted, 0.5)
+}
+
+function p95(values) {
+  const sorted = [...values].sort((a, b) => a - b)
+  return percentile(sorted, 0.95)
+}
+
+/**
+ * @param {{
+ *   entries?: object[],
+ *   certificates?: object[],
+ *   tasks?: Array<{taskId: string, success?: boolean, elapsedMs?: number, tokens?: number}>,
+ *   control?: { successRate?: number, tokensPerTask?: number },
+ *   guard?: { attempts?: number, hits?: number, byReason?: object },
+ *   audit?: { ok?: boolean, count?: number },
+ *   traceCheck?: (taskId: string) => { reconciled?: boolean },
+ * }} [input]
+ */
+export function buildMetricsReport(input = {}) {
+  const entries = Array.isArray(input.entries) ? input.entries : []
+  const certificates = Array.isArray(input.certificates) ? input.certificates : []
+  const tasks = Array.isArray(input.tasks) ? input.tasks : []
+  const missing = []
+
+  // ---- tokens/task：完整任务输入+输出（含重试/回退/失败执行）----
+  const tokensByTask = new Map()
+  for (const entry of entries) {
+    if (entry?.account !== 'execution') continue
+    const key = String(entry.taskId ?? 'unattributed')
+    tokensByTask.set(key, (tokensByTask.get(key) ?? 0) + Math.max(0, num(entry.total)))
+  }
+  const taskTokens = (tasks.length > 0
+    ? tasks.map((task) => Math.max(0, num(task.tokens) || (tokensByTask.get(String(task.taskId)) ?? 0)))
+    : [...tokensByTask.values()])
+  // 既有任务显式 tokens、也有账本 token 事件，才算「有 token 数据」；否则该项缺失。
+  const hasTokenData = tokensByTask.size > 0 || tasks.some((task) => num(task?.tokens) > 0)
+  const tokensPerTask = hasTokenData && taskTokens.length > 0
+    ? Math.round((taskTokens.reduce((sum, value) => sum + value, 0) / taskTokens.length) * 100) / 100
+    : null
+  if (tokensPerTask === null) missing.push('tokensPerTask')
+
+  // ---- 成功率：与对照组同 scorer；≥2pp 下降触发审查 ----
+  const scored = tasks.filter((task) => typeof task?.success === 'boolean')
+  const successRate = scored.length > 0 ? scored.filter((task) => task.success === true).length / scored.length : null
+  if (successRate === null) missing.push('success')
+  const controlRate = Number.isFinite(Number(input?.control?.successRate)) ? Number(input.control.successRate) : null
+  const successDelta = successRate !== null && controlRate !== null ? Math.round((successRate - controlRate) * 10000) / 10000 : null
+  const regression = successDelta !== null && successDelta <= -SUCCESS_REGRESSION_PP
+  const success = {
+    rate: successRate,
+    samples: scored.length,
+    scorer: 'same-as-control',
+    control: controlRate,
+    delta: successDelta,
+    /** §10.1：差值 ≥2pp 下降 ⇒ 触发降级审查。 */
+    reviewRequired: regression,
+    thresholdPp: SUCCESS_REGRESSION_PP,
+  }
+
+  // ---- GDR：每次复用尝试为分母 ----
+  const attempts = Math.max(0, num(input?.guard?.attempts))
+  const hits = Math.max(0, num(input?.guard?.hits))
+  const byReason = { ...(input?.guard?.byReason ?? {}) }
+  const gdr = {
+    attempts,
+    hits,
+    hitRate: attempts > 0 ? Math.round((hits / attempts) * 10000) / 10000 : null,
+    byReason,
+    denominator: 'reuse-attempts',
+  }
+  if (attempts === 0) missing.push('gdr')
+
+  // ---- CCS：替换数 + 证书完整率（必须 100% 可回放）----
+  const dispatched = certificates.filter((cert) => cert?.dispatched !== false)
+  const REQUIRED = ['edgeId', 'toolName', 'schemaHash', 'guardExpr', 'receiptDigest', 'replacedCallbackId', 'taskId']
+  const complete = certificates.filter((cert) => REQUIRED.every((key) => String(cert?.[key] ?? '').trim() !== '') && cert?.viaNativeDispatcher === true)
+  const reconciled = certificates.filter((cert) => {
+    if (typeof input?.traceCheck !== 'function') return true
+    try { return input.traceCheck(String(cert?.taskId ?? ''))?.reconciled === true } catch { return false }
+  })
+  const completeness = certificates.length > 0 ? Math.round((complete.length / certificates.length) * 10000) / 10000 : null
+  const ccs = {
+    substitutions: dispatched.length,
+    certificates: certificates.length,
+    completeness,
+    replayable: completeness === 1,
+    reconciled: certificates.length === 0 ? null : reconciled.length === certificates.length,
+    auditVerified: input?.audit?.ok !== false,
+  }
+  if (certificates.length === 0) missing.push('ccs')
+
+  // ---- 节省归因：按模块分列 + unattributed ----
+  const byModule = {}
+  for (const key of MODULES) byModule[key] = 0
+  for (const entry of entries) {
+    if (entry?.account !== 'execution' || !(num(entry?.savedTokens) > 0)) continue
+    const moduleKey = MODULES.includes(String(entry.module)) ? String(entry.module) : 'unattributed'
+    byModule[moduleKey] += Math.max(0, num(entry.savedTokens))
+  }
+  const attribution = { byModule, total: Object.values(byModule).reduce((sum, value) => sum + value, 0) }
+  if (attribution.total === 0) missing.push('attribution')
+
+  // ---- governance：作者 / RSI 离线 / 选择与验证 ----
+  const governanceByKind = { author: 0, rsiOffline: 0, selection: 0, other: 0 }
+  for (const entry of entries) {
+    if (entry?.account !== 'governance') continue
+    const tokens = Math.max(0, num(entry.total))
+    const kind = String(entry.meta?.kind ?? entry.source ?? 'other')
+    if (kind.includes('edg') || kind.includes('author')) governanceByKind.author += tokens
+    else if (kind.includes('rsi') || String(entry.source) === 'offline') governanceByKind.rsiOffline += tokens
+    else if (kind.includes('select') || kind.includes('valid') || kind.includes('load')) governanceByKind.selection += tokens
+    else governanceByKind.other += tokens
+  }
+  const governance = {
+    ...governanceByKind,
+    total: Object.values(governanceByKind).reduce((sum, value) => sum + value, 0),
+  }
+
+  // ---- 耗时：中位数 + p95 ----
+  const durations = tasks.map((task) => num(task?.elapsedMs)).filter((value) => value > 0)
+  const latency = {
+    medianMs: durations.length > 0 ? median(durations) : null,
+    p95Ms: durations.length > 0 ? p95(durations) : null,
+    samples: durations.length,
+  }
+  if (durations.length === 0) missing.push('latency')
+
+  const uniqueMissing = METRIC_KEYS.filter((key) => missing.includes(key))
+  return Object.freeze({
+    ok: true,
+    complete: uniqueMissing.length === 0,
+    missing: uniqueMissing,
+    tokensPerTask: Object.freeze({ value: tokensPerTask, includesRetries: true, includesFailures: true, samples: taskTokens.length }),
+    success: Object.freeze(success),
+    gdr: Object.freeze(gdr),
+    ccs: Object.freeze(ccs),
+    attribution: Object.freeze({ ...attribution, byModule: Object.freeze({ ...byModule }) }),
+    governance: Object.freeze(governance),
+    latency: Object.freeze(latency),
+    control: Object.freeze({ successRate: controlRate, tokensPerTask: Number.isFinite(Number(input?.control?.tokensPerTask)) ? Number(input.control.tokensPerTask) : null }),
+  })
+}

package/src/cost/milestones.ts

@@ -0,0 +1,206 @@
+// 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 · milestones（里程碑与依赖顺序，设计 §14）。
+ *
+ * 规格原文：
+ *
+ * | 阶段 | 内容 | 产出 |
+ * |---|---|---|
+ * | M1 | 系统层：ledger/budget/policy/audit + 4 切点接入（observe） | 记账报表 + 预算闸测试 |
+ * | M2 | 模块层 A：A1 紧凑输出、A2 渐进纰漏（shadow→enforce 白名单） | 工具面 token 下降 + 归因 |
+ * | M3 | 模块层 B：B1 EDG、B2 GDR（shadow 计算证书，不替换） | 命中率与「本可节省」报表 |
+ * | M4 | B3 CCS enforce（白名单）+ 自动回退 | 真实替换 + 证书链 + 成功率对照 |
+ * | M5 | A3 批量（若宿主支持）、B4 RSI 离线流程、与瓮城回流/信息栏对接 | 离线候选冻结清单 + 面板 |
+ *
+ * 依赖顺序：**M1 必须先行**（没有账本后续收益不可信）；**M4 必须等 M3 的守卫准确率数据**。
+ *
+ * 本文件把这张表变成机器可读的里程碑状态：每个阶段分「实现」与「效果证据」两件事判定，
+ * 缺数据只能说 `effect-unmeasured`，**不许把"实现了"说成"达标了"**。
+ */
+
+export const MILESTONE_IDS = Object.freeze(['M1', 'M2', 'M3', 'M4', 'M5'])
+
+/** M4 放行前，M3 需要给出的守卫准确率最小样本量（与 policy.enforce 门禁一致）。 */
+export const M3_MIN_SAMPLES = 20
+/** M4 放行前要求的最小守卫准确率（与 ENFORCE_GATE.minAccuracy 一致）。 */
+export const M3_MIN_ACCURACY = 0.98
+
+/**
+ * M5 回流放行条件：至少 3 条事件拿到对端回执，且对端自报身份在白名单内。
+ * 自环（同一进程里服务端+客户端）与未知 peer 一律不算达标。
+ */
+export const M5_MIN_RELAY_EVENTS = 3
+export const M5_RELAY_PEERS = Object.freeze(['dsh-fang-bundle', 'contract-server'])
+
+export const MILESTONES = Object.freeze([
+  Object.freeze({
+    id: 'M1',
+    title: '系统层：ledger/budget/policy/audit + 4 切点接入（observe）',
+    deliverable: '记账报表 + 预算闸测试',
+    dependsOn: [],
+    /** 实现落点（文件存在即视为实现完成；行为由测试保证）。 */
+    implementation: ['src/cost/ledger.ts', 'src/cost/budget.ts', 'src/cost/policy.ts', 'src/cost/audit.ts', 'worker/cost-hooks.ts'],
+    tests: ['test/cost-ledger.test.mjs', 'test/cost-budget.test.mjs', 'test/cost-policy.test.mjs', 'test/cost-audit.test.mjs', 'test/worker-cost-hooks.test.ts', 'test/worker-budget-guard.test.ts'],
+  }),
+  Object.freeze({
+    id: 'M2',
+    title: '模块层 A：A1 紧凑输出、A2 渐进纰漏（shadow→enforce 白名单）',
+    deliverable: '工具面 token 下降 + 归因',
+    dependsOn: ['M1'],
+    implementation: ['worker/tool-compact.ts', 'worker/tool-disclosure.ts', 'src/cost/attribution.ts'],
+    tests: ['test/worker-tool-compact.test.ts', 'test/worker-tool-disclosure.test.ts', 'test/cost-attribution.test.mjs', 'test/cost-disclosure.test.mjs'],
+  }),
+  Object.freeze({
+    id: 'M3',
+    title: '模块层 B：B1 EDG、B2 GDR（shadow 计算证书，不替换）',
+    deliverable: '命中率与「本可节省」报表',
+    dependsOn: ['M1'],
+    implementation: ['worker/edg.ts', 'worker/gdr.ts'],
+    tests: ['test/worker-edg.test.ts', 'test/worker-gdr.test.ts', 'test/worker-decision-spi.test.ts'],
+  }),
+  Object.freeze({
+    id: 'M4',
+    title: 'B3 CCS enforce（白名单）+ 自动回退',
+    deliverable: '真实替换 + 证书链 + 成功率对照',
+    dependsOn: ['M3'],
+    implementation: ['worker/ccs.ts'],
+    tests: ['test/worker-ccs.test.ts', 'test/cost-substitution.test.mjs', 'test/invariants.test.ts'],
+  }),
+  Object.freeze({
+    id: 'M5',
+    title: 'A3 批量（若宿主支持）、B4 RSI 离线流程、与瓮城回流/信息栏对接',
+    deliverable: '离线候选冻结清单 + 面板',
+    dependsOn: ['M1'],
+    implementation: ['worker/tool-batch.ts', 'src/cost/rsi.ts', 'scripts/rsi-offline.mjs', 'client.js'],
+    tests: ['test/worker-tool-batch.test.ts', 'test/cost-rsi.test.mjs'],
+  }),
+])
+
+/**
+ * 评估里程碑。
+ *
+ * @param {{
+ *   files?: string[],                       // 仓库里实际存在的文件（相对路径）
+ *   guard?: {samples?: number, accuracy?: number},   // M3 的守卫准确率数据（来自 shadow 报告）
+ *   forkExperiment?: {ok?: boolean},        // M4 的成功率对照（来自 gate 的 G5）
+ *   fangRelay?: {available?: boolean, peer?: string, events?: number,
+ *                sameProcess?: boolean, transport?: string, contractVersion?: string,
+ *                reason?: string},          // M5 的回流对端证据（独立进程实测）
+ * }} evidence
+ */
+export function evaluateMilestones(evidence = {}) {
+  const files = new Set(Array.isArray(evidence.files) ? evidence.files : [])
+  const rows = []
+  const done = new Set()
+  let relayEvidence = null
+
+  for (const milestone of MILESTONES) {
+    const missingImplementation = milestone.implementation.filter((file) => !files.has(file))
+    const missingTests = milestone.tests.filter((file) => !files.has(file))
+    const dependenciesMet = milestone.dependsOn.every((id) => done.has(id))
+    const implemented = missingImplementation.length === 0 && missingTests.length === 0
+
+    let effect = 'unmeasured'
+    const reasons = []
+    if (!implemented) {
+      reasons.push(`missing:${[...missingImplementation, ...missingTests].join('|')}`)
+    }
+    if (!dependenciesMet) {
+      reasons.push(`dependency-unmet:${milestone.dependsOn.filter((id) => !done.has(id)).join('|')}`)
+    }
+
+    // 各阶段的效果证据要求
+    if (implemented && dependenciesMet) {
+      if (milestone.id === 'M1') {
+        effect = 'verified'   // 系统层效果由测试直接证明（记账、预算闸）
+      } else if (milestone.id === 'M2') {
+        effect = evidence.attributionObserved === true ? 'verified' : 'unmeasured'
+        if (effect === 'unmeasured') reasons.push('effect-needs-real-token-drop')
+      } else if (milestone.id === 'M3') {
+        const samples = Math.max(0, Number(evidence?.guard?.samples ?? 0) || 0)
+        const accuracy = Number(evidence?.guard?.accuracy ?? 0) || 0
+        if (samples >= M3_MIN_SAMPLES && accuracy >= M3_MIN_ACCURACY) effect = 'verified'
+        else reasons.push(`effect-needs-guard-accuracy(samples=${samples}, accuracy=${accuracy})`)
+      } else if (milestone.id === 'M4') {
+        if (evidence?.forkExperiment?.ok === true) effect = 'verified'
+        else reasons.push('effect-needs-fork-success-comparison')
+      } else if (milestone.id === 'M5') {
+        // 回流必须有**对端回执**才算达标：可用 + 非自环 + 对端自报身份在白名单 + 至少 3 条事件。
+        const relay = evidence?.fangRelay && typeof evidence.fangRelay === 'object' ? evidence.fangRelay : null
+        const available = relay?.available === true
+        const peer = String(relay?.peer ?? '')
+        const events = Math.max(0, Number(relay?.events ?? 0) || 0)
+        if (!available) {
+          reasons.push(`fang-relay-unavailable:${String(relay?.reason ?? 'not-provided')}`)
+        } else if (relay?.sameProcess === true) {
+          reasons.push('fang-relay-self-loop')
+        } else if (!M5_RELAY_PEERS.includes(peer)) {
+          reasons.push(`fang-relay-peer-invalid:${peer || 'missing'}`)
+        } else if (events < M5_MIN_RELAY_EVENTS) {
+          reasons.push(`fang-relay-no-receipts(events=${events})`)
+        } else {
+          effect = 'verified'
+        }
+        relayEvidence = Object.freeze({
+          available,
+          peer: peer || null,
+          events,
+          sameProcess: relay?.sameProcess === true,
+          transport: relay?.transport ?? null,
+          contractVersion: relay?.contractVersion ?? relay?.peerContractVersion ?? null,
+        })
+      }
+    }
+
+    const status = !implemented
+      ? 'not-implemented'
+      : !dependenciesMet
+        ? 'blocked-by-dependency'
+        : effect === 'verified' ? 'done' : 'implemented-effect-unmeasured'
+
+    rows.push(Object.freeze({
+      id: milestone.id,
+      title: milestone.title,
+      deliverable: milestone.deliverable,
+      dependsOn: milestone.dependsOn,
+      implemented,
+      dependenciesMet,
+      effect,
+      status,
+      reasons,
+      /** M5：回流对端证据（peer 自报 + 事件数 + 是否自环）；其它阶段为 null。 */
+      relay: relayEvidence,
+      /** 剩余缺口说明（不隐藏）。 */
+      notes: milestone.id === 'M5' && relayEvidence?.peer === 'contract-server'
+        ? ['peer=contract-server：契约对端独立进程实测，dsh-fang-bundle 采用 contract 1.1 后应变为 peer=dsh-fang-bundle']
+        : [],
+    }))
+    if (status === 'done') done.add(milestone.id)
+  }
+
+  // 依赖顺序的静态校验：M1 必须最先；M4 只依赖 M3。
+  const orderProblems = []
+  const m1 = MILESTONES.find((item) => item.id === 'M1')
+  if (!m1 || m1.dependsOn.length !== 0) orderProblems.push('M1-must-be-first')
+  const m4 = MILESTONES.find((item) => item.id === 'M4')
+  if (!m4 || !m4.dependsOn.includes('M3')) orderProblems.push('M4-must-depend-on-M3')
+
+  const allImplemented = rows.every((row) => row.implemented)
+  const allDone = rows.every((row) => row.status === 'done')
+  return Object.freeze({
+    ok: orderProblems.length === 0 && allDone,
+    implementedAll: allImplemented,
+    doneAll: allDone,
+    orderProblems,
+    rows: Object.freeze(rows),
+    /** 摘要在面板/报表用：实现了多少、真达标多少。 */
+    summary: Object.freeze({
+      implemented: rows.filter((row) => row.implemented).length,
+      verified: rows.filter((row) => row.status === 'done').length,
+      total: rows.length,
+    }),
+  })
+}

package/src/cost/modules/index.ts

@@ -0,0 +1,13 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+// Copyright (c) 2026 dsh-Master contributors — see LICENSE-CORE.
+// @ts-nocheck
+/** 3.3.0 §11：`src/cost/modules/` 入口（模块清单；可执行实现在 worker/，见 manifests.ts 说明）。 */
+export {
+  MODULE_KIND,
+  MODULE_LAYER,
+  MODULE_MODES,
+  MODULE_MANIFESTS,
+  MODULE_IDS,
+  manifestOf,
+  validateManifests,
+} from './manifests.ts'

package/src/cost/modules/manifests.ts

@@ -0,0 +1,129 @@
+// 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 §11：模块清单（`src/cost/modules/`）。
+ *
+ * **进程边界说明（重要）**：A/B 类模块的可执行实现运行在 **fork worker 进程**里，
+ * 因此实体代码在 `worker/`（`tool-compact.ts`、`tool-disclosure.ts`、`tool-batch.ts`、
+ * `edg.ts`、`gdr.ts`、`ccs.ts`）。本目录提供的是**宿主侧清单**：模块 id、层级、默认档、
+ * 开关环境变量、实现文件与文档锚点 —— 供编排器、面板与门禁统一引用，
+ * 避免"宿主侧再抄一份实现"导致两套语义。
+ */
+
+export const MODULE_KIND = Object.freeze({ tool: 'tool', decision: 'decision' })
+export const MODULE_LAYER = Object.freeze({ a: 'a', b: 'b' })
+export const MODULE_MODES = Object.freeze(['off', 'shadow', 'enforce'])
+
+/** 7 个模块（A1–A3 / B1–B4）的宿主侧清单。 */
+export const MODULE_MANIFESTS = Object.freeze([
+  Object.freeze({
+    id: 'a1-compact',
+    kind: 'tool',
+    layer: 'a',
+    name: '工具输出紧凑化',
+    implementation: 'worker/tool-compact.ts',
+    defaultMode: 'shadow',
+    envFlag: 'DSH_MASTER_COMPACT_MODE',
+    surfaces: ['worker'],
+    changesObservableSemantics: false,
+    docs: 'docs/DESIGN-v3.3.0-cost-optimization.md#a1-tool-compact工具输出紧凑化',
+  }),
+  Object.freeze({
+    id: 'a2-disclosure',
+    kind: 'tool',
+    layer: 'a',
+    name: '渐进式纰漏',
+    implementation: 'worker/tool-disclosure.ts',
+    defaultMode: 'off',
+    envFlag: 'DSH_MASTER_DISCLOSURE',
+    surfaces: ['worker'],
+    changesObservableSemantics: false,
+    docs: 'docs/DESIGN-v3.3.0-cost-optimization.md#a2-tool-disclosure渐进式纰漏',
+  }),
+  Object.freeze({
+    id: 'a3-batch',
+    kind: 'tool',
+    layer: 'a',
+    name: '批量调用引导',
+    implementation: 'worker/tool-batch.ts',
+    defaultMode: 'shadow',
+    envFlag: 'DSH_MASTER_BATCH',
+    surfaces: ['worker'],
+    changesObservableSemantics: false,
+    docs: 'docs/DESIGN-v3.3.0-cost-optimization.md#a3-tool-batch批量调用',
+  }),
+  Object.freeze({
+    id: 'b1-edg',
+    kind: 'decision',
+    layer: 'b',
+    name: '可执行决策图',
+    implementation: 'worker/edg.ts',
+    defaultMode: 'off',
+    envFlag: 'DSH_MASTER_EDG',
+    surfaces: ['worker'],
+    changesObservableSemantics: false,
+    docs: 'docs/DESIGN-v3.3.0-cost-optimization.md#b1-edg可执行决策图',
+  }),
+  Object.freeze({
+    id: 'b2-gdr',
+    kind: 'decision',
+    layer: 'b',
+    name: '回执守卫',
+    implementation: 'worker/gdr.ts',
+    defaultMode: 'off',
+    envFlag: 'DSH_MASTER_GDR',
+    surfaces: ['worker'],
+    changesObservableSemantics: false,
+    docs: 'docs/DESIGN-v3.3.0-cost-optimization.md#b2-gdr回执守卫',
+  }),
+  Object.freeze({
+    id: 'b3-ccs',
+    kind: 'decision',
+    layer: 'b',
+    name: '认证回调替换',
+    implementation: 'worker/ccs.ts',
+    defaultMode: 'off',
+    envFlag: 'DSH_MASTER_CCS',
+    surfaces: ['worker'],
+    /** 替换会**跳过模型推理**：只在 enforce + 白名单下发生。 */
+    changesObservableSemantics: false,
+    docs: 'docs/DESIGN-v3.3.0-cost-optimization.md#b3-ccs认证回调替换',
+  }),
+  Object.freeze({
+    id: 'b4-rsi',
+    kind: 'decision',
+    layer: 'b',
+    name: '离线自改进',
+    implementation: 'src/cost/rsi.ts',
+    defaultMode: 'off',
+    envFlag: null,
+    surfaces: ['host'],
+    changesObservableSemantics: false,
+    docs: 'docs/DESIGN-v3.3.0-cost-optimization.md#b4-rsi离线自改进',
+  }),
+])
+
+export const MODULE_IDS = Object.freeze(MODULE_MANIFESTS.map((manifest) => manifest.id))
+
+export function manifestOf(id) {
+  return MODULE_MANIFESTS.find((manifest) => manifest.id === String(id)) ?? null
+}
+
+/** 校验清单自身：7 个模块、id 唯一、默认档合法。 */
+export function validateManifests(manifests = MODULE_MANIFESTS) {
+  const problems = []
+  const ids = new Set()
+  for (const manifest of manifests) {
+    if (!manifest?.id) problems.push('missing-id')
+    if (ids.has(manifest?.id)) problems.push(`duplicate-id:${manifest.id}`)
+    ids.add(manifest?.id)
+    if (!MODULE_MODES.includes(manifest?.defaultMode)) problems.push(`bad-default-mode:${manifest?.id}`)
+    if (!MODULE_KIND[manifest?.kind]) problems.push(`bad-kind:${manifest?.id}`)
+    if (!MODULE_LAYER[manifest?.layer]) problems.push(`bad-layer:${manifest?.id}`)
+    if (manifest?.changesObservableSemantics !== false) problems.push(`observable-semantics:${manifest?.id}`)
+  }
+  if (manifests.length !== 7) problems.push(`module-count:${manifests.length}!=7`)
+  return { ok: problems.length === 0, problems }
+}