@twinsearth/dsh-master 3.2.10 → 3.3.0

package/src/cost/types.ts

@@ -0,0 +1,298 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+// Copyright (c) 2026 dsh-Master contributors — see LICENSE-CORE.
+
+/**
+ * 3.3.0 成本优化系统层的共享类型（M1）。
+ *
+ * 只放类型与常量，不含运行时逻辑；host 侧 `src/cost/*` 与插件编排器共用。
+ * 对齐 `docs/DESIGN-v3.3.0-cost-optimization.md` §5（系统层）与 §9（安全不变量）。
+ */
+
+/** 两本账：执行节省 vs 治理成本（HarnessMM 论文要求分开核算）。 */
+export type CostAccount = 'execution' | 'governance'
+
+/** 归因模块 id；a* = 工具面（dsh-ops 方向），b* = 决策复用（HarnessMM 方向）。 */
+export type CostModuleId =
+  | 'a1-compact'
+  | 'a2-disclosure'
+  | 'a3-batch'
+  | 'b1-edg'
+  | 'b2-gdr'
+  | 'b3-ccs'
+  | 'b4-rsi'
+  | 'unattributed'
+
+export type CostSource = 'model' | 'tool' | 'substitution' | 'retry' | 'authoring' | 'offline'
+
+/** 事件相位（设计 §5.1）：prompt / completion / tool / authoring / substitution。 */
+export type CostPhase = 'prompt' | 'completion' | 'tool' | 'authoring' | 'substitution'
+
+export const COST_PHASES: readonly CostPhase[] = Object.freeze(['prompt', 'completion', 'tool', 'authoring', 'substitution'])
+
+/**
+ * 作用面（设计 §3.3）：宿主会话工具面与 master Worker 工具面是**两个不同面板**，
+ * 节省必须分开记账，否则会把「装了别人的宿主插件」算成自己的收益。
+ *   * `worker` —— 本项目 Worker 自带工具面（`worker/tools.ts`），A1–A3 在这里生效；
+ *   * `host`   —— 宿主会话工具面（dsh-ops 一类宿主插件生效的地方），本项目只做
+ *                 **可选适配器 + 归因**，不重写、不冒领。
+ */
+export type CostSurface = 'worker' | 'host'
+
+export interface CostTokens {
+  input: number
+  output: number
+  total: number
+}
+
+export interface CostEntryInput {
+  account: CostAccount
+  module?: CostModuleId
+  source?: CostSource
+  /** 相位；缺省由 source 推导（见 ledger.ts PHASE_OF_SOURCE）。 */
+  phase?: CostPhase
+  /** 作用面；缺省为 worker（本项目的自研模块都在这面）。 */
+  surface?: CostSurface
+  /** 外部适配器上报（如 dsh-ops 在宿主面的收益）：只展示，永不计入本项目 executionSaved。 */
+  external?: boolean
+  taskId?: string
+  forkId?: string
+  sessionId?: string
+  /** 会话内轮次与循环步号（可回放定位）。 */
+  turn?: number
+  step?: number
+  provider?: string
+  model?: string
+  toolName?: string
+  ticketId?: string
+  inputTokens?: number
+  outputTokens?: number
+  cachedTokens?: number
+  totalTokens?: number
+  /** 对照组（observe）同任务基线；给出时才计算 saved。 */
+  baselineTokens?: number
+  /** 显式节省归因；给出时优先于 baseline 推导。 */
+  savedTokens?: number
+  /** provider 未返回 usage 时的兜底估算：报表与实测分开列，不混算。 */
+  estimated?: boolean
+  meta?: Record<string, unknown>
+}
+
+export interface CostEntry extends CostTokens {
+  id: string
+  at: number
+  account: CostAccount
+  module: CostModuleId
+  source: CostSource
+  phase: CostPhase
+  surface: CostSurface
+  external: boolean
+  taskId: string | null
+  forkId: string | null
+  sessionId: string | null
+  turn: number
+  step: number
+  provider: string | null
+  model: string | null
+  toolName: string | null
+  ticketId: string | null
+  cached: number
+  baselineTokens: number | null
+  savedTokens: number
+  estimated: boolean
+  meta: Record<string, unknown>
+}
+
+export interface CostBlock {
+  input: number
+  output: number
+  total: number
+  saved: number
+  entries: number
+}
+
+export interface CostSurfaceRow extends CostBlock {
+  surface: CostSurface
+  external: boolean
+}
+
+export interface CostTaskRow extends CostBlock {
+  key: string
+}
+
+export interface CostModuleRow extends CostBlock {
+  module: CostModuleId
+}
+
+export interface CostForkRow extends CostBlock {
+  forkId: string
+}
+
+/** 估算与实测必须分开列（设计 §5.1）：总量各自累计，绝不相加。 */
+export interface CostEstimateSplit {
+  measuredTokens: number
+  measuredEntries: number
+  estimatedTokens: number
+  estimatedEntries: number
+  /** 估算值占全部 token 的比例（0..1），用于报表标注可信度。 */
+  estimatedRatio: number
+}
+
+export interface CostLedgerSnapshot {
+  ok: true
+  count: number
+  dropped: number
+  execution: CostBlock
+  governance: CostBlock
+  netSaved: number
+  ownExecutionSaved: number
+  externalSaved: number
+  /** 按作用面拆分：本项目（worker）与外部适配器（host）永不相加。 */
+  bySurface: CostSurfaceRow[]
+  byModule: CostModuleRow[]
+  byTask: CostTaskRow[]
+  byFork: CostForkRow[]
+  /** 实测 vs 估算（不混算）。 */
+  tokens: CostEstimateSplit
+  persistence: { enabled: boolean; file: string | null; appended: number; failed: number }
+}
+
+export interface CostQuery {
+  taskId?: string
+  forkId?: string
+  sessionId?: string
+  ticketId?: string
+  module?: string
+  account?: CostAccount
+  phase?: CostPhase
+  surface?: CostSurface
+  external?: boolean
+  estimated?: boolean
+  /** 时间窗（含边界）。 */
+  from?: number
+  to?: number
+  limit?: number
+}
+
+export type BudgetUnit = 'task' | 'fork' | 'day'
+export type BudgetExhaustAction = 'hard-stop' | 'degrade'
+
+export interface BudgetRule {
+  unit: BudgetUnit
+  /** token 上限（> 0）。与 limitCost 至少给一个，否则规则无效（fail-closed）。 */
+  limitTokens?: number
+  /** 成本上限（同一货币单位；需要调用方在 authorize 时给 cost 才可判定）。 */
+  limitCost?: number
+  /** 超限策略；默认 hard-stop。 */
+  onExhaust?: BudgetExhaustAction
+  /** degrade 档目标模型；必须在 degradeModels 白名单内，否则自动退化为 hard-stop。 */
+  degradeTo?: string
+}
+
+/** @deprecated 使用 BudgetRule（保留别名以兼容早期调用）。 */
+export type BudgetLimit = BudgetRule
+
+export interface BudgetStateRow {
+  unit: BudgetUnit
+  key: string
+  consumedTokens: number
+  consumedCost: number
+  limitTokens: number | null
+  limitCost: number | null
+  remainingTokens: number | null
+  remainingCost: number | null
+  onExhaust: BudgetExhaustAction
+}
+
+export type PolicyMode = 'observe' | 'shadow' | 'enforce'
+
+export interface EnforceEvidence {
+  /** shadow 期守卫准确率（0..1）。 */
+  accuracy?: number
+  /** shadow 期样本数。 */
+  samples?: number
+  /** shadow 期破坏性工具命中次数（必须为 0）。 */
+  destructiveHits?: number
+}
+
+export interface PolicyDescription {
+  mode: PolicyMode
+  requestedMode: PolicyMode
+  allowlist: string[]
+  gate: { minAccuracy: number; minSamples: number; allowlistRequired: true }
+  lastRefusal: { at: number; next: PolicyMode; reasons: string[] } | null
+}
+
+export interface AuditRecord {
+  seq: number
+  at: number
+  type: string
+  actor: string
+  payload: Record<string, unknown>
+  prevHash: string
+  hash: string
+}
+
+/**
+ * 替换证书（设计 §5.5）：每一次「用已解决决策替换慢模型回调」都必须留下这张凭证。
+ * 与 ledger 事件用同一 `taskId + step` 关联，因此可回放「这一省是怎么来的」。
+ */
+export interface SubstitutionCert {
+  /** 可执行决策图（B1）中的边标识。 */
+  edgeId: string
+  /** 被替换回调原本要调用的工具。 */
+  toolName: string
+  /** 工具 schema 的哈希：schema 变了，旧决策不得复用。 */
+  schemaHash: string
+  /** 守卫表达式（B2 判据），保留原文以便复核。 */
+  guardExpr: string
+  /** 命中时工具回执的摘要（B2 依据它判断守卫）。 */
+  receiptDigest: string
+  /** 被替换掉的模型回调标识（慢模型那一次）。 */
+  replacedCallbackId: string
+  /** 必须经 DSH 原生派发器执行：恒为 true（false 一律拒绝）。 */
+  viaNativeDispatcher: true
+  /** 关联键（与 ledger 事件一致）。 */
+  taskId: string
+  step: number
+  /** 本次替换的归因节省（token）。 */
+  savedTokens?: number
+  moduleId?: string
+  forkId?: string
+  sessionId?: string
+  ticketId?: string
+  at?: number
+}
+
+export const COST_MODULES: readonly CostModuleId[] = Object.freeze([
+  'a1-compact',
+  'a2-disclosure',
+  'a3-batch',
+  'b1-edg',
+  'b2-gdr',
+  'b3-ccs',
+  'b4-rsi',
+  'unattributed',
+])
+
+export const COST_SOURCES: readonly CostSource[] = Object.freeze([
+  'model',
+  'tool',
+  'substitution',
+  'retry',
+  'authoring',
+  'offline',
+])
+
+export const POLICY_MODES: readonly PolicyMode[] = Object.freeze(['observe', 'shadow', 'enforce'])
+
+/** 两个作用面（设计 §3.3）：不可合并统计。 */
+export const COST_SURFACES: readonly CostSurface[] = Object.freeze(['worker', 'host'])
+
+/** 默认预算：与 Worker 现有 maxTokens 对齐（task=50k），fork=500k。 */
+export const DEFAULT_BUDGET_LIMITS: readonly BudgetLimit[] = Object.freeze([
+  Object.freeze({ unit: 'task' as BudgetUnit, limitTokens: 50_000, onExhaust: 'hard-stop' as BudgetExhaustAction }),
+  Object.freeze({ unit: 'fork' as BudgetUnit, limitTokens: 500_000, onExhaust: 'hard-stop' as BudgetExhaustAction }),
+])
+
+/** enforce 门禁（设计 §13）：准确率 ≥0.98、样本 ≥20、零破坏性命中、非空白名单。 */
+export const ENFORCE_GATE = Object.freeze({ minAccuracy: 0.98, minSamples: 20 })

package/src/kernel.ts

@@ -10,7 +10,7 @@
 
 import crypto from 'node:crypto'
 
-export const MASTER_VERSION = '3.2.10'
+export const MASTER_VERSION = '3.3.0'
 export const FANG_CONTRACT_MIN = '3.1.14'
 
 export const SERVICE = Object.freeze({
@@ -21,6 +21,31 @@ export const SERVICE = Object.freeze({
   dual: 'dshMasterDual',
 })
 
+/**
+ * 3.3.0 §11：成本系统的**可选子服务**。
+ *
+ * 主服务 `SERVICE.cost` 的形态不变（向后兼容）；子服务由 cost-optimizer 在能力允许时
+ * 额外 `provide`，消费方必须用 `probeOptionalServices(ctx)` **探测**而不是假定存在 ——
+ * 缺了就是缺了，不能假装拿到空壳对象。
+ */
+export const OPTIONAL_SERVICE = Object.freeze({
+  costLedger: 'dshMasterCostLedger',
+  costBudget: 'dshMasterCostBudget',
+  costPolicy: 'dshMasterCostPolicy',
+  costAudit: 'dshMasterCostAudit',
+})
+
+/** 探测可选子服务是否就位（只读、无副作用）。 */
+export function probeOptionalServices(ctx) {
+  const present = {}
+  for (const [key, name] of Object.entries(OPTIONAL_SERVICE)) {
+    try {
+      present[key] = typeof ctx?.get === 'function' ? Boolean(ctx.get(name)) : false
+    } catch { present[key] = false }
+  }
+  return present
+}
+
 export const FANG_SERVICE = Object.freeze({
   orchestrator: 'fang',
   forker: 'fangForker',
@@ -41,7 +66,7 @@ export const ROW = Object.freeze({
 export const ROLE = Object.freeze({ mother: 'mother', essence: 'essence', fork: 'fork' })
 
 /**
- * 角色矩阵（3.2.10）：
+ * 角色矩阵：
  *   * Router 在 essence 与 mother 激活：只评估/建票/派发，不执行代码；fork 不注册。
  *   * Worker / Worker Agent Loop 在 fork 与 essence 激活：原身可直接执行工单，
  *     分身仍是默认执行体；mother 不执行。