@twinsearth/dsh-master 3.2.9 → 3.3.0

package/src/cost/experiment.ts

@@ -0,0 +1,136 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+// Copyright (c) 2026 dsh-Master contributors — see LICENSE-CORE.
+// @ts-nocheck — host JS→TS 迁移阶段：运行时行为优先，类型注解逐步补齐（worker/ 仍严格检查）。
+
+/**
+ * M5 实验台：**A/B 对照执行器**（control = ccs off / enforce = ccs enforce）。
+ *
+ * 设计原则（决定它能不能当证据）：
+ *   * 走**真实 Worker 代码路径**（工具注册表、A1 紧凑、A3 批量、B1/B2/B3 全都在）；
+ *   * 每组 ≥10 任务，**同一 corpus 同一顺序**，control 与 enforce 只差一个开关；
+ *   * 输出**同表**：tokens/task 与成功率并列，绝不只报实验组；
+ *   * **自报口径**：`harness:'local-dry-run'` 与 `runner` 字段写进结果 ——
+ *     用脚本化 LLM 跑的 dry run 不能冒充「真实 fork 实机」证据（G5 会因此继续被挡住）。
+ */
+
+export const EXPERIMENT_HARNESS = Object.freeze({
+  dryRun: 'local-dry-run',
+  /** 真实 provider + 真实 Worker 代码路径（票据可以是合成的，但模型与工具是真的）。 */
+  realProvider: 'real-provider-real-worker',
+  realFork: 'real-fork',
+})
+
+const num = (value) => {
+  const n = Number(value)
+  return Number.isFinite(n) ? n : 0
+}
+
+/**
+ * 单组执行：把 corpus 逐个跑完，收集指标。
+ *
+ * @param {{
+ *   tasks: Array<{taskId: string, run: (task: object) => Promise<object>}>,
+ *   group: 'control' | 'enforce',
+ * }} input
+ */
+export async function runGroup(input = {}) {
+  const tasks = Array.isArray(input.tasks) ? input.tasks : []
+  const rows = []
+  for (const task of tasks) {
+    const startedAt = Date.now()
+    let result
+    try {
+      result = await task.run(task)
+    } catch (error) {
+      result = { ok: false, error: { code: 'harness-error', message: error instanceof Error ? error.message : String(error) } }
+    }
+    const elapsedMs = Date.now() - startedAt
+    const cost = result?.cost ?? {}
+    rows.push({
+      taskId: String(task.taskId),
+      ok: result?.ok === true,
+      tokens: num(result?.tokenUsage),
+      elapsedMs: num(result?.elapsedMs) || elapsedMs,
+      steps: Array.isArray(result?.steps) ? result.steps.length : 0,
+      a1: cost.compaction
+        ? {
+          mode: cost.compaction.mode,
+          applied: cost.compaction.applied === true,
+          savedChars: num(cost.compaction.savedChars),
+          estimatedTokens: num(cost.compaction.estimatedTokens),
+        }
+        : null,
+      a3: cost.batch ? { taught: cost.batch.taught === true, corrections: num(cost.batch.corrections) } : null,
+      reuse: cost.ccs
+        ? {
+          mode: cost.ccs.mode,
+          attempts: Array.isArray(cost.ccs.attempts) ? cost.ccs.attempts.length : 0,
+          hits: Array.isArray(cost.ccs.attempts) ? cost.ccs.attempts.filter((item) => item.hit === true).length : 0,
+          wouldSaveTokens: Array.isArray(cost.ccs.attempts) ? cost.ccs.attempts.reduce((sum, item) => sum + num(item.wouldSaveTokens), 0) : 0,
+          skippedModelCalls: num(cost.ccs.skippedModelCalls),
+          substitutions: Array.isArray(cost.ccs.substitutions) ? cost.ccs.substitutions.length : 0,
+          dispatched: Array.isArray(cost.ccs.substitutions) ? cost.ccs.substitutions.filter((cert) => cert.dispatched === true).length : 0,
+          failures: Array.isArray(cost.ccs.substitutions) ? cost.ccs.substitutions.filter((cert) => cert.dispatched === false).length : 0,
+          shadowCertificates: Array.isArray(cost.ccs.shadowCertificates) ? cost.ccs.shadowCertificates.length : 0,
+        }
+        : null,
+    })
+  }
+  return { group: String(input.group ?? 'unknown'), tasks: rows }
+}
+
+/** 两组同表对比（成功率差值按 §10.1 的 2pp 门禁）。 */
+export function compareGroups({ control, enforce, harness = EXPERIMENT_HARNESS.dryRun, runner = 'scripted-llm' } = {}) {
+  const avg = (rows) => (rows.length > 0 ? rows.reduce((sum, row) => sum + num(row.tokens), 0) / rows.length : null)
+  const rate = (rows) => (rows.length > 0 ? rows.filter((row) => row.ok === true).length / rows.length : null)
+  const ctl = Array.isArray(control?.tasks) ? control.tasks : []
+  const trt = Array.isArray(enforce?.tasks) ? enforce.tasks : []
+  const controlTokens = avg(ctl)
+  const enforceTokens = avg(trt)
+  const controlSuccess = rate(ctl)
+  const enforceSuccess = rate(trt)
+  const tokenDeltaPct = controlTokens !== null && enforceTokens !== null && controlTokens > 0
+    ? (enforceTokens - controlTokens) / controlTokens
+    : null
+  const successDelta = controlSuccess !== null && enforceSuccess !== null ? enforceSuccess - controlSuccess : null
+  const reuse = trt.map((row) => row.reuse).filter(Boolean)
+  const a1 = trt.map((row) => row.a1).filter(Boolean)
+  return Object.freeze({
+    harness,
+    runner,
+    /** 这条是给 G5 用的：dry-run 永远不足以当证据；真实 provider + 真实 worker 才算测量有效。 */
+    qualifiesForGate: harness === EXPERIMENT_HARNESS.realFork || harness === EXPERIMENT_HARNESS.realProvider,
+    table: [
+      { group: 'control', samples: ctl.length, tokensPerTask: controlTokens, successRate: controlSuccess, elapsedMsMedian: median(ctl.map((row) => num(row.elapsedMs))) },
+      { group: 'enforce', samples: trt.length, tokensPerTask: enforceTokens, successRate: enforceSuccess, elapsedMsMedian: median(trt.map((row) => num(row.elapsedMs))) },
+    ],
+    delta: { tokensPerTask: controlTokens !== null && enforceTokens !== null ? enforceTokens - controlTokens : null, tokensPerTaskPct: tokenDeltaPct, successRate: successDelta },
+    a1: {
+      tasks: a1.length,
+      /** pplied 只反映**最后一次**压缩事件；真正判断贡献要看是否产生了估算节省。 */
+      tasksWithSavings: a1.filter((row) => num(row.estimatedTokens) > 0).length,
+      applied: a1.filter((row) => row.applied === true).length,
+      estimatedTokens: a1.reduce((sum, row) => sum + num(row.estimatedTokens), 0),
+    },
+    reuse: {
+      attempts: reuse.reduce((sum, row) => sum + num(row.attempts), 0),
+      hits: reuse.reduce((sum, row) => sum + num(row.hits), 0),
+      wouldSaveTokens: reuse.reduce((sum, row) => sum + num(row.wouldSaveTokens), 0),
+      skippedModelCalls: reuse.reduce((sum, row) => sum + num(row.skippedModelCalls), 0),
+      dispatched: reuse.reduce((sum, row) => sum + num(row.dispatched), 0),
+      failures: reuse.reduce((sum, row) => sum + num(row.failures), 0),
+      shadowCertificates: reuse.reduce((sum, row) => sum + num(row.shadowCertificates), 0),
+    },
+    /** 与 gate G5 同形，便于直接喂 `evaluateForkExperiment`。 */
+    gateShape: Object.freeze({
+      control: { tasks: ctl.map((row) => ({ taskId: row.taskId, tokens: row.tokens, success: row.ok })) },
+      enforce: { tasks: trt.map((row) => ({ taskId: row.taskId, tokens: row.tokens, success: row.ok })) },
+    }),
+  })
+}
+
+function median(values) {
+  const sorted = [...values].sort((a, b) => a - b)
+  if (sorted.length === 0) return null
+  return sorted[Math.min(sorted.length - 1, Math.ceil(0.5 * sorted.length) - 1)]
+}

package/src/cost/gate.ts

@@ -0,0 +1,191 @@
+// 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 · gate（发布门禁，设计 §10.2）。
+ *
+ * **3.3.0 不通过不发布**。六道门：
+ *
+ * | # | 门禁 | 判定 |
+ * |---|---|---|
+ * | G1 | `npm run check` 0 error | 退出码 |
+ * | G2 | `npm run build` 0 error | 退出码 |
+ * | G3 | `npm test` 全绿（含新增模块测试） | 退出码 + 用例数 |
+ * | G4 | 新增测试至少覆盖：I1–I8 各一条、守卫命中/未命中、schema 漂移、证书回放、归因不重复计 | 覆盖清单逐项核验 |
+ * | G5 | 真实 fork 实机：≥10 任务的对照组 vs enforce 组，tokens/task 与成功率同表 | 样本量 + 同表 + 成功率不退化 |
+ * | G6 | 零残留：临时 profile / 工作区清理证据 | 路径扫描 |
+ * | G7 | 发布需用户明确授权 | 默认 **未授权**（设计不含发布动作） |
+ *
+ * 门禁的价值在于**敢说不**：任一门不满足即 `ok:false` 并列出 `blockers`，
+ * 不允许"部分通过"。
+ */
+
+/** 必须被测试覆盖的能力（G4），每项给出识别标记。 */
+export const REQUIRED_COVERAGE = Object.freeze([
+  { id: 'I1', label: '预算不足不启动模型调用', patterns: [/I1:.*budget/u] },
+  { id: 'I2', label: 'CCS 只经原生派发器 / 无派发器拒绝', patterns: [/I2:.*native dispatcher/u, /I2:.*non-native/u] },
+  { id: 'I3', label: '破坏性工具默认不入池', patterns: [/I3:.*destructive/u] },
+  { id: 'I4', label: 'schema 漂移整图作废', patterns: [/I4:.*schema drift/u] },
+  { id: 'I5', label: '守卫不匹配回落慢模型', patterns: [/I5:.*guard miss/u] },
+  { id: 'I6', label: '模块异常 degraded 且任务继续', patterns: [/I6:.*throwing module/u] },
+  { id: 'I7', label: '压缩回执可回读原文（spill）', patterns: [/I7:.*read back/u] },
+  { id: 'I8', label: '取消信号阻断替换', patterns: [/I8:.*aborted signal/u] },
+  { id: 'guard-hit', label: '守卫命中', patterns: [/all five gates must pass/u] },
+  { id: 'guard-miss', label: '守卫未命中', patterns: [/each gate has its own miss reason/u] },
+  { id: 'schema-drift', label: 'schema 漂移（B2 层）', patterns: [/schema drift archives the whole graph/u, /schemaHash/u] },
+  { id: 'cert-replay', label: '证书回放', patterns: [/100% replayable/u] },
+  { id: 'no-double-count', label: '归因不重复计', patterns: [/doubleCountGuard/u, /mutually exclusive/u] },
+])
+
+/** G5：对照组 vs enforce 组的最小样本量。 */
+export const MIN_FORK_TASKS = 10
+/** G5：成功率允许的最大下降（与 §10.1 的 2pp 门禁一致）。 */
+export const MAX_SUCCESS_DROP_PP = 0.02
+
+const num = (value) => {
+  const n = Number(value)
+  return Number.isFinite(n) ? n : 0
+}
+
+/**
+ * G4：扫描测试源码，逐项确认覆盖（找不到标记即报缺）。
+ * @param {Record<string, string>} sources 文件名 → 源码
+ */
+export function checkCoverage(sources = {}) {
+  const haystack = Object.values(sources).join('\n')
+  const missing = []
+  const covered = []
+  for (const item of REQUIRED_COVERAGE) {
+    const found = item.patterns.some((pattern) => pattern.test(haystack))
+    if (found) covered.push(item.id)
+    else missing.push({ id: item.id, label: item.label })
+  }
+  return { ok: missing.length === 0, covered, missing }
+}
+
+/**
+ * G5：评估真实 fork 实机对照实验。
+ * @param {{control?: {tasks: Array<{taskId: string, tokens: number, success: boolean}>}, enforce?: {tasks: Array<{taskId: string, tokens: number, success: boolean}>}}} input
+ */
+export function evaluateForkExperiment(input = {}) {
+  const control = Array.isArray(input?.control?.tasks) ? input.control.tasks : []
+  const enforce = Array.isArray(input?.enforce?.tasks) ? input.enforce.tasks : []
+  const problems = []
+  // 证据来源必须真实：dry-run（合成语料 + 脚本化模型）不能冒充 G5。
+  const harness = input?.harness === undefined ? 'real-fork' : String(input.harness)
+  if (harness === 'local-dry-run') problems.push('harness-not-real')
+  if (control.length < MIN_FORK_TASKS) problems.push(`control-tasks<${MIN_FORK_TASKS}`)
+  if (enforce.length < MIN_FORK_TASKS) problems.push(`enforce-tasks<${MIN_FORK_TASKS}`)
+
+  const avg = (rows) => (rows.length > 0 ? rows.reduce((sum, row) => sum + num(row?.tokens), 0) / rows.length : null)
+  const rate = (rows) => (rows.length > 0 ? rows.filter((row) => row?.success === true).length / rows.length : null)
+
+  const controlTokensPerTask = avg(control)
+  const enforceTokensPerTask = avg(enforce)
+  const controlSuccess = rate(control)
+  const enforceSuccess = rate(enforce)
+  const tokenDelta = controlTokensPerTask !== null && enforceTokensPerTask !== null
+    ? Math.round((enforceTokensPerTask - controlTokensPerTask) * 100) / 100
+    : null
+  const successDelta = controlSuccess !== null && enforceSuccess !== null
+    ? Math.round((enforceSuccess - controlSuccess) * 10000) / 10000
+    : null
+  if (successDelta !== null && successDelta <= -MAX_SUCCESS_DROP_PP) problems.push('success-regression>=2pp')
+  // 同表：两组必须都在同一份报告里给出 tokens/task 与成功率
+  const sameTable = controlTokensPerTask !== null && enforceTokensPerTask !== null && controlSuccess !== null && enforceSuccess !== null
+  if (!sameTable) problems.push('groups-not-in-same-table')
+
+  return {
+    ok: problems.length === 0,
+    problems,
+    samples: { control: control.length, enforce: enforce.length },
+    table: [
+      { group: 'control', samples: control.length, tokensPerTask: controlTokensPerTask, successRate: controlSuccess },
+      { group: 'enforce', samples: enforce.length, tokensPerTask: enforceTokensPerTask, successRate: enforceSuccess },
+    ],
+    delta: { tokensPerTask: tokenDelta, successRate: successDelta },
+    /** token 变好且成功率不退化，才算"通过且有效"。 */
+    improvement: tokenDelta !== null && tokenDelta < 0 && (successDelta === null || successDelta > -MAX_SUCCESS_DROP_PP),
+  }
+}
+
+/**
+ * G6：零残留——给出的路径里不允许还有临时 profile / 工作区。
+ * @param {Array<{path: string, exists: boolean, kind?: string}>} checks
+ */
+export function checkResidue(checks = []) {
+  const leftovers = checks.filter((entry) => entry?.exists === true).map((entry) => ({ path: String(entry.path), kind: String(entry.kind ?? 'unknown') }))
+  return {
+    ok: leftovers.length === 0,
+    checked: checks.length,
+    leftovers,
+    /** 没有检查项等于没有证据，不算通过。 */
+    evidence: checks.length > 0 ? '<results>' : null,
+  }
+}
+
+/**
+ * 汇总门禁。
+ * @param {{
+ *   commands?: Array<{id: string, exitCode: number, note?: string}>,
+ *   coverage?: ReturnType<typeof checkCoverage>,
+ *   forkExperiment?: ReturnType<typeof evaluateForkExperiment>,
+ *   residue?: ReturnType<typeof checkResidue>,
+ *   releaseAuthorized?: boolean,
+ * }} input
+ */
+export function evaluateGate(input = {}) {
+  const items = []
+  const blockers = []
+
+  for (const command of Array.isArray(input.commands) ? input.commands : []) {
+    const id = String(command?.id ?? 'unknown')
+    const passed = num(command?.exitCode) === 0
+    items.push({ gate: id, ok: passed, detail: `exit=${num(command?.exitCode)}${command?.note ? ` ${command.note}` : ''}` })
+    if (!passed) blockers.push(`${id}:exit-code`)
+  }
+
+  const coverage = input.coverage
+  if (!coverage) {
+    blockers.push('G4:coverage-not-checked')
+    items.push({ gate: 'G4', ok: false, detail: '未执行覆盖核验' })
+  } else {
+    items.push({ gate: 'G4', ok: coverage.ok === true, detail: coverage.ok ? `${coverage.covered.length} 项全中` : `缺 ${coverage.missing.map((item) => item.id).join(',')}` })
+    if (coverage.ok !== true) blockers.push(`G4:missing:${coverage.missing.map((item) => item.id).join(',')}`)
+  }
+
+  const fork = input.forkExperiment
+  if (!fork) {
+    blockers.push('G5:fork-experiment-missing')
+    items.push({ gate: 'G5', ok: false, detail: '尚无真实 fork 对照数据（≥10 任务/组）' })
+  } else {
+    items.push({ gate: 'G5', ok: fork.ok === true, detail: fork.ok ? `control ${fork.table[0].tokensPerTask} → enforce ${fork.table[1].tokensPerTask} tokens/task` : fork.problems.join(',') })
+    if (fork.ok !== true) blockers.push(`G5:${fork.problems.join(',')}`)
+  }
+
+  const residue = input.residue
+  if (!residue) {
+    blockers.push('G6:residue-not-checked')
+    items.push({ gate: 'G6', ok: false, detail: '未提供清理证据' })
+  } else {
+    items.push({ gate: 'G6', ok: residue.ok === true, detail: residue.ok ? `${residue.checked} 个路径均无残留` : `残留: ${residue.leftovers.map((item) => item.path).join(',')}` })
+    if (residue.ok !== true) blockers.push('G6:residue')
+  }
+
+  // G7：默认未授权。设计本身不含发布动作；授权是人工显式行为。
+  const authorized = input.releaseAuthorized === true
+  items.push({ gate: 'G7', ok: authorized, detail: authorized ? '用户已明确授权' : '未授权（发布需用户明确授权）' })
+  if (!authorized) blockers.push('G7:release-not-authorized')
+
+  const hardGates = ['G1', 'G2', 'G3', 'G4', 'G5', 'G6']
+  const hardOk = items.filter((item) => hardGates.includes(item.gate)).every((item) => item.ok)
+  return {
+    ok: hardOk && authorized,
+    /** 不发布 ≠ 代码不可用：G1–G4 + G6 全绿时，代码质量门禁是过了的。 */
+    bootstrapOk: hardOk,
+    blockers,
+    items,
+    releaseAuthorized: authorized,
+  }
+}

package/src/cost/host-surface.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 · 宿主会话工具面适配器（可选）。
+ *
+ * 设计 §3.3：`dsh-ops` 这类宿主插件作用于**宿主会话工具面**（DSH 原生工具准入/
+ * 执行器接口），而本项目 A1–A3 作用于**master Worker 自有工具面**（`worker/tools.ts`）。
+ * 两者作用面不同，不能合并统计，也不能互相替代。
+ *
+ * 因此本文件**不重写、不依赖、不冒领**任何宿主插件：
+ *   * 它只提供一个「外部收益登记」入口，由宿主侧（或用户脚本）把某个宿主插件的
+ *     自报收益按 `surface: 'host', external: true` 写入账本；
+ *   * 这些条目永远不进入 `ownExecutionSaved` / `netSaved`，只作为对照展示；
+ *   * 未安装宿主插件时，本适配器完全空转（无网络、无副作用、零依赖）。
+ *
+ * 这是「双管齐下」的第二半：**协议等价实现（Worker 面自研）+ 可选适配器（宿主面归因）**。
+ */
+
+import { createCostBus } from './bus.ts'
+
+const SOURCES = new Set(['dsh-ops', 'other'])
+
+function finiteNonNegative(value) {
+  const n = Number(value)
+  return Number.isFinite(n) && n >= 0 ? Math.floor(n) : null
+}
+
+/**
+ * @param {{
+ *   ledger: {append: Function},
+ *   enabled?: boolean,
+ *   source?: string,
+ *   bus?: ReturnType<typeof createCostBus>,
+ *   now?: () => number,
+ * }} options
+ */
+export function createHostSurfaceAdapter(options = {}) {
+  const ledger = options.ledger
+  if (!ledger || typeof ledger.append !== 'function') throw new Error('host-surface adapter requires a ledger')
+  const enabled = options.enabled === true
+  const source = SOURCES.has(String(options.source ?? 'dsh-ops')) ? String(options.source ?? 'dsh-ops') : 'other'
+  const bus = options.bus && typeof options.bus.publish === 'function' ? options.bus : null
+  const now = typeof options.now === 'function' ? options.now : () => Date.now()
+  let recorded = 0
+  let tokensClaimed = 0
+
+  /**
+   * 登记一次宿主面外部收益（只展示，不计入本项目节省）。
+   * @param {{taskId?: string, savedTokens: number, baselineTokens?: number, meta?: object}} input
+   */
+  function record(input = {}) {
+    if (!enabled) return { ok: false, code: 'host-adapter-disabled', message: 'host surface adapter is opt-in; enable it in config' }
+    const saved = finiteNonNegative(input.savedTokens)
+    if (saved === null) return { ok: false, code: 'saved-tokens-invalid', message: 'savedTokens must be a non-negative number' }
+    const appended = ledger.append({
+      account: 'execution',
+      surface: 'host',
+      external: true,
+      module: 'a1-compact',
+      source: 'tool',
+      phase: 'tool',
+      taskId: input.taskId,
+      totalTokens: 0,
+      savedTokens: saved,
+      meta: {
+        ...(input.meta && typeof input.meta === 'object' ? input.meta : {}),
+        adapter: source,
+        external: true,
+        note: 'third-party host-surface saving; shown for comparison only',
+      },
+    })
+    if (!appended.ok) return { ok: false, code: appended.code, message: appended.message }
+    recorded += 1
+    tokensClaimed += saved
+    try { bus?.publish?.('cost.host-surface', { adapter: source, savedTokens: saved, taskId: input.taskId ?? null }) } catch { /* ignore */ }
+    return { ok: true, adapter: source, external: true, savedTokens: saved, ledger: { id: appended.entry.id }, at: now() }
+  }
+
+  function status() {
+    return Object.freeze({
+      ok: true,
+      enabled,
+      adapter: source,
+      /** 明确声明：本适配器不产生本项目收益。 */
+      contributesToOwnSavings: false,
+      recorded,
+      savedTokens: tokensClaimed,
+      note: enabled
+        ? '外部宿主面收益只做对照展示，不计入 executionSaved / netSaved'
+        : '未启用：本设计不依赖任何第三方宿主插件',
+    })
+  }
+
+  return Object.freeze({ record, status })
+}