@mzzsfy/dsh-usage-dash 0.3.0 → 0.5.0

package/src/store.js

@@ -82,8 +82,12 @@ export const usageRowSchema = z.object({
   outputTokens: z.number(),
   cacheReadTokens: z.number(),
   cacheWriteTokens: z.number(),
-  // 模型时长累计(毫秒):optional 兼容存量记录(域 open 逐记录 parse)
+  // 模型时长累计(毫秒)与 decode 口径速度分子:optional 兼容存量记录(域 open 逐记录 parse)
   durationMs: z.number().optional(),
+  decodeTokens: z.number().optional(),
+  // 首 token 延迟累计(毫秒)与样本步数:optional 兼容存量记录
+  ttftMs: z.number().optional(),
+  ttftSteps: z.number().optional(),
   requests: z.number(),
   turns: z.number(),
   lastSeen: z.number(),
@@ -104,6 +108,24 @@ export const usageStatsDomain = defineDomain({
   },
 })
 
+// 重建回退备份域:与主域同构表,global 多记 takenAt(快照时刻)。
+// 独立域而非主域内备份表——reset 清主域数据,同域备份会陪葬
+export const usageBackupDomain = defineDomain({
+  name: `${DOMAIN_NAME}_backup`,
+  version: 1,
+  tables: {
+    [TABLE_BUCKETS]: domainTable(usageRowSchema),
+  },
+  global: {
+    schema: z.object({
+      backfilledSessions: z.array(z.string()),
+      liveFirstSeq: z.record(z.string(), z.number()).optional(),
+      takenAt: z.number().optional(),
+    }),
+    initial: { backfilledSessions: [], liveFirstSeq: {}, takenAt: undefined },
+  },
+})
+
 export function rowKey(g, bucket, provider, model) {
   return `${g}|${bucket}|${provider}|${model}`
 }
@@ -118,13 +140,17 @@ function emptyRow(bucket, provider, model, nowMs) {
     cacheReadTokens: 0,
     cacheWriteTokens: 0,
     durationMs: 0,
+    decodeTokens: 0,
+    ttftMs: 0,
+    ttftSteps: 0,
     requests: 0,
     turns: 0,
     lastSeen: nowMs,
   }
 }
 
-// 样本折叠为计数增量:turn/request 只计次,token 样本累加四类桶
+// 样本折叠为计数增量:turn/request 只计次,token 样本累加四类桶;
+// decodeTokens 与 durationMs 同源配对构成速度,timing 缺失按零累计
 function deltaOf(sample, nowMs) {
   const delta = emptyRow('', '', '', nowMs)
   delete delta.bucket
@@ -138,6 +164,9 @@ function deltaOf(sample, nowMs) {
     delta.cacheReadTokens = sample.cacheReadTokens
     delta.cacheWriteTokens = sample.cacheWriteTokens
     delta.durationMs = sample.durationMs ?? 0
+    delta.decodeTokens = sample.decodeTokens ?? 0
+    delta.ttftMs = sample.ttftMs ?? 0
+    delta.ttftSteps = sample.ttftMs !== undefined ? 1 : 0
   }
   return delta
 }
@@ -152,6 +181,9 @@ function addDelta(base, delta) {
     cacheWriteTokens: base.cacheWriteTokens + delta.cacheWriteTokens,
     // base 侧 ?? 0 容存量旧格式行(缺字段);delta 侧经 deltaOf 恒为数值
     durationMs: (base.durationMs ?? 0) + delta.durationMs,
+    decodeTokens: (base.decodeTokens ?? 0) + delta.decodeTokens,
+    ttftMs: (base.ttftMs ?? 0) + delta.ttftMs,
+    ttftSteps: (base.ttftSteps ?? 0) + delta.ttftSteps,
     requests: base.requests + delta.requests,
     turns: base.turns + delta.turns,
     lastSeen: Math.max(base.lastSeen, delta.lastSeen),
@@ -171,6 +203,8 @@ export class UsageStore {
     this.onFlushError = options.onFlushError
     this.table = null
     this.domain = null
+    this.backupDomain = undefined
+    this.backupTable = undefined
     this.openError = undefined
     this.lastPruneDay = ''
     this.markChain = Promise.resolve()
@@ -191,6 +225,9 @@ export class UsageStore {
     if ((cursor?.backfilledSessions?.length ?? 0) === 0 && !this.table.keys().next().done) {
       for (const key of [...this.table.keys()]) await this.table.delete(key)
     }
+    // 备份域打开失败仅禁用回退能力,不拖垮主采集(openError 只覆盖主域)
+    this.backupDomain = await facility.open(usageBackupDomain).catch(() => undefined)
+    this.backupTable = this.backupDomain?.table(TABLE_BUCKETS)
   }
 
   get degradation() {
@@ -375,6 +412,9 @@ export class UsageStore {
   reset(boundaries) {
     return this.enqueueGlobalWrite(async () => {
       await this.flushBatch()
+      // 清空前快照到备份域:重建丢数据(规则缺陷/中断/口径变化)可整体回退;
+      // 备份不可用视为 reset 失败——回退安全带是重建的前置条件
+      await this.snapshotToBackup()
       const table = this.requireTable()
       for (const key of [...table.keys()]) await table.delete(key)
       const liveFirstSeq = {}
@@ -383,11 +423,53 @@ export class UsageStore {
     })
   }
 
-  // global 只有整值覆写:全部游标写挂同一链,读改写不再交错
+  // 当前全量(表行 + 游标 + 时刻)写入备份域,覆盖旧备份:恢复点恒为最近一次清空/恢复前;
+  // 备份域不可用时跳过(重建不被卡死,仅失去回退点,backupInfo 透明展示)
+  async snapshotToBackup() {
+    if (this.backupTable === undefined) return
+    const cursor = this.readCursor() ?? {}
+    for (const key of [...this.backupTable.keys()]) await this.backupTable.delete(key)
+    for (const [key, row] of this.requireTable().entries()) await this.backupTable.put(key, row)
+    await this.backupDomain.global.set({
+      backfilledSessions: cursor.backfilledSessions ?? [],
+      liveFirstSeq: cursor.liveFirstSeq ?? {},
+      takenAt: this.now(),
+    })
+  }
+
+  // 备份写回主域;当前态先入备份(恢复动作自身可回退),故必须先取备份内容
+  // 再覆盖备份域;返回快照时刻与回写行数
+  async restoreFromBackup() {
+    if (this.backupTable === undefined) throw new Error('usage backup domain unavailable')
+    return this.enqueueGlobalWrite(async () => {
+      await this.flushBatch()
+      const savedRows = [...this.backupTable.entries()]
+      const saved = this.backupDomain.global.get()
+      await this.snapshotToBackup()
+      for (const key of [...this.requireTable().keys()]) await this.table.delete(key)
+      for (const [key, row] of savedRows) await this.table.put(key, row)
+      await this.writeGlobal(saved?.backfilledSessions ?? [], saved?.liveFirstSeq ?? {})
+      return { takenAt: saved?.takenAt, rows: savedRows.length }
+    })
+  }
+
+  // 备份元信息:available=false 表示无回退点(从未重建/备份域不可用)
+  backupInfo() {
+    if (this.backupTable === undefined) return { available: false }
+    const saved = this.backupDomain.global.get()
+    return {
+      available: typeof saved?.takenAt === 'number',
+      takenAt: saved?.takenAt,
+      rows: [...this.backupTable.keys()].length,
+      sessions: saved?.backfilledSessions?.length ?? 0,
+    }
+  }
+
+  // global 只有整值覆写:全部游标写挂同一链,读改写不再交错;write 返回值透传
   enqueueGlobalWrite(write) {
     const pending = this.markChain.then(async () => {
       await this.ready
-      await write()
+      return write()
     })
     this.markChain = pending.then(() => {}, () => {})
     return pending

package/test/archive-reader.test.mjs

@@ -0,0 +1,365 @@
+// archive-reader 行为测试:宿主 sessionPersistence API 多版本适配层的
+// 工厂分派与各代映射。宿主 API 形状以各代真实签名为蓝本,collector 只见
+// 内部统一契约(list → [{id}],readLog → {inheritedEventCount, events})。
+// 分页读、close 吞错、畸形行丢弃对齐竞品 0.1.12 双路径语义;
+// V3 日志兼容由 collector 测试的专有事件忽略用例钉住。
+
+import test from 'node:test'
+import assert from 'node:assert/strict'
+import { mkdtempSync, mkdirSync, writeFileSync, rmSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import { zstdCompressSync } from 'node:zlib'
+
+import { createArchiveReader } from '../src/archive-reader.js'
+
+const ev = (seq) => ({ type: 'turn/end', seq, time: 0, data: { turn: 0 } })
+const NAMES = {
+  handle: 'HandleArchiveReader',
+  inspect: 'InspectArchiveReader',
+  unknown: 'UnknownArchiveReader',
+}
+const nameOf = (reader) => reader.constructor.name
+
+test('工厂:open 形宿主分派到 handle 代适配器', () => {
+  const persistence = { open: () => {}, list: () => {} }
+  assert.equal(nameOf(createArchiveReader(persistence)), NAMES.handle)
+})
+
+test('工厂:inspect 形宿主分派到 inspect 代适配器', () => {
+  const persistence = { inspect: () => {}, list: () => {} }
+  assert.equal(nameOf(createArchiveReader(persistence)), NAMES.inspect)
+})
+
+test('工厂:两代形状都不匹配分派到 unknown 恒抛适配器', async () => {
+  const reader = createArchiveReader({})
+  assert.equal(nameOf(reader), NAMES.unknown)
+  await assert.rejects(reader.list(), /sessionPersistence/)
+  await assert.rejects(reader.readLog('s1'), /sessionPersistence/)
+})
+
+test('handle 代:list 归一 snapshot 为 {id},signal 包裹透传,畸形行丢弃', () => {
+  return withDirectRoot(async () => {
+    const seen = []
+    const persistence = {
+      async list(options) {
+        seen.push(options)
+        return [
+          { header: { id: 'a' }, revision: 'r1', sizeBytes: 10 },
+          { header: { id: 'b' }, revision: 'r2' },
+          { revision: 'no-header' },
+          null,
+          { header: { id: '' } },
+        ]
+      },
+      async open() {
+        throw new Error('not reached')
+      },
+    }
+    const signal = new AbortController().signal
+    const reader = createArchiveReader(persistence)
+    assert.deepEqual(await reader.list(signal), [{ id: 'a' }, { id: 'b' }])
+    assert.deepEqual(seen, [{ signal }])
+  })
+})
+
+test('handle 代:readLog 分页循环直到空页,handle 元数据透出', async () => {
+  const calls = []
+  const events = Array.from({ length: 1250 }, (_, seq) => ev(seq))
+  const persistence = {
+    async open(id, access, options) {
+      calls.push(['open', id, access, options])
+      return {
+        header: { id },
+        inheritedEventCount: 3,
+        async read(offset, length, readOptions) {
+          calls.push(['read', offset, length])
+          assert.equal(typeof readOptions, 'object')
+          assert.equal(length, 500)
+          return { eventState: 'detached', events: events.slice(offset, offset + length) }
+        },
+        async close() {
+          calls.push(['close'])
+        },
+      }
+    },
+  }
+  const signal = new AbortController().signal
+  const reader = createArchiveReader(persistence)
+  const result = await reader.readLog('s1', signal)
+  assert.equal(result.inheritedEventCount, 3)
+  assert.deepEqual(result.events, events)
+  const reads = calls.filter(([kind]) => kind === 'read')
+  // 1250 条 = 500+500+250 三页取到,第 4 次读到空页才终止
+  assert.equal(reads.length, 4)
+  assert.deepEqual(reads.map(([, offset]) => offset), [0, 500, 1000, 1250])
+  assert.deepEqual(calls[calls.length - 1], ['close'])
+})
+
+test('handle 代:inheritedEventCount 非法值回落 0', async () => {
+  const persistence = {
+    async open() {
+      return {
+        inheritedEventCount: -5,
+        async read() {
+          return { eventState: 'detached', events: [] }
+        },
+        async close() {},
+      }
+    },
+  }
+  const reader = createArchiveReader(persistence)
+  const result = await reader.readLog('s1')
+  assert.equal(result.inheritedEventCount, 0)
+  assert.deepEqual(result.events, [])
+})
+
+test('handle 代:read 抛错时 close 仍被调用且原错误传播', async () => {
+  let closed = 0
+  const failure = new Error('corrupted log')
+  const persistence = {
+    async open() {
+      return {
+        inheritedEventCount: 0,
+        async read() {
+          throw failure
+        },
+        async close() {
+          closed += 1
+        },
+      }
+    },
+  }
+  const reader = createArchiveReader(persistence)
+  await assert.rejects(reader.readLog('s1'), (error) => error === failure)
+  assert.equal(closed, 1)
+})
+
+test('handle 代:read 抛错且 close 也抛错时,原错误传播不被掩盖', async () => {
+  const failure = new Error('corrupted log')
+  const persistence = {
+    async open() {
+      return {
+        inheritedEventCount: 0,
+        async read() {
+          throw failure
+        },
+        async close() {
+          throw new Error('close failure')
+        },
+      }
+    },
+  }
+  const reader = createArchiveReader(persistence)
+  await assert.rejects(reader.readLog('s1'), (error) => error === failure)
+})
+
+test('handle 代:read 成功后 close 失败被吞掉,读取结果照常返回', async () => {
+  let closed = 0
+  const events = [ev(0)]
+  let reads = 0
+  const persistence = {
+    async open() {
+      return {
+        inheritedEventCount: 0,
+        async read() {
+          reads += 1
+          // 首读返回数据页,再读返回空页终止分页循环
+          return { eventState: 'detached', events: reads === 1 ? events : [] }
+        },
+        async close() {
+          closed += 1
+          throw new Error('close failure')
+        },
+      }
+    },
+  }
+  const reader = createArchiveReader(persistence)
+  const result = await reader.readLog('s1')
+  assert.equal(closed, 1)
+  assert.deepEqual(result, { inheritedEventCount: 0, events })
+})
+
+test('handle 代:abort 中断分页循环,当前页已读数据保留', async () => {
+  const controller = new AbortController()
+  const events = Array.from({ length: 700 }, (_, seq) => ev(seq))
+  const persistence = {
+    async open() {
+      return {
+        inheritedEventCount: 0,
+        async read(offset) {
+          if (offset > 0) controller.abort()
+          return { eventState: 'detached', events: events.slice(offset, offset + 500) }
+        },
+        async close() {},
+      }
+    },
+  }
+  const reader = createArchiveReader(persistence)
+  // abort 在第二页读取时触发:第二页已返回故被保留,下一轮循环检测到中止退出
+  const result = await reader.readLog('s1', controller.signal)
+  assert.equal(result.events.length, 700)
+})
+
+test('handle 代:open 抛错直接传播,不触发 close', async () => {
+  const failure = new Error('format unsupported')
+  const persistence = {
+    async open() {
+      throw failure
+    },
+  }
+  const reader = createArchiveReader(persistence)
+  await assert.rejects(reader.readLog('s1'), (error) => error === failure)
+})
+
+test('inspect 代:list 归一 header 数组为 {id},signal 直传,畸形行丢弃', () => {
+  return withDirectRoot(async () => {
+    const seen = []
+    const persistence = {
+      async list(arg) {
+        seen.push(arg)
+        return [{ id: 'a', createdAt: 1 }, { id: 'b', createdAt: 2 }, null, {}]
+      },
+      async inspect() {
+        throw new Error('not reached')
+      },
+    }
+    const signal = new AbortController().signal
+    const reader = createArchiveReader(persistence)
+    assert.deepEqual(await reader.list(signal), [{ id: 'a' }, { id: 'b' }])
+    assert.deepEqual(seen, [signal])
+  })
+})
+
+test('inspect 代:readLog 经 inspect 整读,signal 直传', async () => {
+  const seen = []
+  const events = [ev(0)]
+  const signal = new AbortController().signal
+  const persistence = {
+    async inspect(id, arg) {
+      seen.push([id, arg])
+      return { meta: { id }, inheritedEventCount: 2, events }
+    },
+  }
+  const reader = createArchiveReader(persistence)
+  assert.deepEqual(
+    await reader.readLog('s1', signal),
+    { inheritedEventCount: 2, events },
+  )
+  assert.deepEqual(seen, [['s1', signal]])
+})
+
+// 降级直读的测试桩:DSH_HOME 指向临时根,档案落 sessions/<bucket>/<id>/
+function withDirectRoot(run) {
+  const root = mkdtempSync(join(tmpdir(), 'ud-fallback-'))
+  process.env.DSH_HOME = root
+  return Promise.resolve(run(root)).finally(() => {
+    delete process.env.DSH_HOME
+    rmSync(root, { recursive: true, force: true })
+  })
+}
+
+function seedArtifact(root, id, events) {
+  const text = [
+    JSON.stringify({ type: 'session/header', id }),
+    ...events.map((event) => JSON.stringify(event)),
+  ].join('\n')
+  const dir = join(root, 'sessions', 'bucket-x', id)
+  mkdirSync(dir, { recursive: true })
+  writeFileSync(join(dir, 'session.v3.jsonl.zstd'), zstdCompressSync(Buffer.from(text)))
+}
+
+test('handle 代:宿主拒读(descriptor)降级文件直读', () => {
+  return withDirectRoot(async (root) => {
+    seedArtifact(root, 'refused', [ev(0), ev(1)])
+    const persistence = {
+      async open() {
+        return {
+          inheritedEventCount: 0,
+          async read() {
+            throw new Error('subagent session "refused" uses unsupported descriptor version 2')
+          },
+          async close() {},
+        }
+      },
+    }
+    const reader = createArchiveReader(persistence)
+    const result = await reader.readLog('refused')
+    assert.equal(result.inheritedEventCount, 0)
+    assert.equal(result.events.length, 2)
+  })
+})
+
+test('handle 代:open 阶段拒读(descriptor 校验)同样降级直读', () => {
+  return withDirectRoot(async (root) => {
+    seedArtifact(root, 'open-refused', [ev(3)])
+    const persistence = {
+      async open() {
+        throw new Error('session "open-refused" header uses unsupported descriptor version 2')
+      },
+    }
+    const reader = createArchiveReader(persistence)
+    const result = await reader.readLog('open-refused')
+    assert.equal(result.events.length, 1)
+  })
+})
+
+test('handle 代:open 拒读且直读失败时,原错误传播', () => {
+  return withDirectRoot(async () => {
+    const persistence = {
+      async open() {
+        throw new Error('session "absent" header uses unsupported descriptor version 2')
+      },
+    }
+    const reader = createArchiveReader(persistence)
+    await assert.rejects(reader.readLog('absent'), /descriptor version 2/)
+  })
+})
+
+test('handle 代:非拒读错误不触发直读,原错误传播', () => {
+  return withDirectRoot((root) => {
+    seedArtifact(root, 'gone', [ev(0)])
+    const persistence = {
+      async open() {
+        throw new Error('session "gone" not found')
+      },
+    }
+    const reader = createArchiveReader(persistence)
+    return assert.rejects(reader.readLog('gone'), /not found/)
+  })
+})
+
+test('handle 代:拒读且直读也失败时,原错误传播', () => {
+  return withDirectRoot(async (root) => {
+    const persistence = {
+      async open() {
+        return {
+          inheritedEventCount: 0,
+          async read() {
+            throw new Error('stored log is corrupt: SessionFormatError: seq gap')
+          },
+          async close() {},
+        }
+      },
+    }
+    const reader = createArchiveReader(persistence)
+    await assert.rejects(reader.readLog('absent'), /corrupt/)
+  })
+})
+
+test('handle 代:list 并集补齐宿主不可见的磁盘档案', () => {
+  return withDirectRoot(async (root) => {
+    seedArtifact(root, 'v3-only', [ev(0)])
+    const persistence = {
+      async list() {
+        return [{ header: { id: 'host-known' } }]
+      },
+      async open() {
+        throw new Error('not reached')
+      },
+    }
+    const reader = createArchiveReader(persistence)
+    const ids = (await reader.list()).map((row) => row.id).sort()
+    assert.deepEqual(ids, ['host-known', 'v3-only'])
+  })
+})