@twinsearth/dsh-master 3.2.10 → 3.3.0

package/src/cost/ledger-report.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 · M1 记账报表（`ledger-report`）。
+ *
+ * 交付物「记账报表」的实体：把账本事件整理成**可读、可核对**的报表，
+ * 并且遵守前几节定下的口径纪律：
+ *
+ *   * **估算 ≠ 实测**：两列分开给，`estimatedRatio` 显式展示，不混算；
+ *   * **两本账不合并**：execution 与 governance 分账，`netSaved` 只在能对上时给；
+ *   * **外部面单列**：宿主面外部插件自报收益永不并入本项目节省；
+ *   * **unattributed 必须留位**：归因缺口显式展示为 0 或非 0，不允许"消失"；
+ *   * **非法行不入账**：JSONL 里坏行跳过并计数，不静默丢弃也不假装成功。
+ */
+
+import { COST_MODULES, COST_PHASES, COST_SURFACES } from './types.ts'
+
+const num = (value) => {
+  const n = Number(value)
+  return Number.isFinite(n) ? n : 0
+}
+const nonNegative = (value) => Math.max(0, num(value))
+
+/**
+ * 解析落盘的 JSONL 账本（`cost-ledger.jsonl`，逐行追加）。
+ * 坏行跳过并计数 —— 报表必须能说明"有多少行没读进来"。
+ * @param {string} text
+ */
+export function parseLedgerJsonl(text) {
+  const entries = []
+  let skipped = 0
+  for (const line of String(text ?? '').split('\n')) {
+    const trimmed = line.trim()
+    if (trimmed === '') continue
+    try {
+      const parsed = JSON.parse(trimmed)
+      if (parsed && typeof parsed === 'object' && (parsed.account === 'execution' || parsed.account === 'governance')) entries.push(parsed)
+      else skipped += 1
+    } catch {
+      skipped += 1
+    }
+  }
+  return { entries, skipped }
+}
+
+const emptyRow = () => ({ entries: 0, inputTokens: 0, outputTokens: 0, total: 0, savedTokens: 0, estimated: false })
+function addTo(map, key, entry) {
+  if (!map.has(key)) map.set(key, { ...emptyRow(), key })
+  const row = map.get(key)
+  row.entries += 1
+  row.inputTokens += nonNegative(entry.inputTokens)
+  row.outputTokens += nonNegative(entry.outputTokens)
+  row.total += nonNegative(entry.total)
+  row.savedTokens += nonNegative(entry.savedTokens)
+  if (entry.estimated === true) row.estimated = true
+  return row
+}
+
+/**
+ * 记账报表。
+ *
+ * @param {{
+ *   entries?: object[],
+ *   from?: number,
+ *   to?: number,
+ *   bucketMs?: number,
+ * }} [input]
+ */
+export function buildLedgerReport(input = {}) {
+  const from = Number.isFinite(Number(input.from)) ? Number(input.from) : null
+  const to = Number.isFinite(Number(input.to)) ? Number(input.to) : null
+  const bucketMs = Math.max(1, Number(input.bucketMs ?? 60 * 60 * 1000) || 60 * 60 * 1000)
+  const raw = Array.isArray(input.entries) ? input.entries : []
+
+  const byPhase = new Map()
+  const byModule = new Map()
+  const byTask = new Map()
+  const bySurface = new Map()
+  const accounts = {
+    execution: { entries: 0, total: 0, savedTokens: 0 },
+    governance: { entries: 0, total: 0, savedTokens: 0 },
+  }
+  const tokens = { measuredTokens: 0, estimatedTokens: 0, inputTokens: 0, outputTokens: 0 }
+  const buckets = new Map()
+  let ownExecutionSaved = 0
+  let externalSaved = 0
+  let filtered = 0
+  let invalid = 0
+
+  for (const entry of raw) {
+    if (!entry || (entry.account !== 'execution' && entry.account !== 'governance')) { invalid += 1; continue }
+    const at = num(entry.at)
+    if (from !== null && at < from) { filtered += 1; continue }
+    if (to !== null && at > to) { filtered += 1; continue }
+
+    const account = accounts[entry.account]
+    account.entries += 1
+    account.total += nonNegative(entry.total)
+
+    const total = nonNegative(entry.total)
+    const saved = nonNegative(entry.savedTokens)
+    if (entry.estimated === true) tokens.estimatedTokens += total
+    else tokens.measuredTokens += total
+    tokens.inputTokens += nonNegative(entry.inputTokens)
+    tokens.outputTokens += nonNegative(entry.outputTokens)
+
+    if (entry.account === 'execution' && saved > 0) {
+      if (entry.external === true) externalSaved += saved
+      else ownExecutionSaved += saved
+    }
+    account.savedTokens += saved
+
+    addTo(byPhase, String(entry.phase ?? 'unknown'), entry)
+    addTo(byModule, String(entry.module ?? 'unattributed'), entry)
+    addTo(byTask, String(entry.taskId ?? 'unattributed'), entry)
+    addTo(bySurface, String(entry.surface ?? 'worker'), entry)
+
+    const bucketKey = Math.floor(at / bucketMs) * bucketMs
+    if (!buckets.has(bucketKey)) buckets.set(bucketKey, { at: bucketKey, entries: 0, total: 0, savedTokens: 0, estimatedTokens: 0 })
+    const bucket = buckets.get(bucketKey)
+    bucket.entries += 1
+    bucket.total += total
+    bucket.savedTokens += saved
+    if (entry.estimated === true) bucket.estimatedTokens += total
+  }
+
+  // 固定列：模块与相位都按枚举铺满，缺的给 0（报表要能一眼看出"这一项是 0"而不是"没这一列"）
+  const phaseRows = COST_PHASES.map((phase) => byPhase.get(phase) ?? { ...emptyRow(), key: phase })
+  const moduleRows = COST_MODULES.map((module) => byModule.get(module) ?? { ...emptyRow(), key: module })
+  const surfaceRows = COST_SURFACES.map((surface) => bySurface.get(surface) ?? { ...emptyRow(), key: surface })
+  const taskRows = [...byTask.values()].sort((a, b) => b.total - a.total || a.key.localeCompare(b.key))
+
+  const allTokens = tokens.measuredTokens + tokens.estimatedTokens
+  return Object.freeze({
+    ok: true,
+    window: Object.freeze({ from, to, bucketMs }),
+    counts: Object.freeze({ entries: accounts.execution.entries + accounts.governance.entries, invalid, filtered }),
+    accounts: Object.freeze({
+      execution: Object.freeze({ ...accounts.execution }),
+      governance: Object.freeze({ ...accounts.governance }),
+      /** 两本账相减只在 execution 为「本项目（非外部）」口径时成立。 */
+      netSaved: ownExecutionSaved - accounts.governance.total,
+    }),
+    tokens: Object.freeze({ ...tokens, estimatedRatio: allTokens > 0 ? tokens.estimatedTokens / allTokens : 0 }),
+    savings: Object.freeze({
+      ownExecutionSaved,
+      /** 外部面收益：只展示，不计入本项目净节省。 */
+      externalSaved,
+    }),
+    byPhase: Object.freeze(phaseRows.map((row) => Object.freeze(row))),
+    byModule: Object.freeze(moduleRows.map((row) => Object.freeze(row))),
+    bySurface: Object.freeze(surfaceRows.map((row) => Object.freeze(row))),
+    byTask: Object.freeze(taskRows.map((row) => Object.freeze(row))),
+    timeline: Object.freeze([...buckets.values()].sort((a, b) => a.at - b.at).map((row) => Object.freeze(row))),
+    /** 记账口径声明，供报表阅读者核对（写进报表而不是只写在文档里）。 */
+    discipline: Object.freeze({
+      estimatedAndMeasuredSeparated: true,
+      accountsNotMerged: true,
+      externalNeverSummed: true,
+      unattributedAlwaysListed: true,
+    }),
+  })
+}
+
+/** 人读行（CLI / 面板共用，避免两处格式分叉）。 */
+export function formatLedgerReport(report) {
+  const lines = []
+  lines.push(`记账报表  窗口 ${report.window.from ?? '-'} → ${report.window.to ?? '-'}`)
+  lines.push(`事件 ${report.counts.entries} 条（非法 ${report.counts.invalid}，被窗口过滤 ${report.counts.filtered}）`)
+  lines.push('')
+  lines.push('账本            条数      token      节省')
+  for (const [name, row] of Object.entries(report.accounts)) {
+    if (name === 'netSaved') continue
+    lines.push(`${name.padEnd(14)} ${String(row.entries).padEnd(8)} ${String(row.total).padEnd(10)} ${row.savedTokens}`)
+  }
+  lines.push(`净节省（本项目） ${report.accounts.netSaved}`)
+  lines.push(`外部面收益（不并入） ${report.savings.externalSaved}`)
+  lines.push('')
+  lines.push(`估算占比 ${(report.tokens.estimatedRatio * 100).toFixed(1)}%（实测 ${report.tokens.measuredTokens} / 估算 ${report.tokens.estimatedTokens}）`)
+  lines.push('')
+  lines.push('按模块             token     节省')
+  for (const row of report.byModule) lines.push(`${row.key.padEnd(16)} ${String(row.total).padEnd(10)} ${row.savedTokens}`)
+  return lines.join('\n')
+}

package/src/cost/ledger.ts

@@ -0,0 +1,385 @@
+// 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 系统层 · ledger（计量账本，设计 §5.1）。
+ *
+ * 按**事件**记账（不是按聚合），每个事件带 task/fork/session/turn/step/phase，
+ * 因此可回放、可按维度查询。
+ *
+ * 口径纪律：
+ *   * 两本账 `execution` / `governance` 分开；`netSaved` 只减 governance；
+ *   * 作用面 `worker` / `host` 分开，外部适配器（`external`）永不计入本项目节省；
+ *   * 估算 token（provider 未返回 usage 的兜底）标记 `estimated: true`，
+ *     报表中与实测**分列**、不相加。
+ *
+ * 存储：进程内环形缓冲（有界）+ 可选 JSONL 落盘（`<dataDir>/cost-ledger.jsonl`）。
+ * 选择「逐行追加」而不是整文件重写：账本只增不改，单行 append 是 O(1)；
+ * 整文件 tmp+rename（ticket-store 的风格）会让每次记账变成 O(n)，账本量大时不可接受。
+ * 追加失败不影响主流程，只累加 `failed` 计数（成本记账不得打断执行）。
+ */
+
+import fs from 'node:fs'
+import path from 'node:path'
+
+import { COST_MODULES, COST_SURFACES, COST_PHASES } from './types.ts'
+
+/** source → phase 的缺省推导（调用方也可显式给 phase）。 */
+const PHASE_OF_SOURCE = Object.freeze({
+  model: 'completion',
+  tool: 'tool',
+  substitution: 'substitution',
+  retry: 'prompt',
+  authoring: 'authoring',
+  offline: 'authoring',
+})
+
+const LEDGER_FILE = 'cost-ledger.jsonl'
+
+function finiteTokens(value) {
+  const n = Number(value)
+  return Number.isFinite(n) && n >= 0 ? Math.floor(n) : null
+}
+
+function emptyBlock() {
+  return { input: 0, output: 0, total: 0, saved: 0, entries: 0 }
+}
+
+function addToBlock(block, entry) {
+  block.input += entry.input
+  block.output += entry.output
+  block.total += entry.total
+  block.saved += entry.savedTokens
+  block.entries += 1
+}
+
+const str = (value) => (value === undefined || value === null ? null : String(value))
+const int = (value, fallback = 0) => {
+  const n = Number(value)
+  return Number.isFinite(n) ? Math.trunc(n) : fallback
+}
+
+/**
+ * @param {{
+ *   now?: () => number, maxEntries?: number, maxTasks?: number,
+ *   dataDir?: string, persist?: boolean, logger?: { warn?: Function },
+ * }} [options]
+ */
+export function createLedger(options = {}) {
+  const now = typeof options.now === 'function' ? options.now : () => Date.now()
+  const maxEntries = Math.max(1, Number(options.maxEntries ?? 5000) || 5000)
+  const maxTasks = Math.max(1, Number(options.maxTasks ?? 200) || 200)
+  const dataDir = options.dataDir === undefined || options.dataDir === null ? '' : String(options.dataDir).trim()
+  const persistEnabled = options.persist === true && dataDir !== ''
+  const file = persistEnabled ? path.join(dataDir, LEDGER_FILE) : null
+  let persistedAppends = 0
+  let persistedFailures = 0
+
+  const entries = []
+  const totals = { execution: emptyBlock(), governance: emptyBlock() }
+  const byModule = new Map()
+  const byTask = new Map()
+  const byFork = new Map()
+  /** 按作用面拆分（worker = 本项目自研；host = 外部适配器，只展示不并入）。 */
+  const bySurface = new Map()
+  /** 本项目自己的执行节省（worker 面、非外部）与外部适配器自报节省（分开累计）。 */
+  let ownExecutionSaved = 0
+  let externalExecutionSaved = 0
+  /** 实测 vs 估算（不混算）。 */
+  const estimateSplit = { measuredTokens: 0, measuredEntries: 0, estimatedTokens: 0, estimatedEntries: 0 }
+  let dropped = 0
+  let seq = 0
+
+  const moduleRow = (module) => {
+    if (!byModule.has(module)) byModule.set(module, emptyBlock())
+    return byModule.get(module)
+  }
+  const taskRow = (key) => {
+    if (!byTask.has(key)) byTask.set(key, emptyBlock())
+    return byTask.get(key)
+  }
+  const forkRow = (key) => {
+    if (!byFork.has(key)) byFork.set(key, emptyBlock())
+    return byFork.get(key)
+  }
+  const surfaceRow = (surface, external) => {
+    const key = `${surface}|${external ? 'external' : 'own'}`
+    if (!bySurface.has(key)) bySurface.set(key, { ...emptyBlock(), surface, external })
+    return bySurface.get(key)
+  }
+
+  /** 单行追加；失败只计数，不影响主流程。回放期间不重复落盘。 */
+  let replaying = false
+  function persistLine(entry) {
+    if (!file || replaying) return
+    try {
+      fs.mkdirSync(dataDir, { recursive: true })
+      const line = `${JSON.stringify({ v: 1, ...entry })}\n`
+      // 单次 append 调用：账本只增不改，避免整文件重写。
+      fs.appendFileSync(file, line, 'utf8')
+      persistedAppends += 1
+    } catch (error) {
+      persistedFailures += 1
+      try { options.logger?.warn?.(`[cost-ledger] append failed: ${String(error?.message ?? error)}`) } catch { /* ignore */ }
+    }
+  }
+
+  function append(input = {}) {
+    const account = String(input.account ?? '')
+    if (account !== 'execution' && account !== 'governance') {
+      return { ok: false, code: 'account-invalid', message: 'account must be execution or governance' }
+    }
+    const source = input.source === undefined ? 'model' : String(input.source)
+    if (!Object.prototype.hasOwnProperty.call(PHASE_OF_SOURCE, source)) {
+      return { ok: false, code: 'source-invalid', message: `source must be one of ${Object.keys(PHASE_OF_SOURCE).join('/')}` }
+    }
+    const phase = input.phase === undefined ? PHASE_OF_SOURCE[source] : String(input.phase)
+    if (!COST_PHASES.includes(phase)) {
+      return { ok: false, code: 'phase-invalid', message: `phase must be one of ${COST_PHASES.join('/')}` }
+    }
+    const module = input.module === undefined ? 'unattributed' : String(input.module)
+    if (!COST_MODULES.includes(module)) {
+      return { ok: false, code: 'module-invalid', message: `module must be one of ${COST_MODULES.join('/')}` }
+    }
+    const surface = input.surface === undefined ? 'worker' : String(input.surface)
+    if (!COST_SURFACES.includes(surface)) {
+      return { ok: false, code: 'surface-invalid', message: `surface must be one of ${COST_SURFACES.join('/')}` }
+    }
+    const external = input.external === true
+    const inputTokens = finiteTokens(input.inputTokens ?? 0)
+    const outputTokens = finiteTokens(input.outputTokens ?? 0)
+    const cachedTokens = finiteTokens(input.cachedTokens ?? 0)
+    if (inputTokens === null) return { ok: false, code: 'input-tokens-invalid', message: 'inputTokens must be a non-negative number' }
+    if (outputTokens === null) return { ok: false, code: 'output-tokens-invalid', message: 'outputTokens must be a non-negative number' }
+    if (cachedTokens === null) return { ok: false, code: 'cached-tokens-invalid', message: 'cachedTokens must be a non-negative number' }
+    const totalInput = input.totalTokens === undefined ? inputTokens + outputTokens : finiteTokens(input.totalTokens)
+    if (totalInput === null) return { ok: false, code: 'total-tokens-invalid', message: 'totalTokens must be a non-negative number' }
+    if (totalInput === 0 && inputTokens + outputTokens > 0) {
+      return { ok: false, code: 'total-tokens-invalid', message: 'totalTokens is zero while input/output tokens are not' }
+    }
+    const baseline = input.baselineTokens === undefined ? null : finiteTokens(input.baselineTokens)
+    if (baseline === null && input.baselineTokens !== undefined) {
+      return { ok: false, code: 'baseline-tokens-invalid', message: 'baselineTokens must be a non-negative number' }
+    }
+    const explicitSaved = input.savedTokens === undefined ? null : finiteTokens(input.savedTokens)
+    if (explicitSaved === null && input.savedTokens !== undefined) {
+      return { ok: false, code: 'saved-tokens-invalid', message: 'savedTokens must be a non-negative number' }
+    }
+    // 显式 savedTokens 优先（归因条目 total=0，只能由调用方给出节省）；
+    // 只有 baseline 时按 baseline - total 推导；两者都没有则 0。
+    const savedTokens = explicitSaved !== null
+      ? explicitSaved
+      : (baseline === null ? 0 : Math.max(0, baseline - totalInput))
+    const estimated = input.estimated === true
+
+    const at = now()
+    seq += 1
+    const entry = Object.freeze({
+      id: `cost_${at.toString(36)}_${seq.toString(36)}`,
+      at,
+      account,
+      module,
+      source,
+      phase,
+      surface,
+      external,
+      taskId: str(input.taskId),
+      forkId: str(input.forkId),
+      sessionId: str(input.sessionId),
+      ticketId: str(input.ticketId),
+      turn: int(input.turn),
+      step: int(input.step),
+      provider: str(input.provider),
+      model: str(input.model),
+      toolName: str(input.toolName),
+      input: inputTokens,
+      output: outputTokens,
+      cached: cachedTokens,
+      total: totalInput,
+      baselineTokens: baseline,
+      savedTokens,
+      estimated,
+      meta: Object.freeze({ ...(input.meta ?? {}) }),
+    })
+
+    entries.push(entry)
+    if (entries.length > maxEntries) {
+      entries.shift()
+      dropped += 1
+    }
+    addToBlock(totals[account], entry)
+    addToBlock(moduleRow(module), entry)
+    addToBlock(surfaceRow(surface, external), entry)
+    addToBlock(forkRow(entry.forkId ?? 'unattributed'), entry)
+    const taskKey = entry.taskId ?? entry.ticketId ?? 'unattributed'
+    addToBlock(taskRow(taskKey), entry)
+    while (byTask.size > maxTasks) {
+      const oldest = byTask.keys().next().value
+      byTask.delete(oldest)
+    }
+    if (account === 'execution') {
+      if (external) externalExecutionSaved += savedTokens
+      else if (surface === 'worker') ownExecutionSaved += savedTokens
+    }
+    if (estimated) {
+      estimateSplit.estimatedTokens += totalInput
+      estimateSplit.estimatedEntries += 1
+    } else {
+      estimateSplit.measuredTokens += totalInput
+      estimateSplit.measuredEntries += 1
+    }
+    persistLine(entry)
+    return { ok: true, entry }
+  }
+
+  function snapshot() {
+    const execution = Object.freeze({ ...totals.execution })
+    const governance = Object.freeze({ ...totals.governance })
+    const bySurfaceRows = [...bySurface.values()].map((row) => Object.freeze({ ...row })).sort((a, b) => b.total - a.total)
+    const byModuleRows = [...byModule.entries()].map(([module, block]) => Object.freeze({ module, ...block })).sort((a, b) => b.total - a.total)
+    const byTaskRows = [...byTask.entries()].map(([key, block]) => Object.freeze({ key, ...block })).sort((a, b) => b.total - a.total)
+    const byForkRows = [...byFork.entries()].map(([forkId, block]) => Object.freeze({ forkId, ...block })).sort((a, b) => b.total - a.total)
+    const allTokens = estimateSplit.measuredTokens + estimateSplit.estimatedTokens
+    return Object.freeze({
+      ok: true,
+      count: entries.length,
+      dropped,
+      execution,
+      governance,
+      /** 只算本项目（worker 面）的执行节省减去治理成本；外部适配器不参与。 */
+      netSaved: ownExecutionSaved - governance.total,
+      ownExecutionSaved,
+      externalSaved: externalExecutionSaved,
+      bySurface: bySurfaceRows,
+      byModule: byModuleRows,
+      byTask: byTaskRows,
+      byFork: byForkRows,
+      tokens: Object.freeze({
+        ...estimateSplit,
+        estimatedRatio: allTokens > 0 ? estimateSplit.estimatedTokens / allTokens : 0,
+      }),
+      persistence: Object.freeze({
+        enabled: persistEnabled,
+        file,
+        appended: persistedAppends,
+        failed: persistedFailures,
+      }),
+    })
+  }
+
+  /**
+   * 按维度查询（设计 §5.1）：task / fork / session / module / account / phase / 时间窗。
+   * 返回最近 limit 条（按时间正序）。
+   */
+  function query(filter = {}) {
+    const limit = Math.max(1, Number(filter.limit ?? 200) || 200)
+    const matches = entries.filter((entry) => {
+      if (filter.taskId !== undefined && entry.taskId !== String(filter.taskId)) return false
+      if (filter.forkId !== undefined && entry.forkId !== String(filter.forkId)) return false
+      if (filter.sessionId !== undefined && entry.sessionId !== String(filter.sessionId)) return false
+      if (filter.ticketId !== undefined && entry.ticketId !== String(filter.ticketId)) return false
+      if (filter.module !== undefined && entry.module !== String(filter.module)) return false
+      if (filter.account !== undefined && entry.account !== String(filter.account)) return false
+      if (filter.phase !== undefined && entry.phase !== String(filter.phase)) return false
+      if (filter.surface !== undefined && entry.surface !== String(filter.surface)) return false
+      if (filter.external !== undefined && entry.external !== filter.external) return false
+      if (filter.estimated !== undefined && entry.estimated !== filter.estimated) return false
+      if (filter.from !== undefined && entry.at < Number(filter.from)) return false
+      if (filter.to !== undefined && entry.at > Number(filter.to)) return false
+      return true
+    })
+    const rows = matches.slice(-limit)
+    return Object.freeze({
+      ok: true,
+      matched: matches.length,
+      returned: rows.length,
+      tokens: rows.reduce((sum, entry) => sum + entry.total, 0),
+      saved: rows.reduce((sum, entry) => sum + entry.savedTokens, 0),
+      entries: rows.slice(),
+    })
+  }
+
+  /** 从 JSONL 重新装载（进程重启后回放）；只读文件，不改内存中的既有事件。 */
+  function replay(direction = 'forward') {
+    if (!file) return { ok: false, code: 'persistence-disabled', message: 'ledger has no dataDir' }
+    let text
+    try {
+      text = fs.readFileSync(file, 'utf8')
+    } catch (error) {
+      if (error?.code === 'ENOENT') return { ok: true, loaded: 0, skipped: 0 }
+      return { ok: false, code: 'read-failed', message: String(error?.message ?? error) }
+    }
+    const lines = text.split('\n').filter((line) => line.trim() !== '')
+    const ordered = direction === 'reverse' ? [...lines].reverse() : lines
+    let loaded = 0
+    let skipped = 0
+    replaying = true
+    try {
+      for (const line of ordered) {
+        try {
+          const parsed = JSON.parse(line)
+          if (!parsed || typeof parsed !== 'object') { skipped += 1; continue }
+          const result = append({
+            account: parsed.account,
+            module: parsed.module,
+            source: parsed.source,
+            phase: parsed.phase,
+            surface: parsed.surface,
+            external: parsed.external,
+            taskId: parsed.taskId ?? undefined,
+            forkId: parsed.forkId ?? undefined,
+            sessionId: parsed.sessionId ?? undefined,
+            ticketId: parsed.ticketId ?? undefined,
+            turn: parsed.turn,
+            step: parsed.step,
+            provider: parsed.provider ?? undefined,
+            model: parsed.model ?? undefined,
+            toolName: parsed.toolName ?? undefined,
+            inputTokens: parsed.input,
+            outputTokens: parsed.output,
+            cachedTokens: parsed.cached,
+            totalTokens: parsed.total,
+            baselineTokens: parsed.baselineTokens ?? undefined,
+            savedTokens: parsed.savedTokens,
+            estimated: parsed.estimated,
+            meta: parsed.meta,
+          })
+          if (result.ok) loaded += 1
+          else skipped += 1
+        } catch {
+          skipped += 1
+        }
+      }
+    } finally {
+      replaying = false
+    }
+    return { ok: true, loaded, skipped }
+  }
+
+  function list(limit = 50) {
+    const n = Math.max(1, Number(limit) || 50)
+    return entries.slice(-n)
+  }
+
+  function reset() {
+    entries.length = 0
+    byModule.clear()
+    byTask.clear()
+    byFork.clear()
+    bySurface.clear()
+    Object.assign(totals.execution, emptyBlock())
+    Object.assign(totals.governance, emptyBlock())
+    ownExecutionSaved = 0
+    externalExecutionSaved = 0
+    estimateSplit.measuredTokens = 0
+    estimateSplit.measuredEntries = 0
+    estimateSplit.estimatedTokens = 0
+    estimateSplit.estimatedEntries = 0
+    dropped = 0
+    seq = 0
+    return { ok: true }
+  }
+
+  return Object.freeze({ append, snapshot, query, replay, list, reset })
+}