@twinsearth/dsh-master 3.2.10 → 3.3.1

package/src/cost/attribution.ts

@@ -0,0 +1,186 @@
+// 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 系统层 · attribution（归因，设计 §5.4）。
+ *
+ * 三条硬规则：
+ *   1. **每条 savedTokens 必须带 moduleId**（缺失 ⇒ `module-missing`，不猜、不默认）；
+ *   2. 差额进 `unattributed`，报表**单列**——未归因收益不得算作任何模块收益；
+ *   3. 归因算法（工具面）：`baselineOutputTokens(toolName, 长度) − actualOutputTokens`，
+ *      baseline 由 A1 固定拟合式给出（`worker/baseline-fit.ts`，参数在 docs §5.4.1 冻结）。
+ *
+ * 另守 §5.3 口径：`shadow` 只累计「本可节省」，`enforce` 才写入 execution 账本且
+ * `totalTokens=0`（不重复计入已消耗 token）。
+ */
+
+import { COST_MODULES } from './types.ts'
+
+function finiteNonNegative(value) {
+  const n = Number(value)
+  return Number.isFinite(n) && n >= 0 ? Math.floor(n) : null
+}
+
+/**
+ * @param {{ledger: {append: Function}, now?: () => number}} options
+ */
+export function createAttribution(options = {}) {
+  const ledger = options.ledger
+  if (!ledger || typeof ledger.append !== 'function') throw new Error('attribution requires a ledger')
+  const now = typeof options.now === 'function' ? options.now : () => Date.now()
+  const allowed = new Set(COST_MODULES)
+  const modules = new Map()
+  const tasks = new Map()
+
+  const moduleRow = (module) => {
+    if (!modules.has(module)) modules.set(module, { module, events: 0, projectedTokens: 0, enforceSavedTokens: 0 })
+    return modules.get(module)
+  }
+  const taskRow = (taskId, module) => {
+    const key = `${taskId ?? ''}|${module}`
+    if (!tasks.has(key)) tasks.set(key, { key, taskId: taskId === undefined ? null : String(taskId), module, events: 0, projectedTokens: 0, enforceSavedTokens: 0 })
+    return tasks.get(key)
+  }
+
+  /**
+   * @param {{taskId?: string, module: string, savedTokens: number, mode?: string, meta?: object,
+   *          forkId?: string, sessionId?: string}} input
+   */
+  function attribute(input = {}) {
+    const saved = finiteNonNegative(input.savedTokens)
+    if (saved === null) return { ok: false, code: 'saved-tokens-invalid', message: 'savedTokens must be a non-negative number' }
+    // §5.4-1：moduleId 必填，缺失不猜默认值。
+    if (input.module === undefined || input.module === null || String(input.module).trim() === '') {
+      return { ok: false, code: 'module-missing', message: 'every savedTokens must carry a moduleId' }
+    }
+    const module = String(input.module)
+    if (!allowed.has(module)) return { ok: false, code: 'module-invalid', message: `module must be one of ${COST_MODULES.join('/')}` }
+    const enforce = String(input.mode ?? 'shadow') === 'enforce'
+    const row = moduleRow(module)
+    const perTask = taskRow(input.taskId, module)
+
+    if (!enforce) {
+      row.events += 1
+      row.projectedTokens += saved
+      perTask.events += 1
+      perTask.projectedTokens += saved
+      return {
+        ok: true,
+        mode: 'shadow',
+        module,
+        projectedTokens: saved,
+        shadow: { events: row.events, projectedTokens: row.projectedTokens, appliedTokens: row.enforceSavedTokens },
+        at: now(),
+      }
+    }
+
+    const appended = ledger.append({
+      account: 'execution',
+      module,
+      source: 'tool',
+      phase: 'tool',
+      taskId: input.taskId === undefined ? null : String(input.taskId),
+      forkId: input.forkId,
+      sessionId: input.sessionId,
+      step: input.step,
+      turn: input.turn,
+      totalTokens: 0,
+      savedTokens: saved,
+      meta: { kind: 'attribution', ...(input.meta && typeof input.meta === 'object' ? input.meta : {}), mode: 'enforce' },
+    })
+    if (!appended.ok) return { ok: false, code: appended.code, message: appended.message }
+    row.events += 1
+    row.enforceSavedTokens += saved
+    perTask.events += 1
+    perTask.enforceSavedTokens += saved
+    return {
+      ok: true,
+      mode: 'enforce',
+      module,
+      savedTokens: saved,
+      ledger: { id: appended.entry.id },
+      shadow: { events: row.events, projectedTokens: row.projectedTokens, appliedTokens: row.enforceSavedTokens },
+      at: now(),
+    }
+  }
+
+  /**
+   * §5.4-2：按「总额 − 各模块之和」结算，差额自动进 `unattributed`。
+   * 任何未提供 moduleId 的条目都会被拒绝（模块收益不得凭空出现）。
+   *
+   * @param {{taskId?: string, totalSavedTokens: number, items?: Array<{module: string, savedTokens: number}>,
+   *          mode?: string, forkId?: string, sessionId?: string}} input
+   */
+  function attributeTotal(input = {}) {
+    const total = finiteNonNegative(input.totalSavedTokens)
+    if (total === null) return { ok: false, code: 'saved-tokens-invalid', message: 'totalSavedTokens must be a non-negative number' }
+    const items = Array.isArray(input.items) ? input.items : []
+    let attributed = 0
+    const applied = []
+    for (const item of items) {
+      const out = attribute({
+        taskId: input.taskId,
+        module: item?.module,
+        savedTokens: item?.savedTokens,
+        mode: input.mode,
+        forkId: input.forkId,
+        sessionId: input.sessionId,
+        meta: { kind: 'module-share' },
+      })
+      if (!out.ok) return out
+      attributed += finiteNonNegative(item?.savedTokens) ?? 0
+      applied.push({ module: String(item.module), savedTokens: finiteNonNegative(item?.savedTokens) ?? 0 })
+    }
+    if (attributed > total) {
+      return { ok: false, code: 'attribution-overflow', message: `attributed ${attributed} exceeds total ${total}` }
+    }
+    const residual = total - attributed
+    if (residual > 0) {
+      const out = attribute({
+        taskId: input.taskId,
+        module: 'unattributed',
+        savedTokens: residual,
+        mode: input.mode,
+        forkId: input.forkId,
+        sessionId: input.sessionId,
+        meta: { kind: 'residual' },
+      })
+      if (!out.ok) return out
+    }
+    return { ok: true, totalSavedTokens: total, attributedTokens: attributed, unattributedTokens: residual, items: applied, at: now() }
+  }
+
+  function snapshot() {
+    const moduleRows = [...modules.values()]
+      .map((item) => Object.freeze({ ...item }))
+      .sort((a, b) => b.projectedTokens + b.enforceSavedTokens - (a.projectedTokens + a.enforceSavedTokens))
+    const taskRows = [...tasks.values()]
+      .map((item) => Object.freeze({ ...item }))
+      .sort((a, b) => b.projectedTokens + b.enforceSavedTokens - (a.projectedTokens + a.enforceSavedTokens))
+    const named = moduleRows.filter((row) => row.module !== 'unattributed')
+    const unattributed = moduleRows.filter((row) => row.module === 'unattributed')
+    const sum = (rows, key) => rows.reduce((total, row) => total + row[key], 0)
+    return Object.freeze({
+      ok: true,
+      modules: moduleRows,
+      tasks: taskRows,
+      /** 模块收益（不含 unattributed）——报表只能把这一项当「模块业绩」。 */
+      attributedSavedTotal: sum(named, 'enforceSavedTokens'),
+      attributedProjectedTotal: sum(named, 'projectedTokens'),
+      /** 未归因收益：单列，永不并入上面的模块业绩。 */
+      unattributedSavedTotal: sum(unattributed, 'enforceSavedTokens'),
+      unattributedProjectedTotal: sum(unattributed, 'projectedTokens'),
+      projectedTotal: sum(moduleRows, 'projectedTokens'),
+      enforceSavedTotal: sum(moduleRows, 'enforceSavedTokens'),
+    })
+  }
+
+  function reset() {
+    modules.clear()
+    tasks.clear()
+    return { ok: true }
+  }
+
+  return Object.freeze({ attribute, attributeTotal, snapshot, reset })
+}

package/src/cost/audit.ts

@@ -0,0 +1,170 @@
+// 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 系统层 · audit（哈希链审计，设计 §5.5）。
+ *
+ * 结构约束：
+ *   * **只追加**：没有 update/delete/rewrite API，记录 `Object.freeze`；
+ *   * 每条记录含 `prevHash` 与自身 `hash`，任何篡改或截断都会在 `verify()` 断链；
+ *   * 每次替换写一条 `SubstitutionCert`（edgeId / toolName / schemaHash / guardExpr /
+ *     receiptDigest / replacedCallbackId / viaNativeDispatcher: true），
+ *     并与 ledger 事件用同一 `taskId + step` 关联 —— 报表可回放「这一省是怎么来的」。
+ */
+
+import crypto from 'node:crypto'
+
+/** SubstitutionCert 必填字段；缺任何一项都不得落链（否则证书无法复核）。 */
+const CERT_REQUIRED = Object.freeze([
+  'edgeId',
+  'toolName',
+  'schemaHash',
+  'guardExpr',
+  'receiptDigest',
+  'replacedCallbackId',
+  'taskId',
+])
+
+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'
+}
+
+function hashOf(seq, at, type, actor, payload, prevHash) {
+  const body = canonical([seq, at, type, actor, payload, prevHash])
+  return `sha256:${crypto.createHash('sha256').update(body).digest('hex')}`
+}
+
+/**
+ * @param {{now?: () => number, maxRecords?: number}} [options]
+ */
+export function createAuditChain(options = {}) {
+  const now = typeof options.now === 'function' ? options.now : () => Date.now()
+  const maxRecords = Math.max(1, Number(options.maxRecords ?? 2000) || 2000)
+  const records = []
+  let seq = 0
+  let dropped = 0
+
+  function append({ type, actor = 'cost-system', payload = {} } = {}) {
+    seq += 1
+    const at = now()
+    const prevHash = records.length > 0 ? records[records.length - 1].hash : ''
+    const record = Object.freeze({
+      seq,
+      at,
+      type: String(type ?? 'unknown'),
+      actor: String(actor ?? 'cost-system'),
+      payload: Object.freeze({ ...payload }),
+      prevHash,
+      hash: hashOf(seq, at, String(type ?? 'unknown'), String(actor ?? 'cost-system'), payload, prevHash),
+    })
+    records.push(record)
+    if (records.length > maxRecords) {
+      records.shift()
+      dropped += 1
+    }
+    return record
+  }
+
+  /**
+   * 写一条 SubstitutionCert（§5.5）。fail-closed：
+   *   * 必填字段缺失/空白 ⇒ 拒绝；
+   *   * `viaNativeDispatcher` 必须严格为 `true`（非原生派发不得替换）；
+   *   * `taskId + step` 是回放键，step 必须是非负整数。
+   */
+  function appendSubstitution(cert = {}) {
+    const missing = CERT_REQUIRED.filter((key) => {
+      const value = cert?.[key]
+      return value === undefined || value === null || String(value).trim() === ''
+    })
+    if (missing.length > 0) {
+      return { ok: false, code: 'cert-invalid', message: `substitution cert missing ${missing.join(',')}`, missing }
+    }
+    if (cert.viaNativeDispatcher !== true) {
+      return { ok: false, code: 'cert-not-native', message: 'substitution must be executed via the native dispatcher' }
+    }
+    const step = Number(cert.step)
+    if (!Number.isInteger(step) || step < 0) {
+      return { ok: false, code: 'cert-step-invalid', message: 'step must be a non-negative integer' }
+    }
+    const savedTokens = Number(cert.savedTokens ?? 0)
+    if (!Number.isFinite(savedTokens) || savedTokens < 0) {
+      return { ok: false, code: 'cert-saved-invalid', message: 'savedTokens must be a non-negative number' }
+    }
+    const payload = Object.freeze({
+      kind: 'substitution-cert',
+      edgeId: String(cert.edgeId),
+      toolName: String(cert.toolName),
+      schemaHash: String(cert.schemaHash),
+      guardExpr: String(cert.guardExpr),
+      receiptDigest: String(cert.receiptDigest),
+      replacedCallbackId: String(cert.replacedCallbackId),
+      /** M4：落链即代表「已经过原生派发器真的派发」；证书链核对直接读这一位。 */
+      dispatched: true,
+      viaNativeDispatcher: true,
+      taskId: String(cert.taskId),
+      step,
+      forkId: cert.forkId === undefined ? null : String(cert.forkId),
+      sessionId: cert.sessionId === undefined ? null : String(cert.sessionId),
+      ticketId: cert.ticketId === undefined ? null : String(cert.ticketId),
+      moduleId: cert.moduleId === undefined ? null : String(cert.moduleId),
+      savedTokens,
+    })
+    const record = append({ type: 'cost.substitution', actor: 'cost-ccs', payload })
+    return { ok: true, cert: payload, record }
+  }
+
+  function verify(source) {
+    const list = Array.isArray(source) ? source : records
+    let prevHash = ''
+    let expectedSeq = 1
+    for (const record of list) {
+      if (record.seq !== expectedSeq) return { ok: false, count: list.length, brokenAt: record.seq, reason: 'seq-gap' }
+      if (record.prevHash !== prevHash) return { ok: false, count: list.length, brokenAt: record.seq, reason: 'prev-hash-mismatch' }
+      const expected = hashOf(record.seq, record.at, record.type, record.actor, record.payload, record.prevHash)
+      if (record.hash !== expected) return { ok: false, count: list.length, brokenAt: record.seq, reason: 'hash-mismatch' }
+      prevHash = record.hash
+      expectedSeq += 1
+    }
+    return { ok: true, count: list.length, brokenAt: null, reason: null }
+  }
+
+  function snapshot(limit = 50) {
+    const n = Math.max(1, Number(limit) || 50)
+    return Object.freeze({
+      ok: true,
+      count: records.length,
+      dropped,
+      verified: verify(),
+      records: records.slice(-n),
+    })
+  }
+
+  function reset() {
+    records.length = 0
+    seq = 0
+    dropped = 0
+    return { ok: true }
+  }
+
+  /** 取某任务/步骤的证书（回放用；不改链）。 */
+  function substitutions(filter = {}) {
+    const taskId = filter.taskId === undefined ? null : String(filter.taskId)
+    const step = filter.step === undefined ? null : Number(filter.step)
+    const rows = records
+      .filter((record) => record.type === 'cost.substitution')
+      .filter((record) => (taskId === null ? true : record.payload.taskId === taskId))
+      .filter((record) => (step === null ? true : record.payload.step === step))
+    return Object.freeze(rows.map((record) => Object.freeze({ ...record.payload, seq: record.seq, at: record.at, hash: record.hash })))
+  }
+
+  // 只追加：对外**不暴露**任何修改/删除入口（records() 返回副本）。
+  return Object.freeze({ append, appendSubstitution, verify, snapshot, reset, records: () => records.slice(), substitutions })
+}

package/src/cost/budget.ts

@@ -0,0 +1,226 @@
+// 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 系统层 · budget（预算闸，设计 §5.2）。
+ *
+ * 规格要点：
+ *   * 规则：`unit(task|fork|day) + limitTokens? + limitCost? + onExhaust(hard-stop|degrade)`；
+ *   * **检查点只在 ① beforeModelCall**（`authorize()` 即该检查点，其它地方不得自行扣减）；
+ *   * 超限返回 `masterError('budget-exhausted', …)` 形状 + 结构化 `remaining`；
+ *   * **fail-closed**：额度不足不得「先跑着看」——拒绝时**不扣额度**、不放行；
+ *   * `degrade` 档只允许降级到**已在白名单**的廉价模型，绝不引入新 provider。
+ *
+ * 成本维度（`limitCost`）需要调用方给出本次预估成本（`cost` 字段）；
+ * 未提供成本时成本维度不可判定，会显式标 `costTracked: false`，而不是假装达标。
+ */
+
+import { DEFAULT_BUDGET_LIMITS } from './types.ts'
+
+const UNITS = ['task', 'fork', 'day']
+const EXHAUST_ACTIONS = ['hard-stop', 'degrade']
+
+/** 与 kernel.masterError 同形状（host 侧不反向依赖 kernel，避免子系统耦合）。 */
+function masterError(code, message, detail) {
+  const out = { ok: false, code: String(code), error: String(message ?? code) }
+  if (detail !== undefined) out.detail = detail
+  return out
+}
+
+function positiveLimit(value) {
+  const n = Number(value)
+  return Number.isFinite(n) && n > 0 ? Math.floor(n) : null
+}
+
+function keyOf(unit, key) {
+  return `${unit}:${String(key ?? 'default')}`
+}
+
+/**
+ * @param {{
+ *   limits?: Array<{unit:string, limitTokens?:number, limitCost?:number, onExhaust?:string, degradeTo?:string}>,
+ *   degradeModels?: string[],   // degrade 允许的廉价模型白名单（不在此列表 ⇒ 一律 hard-stop）
+ *   now?: () => number,
+ * }} [options]
+ */
+export function createBudget(options = {}) {
+  const now = typeof options.now === 'function' ? options.now : () => Date.now()
+  const source = Array.isArray(options.limits) && options.limits.length > 0 ? options.limits : DEFAULT_BUDGET_LIMITS
+  const degradeModels = Object.freeze(
+    (Array.isArray(options.degradeModels) ? options.degradeModels : [])
+      .map((item) => String(item ?? '').trim())
+      .filter(Boolean),
+  )
+  const limits = []
+  const invalid = []
+  for (const item of source) {
+    const unit = String(item?.unit ?? '')
+    const limitTokens = item?.limitTokens === undefined ? null : positiveLimit(item.limitTokens)
+    const limitCost = item?.limitCost === undefined ? null : positiveLimit(item.limitCost)
+    if (!UNITS.includes(unit) || (limitTokens === null && limitCost === null)) {
+      // 既无 token 上限也无成本上限的规则没有意义：配置错误必须显式暴露（fail-closed）。
+      invalid.push({ unit, limitTokens: item?.limitTokens, limitCost: item?.limitCost })
+      continue
+    }
+    if (limits.some((rule) => rule.unit === unit)) {
+      // 同一 unit 只能有一条规则（先注册先得），否则判定口径不确定。
+      invalid.push({ unit, reason: 'duplicate-unit' })
+      continue
+    }
+    const onExhaust = EXHAUST_ACTIONS.includes(String(item?.onExhaust)) ? String(item.onExhaust) : 'hard-stop'
+    const degradeTo = item?.degradeTo === undefined ? null : String(item.degradeTo)
+    // degrade 档必须在白名单内，否则等于开了个后门：降级为 hard-stop。
+    const effective = onExhaust === 'degrade' && degradeTo !== null && degradeModels.includes(degradeTo)
+      ? 'degrade'
+      : 'hard-stop'
+    if (onExhaust === 'degrade' && effective !== 'degrade') {
+      invalid.push({ unit, degradeTo, reason: 'degrade-model-not-allowlisted' })
+    }
+    limits.push(Object.freeze({
+      unit,
+      limitTokens,
+      limitCost,
+      onExhaust: effective,
+      degradeTo: effective === 'degrade' ? degradeTo : null,
+    }))
+  }
+  const limitOf = (unit) => limits.find((item) => item.unit === unit) ?? null
+  const consumed = new Map()
+  const used = (unit, key) => consumed.get(keyOf(unit, key)) ?? { tokens: 0, cost: 0 }
+
+  /**
+   * ① beforeModelCall 的唯一检查点。
+   * @param {{unit: string, key?: string, tokens?: number, cost?: number}} input
+   */
+  function authorize(input = {}) {
+    const unit = String(input.unit)
+    const key = String(input.key ?? 'default')
+    const requested = Number(input.tokens ?? 0)
+    const requestedCost = Number(input.cost ?? 0)
+    if (!Number.isFinite(requested) || requested < 0) {
+      return masterError('tokens-invalid', 'tokens must be a non-negative number')
+    }
+    if (!Number.isFinite(requestedCost) || requestedCost < 0) {
+      return masterError('cost-invalid', 'cost must be a non-negative number')
+    }
+    const limit = limitOf(unit)
+    if (!limit) {
+      return { ok: true, unlimited: true, unit, key, requested, remaining: null, costTracked: false, at: now() }
+    }
+
+    const current = used(unit, key)
+    const remainingTokens = limit.limitTokens === null ? null : Math.max(0, limit.limitTokens - current.tokens)
+    const remainingCost = limit.limitCost === null ? null : Math.max(0, limit.limitCost - current.cost)
+    const tokenExhausted = limit.limitTokens !== null && requested > remainingTokens
+    const costExhausted = limit.limitCost !== null && requestedCost > remainingCost
+    const costTracked = limit.limitCost === null ? false : Number(input.cost) > 0
+
+    if (tokenExhausted || costExhausted) {
+      const reason = tokenExhausted ? 'tokens' : 'cost'
+      // degrade 档：只降级到白名单里的廉价模型；否则一律 fail-closed。
+      if (limit.onExhaust === 'degrade' && limit.degradeTo && degradeModels.includes(limit.degradeTo)) {
+        return {
+          ok: true,
+          degraded: true,
+          action: 'degrade',
+          unit,
+          key,
+          model: limit.degradeTo,
+          reason,
+          limitTokens: limit.limitTokens,
+          limitCost: limit.limitCost,
+          consumedTokens: current.tokens,
+          consumedCost: current.cost,
+          remainingTokens,
+          remainingCost,
+          requested,
+          requestedCost,
+          costTracked,
+          onExhaust: 'degrade',
+          at: now(),
+        }
+      }
+      // fail-closed：拒绝且**不扣额度**，绝不「先跑着看」。
+      return masterError('budget-exhausted', `预算不足：${unit}/${key} 剩余 ${remainingTokens ?? '∞'} token`, {
+        unit,
+        key,
+        reason,
+        limitTokens: limit.limitTokens,
+        limitCost: limit.limitCost,
+        consumedTokens: current.tokens,
+        consumedCost: current.cost,
+        remainingTokens,
+        remainingCost,
+        requested,
+        requestedCost,
+        costTracked,
+        onExhaust: limit.onExhaust,
+        /** 剩余信息同时平铺在顶层，便于调用方不需解 detail。 */
+        remaining: { tokens: remainingTokens, cost: remainingCost },
+        at: now(),
+      })
+    }
+
+    const nextTokens = current.tokens + Math.floor(requested)
+    const nextCost = current.cost + requestedCost
+    consumed.set(keyOf(unit, key), { tokens: nextTokens, cost: nextCost })
+    return {
+      ok: true,
+      unit,
+      key,
+      requested,
+      requestedCost,
+      consumedTokens: nextTokens,
+      consumedCost: nextCost,
+      limitTokens: limit.limitTokens,
+      limitCost: limit.limitCost,
+      remainingTokens: limit.limitTokens === null ? null : limit.limitTokens - nextTokens,
+      remainingCost: limit.limitCost === null ? null : limit.limitCost - nextCost,
+      costTracked,
+      at: now(),
+    }
+  }
+
+  function refund({ unit, key = 'default', tokens = 0, cost = 0 } = {}) {
+    const n = Number(tokens)
+    const c = Number(cost)
+    if (!Number.isFinite(n) || n < 0 || !Number.isFinite(c) || c < 0 || (n === 0 && c === 0)) {
+      return masterError('refund-invalid', 'refund requires positive tokens and/or cost')
+    }
+    const k = keyOf(String(unit), key)
+    const current = consumed.get(k) ?? { tokens: 0, cost: 0 }
+    const next = { tokens: Math.max(0, current.tokens - Math.floor(n)), cost: Math.max(0, current.cost - c) }
+    consumed.set(k, next)
+    return { ok: true, unit: String(unit), key: String(key), consumedTokens: next.tokens, consumedCost: next.cost, at: now() }
+  }
+
+  function state() {
+    const rows = []
+    for (const limit of limits) {
+      for (const [k, value] of consumed.entries()) {
+        const prefix = `${limit.unit}:`
+        if (!k.startsWith(prefix)) continue
+        rows.push(Object.freeze({
+          unit: limit.unit,
+          key: k.slice(prefix.length),
+          consumedTokens: value.tokens,
+          consumedCost: value.cost,
+          limitTokens: limit.limitTokens,
+          limitCost: limit.limitCost,
+          remainingTokens: limit.limitTokens === null ? null : Math.max(0, limit.limitTokens - value.tokens),
+          remainingCost: limit.limitCost === null ? null : Math.max(0, limit.limitCost - value.cost),
+          onExhaust: limit.onExhaust,
+        }))
+      }
+    }
+    return Object.freeze({ ok: true, limits, invalid, degradeModels: degradeModels.slice(), rows, at: now() })
+  }
+
+  function reset() {
+    consumed.clear()
+    return { ok: true }
+  }
+
+  return Object.freeze({ authorize, refund, state, reset, limits: () => limits.slice(), degradeModels: () => degradeModels.slice() })
+}

package/src/cost/bus.ts

@@ -0,0 +1,97 @@
+// 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 系统层 · bus（事件总线与回流出口，设计 §5.6）。
+ *
+ * 对外只暴露三种内部事件（冒号命名，与 Router 事件通道一致）：
+ *   * `cost:event`         —— 账本/归因/预算等一般成本事件（payload.kind 区分）；
+ *   * `cost:degraded`      —— 模块降级（不伪装成节省）；
+ *   * `cost:substitution`  —— 替换证书（与审计链同源）。
+ *
+ * 可选对外出口（3.3.0 不阻塞主线）：
+ *   * `web`  —— Worker→Router 既有事件通道（Router 落库后供状态页/分身信息栏读取）；
+ *   * `fang` —— 瓮城「产物回流」；未就绪时状态里必须显式 `available: false` + 原因，
+ *               **不得**静默丢弃或假装成功。
+ */
+
+export const COST_EVENT_TYPES = Object.freeze(['cost:event', 'cost:degraded', 'cost:substitution'])
+
+/**
+ * @param {{maxEvents?: number, now?: () => number, relays?: Array<{name:string, publish?:Function, available?:boolean, reason?:string}>}} [options]
+ */
+export function createCostBus(options = {}) {
+  const now = typeof options.now === 'function' ? options.now : () => Date.now()
+  const maxEvents = Math.max(1, Number(options.maxEvents ?? 200) || 200)
+  const events = []
+  const subscribers = new Set()
+  /** 外部出口（web / fang）；available=false 的出口只记录状态，不投递。 */
+  const relays = (Array.isArray(options.relays) ? options.relays : [])
+    .filter((relay) => relay && typeof relay === 'object' && relay.name)
+    .map((relay) => ({
+      name: String(relay.name),
+      publish: typeof relay.publish === 'function' ? relay.publish : null,
+      available: relay.available === true && typeof relay.publish === 'function',
+      reason: String(relay.reason ?? ''),
+      delivered: 0,
+      failed: 0,
+    }))
+  let dropped = 0
+
+  function publish(type, payload = {}) {
+    const event = Object.freeze({ type: String(type ?? 'unknown'), at: now(), payload: Object.freeze({ ...payload }) })
+    events.push(event)
+    if (events.length > maxEvents) {
+      events.shift()
+      dropped += 1
+    }
+    for (const listener of [...subscribers]) {
+      try { listener(event) } catch { /* 订阅者异常不影响成本链路 */ }
+    }
+    for (const relay of relays) {
+      if (!relay.available || !relay.publish) continue
+      try {
+        relay.publish(event)
+        relay.delivered += 1
+      } catch {
+        relay.failed += 1
+        // 出口失败不得影响主流程，但必须留痕（failed 计数），不静默吞掉。
+      }
+    }
+    return event
+  }
+
+  function subscribe(listener) {
+    if (typeof listener !== 'function') return () => {}
+    subscribers.add(listener)
+    return () => { subscribers.delete(listener) }
+  }
+
+  function snapshot(limit = 50) {
+    const n = Math.max(1, Number(limit) || 50)
+    return Object.freeze({
+      ok: true,
+      count: events.length,
+      dropped,
+      subscribers: subscribers.size,
+      events: events.slice(-n),
+      /** §5.6 出口状态：不可用必须显式说明原因，不假装成功。 */
+      relays: relays.map((relay) => Object.freeze({
+        name: relay.name,
+        available: relay.available,
+        reason: relay.reason,
+        delivered: relay.delivered,
+        failed: relay.failed,
+      })),
+    })
+  }
+
+  function reset() {
+    events.length = 0
+    dropped = 0
+    return { ok: true }
+  }
+
+  return Object.freeze({ publish, subscribe, snapshot, reset })
+}