@twinsearth/dsh-master 3.2.9 → 3.3.0

package/worker/cost-modules.ts

@@ -0,0 +1,356 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+// Copyright (c) 2026 dsh-Master contributors — see LICENSE-CORE.
+
+/**
+ * 3.3.0 模块注册表 + 内置模块适配器（设计 §6 SPI）。
+ *
+ * 注册表是 Worker 与模块层之间唯一的中介：Agent Loop 只调注册表，
+ * 注册表负责顺序应用、异常隔离（fail-open）、模式约束（shadow 不改执行）与归因汇总。
+ * A1 由 `tool-compact.ts` 的纯格式化函数适配成 ToolModule；A2/A3 与 B1–B4 后续按同一 SPI 接入。
+ */
+
+import type {
+  CostModule,
+  DecisionModule,
+  Edg,
+  EdgDraft,
+  EdgEdge,
+  GuardVerdict,
+  ModelCallInfo,
+  ModelResponseInfo,
+  ModuleAttribution,
+  ModuleDegraded,
+  ModuleMode,
+  ModuleRegistry,
+  SubstitutionCertDraft,
+  ToolCallView,
+  ToolCtx,
+  ToolModule,
+  ToolReceipt,
+  ToolTransformInput,
+  TurnSnapshot,
+} from './cost-spi.ts'
+import { createToolCompactor } from './tool-compact.ts'
+import { normalizeCompactMode } from './tool-compact.ts'
+import { createSpillStore } from './spill.ts'
+
+const estimateTokens = (chars: number): number => (chars > 0 ? Math.ceil(chars / 4) : 0)
+
+export interface ModuleRegistryOptions {
+  /** 启动时附加的模块（顺序即应用顺序）。 */
+  modules?: CostModule[]
+  /** 模块异常的留痕出口（每次「模块+阶段」首次与每 20 次上报一次）。 */
+  onDegraded?(event: ModuleDegraded): void
+}
+
+export function createModuleRegistry(options: ModuleRegistryOptions = {}): ModuleRegistry {
+  const toolModules: ToolModule[] = []
+  const decisionModules: DecisionModule[] = []
+  const ids = new Set<string>()
+  const errors: string[] = []
+  const degradedList: ModuleDegraded[] = []
+  const degradedCounts = new Map<string, ModuleDegraded>()
+  let stats = { evaluated: 0, applied: 0, savedChars: 0 }
+  const byModule: Record<string, number> = {}
+
+  const noteError = (message: string): void => {
+    if (errors.length < 20) errors.push(message)
+  }
+
+  /** 模块异常：fail-open 留痕（不改写本次输出、不阻断 Agent Loop）。 */
+  const noteDegraded = (module: string, phase: ModuleDegraded['phase'], error: unknown): void => {
+    const message = error instanceof Error ? error.message : String(error)
+    noteError(`${module}: ${message}`)
+    const key = `${module}|${phase}`
+    const previous = degradedCounts.get(key)
+    const count = (previous?.count ?? 0) + 1
+    const event: ModuleDegraded = { module, phase, message, count, at: Date.now() }
+    degradedCounts.set(key, event)
+    const existing = degradedList.findIndex((item) => item.module === module && item.phase === phase)
+    if (existing >= 0) degradedList[existing] = event
+    else degradedList.push(event)
+    if (count === 1 || count % 20 === 0) {
+      try { options.onDegraded?.(event) } catch { /* 留痕失败不得影响执行 */ }
+    }
+  }
+
+  function register(module: CostModule): boolean {
+    if (!module || typeof module !== 'object') return false
+    const id = String((module as { id?: unknown }).id ?? '')
+    if (!id || ids.has(id)) return false
+    ids.add(id)
+    if (module.kind === 'tool') toolModules.push(module as ToolModule)
+    else if (module.kind === 'decision') decisionModules.push(module as DecisionModule)
+    else return false
+    return true
+  }
+
+  for (const module of options.modules ?? []) register(module)
+
+  /**
+   * ③ 派发前：顺序应用 `beforeDispatch`。
+   * **只有 enforce 档才真的改写/屏蔽**；shadow 只记录「本可…」，observe/off 跳过。
+   */
+  function beforeToolDispatch(input: { ticketId: string; stepIndex: number; call: ToolCallView }) {
+    const attributions: ModuleAttribution[] = []
+    let call = input.call
+    for (const module of toolModules) {
+      if (module.mode === 'off' || typeof module.beforeDispatch !== 'function') continue
+      try {
+        if (!module.appliesTo(call.name)) continue
+        const ctx: ToolCtx = { ticketId: input.ticketId, stepIndex: input.stepIndex, mode: module.mode, originalToolName: input.call.name }
+        const next = module.beforeDispatch(call, ctx)
+        const wouldChange = next === null || next.name !== call.name || JSON.stringify(next.args ?? {}) !== JSON.stringify(call.args ?? {})
+        if (!wouldChange) continue
+        const attribution: ModuleAttribution = {
+          module: module.id,
+          mode: module.mode,
+          applied: module.mode === 'enforce',
+          originalChars: 0,
+          resultChars: 0,
+          savedChars: 0,
+          estimatedTokens: 0,
+          meta: { point: 'beforeDispatch', hidden: next === null, from: call.name, to: next === null ? null : next.name },
+        }
+        attributions.push(attribution)
+        if (module.mode !== 'enforce') continue
+        if (next === null) {
+          return { call, hidden: true as const, hiddenBy: module.id, reason: 'hidden-by-module', attributions, errors: errors.slice() }
+        }
+        call = next
+      } catch (error) {
+        noteDegraded(module.id, 'beforeDispatch', error)
+      }
+    }
+    return { call, hidden: false as const, attributions, errors: errors.slice() }
+  }
+
+  /** ④ 回执：顺序应用 `afterReceipt`（shadow 只算不换）。 */
+  function afterToolReceipt(input: ToolTransformInput): { text: string; attributions: ModuleAttribution[]; errors: string[] } {
+    const attributions: ModuleAttribution[] = []
+    let text = String(input.text ?? '')
+    for (const module of toolModules) {
+      if (module.mode === 'off' || typeof module.afterReceipt !== 'function') continue
+      try {
+        if (!module.appliesTo(input.toolName)) continue
+        const ctx: ToolCtx = { ticketId: input.ticketId, stepIndex: input.stepIndex, mode: module.mode, originalToolName: input.toolName }
+        const out = module.afterReceipt({ text }, ctx)
+        if (!out || typeof out.text !== 'string') continue
+        const originalChars = text.length
+        const resultChars = out.text.length
+        const savedChars = Math.max(0, originalChars - resultChars)
+        // §5.4：模块可给出拟合式算出的 token 归因；否则退回字符/4 估算。
+        const moduleTokens = Math.max(0, Number(out.savedTokens ?? 0) || 0)
+        const estimatedTokens = moduleTokens > 0 ? moduleTokens : estimateTokens(savedChars)
+        // 是否「真的替换」由模式决定：模块在 shadow 下不得改变执行；
+        // A1 自己在「不更短」时返回原文，因此长度纪律不放在注册表里。
+        const applied = module.mode === 'enforce' && out.text !== text
+        attributions.push({
+          module: module.id,
+          mode: module.mode,
+          applied,
+          originalChars,
+          resultChars: applied ? resultChars : originalChars,
+          savedChars: applied ? savedChars : 0,
+          estimatedTokens: applied ? estimatedTokens : 0,
+          meta: { point: 'afterReceipt', toolName: input.toolName, wouldSaveChars: savedChars },
+        })
+        stats.evaluated += 1
+        if (applied) {
+          stats.applied += 1
+          stats.savedChars += savedChars
+          byModule[module.id] = (byModule[module.id] ?? 0) + estimatedTokens
+          text = out.text
+        }
+      } catch (error) {
+        noteDegraded(module.id, 'afterReceipt', error)
+      }
+    }
+    return { text, attributions, errors: errors.slice() }
+  }
+
+  /* ---------------- B 类：决策复用（§7 SPI） ---------------- */
+
+  /** ② 作者步骤：每个 B 模块产出一张候选图（异常 fail-open 留痕）。 */
+  async function authorGraphs(turn: TurnSnapshot): Promise<{ drafts: Array<{ module: string; draft: EdgDraft }>; errors: string[] }> {
+    const drafts: Array<{ module: string; draft: EdgDraft }> = []
+    for (const module of decisionModules) {
+      if (module.mode === 'off' || typeof module.author !== 'function') continue
+      try {
+        const draft = await module.author(turn)
+        if (draft && Array.isArray(draft.edges) && draft.edges.length > 0) drafts.push({ module: module.id, draft })
+      } catch (error) {
+        noteDegraded(module.id, 'author', error)
+      }
+    }
+    return { drafts, errors: errors.slice() }
+  }
+
+  /** ④ 守卫：收集所有命中（observe 只计数，shadow 落证书，enforce 可替换）。 */
+  function guardReceipt(input: { receipt: ToolReceipt; graph: Edg }): {
+    verdicts: Array<{ module: string; mode: ModuleMode; verdict: GuardVerdict }>
+    hit: { module: string; mode: ModuleMode; verdict: GuardVerdict } | null
+    errors: string[]
+  } {
+    const verdicts: Array<{ module: string; mode: ModuleMode; verdict: GuardVerdict }> = []
+    for (const module of decisionModules) {
+      if (module.mode === 'off' || typeof module.guard !== 'function') continue
+      try {
+        const verdict = module.guard(input.receipt, input.graph)
+        if (!verdict || typeof verdict !== 'object') continue
+        verdicts.push({ module: module.id, mode: module.mode, verdict })
+      } catch (error) {
+        noteDegraded(module.id, 'guard', error)
+      }
+    }
+    const hit = verdicts.find((item) => item.verdict.hit === true) ?? null
+    return { verdicts, hit, errors: errors.slice() }
+  }
+
+  /**
+   * 命中后的替换：只有 `enforce` 真的执行（且需策略层白名单放行，由调用方判定）；
+   * `shadow` 只产出「本可替换」的证书草案，不执行任何工具。
+   */
+  async function substitute(input: {
+    edge: EdgEdge
+    receipt: ToolReceipt
+    ctx: ToolCtx
+    mode: ModuleMode
+  }): Promise<{ executed: boolean; certificate: SubstitutionCertDraft | null; module: string | null; errors: string[] }> {
+    for (const module of decisionModules) {
+      if (module.mode === 'off' || typeof module.substitute !== 'function') continue
+      if (module.id !== input.ctx.ticketId && false) continue
+      try {
+        const certificate = await module.substitute(input.edge, input.receipt, input.ctx)
+        if (!certificate) continue
+        // 非原生派发的证书一律拒绝（§5.5 硬约束）。
+        if (certificate.viaNativeDispatcher !== true) {
+          noteDegraded(module.id, 'substitute', new Error('substitute must go through the native dispatcher'))
+          continue
+        }
+        const executed = input.mode === 'enforce'
+        return { executed, certificate, module: module.id, errors: errors.slice() }
+      } catch (error) {
+        noteDegraded(module.id, 'substitute', error)
+      }
+    }
+    return { executed: false, certificate: null, module: null, errors: errors.slice() }
+  }
+
+  function beforeModelCall(info: ModelCallInfo): void {
+    for (const module of decisionModules) {
+      try { module.beforeModelCall?.(info) } catch (error) {
+        noteDegraded(module.id, 'beforeModelCall', error)
+      }
+    }
+  }
+
+  function afterModelResponse(info: ModelResponseInfo): void {
+    for (const module of decisionModules) {
+      try { module.afterModelResponse?.(info) } catch (error) {
+        noteDegraded(module.id, 'afterModelResponse', error)
+      }
+    }
+  }
+
+  function describe(): Array<{ id: string; kind: string; mode: string; surface: string }> {
+    return [
+      ...toolModules.map((module) => ({ id: module.id, kind: module.kind, mode: module.mode, surface: module.surface })),
+      ...decisionModules.map((module) => ({ id: module.id, kind: module.kind, mode: module.mode, surface: 'worker' })),
+    ]
+  }
+
+  /** 工具面常驻成本：各 A 模块自报之和（供 prompt 成本报表）。 */
+  function promptCost(): { toolTokens: number; schemaCount: number; byModule: Record<string, { toolTokens: number; schemaCount: number }> } {
+    const byModuleCost: Record<string, { toolTokens: number; schemaCount: number }> = {}
+    let toolTokens = 0
+    let schemaCount = 0
+    for (const module of toolModules) {
+      if (typeof module.promptCost !== 'function') continue
+      try {
+        const cost = module.promptCost()
+        const tokens = Math.max(0, Number(cost?.toolTokens ?? 0) || 0)
+        const count = Math.max(0, Number(cost?.schemaCount ?? 0) || 0)
+        byModuleCost[module.id] = { toolTokens: tokens, schemaCount: count }
+        toolTokens += tokens
+        schemaCount += count
+      } catch (error) {
+        noteDegraded(module.id, 'afterReceipt', error)
+      }
+    }
+    return { toolTokens, schemaCount, byModule: byModuleCost }
+  }
+
+  function summary(): { evaluated: number; applied: number; savedChars: number; estimatedTokens: number; byModule: Record<string, number> } {
+    return {
+      evaluated: stats.evaluated,
+      applied: stats.applied,
+      savedChars: stats.savedChars,
+      estimatedTokens: estimateTokens(stats.savedChars),
+      byModule: { ...byModule },
+    }
+  }
+
+  function degraded(): ModuleDegraded[] {
+    return degradedList.map((item) => ({ ...item }))
+  }
+
+  function resetTask(): void {
+    stats = { evaluated: 0, applied: 0, savedChars: 0 }
+    for (const key of Object.keys(byModule)) delete byModule[key]
+    errors.length = 0
+    degradedList.length = 0
+    degradedCounts.clear()
+  }
+
+  return Object.freeze({
+    register,
+    beforeToolDispatch,
+    afterToolReceipt,
+    transformToolResult: afterToolReceipt,
+    authorGraphs,
+    guardReceipt,
+    substitute,
+    beforeModelCall,
+    afterModelResponse,
+    describe,
+    promptCost,
+    summary,
+    degraded,
+    resetTask,
+  })
+}
+
+/** A1：把 tool-compact 的纯格式化函数适配成 ToolModule（SPI §6）。 */
+export function createCompactModule(mode?: string, options: { workspace?: string; spill?: boolean; spillThresholdChars?: number } = {}): ToolModule {
+  const resolved = normalizeCompactMode(mode) as ModuleMode
+  // spill：大输出落盘 + 摘要（原文仍可回读）。只在 enforce 生效，且必须有 workspace。
+  const spill = options.spill !== false && options.workspace
+    ? createSpillStore({ workspace: options.workspace })
+    : null
+  const compactor = createToolCompactor({
+    mode: 'enforce',
+    spill: spill ? { save: (input) => spill.save({ ticketId: 'worker', stepIndex: 0, toolName: 'tool', text: input.text }) } : null,
+    spillThresholdChars: options.spillThresholdChars,
+  })
+  const handled = new Set(['fs_read_file', 'fs_list_dir', 'fs_write_file', 'exec_shell_in_vm'])
+  return Object.freeze({
+    id: 'a1-compact' as const,
+    kind: 'tool' as const,
+    surface: 'worker' as const,
+    mode: resolved,
+    appliesTo(toolName: string): boolean {
+      return handled.has(String(toolName ?? ''))
+    },
+    afterReceipt(result: { text: string; truncated?: boolean }, ctx: ToolCtx) {
+      // 候选压缩结果一律算出；**由注册表按模式决定是否真的替换**（shadow 不改变执行）。
+      const candidate = compactor.compact({ toolName: ctx.originalToolName, text: result.text })
+      if (!candidate.evaluated || !candidate.applied) return null
+      return { text: candidate.text, truncated: result.truncated, savedTokens: candidate.estimatedTokens }
+    },
+    /** A1 不新增常驻工具：prompt 成本为 0（真实 schema 成本由 Agent Loop 另计）。 */
+    promptCost() {
+      return { toolTokens: 0, schemaCount: 0 }
+    },
+  })
+}

package/worker/cost-spi.ts

@@ -0,0 +1,283 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+// Copyright (c) 2026 dsh-Master contributors — see LICENSE-CORE.
+
+/**
+ * 3.3.0 模块层 SPI（ToolModule / DecisionModule，设计 §6 / §7）。
+ *
+ * 这是「系统层 ↔ 模块层」之间唯一的契约面：A 类模块（工具面）实现 ToolModule，
+ * B 类模块（决策复用）实现 DecisionModule；Worker 的四个切点只与注册表交互，
+ * 不认识任何具体模块。新增模块不需要改动 agent-loop.ts。
+ *
+ * 硬性约束（设计 §9）：
+ *   * 模块异常一律 fail-open 并留痕，不得中断 Agent Loop；
+ *   * 模块只能在**自己的**职责面内改写（A 类改工具调用/回执，B 类改决策复用），
+ *     不得触碰权限、Mandate、预算与状态机；
+ *   * `shadow` 档只计算、**不改变执行**（beforeDispatch 的改写/屏蔽只在 enforce 生效）；
+ *   * 每次生效必须产出归因（shadow 只报「本可节省」）。
+ */
+
+export type ToolModuleId = 'a1-compact' | 'a2-disclosure' | 'a3-batch'
+export type DecisionModuleId = 'b1-edg' | 'b2-gdr' | 'b3-ccs' | 'b4-rsi'
+export type ModuleMode = 'off' | 'shadow' | 'enforce'
+
+export interface ModuleAttribution {
+  module: ToolModuleId | DecisionModuleId
+  mode: ModuleMode
+  /** 是否真的改写了本次执行。 */
+  applied: boolean
+  originalChars: number
+  resultChars: number
+  savedChars: number
+  estimatedTokens: number
+  /** 附加信息（命中率、守卫名等），仅用于报表。 */
+  meta?: Record<string, unknown>
+}
+
+/* ------------------------------------------------------------------ *
+ * A 类：工具面模块（设计 §6 SPI）
+ * ------------------------------------------------------------------ */
+
+/** ③ 派发前的工具调用视图（只含路由所需字段，不含任何权限信息）。 */
+export interface ToolCallView {
+  id: string
+  name: string
+  /** 已解析的参数对象（原始 JSON 字符串由 Agent Loop 保留）。 */
+  args: Record<string, unknown>
+}
+
+/** ④ 工具回执视图。 */
+export interface ToolResultView {
+  text: string
+  /** Agent Loop 侧是否已按长度截断（模块不得反向「补长」）。 */
+  truncated?: boolean
+  /**
+   * 模块自算的归因节省（token）。给出时注册表优先采用它
+   * （例如 A1 的固定拟合式 §5.4.1），否则按「字符差/4」估算。
+   */
+  savedTokens?: number
+}
+
+export interface ToolCtx {
+  ticketId: string
+  stepIndex: number
+  /** 本模块当前生效档位（由注册表按模块自身 mode 注入）。 */
+  mode: ModuleMode
+  /** 原始工具名（beforeDispatch 改写后仍保留，便于模块识别自己）。 */
+  originalToolName: string
+}
+
+/**
+ * A 类：工具面模块。
+ *
+ *   * `beforeDispatch`（③）：工具名/描述映射，可隐藏官方工具（返回 `null`）；
+ *   * `afterReceipt`（④）：回执压缩，必须保留可用性（行号、可定位、错误可读）；
+ *   * `promptCost`：工具面常驻成本（供 prompt 成本报表）。
+ */
+export interface ToolModule {
+  readonly id: ToolModuleId
+  readonly kind: 'tool'
+  /**
+   * 作用面（设计 §3.3）：Worker 内注册的模块恒为 `worker`。
+   * 宿主会话工具面（dsh-ops 一类宿主插件）不在本 SPI 内，由宿主侧适配器单独归因。
+   */
+  readonly surface: 'worker'
+  readonly mode: ModuleMode
+  appliesTo(toolName: string): boolean
+  /**
+   * ③ 派发前：返回改写后的调用（可改 name/args）；
+   * 返回 `null` 表示**本模块屏蔽该工具**（不执行，回一条结构化拒绝给模型）。
+   * 仅在 `enforce` 档生效；shadow 只记录「本可屏蔽/改写」。
+   */
+  beforeDispatch?(call: ToolCallView, ctx: ToolCtx): ToolCallView | null
+  /** ④ 回执：返回压缩后的结果；`null` 表示不改。 */
+  afterReceipt?(result: ToolResultView, ctx: ToolCtx): ToolResultView | null
+  /** 工具面常驻成本（模块自报；为空表示不新增常驻工具）。 */
+  promptCost?(): { toolTokens: number; schemaCount: number }
+}
+
+/** 兼容别名：旧调用点用的 transformToolResult 输入/输出形态。 */
+export interface ToolTransformInput {
+  ticketId: string
+  stepIndex: number
+  toolName: string
+  args?: Record<string, unknown>
+  text: string
+  mode?: ModuleMode
+}
+
+export interface ToolTransformOutput {
+  text: string
+  applied: boolean
+  originalChars: number
+  resultChars: number
+  savedChars: number
+  estimatedTokens: number
+  meta?: Record<string, unknown>
+}
+
+/* ------------------------------------------------------------------ *
+ * B 类：决策复用模块（设计 §7 SPI）
+ * ------------------------------------------------------------------ */
+
+/** 工具回执（守卫判据的输入）。`digest` 是回执内容的稳定摘要。 */
+export interface ToolReceipt {
+  toolName: string
+  args: Record<string, unknown>
+  text: string
+  /** 回执摘要（schemaHash + 内容摘要），守卫与证书都用它做关联。 */
+  digest: string
+  stepIndex: number
+  ticketId: string
+}
+
+/** 可执行决策图的边/图/判定以 `worker/edg.ts`（B1）为唯一权威定义，这里只做再导出。 */
+export type { EdgGraph as Edg, EdgEdge, EdgGuard, EdgArgSource, EdgGraph, EdgState, EdgSource } from './edg.ts'
+import type { EdgGraph as EdgGraphType, EdgEdge as EdgEdgeType } from './edg.ts'
+
+/** 慢模型输出里抽取出的候选决策图（作者步骤产物；成本入 governance）。 */
+export interface EdgDraft {
+  edges: Array<Omit<EdgEdgeType, 'id'> & { id?: string }>
+  model?: string
+  note?: string
+}
+
+/** 守卫判定结果（GDR 的 `GdrMatch` 是它的超集）。 */
+export interface GuardVerdict {
+  hit: boolean
+  edgeId?: string
+  /** 未命中原因（可读、可审计）。 */
+  reason?: string
+  receiptDigest: string
+  /** 命中时预估「本可节省」的 token（shadow 用来算对照收益）。 */
+  wouldSaveTokens?: number
+}
+
+/** ② 作者步骤的输入快照。 */
+export interface TurnSnapshot {
+  ticketId: string
+  taskId?: string
+  turn: number
+  stepIndex: number
+  model?: string
+  /** 慢模型本轮文本输出。 */
+  assistant: string
+  toolCalls: Array<{ name: string; args: Record<string, unknown> }>
+  receipts: ToolReceipt[]
+}
+
+/** 替换证书草案（Worker 侧形态；host 侧同名类型用于审计链）。 */
+export interface SubstitutionCertDraft {
+  edgeId: string
+  toolName: string
+  schemaHash: string
+  guardExpr: string
+  receiptDigest: string
+  replacedCallbackId: string
+  viaNativeDispatcher: true
+  taskId: string
+  step: number
+  savedTokens?: number
+  moduleId?: string
+}
+
+export interface ModelCallInfo {
+  ticketId: string
+  stepIndex: number
+  model?: string
+  historyChars: number
+}
+
+export interface ModelResponseInfo {
+  ticketId: string
+  stepIndex: number
+  usage: { input: number; output: number; total: number }
+  latencyMs: number
+  /** provider 未返回 usage、由 harness 兜底估算（不得当实测上报）。 */
+  estimated?: boolean
+}
+
+/**
+ * B 类：决策复用模块（设计 §7）。
+ *
+ *   * `author`（②）：从慢模型输出抽取候选决策图，作者成本入 **governance**；
+ *   * `guard`（④）：拿回执判断是否命中已存边；
+ *   * `substitute`：命中后**经原生派发器**执行并返回证书。
+ *
+ * 三档语义（§5.3）由注册表强制：observe 只计数、shadow 只算并落证书、enforce 才真的替换。
+ */
+export interface DecisionModule {
+  readonly id: DecisionModuleId
+  readonly kind: 'decision'
+  readonly mode: ModuleMode
+  /** ② 作者步骤：产出候选 EDG（可为 null）。 */
+  author?(turn: TurnSnapshot): Promise<EdgDraft | null>
+  /** ④ 守卫：拿回执判断是否命中某条已存边。 */
+  guard?(receipt: ToolReceipt, graph: EdgGraphType): GuardVerdict
+  /** 命中后：经原生派发器执行并返回证书。 */
+  substitute?(edge: EdgEdgeType, receipt: ToolReceipt, ctx: ToolCtx): Promise<SubstitutionCertDraft>
+  /** 可选：模型调用前后（统计/RSI 反馈用）。 */
+  beforeModelCall?(info: ModelCallInfo): void
+  afterModelResponse?(info: ModelResponseInfo): void
+  /** 本模块累计的归因（命中/跳过次数等）。 */
+  attribution?(): ModuleAttribution | null
+}
+
+export type CostModule = ToolModule | DecisionModule
+
+/** 复用异常时的降级信号（目标 2.1-5：降级本身必须留痕，不伪装成节省）。 */
+export interface ModuleDegraded {
+  module: string
+  phase: 'beforeDispatch' | 'afterReceipt' | 'author' | 'guard' | 'substitute' | 'beforeModelCall' | 'afterModelResponse'
+  message: string
+  /** 同一模块+阶段累计发生次数（去重后上报，避免刷爆事件流）。 */
+  count: number
+  at: number
+}
+
+export interface ModuleRegistry {
+  /** 注册模块；重复 id 会被忽略并返回 false（先注册先得）。 */
+  register(module: CostModule): boolean
+  /** ③ 派发前：顺序应用 beforeDispatch；返回最终调用与是否被屏蔽。 */
+  beforeToolDispatch(input: {
+    ticketId: string
+    stepIndex: number
+    call: ToolCallView
+  }): { call: ToolCallView; hidden: false; attributions: ModuleAttribution[]; errors: string[] } | {
+    call: ToolCallView
+    hidden: true
+    hiddenBy: string
+    reason: string
+    attributions: ModuleAttribution[]
+    errors: string[]
+  }
+  /** ④ 回执：顺序应用 afterReceipt；返回最终文本与全部归因。 */
+  afterToolReceipt(input: ToolTransformInput): { text: string; attributions: ModuleAttribution[]; errors: string[] }
+  /** 兼容别名（等同 afterToolReceipt）。 */
+  transformToolResult(input: ToolTransformInput): { text: string; attributions: ModuleAttribution[]; errors: string[] }
+  /** 广播给 B 类模块。 */
+  beforeModelCall(info: ModelCallInfo): void
+  afterModelResponse(info: ModelResponseInfo): void
+  /** ② 作者步骤：收集候选决策图（成本入 governance，由宿主记账）。 */
+  authorGraphs(turn: TurnSnapshot): Promise<{ drafts: Array<{ module: string; draft: EdgDraft }>; errors: string[] }>
+  /** ④ 守卫：收集命中（observe 只计数 / shadow 落证书 / enforce 可替换）。 */
+  guardReceipt(input: { receipt: ToolReceipt; graph: EdgGraphType }): {
+    verdicts: Array<{ module: string; mode: ModuleMode; verdict: GuardVerdict }>
+    hit: { module: string; mode: ModuleMode; verdict: GuardVerdict } | null
+    errors: string[]
+  }
+  /** 命中后替换：仅 enforce 真正执行；shadow 只产出「本可替换」证书。 */
+  substitute(input: { edge: EdgEdgeType; receipt: ToolReceipt; ctx: ToolCtx; mode: ModuleMode }): Promise<{
+    executed: boolean
+    certificate: SubstitutionCertDraft | null
+    module: string | null
+    errors: string[]
+  }>
+  describe(): Array<{ id: string; kind: string; mode: string; surface: string }>
+  /** 工具面常驻成本（各 A 模块自报之和）。 */
+  promptCost(): { toolTokens: number; schemaCount: number; byModule: Record<string, { toolTokens: number; schemaCount: number }> }
+  /** 本次任务累计归因汇总（按模块）。 */
+  summary(): { evaluated: number; applied: number; savedChars: number; estimatedTokens: number; byModule: Record<string, number> }
+  /** 降级记录（模块异常留痕）。 */
+  degraded(): ModuleDegraded[]
+  resetTask(): void
+}