@mzzsfy/dsh-usage-dash 0.3.0 → 0.4.0

package/test/collector.test.mjs

@@ -72,17 +72,46 @@ function fakeSessions(handles = []) {
 }
 
 // definitions: [{ id, events?, inheritedEventCount?, fail? }]
+// 内部统一契约形状(list → [{id}],readLog → {inheritedEventCount, events}),
+// 宿主 persistence 的多版本映射由 archive-reader 测试单独覆盖
 function fakePersistence(definitions = []) {
   const byId = new Map(definitions.map((def) => [def.id, def]))
   return {
     async list() {
       return definitions.map((def) => ({ id: def.id }))
     },
-    async inspect(id) {
+    async readLog(id) {
       const def = byId.get(id)
       if (!def) throw new Error(`session "${id}" not found`)
       if (def.fail) throw new Error(def.fail)
-      return { meta: { id }, inheritedEventCount: def.inheritedEventCount ?? 0, events: def.events ?? [] }
+      return { inheritedEventCount: def.inheritedEventCount ?? 0, events: def.events ?? [] }
+    },
+  }
+}
+
+// 宿主 handle 代形状(list 返回 snapshot,open/read/close 读体),供走
+// rescan → 工厂分派 → backfill 的装配路径测试使用
+function fakeHostPersistence(definitions = []) {
+  const byId = new Map(definitions.map((def) => [def.id, def]))
+  return {
+    async list() {
+      return definitions.map((def) => ({ header: { id: def.id }, revision: {} }))
+    },
+    async open(id, access) {
+      const def = byId.get(id)
+      if (!def) throw new Error(`session "${id}" not found`)
+      return {
+        header: { id },
+        inheritedEventCount: def.inheritedEventCount ?? 0,
+        access,
+        async read(offset, length) {
+          if (def.fail) throw new Error(def.fail)
+          const all = def.events ?? []
+          const start = typeof offset === 'number' && offset > 0 ? offset : 0
+          return { eventState: 'detached', events: all.slice(start, typeof length === 'number' ? start + length : undefined) }
+        },
+        async close() {},
+      }
     },
   }
 }
@@ -250,6 +279,67 @@ test('四桶全零 usage 为噪声不产样本', async () => {
   assert.equal(store.samples.length, 0)
 })
 
+test('V3 日志兼容:V3 专有事件与新字段被折叠忽略不炸', async () => {
+  const { ctx, store } = liveCollector()
+  const t = local(2026, 8, 2, 10, 0)
+  // V3 新增事件(SESSION_FORMAT_VERSION 3):统计不消费,折叠必须安全忽略
+  ctx.emit('session/event', session('s1'), ev('system/message', 1, t, { turn: 0, step: 0, message: { role: 'system', content: 'sys' } }))
+  ctx.emit('session/event', session('s1'), ev('assistant/attempt', 2, t, { turn: 0, step: 0, stream: [] }))
+  ctx.emit('session/event', session('s1'), ev('request/header', 3, t, { header: { config: {} }, reason: 'initial' }))
+  ctx.emit('session/event', session('s1'), ev('user/message', 4, t, { role: 'user', content: 'hi' }, ))
+  ctx.emit('session/event', session('s1'), ev('tool/call', 5, t, { turn: 0, step: 0, callId: 'c1', name: 'n', arguments: '{}' }))
+  ctx.emit('session/event', session('s1'), ev('tool/result', 6, t, { turn: 0, step: 0, message: { role: 'toolResult', content: 'r' } }))
+  ctx.emit('session/event', session('s1'), ev('session/end-seed', 7, t, {}))
+  ctx.emit('session/event', session('s1'), ev('step/end', 8, t, { turn: 0, step: 0 }))
+  ctx.emit('session/event', session('s1'), ev('turn/start', 9, t, { turn: 1 }))
+  // V3 assistant/message 携带 stream/surfaceOp/interrupted 等新字段:usage 折叠不受影响
+  ctx.emit('session/event', session('s1'), ev('assistant/message', 10, t, {
+    turn: 1,
+    step: 0,
+    usage: usage({ inputTokens: 5 }),
+    message: { role: 'assistant', source: { provider: 'p', model: 'm' } },
+    stream: [{ type: 'text-delta', text: 'x' }],
+    surfaceOp: 'append',
+    interrupted: true,
+  }))
+  await tick()
+  assert.equal(store.samples.length, 1)
+  assert.equal(store.samples[0].inputTokens, 5)
+  assert.equal(store.samples[0].model, 'p/m')
+})
+
+test('V3 日志兼容:回扫重放 V3 事件流,样本与游标正确', async () => {
+  const t = local(2026, 8, 2, 14, 0)
+  const persistence = fakePersistence([{
+    id: 'v3session',
+    events: [
+      ev('request/header', 0, t, { header: { config: {} }, reason: 'resume' }),
+      ev('system/message', 1, t, { turn: 0, step: 0, message: { role: 'system', content: 'sys' } }),
+      ev('user/message', 2, t, { role: 'user', content: 'q' }),
+      ev('step/start', 3, t, { turn: 0, step: 0 }),
+      ev('assistant/attempt', 4, t, { turn: 0, step: 0, stream: [] }),
+      ev('assistant/message', 5, t, {
+        turn: 0,
+        step: 0,
+        usage: usage({ inputTokens: 7 }),
+        message: { role: 'assistant', source: { provider: 'p', model: 'm' } },
+        stream: [],
+      }),
+      ev('step/end', 6, t, { turn: 0, step: 0 }),
+      ev('turn/end', 7, t, { turn: 0, reason: { kind: 'completed' } }),
+    ],
+  }])
+  const store = fakeStore()
+  const collector = new UsageCollector(fakeCtx({ persistence }), store)
+  await collector.backfill(persistence, fakeSessions())
+  assert.deepEqual(store.samples.map((sample) => [sample.request ?? sample.turn ?? false, sample.inputTokens]), [
+    [true, 0],
+    [false, 7],
+    [true, 0],
+  ])
+  assert.deepEqual([...store.state.backfilledSessions], ['v3session'])
+})
+
 test('纯缓存调用(仅缓存桶非零)仍产样本', async () => {
   const { ctx, store } = liveCollector()
   const t = local(2026, 8, 2, 10, 0)
@@ -578,6 +668,56 @@ test('回扫:record 失败使会话失败并保留游标重试机会', async ()
   assert.equal(collector.status().done, 1)
 })
 
+test('回扫:skipped 计数独立累加,超过日志上限不漂移', async () => {
+  const t = local(2026, 8, 2, 14, 0)
+  const defs = Array.from({ length: 210 }, (_, i) => ({ id: `bad${i}`, fail: 'uses unsupported descriptor version 2' }))
+  const persistence = fakePersistence(defs)
+  const store = fakeStore()
+  const collector = new UsageCollector(fakeCtx({ persistence }), store)
+  await collector.backfill(persistence, fakeSessions())
+  assert.equal(collector.status().skippedSessions, 210)
+  assert.equal(collector.status().log.length, 200)
+  assert.deepEqual(collector.status().skippedBreakdown, { descriptor: 210, corrupt: 0, legacy: 0, other: 0 })
+})
+
+test('回扫:skipped 按 detail 归因分类,次轮扫描计数复位', async () => {
+  const t = local(2026, 8, 2, 14, 0)
+  const persistence = fakePersistence([
+    { id: 'a', fail: 'uses unsupported descriptor version 2; source v0 artifact remains unchanged' },
+    { id: 'b', fail: 'stored log is corrupt: SessionFormatError: seq gap' },
+    { id: 'c', fail: 'format v0 contains unknown member "editor"' },
+    { id: 'd', fail: 'mystery failure' },
+    { id: 'ok', events: [ev('turn/end', 0, t)] },
+  ])
+  const store = fakeStore()
+  const collector = new UsageCollector(fakeCtx({ persistence }), store)
+  await collector.backfill(persistence, fakeSessions())
+  assert.deepEqual(collector.status().skippedBreakdown, { descriptor: 1, corrupt: 1, legacy: 1, other: 1 })
+  assert.equal(collector.status().skippedSessions, 4)
+  // 次轮:失败档不进游标会重现,但本轮从空游标重扫,计数从头累计且包含上一轮成功档
+  await collector.backfill(persistence, fakeSessions())
+  assert.equal(collector.status().skippedSessions, 4)
+  assert.deepEqual(collector.status().skippedBreakdown, { descriptor: 1, corrupt: 1, legacy: 1, other: 1 })
+})
+
+test('回扫:list 失败记入 error 并向上传播,running 复位', async () => {
+  const failure = new Error('sessionPersistence API 未识别')
+  const persistence = {
+    async list() {
+      throw failure
+    },
+    async readLog() {
+      throw new Error('not reached')
+    },
+  }
+  const store = fakeStore()
+  const collector = new UsageCollector(fakeCtx({ persistence }), store)
+  await assert.rejects(collector.backfill(persistence, fakeSessions()), (error) => error === failure)
+  assert.equal(collector.status().error, failure.message)
+  assert.equal(collector.status().running, false)
+  assert.equal(store.samples.length, 0)
+})
+
 test('abort:已中止 signal 直接返回不进入扫描', async () => {
   const persistence = fakePersistence([{ id: 's1', events: [] }])
   const store = fakeStore()
@@ -597,9 +737,9 @@ test('abort:扫描中中断停止处理且不写游标', async () => {
     async list() {
       return [{ id: 's1' }]
     },
-    async inspect(id) {
+    async readLog() {
       controller.abort()
-      return { meta: { id }, inheritedEventCount: 0, events: [ev('turn/end', 0, t)] }
+      return { inheritedEventCount: 0, events: [ev('turn/end', 0, t)] }
     },
   }
   const store = fakeStore()
@@ -625,14 +765,14 @@ test('回扫并发受默认并发 4 约束', async () => {
     async list() {
       return defs.map((def) => ({ id: def.id }))
     },
-    async inspect(id) {
+    async readLog(id) {
       inFlight += 1
       peak = Math.max(peak, inFlight)
       if (inFlight >= EXPECTED_CONCURRENCY) release()
       await Promise.race([gate, new Promise((resolve) => setTimeout(resolve, GATE_TIMEOUT_MS))])
       inFlight -= 1
       const def = defs.find((candidate) => candidate.id === id)
-      return { meta: { id }, inheritedEventCount: 0, events: def.events }
+      return { inheritedEventCount: 0, events: def.events }
     },
   }
   const store = fakeStore()
@@ -645,7 +785,7 @@ test('回扫并发受默认并发 4 约束', async () => {
 test('resetAndRescan 以 wipe 时刻日志长度为活跃会话边界并重扫', async () => {
   const t = local(2026, 8, 2, 9, 0)
   const events = Array.from({ length: 13 }, (_, seq) => ev('turn/end', seq, t))
-  const persistence = fakePersistence([{ id: 'live-a', events }])
+  const persistence = fakeHostPersistence([{ id: 'live-a', events }])
   const sessions = fakeSessions([{ id: 'live-a', seq: 10 }, { id: 'live-b' }])
   const store = fakeStore()
   store.state.liveFirstSeq.set('live-a', 3)
@@ -661,7 +801,7 @@ test('resetAndRescan 以 wipe 时刻日志长度为活跃会话边界并重扫',
 
 test('并发 resetAndRescan 合并为一次重建', async () => {
   const store = fakeStore()
-  const collector = new UsageCollector(fakeCtx(), store)
+  const collector = new UsageCollector(fakeCtx({ persistence: fakeHostPersistence() }), store)
   const first = collector.resetAndRescan()
   const second = collector.resetAndRescan()
   await Promise.all([first, second])
@@ -682,8 +822,12 @@ test('status() 返回快照,外部修改不影响内部状态', async () => {
     error: undefined,
     recordFailures: 0,
     skippedSessions: 0,
+    skippedBreakdown: { descriptor: 0, corrupt: 0, legacy: 0, other: 0 },
     log: [],
   })
+  const before = collector.status().skippedBreakdown
+  before.descriptor = 99
+  assert.equal(collector.status().skippedBreakdown.descriptor, 0)
   await collector.backfill(persistence, fakeSessions())
   const snapshot = collector.status()
   assert.equal(snapshot.running, false)

package/test/direct-log-reader.test.mjs

@@ -0,0 +1,104 @@
+// direct-log-reader 测试:多帧 zstd 解压、JSONL 宽松解析、目录定位与 id 枚举。
+// 全部经由 root 参数注入临时目录,不依赖真实 DSH_HOME
+
+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 { decodeZstdFile, parseJsonlEvents, findSessionDir, listSessionIdsDirect, readSessionLogDirect } from '../src/direct-log-reader.js'
+
+function tempRoot() {
+  return mkdtempSync(join(tmpdir(), 'ud-direct-'))
+}
+
+const MAGIC = Buffer.from([0x28, 0xb5, 0x2f, 0xfd])
+
+test('decodeZstdFile:多帧顺序解压拼接', () => {
+  const a = zstdCompressSync(Buffer.from('hello\n'))
+  const b = zstdCompressSync(Buffer.from('world\n'))
+  const bytes = Buffer.concat([MAGIC.slice(0, 3), a.subarray(3), MAGIC.slice(0, 3), b.subarray(3)])
+  assert.equal(decodeZstdFile(bytes), 'hello\nworld\n')
+})
+
+test('decodeZstdFile:无帧抛错', () => {
+  assert.throws(() => decodeZstdFile(Buffer.from('plain text')), /no zstd frame/)
+})
+
+test('parseJsonlEvents:header 行剔除,坏行跳过,事件保留', () => {
+  const text = [
+    JSON.stringify({ type: 'session/header', id: 's1', version: 1 }),
+    JSON.stringify({ type: 'assistant/message', seq: 1, data: { turn: 0, step: 0, usage: { inputTokens: 5 } } }),
+    'not json',
+    '',
+    JSON.stringify({ type: 'request/context', seq: 2, data: { provider: 'p', model: 'm' } }),
+  ].join('\n')
+  const events = parseJsonlEvents(text)
+  assert.equal(events.length, 2)
+  assert.equal(events[0].type, 'assistant/message')
+  assert.equal(events[1].type, 'request/context')
+})
+
+test('findSessionDir:跨 cwd 桶定位 id 目录', () => {
+  const root = tempRoot()
+  try {
+    const dir = join(root, '--C-users-proj--', 'sid-1')
+    mkdirSync(dir, { recursive: true })
+    writeFileSync(join(dir, 'session.jsonl.zstd'), zstdCompressSync(Buffer.from('{}\n')))
+    assert.equal(findSessionDir('sid-1', root), dir)
+    assert.equal(findSessionDir('missing', root), undefined)
+    assert.equal(findSessionDir('sid-1', join(root, 'nope')), undefined)
+  } finally {
+    rmSync(root, { recursive: true, force: true })
+  }
+})
+
+test('listSessionIdsDirect:只收含日志文件的会话目录', () => {
+  const root = tempRoot()
+  try {
+    const withLog = join(root, 'bucket-a', 'id-1')
+    mkdirSync(withLog, { recursive: true })
+    writeFileSync(join(withLog, 'session.jsonl.zstd'), '')
+    const withV3 = join(root, 'bucket-a', 'id-2')
+    mkdirSync(withV3, { recursive: true })
+    writeFileSync(join(withV3, 'session.v3.jsonl.zstd'), '')
+    const empty = join(root, 'bucket-b', 'id-3')
+    mkdirSync(empty, { recursive: true })
+    assert.deepEqual(listSessionIdsDirect(root).sort(), ['id-1', 'id-2'])
+  } finally {
+    rmSync(root, { recursive: true, force: true })
+  }
+})
+
+test('readSessionLogDirect:压缩档案解出事件流', () => {
+  const root = tempRoot()
+  try {
+    const dir = join(root, 'bucket', 'sid-9')
+    mkdirSync(dir, { recursive: true })
+    const text = [
+      JSON.stringify({ type: 'session/header', id: 'sid-9' }),
+      JSON.stringify({ type: 'assistant/message', seq: 0, data: { turn: 0, step: 0, usage: { inputTokens: 7 } } }),
+    ].join('\n')
+    writeFileSync(join(dir, 'session.v3.jsonl.zstd'), zstdCompressSync(Buffer.from(text)))
+    const events = readSessionLogDirect('sid-9', root)
+    assert.equal(events.length, 1)
+    assert.equal(events[0].data.usage.inputTokens, 7)
+  } finally {
+    rmSync(root, { recursive: true, force: true })
+  }
+})
+
+test('readSessionLogDirect:明文 jsonl 档案同样可读', () => {
+  const root = tempRoot()
+  try {
+    const dir = join(root, 'bucket', 'sid-plain')
+    mkdirSync(dir, { recursive: true })
+    writeFileSync(join(dir, 'session.jsonl'), JSON.stringify({ type: 'turn/end', seq: 0 }))
+    const events = readSessionLogDirect('sid-plain', root)
+    assert.equal(events.length, 1)
+  } finally {
+    rmSync(root, { recursive: true, force: true })
+  }
+})

package/test/pricing-parity.test.mjs

@@ -15,6 +15,7 @@ import {
   CONDITION_KINDS as hostConditionKinds,
   TOKENS_PER_MILLION as hostTokensPerMillion,
 } from '../src/pricing.js'
+import { refOf as hostRefOf } from '../src/collector.js'
 
 const core = new Function(`${CLIENT_BODY}\nreturn { ${DECLARATION_NAMES.join(', ')} }`)()
 
@@ -27,6 +28,8 @@ const {
   CURRENCIES: clientCurrencies,
   CONDITION_KINDS: clientConditionKinds,
   TOKENS_PER_MILLION: clientTokensPerMillion,
+  MODEL_UNROUTED: clientModelUnrouted,
+  turnModelOf: clientTurnModelOf,
 } = core
 
 // 本地时区固定时刻(2026-03-15 为周日):同一 Date 实例喂双侧
@@ -36,32 +39,40 @@ const SUNDAY_0900 = [2026, 2, 15, 9, 0]
 const SUNDAY_2330 = [2026, 2, 15, 23, 30]
 const SUNDAY_0300 = [2026, 2, 15, 3, 0]
 const SUNDAY_1200 = [2026, 2, 15, 12, 0]
+const MON_JAN01 = [2026, 0, 1, 12, 0]
 const MON_JAN15 = [2026, 0, 15, 12, 0]
 const MON_JAN16 = [2026, 0, 16, 12, 0]
 const MON_JAN26 = [2026, 0, 26, 12, 0]
+const MON_JAN31 = [2026, 0, 31, 12, 0]
 const MON_JAN03 = [2026, 0, 3, 12, 0]
 const FEB_30_ROLLS_TO_MAR02 = [2026, 1, 30, 12, 0]
 
 const CONDITION_VECTORS = [
   { name: 'dailyWindow from<to 命中', condition: { kind: 'dailyWindow', from: '09:00', to: '18:00' }, date: SUNDAY_0930, expected: true },
-  { name: 'dailyWindow 含头不含尾', condition: { kind: 'dailyWindow', from: '09:00', to: '18:00' }, date: SUNDAY_1800, expected: false },
+  { name: 'dailyWindow 双闭含 to 端点', condition: { kind: 'dailyWindow', from: '09:00', to: '18:00' }, date: SUNDAY_1800, expected: true },
   { name: 'dailyWindow 含头', condition: { kind: 'dailyWindow', from: '09:00', to: '18:00' }, date: SUNDAY_0900, expected: true },
   { name: 'dailyWindow 跨午夜夜段命中', condition: { kind: 'dailyWindow', from: '22:00', to: '06:00' }, date: SUNDAY_2330, expected: true },
   { name: 'dailyWindow 跨午夜凌晨命中', condition: { kind: 'dailyWindow', from: '22:00', to: '06:00' }, date: SUNDAY_0300, expected: true },
   { name: 'dailyWindow 跨午夜日间不命中', condition: { kind: 'dailyWindow', from: '22:00', to: '06:00' }, date: SUNDAY_1200, expected: false },
-  { name: 'dailyWindow from===to 全天', condition: { kind: 'dailyWindow', from: '00:00', to: '00:00' }, date: SUNDAY_1200, expected: true },
+  { name: 'dailyWindow from===to 单点命中', condition: { kind: 'dailyWindow', from: '12:00', to: '12:00' }, date: SUNDAY_1200, expected: true },
+  { name: 'dailyWindow 00:00~23:59 全天含尾', condition: { kind: 'dailyWindow', from: '00:00', to: '23:59' }, date: SUNDAY_2330, expected: true },
   { name: 'dailyWindow 非法格式', condition: { kind: 'dailyWindow', from: 'abc', to: '06:00' }, date: SUNDAY_1200, expected: false },
   { name: 'weekdays 命中周日', condition: { kind: 'weekdays', days: [0] }, date: SUNDAY_0930, expected: true },
   { name: 'weekdays 空 days 不成立', condition: { kind: 'weekdays', days: [] }, date: SUNDAY_0930, expected: false },
   { name: 'weekdays 未命中', condition: { kind: 'weekdays', days: [1] }, date: SUNDAY_0930, expected: false },
   { name: 'weekdays days 非数组', condition: { kind: 'weekdays', days: 'x' }, date: SUNDAY_0930, expected: false },
-  { name: 'monthDays 双闭含端', condition: { kind: 'monthDays', from: 1, to: 15 }, date: MON_JAN15, expected: true },
+  { name: 'monthDays 双闭含 to 端点', condition: { kind: 'monthDays', from: 1, to: 15 }, date: MON_JAN15, expected: true },
+  { name: 'monthDays 含首日', condition: { kind: 'monthDays', from: 1, to: 15 }, date: MON_JAN01, expected: true },
   { name: 'monthDays 界外', condition: { kind: 'monthDays', from: 1, to: 15 }, date: MON_JAN16, expected: false },
+  { name: 'monthDays 1~31 全月', condition: { kind: 'monthDays', from: 1, to: 31 }, date: MON_JAN31, expected: true },
+  { name: 'monthDays from===to 单日命中', condition: { kind: 'monthDays', from: 15, to: 15 }, date: MON_JAN15, expected: true },
   { name: 'monthDays 环绕起点命中', condition: { kind: 'monthDays', from: 26, to: 5 }, date: MON_JAN26, expected: true },
   { name: 'monthDays 环绕中段不命中', condition: { kind: 'monthDays', from: 26, to: 5 }, date: MON_JAN15, expected: false },
-  { name: 'monthDays 环绕终点命中', condition: { kind: 'monthDays', from: 26, to: 5 }, date: MON_JAN03, expected: true },
+  { name: 'monthDays 环绕终点含端点', condition: { kind: 'monthDays', from: 26, to: 5 }, date: MON_JAN03, expected: true },
   { name: 'monthDays 非整数不成立', condition: { kind: 'monthDays', from: 1.5, to: 5 }, date: MON_JAN15, expected: false },
   { name: 'dateRange 命中', condition: { kind: 'dateRange', from: '2026-01-01', to: '2026-01-31' }, date: MON_JAN15, expected: true },
+  { name: 'dateRange to 端点命中', condition: { kind: 'dateRange', from: '2026-01-01', to: '2026-01-31' }, date: MON_JAN31, expected: true },
+  { name: 'dateRange from===to 单日命中', condition: { kind: 'dateRange', from: '2026-01-15', to: '2026-01-15' }, date: MON_JAN15, expected: true },
   { name: 'dateRange 倒序不成立', condition: { kind: 'dateRange', from: '2026-01-31', to: '2026-01-01' }, date: MON_JAN15, expected: false },
   { name: 'dateRange 非零填充不成立', condition: { kind: 'dateRange', from: '2026-1-1', to: '2026-1-31' }, date: MON_JAN15, expected: false },
   { name: 'dateRange 2 月 30 号滚月后不命中', condition: { kind: 'dateRange', from: '2026-02-01', to: '2026-02-28' }, date: FEB_30_ROLLS_TO_MAR02, expected: false },
@@ -292,3 +303,26 @@ test(`costOf 双侧一致(${COST_VECTORS.length} 向量)`, () => {
     assert.deepEqual(host, vector.expected, vector.name)
   }
 })
+
+// 路由引用键双实现同源:采集器 refOf(样本 model 键)与 client 注入点B turnModelOf(回合计价键)
+// 双全拼两段、仅 model 用裸名、多 route 取首条;键不成立时两侧各按自身约定降级
+// (refOf→undefined,turnModelOf→全通配键),该场景单独断言各自约定值
+const REF_VECTORS = [
+  { name: '双全拼两段', route: { provider: 'deepseek', model: 'deepseek-chat' }, expected: 'deepseek/deepseek-chat' },
+  { name: '仅 model 用裸名', route: { model: 'm' }, expected: 'm' },
+  { name: 'provider 空串按裸名', route: { provider: '', model: 'm' }, expected: 'm' },
+  { name: 'provider 非空 model 空串不成立', route: { provider: 'p', model: '' }, expected: undefined },
+  { name: '空 route 对象不成立', route: {}, expected: undefined },
+  { name: '多 route 取首条', route: { provider: 'a', model: 'x' }, tail: { provider: 'b', model: 'y' }, expected: 'a/x' },
+]
+
+test(`路由引用键双侧一致(${REF_VECTORS.length} 向量)`, () => {
+  for (const vector of REF_VECTORS) {
+    const routes = vector.tail ? [vector.route, vector.tail] : [vector.route]
+    assert.equal(hostRefOf(vector.route), vector.expected, vector.name)
+    assert.equal(clientTurnModelOf({ routes }), vector.expected ?? clientModelUnrouted, vector.name)
+  }
+  assert.equal(hostRefOf(null), undefined)
+  assert.equal(clientTurnModelOf({ routes: [] }), clientModelUnrouted)
+  assert.equal(clientTurnModelOf(null), clientModelUnrouted)
+})

package/test/pricing.test.mjs

@@ -228,37 +228,47 @@ test('rules 非数组或 timestamp 非法返回 null', () => {
   assert.equal(matchPrice([makeRule()], 'a/b', Number.NaN), null)
 })
 
-test('dailyWindow from<to 含头不含尾', () => {
-  // Given 10:00~12:00 When 逐时刻判定 Then 10:00 与 11:59 命中,09:59 与 12:00 不命中
+test('dailyWindow from<to 双闭含两端', () => {
+  // Given 10:00~12:00 When 逐时刻判定 Then 10:00 与 12:00 命中,09:59 与 12:01 不命中
   const condition = { kind: 'dailyWindow', from: '10:00', to: '12:00' }
   assert.equal(conditionMatches(condition, localTime(6, 10)), true)
   assert.equal(conditionMatches(condition, localTime(6, 11, 59)), true)
+  assert.equal(conditionMatches(condition, localTime(6, 12)), true)
   assert.equal(conditionMatches(condition, localTime(6, 9, 59)), false)
-  assert.equal(conditionMatches(condition, localTime(6, 12)), false)
+  assert.equal(conditionMatches(condition, localTime(6, 12, 1)), false)
 })
 
 test('dailyWindow 跨午夜窗口按本地分量命中', () => {
-  // Given 22:00~02:00 When 本地 23:30 与次日 01:00 Then 命中;本地正午不命中
+  // Given 22:00~02:00 When 本地 23:30 与次日 01:00/02:00 Then 命中;本地正午不命中
   const condition = { kind: 'dailyWindow', from: '22:00', to: '02:00' }
   assert.equal(conditionMatches(condition, localTime(6, 23, 30)), true)
   assert.equal(conditionMatches(condition, new Date(2026, 8, 7, 1)), true)
+  assert.equal(conditionMatches(condition, new Date(2026, 8, 7, 2)), true)
   assert.equal(conditionMatches(condition, localTime(6, 12)), false)
 })
 
-test('dailyWindow from===to 全天生效', () => {
-  // Given 10:00~10:00 When 判定 00:00/10:00/23:59 Then 全部命中
+test('dailyWindow from===to 为单点仅命中该时刻', () => {
+  // Given 10:00~10:00 双闭单点 When 判定 10:00 与其他时刻 Then 仅 10:00 命中
   const condition = { kind: 'dailyWindow', from: '10:00', to: '10:00' }
-  assert.equal(conditionMatches(condition, localTime(6, 0)), true)
   assert.equal(conditionMatches(condition, localTime(6, 10)), true)
+  assert.equal(conditionMatches(condition, localTime(6, 10, 1)), false)
+  assert.equal(conditionMatches(condition, localTime(6, 23, 59)), false)
+})
+
+test('dailyWindow 全天用 00:00~23:59 表达', () => {
+  // Given 00:00~23:59 When 判定 00:00 与 23:59 Then 全部命中
+  const condition = { kind: 'dailyWindow', from: '00:00', to: '23:59' }
+  assert.equal(conditionMatches(condition, localTime(6, 0)), true)
   assert.equal(conditionMatches(condition, localTime(6, 23, 59)), true)
 })
 
 test('dailyWindow 分钟级评估', () => {
-  // Given 10:05~10:10 When 判定 10:05/10:09/10:10 Then 前两者命中
+  // Given 10:05~10:10 When 判定 10:05/10:09/10:10/10:11 Then 前三者命中
   const condition = { kind: 'dailyWindow', from: '10:05', to: '10:10' }
   assert.equal(conditionMatches(condition, localTime(6, 10, 5)), true)
   assert.equal(conditionMatches(condition, localTime(6, 10, 9)), true)
-  assert.equal(conditionMatches(condition, localTime(6, 10, 10)), false)
+  assert.equal(conditionMatches(condition, localTime(6, 10, 10)), true)
+  assert.equal(conditionMatches(condition, localTime(6, 10, 11)), false)
 })
 
 test('weekdays 集合按 getDay 命中', () => {
@@ -273,10 +283,11 @@ test('weekdays 空数组条件不成立', () => {
   assert.equal(conditionMatches({ kind: 'weekdays', days: [] }, SUNDAY), false)
 })
 
-test('monthDays 正向段双闭含单日', () => {
-  // Given 1~15 When 判定 1/15/16 号 Then 双闭;Given 5~5 When 判定 5/6 号 Then 单日
+test('monthDays 双闭含两端,from===to 为单日', () => {
+  // Given 1~15 When 判定 1/14/15/16 号 Then 含 1 与 15 不含 16;Given 5~5 单日 When 判定 5/6 号 Then 仅 5 命中
   const span = { kind: 'monthDays', from: 1, to: 15 }
   assert.equal(conditionMatches(span, new Date(2026, 8, 1)), true)
+  assert.equal(conditionMatches(span, new Date(2026, 8, 14)), true)
   assert.equal(conditionMatches(span, new Date(2026, 8, 15)), true)
   assert.equal(conditionMatches(span, new Date(2026, 8, 16)), false)
   const single = { kind: 'monthDays', from: 5, to: 5 }
@@ -284,44 +295,65 @@ test('monthDays 正向段双闭含单日', () => {
   assert.equal(conditionMatches(single, new Date(2026, 8, 6)), false)
 })
 
-test('monthDays 单日 31 号在 2 月自然不触发', () => {
-  // Given 31~31 When 判定 1 月 31 号与 2 月末 Then 前者命中;2 月无 31 号,该月任意日不命中
+test('monthDays 全月用 1~31 表达,31 号仅大月命中', () => {
+  // Given 1~31 When 判定 1/30/31 号 Then 全月命中;2 月无 31 号自然不触发
+  const month = { kind: 'monthDays', from: 1, to: 31 }
+  assert.equal(conditionMatches(month, new Date(2026, 8, 1)), true)
+  assert.equal(conditionMatches(month, new Date(2026, 8, 30)), true)
+  assert.equal(conditionMatches(month, new Date(2026, 0, 31)), true)
+  assert.equal(conditionMatches(month, new Date(2026, 1, 28)), true)
+})
+
+test('monthDays 单日 31 号用 31~31 表达', () => {
+  // Given 31~31 When 判定 1 月 31 号与 2 月末 Then 仅大月 31 号命中,2 月无 31 号自然不触发
   const condition = { kind: 'monthDays', from: 31, to: 31 }
   assert.equal(conditionMatches(condition, new Date(2026, 0, 31)), true)
   assert.equal(conditionMatches(condition, new Date(2026, 1, 28)), false)
 })
 
-test('monthDays 26~25 跨月环绕覆盖全月', () => {
-  // Given 26~25 账单周期 When 判定 26/31/1/25/15 号 Then 26..31 并 1..25 覆盖全月,含 15
+test('monthDays 26~25 跨月环绕为 26 起至次月 25', () => {
+  // Given 26~25 账单周期双闭 When 判定 26/31/1/24/25/15 号 Then 26..31 并 1..25 命中
   const condition = { kind: 'monthDays', from: 26, to: 25 }
   assert.equal(conditionMatches(condition, new Date(2026, 0, 26)), true)
   assert.equal(conditionMatches(condition, new Date(2026, 0, 31)), true)
   assert.equal(conditionMatches(condition, new Date(2026, 1, 1)), true)
+  assert.equal(conditionMatches(condition, new Date(2026, 1, 24)), true)
   assert.equal(conditionMatches(condition, new Date(2026, 1, 25)), true)
   assert.equal(conditionMatches(condition, new Date(2026, 0, 15)), true)
 })
 
 test('monthDays 27~10 环绕存在不命中间隙', () => {
-  // Given 27~10 When 判定 27/31/1/10 与 15/26 号 Then 前四命中,间隙内不命中
+  // Given 27~10 双闭 When 判定 27/31/1/10 与 9/15/26 号 Then 27..31 并 1..10 命中,间隙不命中
   const condition = { kind: 'monthDays', from: 27, to: 10 }
   assert.equal(conditionMatches(condition, new Date(2026, 0, 27)), true)
   assert.equal(conditionMatches(condition, new Date(2026, 0, 31)), true)
   assert.equal(conditionMatches(condition, new Date(2026, 1, 1)), true)
   assert.equal(conditionMatches(condition, new Date(2026, 1, 10)), true)
+  assert.equal(conditionMatches(condition, new Date(2026, 1, 9)), true)
+  assert.equal(conditionMatches(condition, new Date(2026, 1, 11)), false)
   assert.equal(conditionMatches(condition, new Date(2026, 0, 15)), false)
   assert.equal(conditionMatches(condition, new Date(2026, 0, 26)), false)
 })
 
-test('dateRange 双闭区间', () => {
-  // Given 2026-01-01~2026-01-31 When 判定首末日与界外 Then 端点命中,两侧不命中
+test('dateRange 双闭含两端', () => {
+  // Given 2026-01-01~2026-01-31 When 判定首日/中间/末日/界外 Then 首日中间末日命中,两侧不命中
   const condition = { kind: 'dateRange', from: '2026-01-01', to: '2026-01-31' }
   assert.equal(conditionMatches(condition, new Date(2026, 0, 1)), true)
   assert.equal(conditionMatches(condition, new Date(2026, 0, 15)), true)
+  assert.equal(conditionMatches(condition, new Date(2026, 0, 30)), true)
   assert.equal(conditionMatches(condition, new Date(2026, 0, 31)), true)
   assert.equal(conditionMatches(condition, new Date(2025, 11, 31)), false)
   assert.equal(conditionMatches(condition, new Date(2026, 1, 1)), false)
 })
 
+test('dateRange from===to 为单日命中', () => {
+  // Given 同日区间双闭 When 判定该日与前后日 Then 仅该日命中
+  const single = { kind: 'dateRange', from: '2026-01-15', to: '2026-01-15' }
+  assert.equal(conditionMatches(single, new Date(2026, 0, 15)), true)
+  assert.equal(conditionMatches(single, new Date(2026, 0, 14)), false)
+  assert.equal(conditionMatches(single, new Date(2026, 0, 16)), false)
+})
+
 test('dateRange 倒序属配置错误不成立', () => {
   const condition = { kind: 'dateRange', from: '2026-02-01', to: '2026-01-01' }
   assert.equal(conditionMatches(condition, new Date(2026, 0, 15)), false)

package/test/query.test.mjs

@@ -393,6 +393,7 @@ test('attachCosts M 行 unpriced 按父 H 桶去重', () => {
 })
 
 test('attachCosts D 端点按 H 行桶起点计价折叠到日槽', () => {
+  // 双闭:两日期段不相邻不重叠,22/23 桶起点 01-01 落段一,00 桶起点 01-02 落段二
   const costRows = [
     makeRow({ bucket: '2020-01-01T22', model: 'm1', inputTokens: 1000000 }),
     makeRow({ bucket: '2020-01-01T23', model: 'm1', inputTokens: 1000000 }),
@@ -404,7 +405,7 @@ test('attachCosts D 端点按 H 行桶起点计价折叠到日槽', () => {
   ]
   const rules = [
     ruleOf({ price: inputPrice(1), conditions: [{ kind: 'dateRange', from: '2020-01-01', to: '2020-01-01' }] }),
-    ruleOf({ price: inputPrice(3), conditions: [{ kind: 'dateRange', from: '2020-01-02', to: '2020-01-02' }] }),
+    ruleOf({ price: inputPrice(3), conditions: [{ kind: 'dateRange', from: '2020-01-02', to: '2020-01-03' }] }),
   ]
   const result = aggregateRange(aggregateRows, 'D', '2020-01-01', '2020-01-02')
   const out = attachCosts(result, costRows, 'D', rules)

package/test/routes.test.mjs

@@ -69,6 +69,13 @@ function makeStore({ rows = [], fail } = {}) {
   const calls = { rangeRows: 0 }
   return {
     calls,
+    backupInfo() {
+      return { available: false }
+    },
+    async restoreFromBackup() {
+      calls.restoreFromBackup = (calls.restoreFromBackup ?? 0) + 1
+      return { takenAt: 0, rows: 0 }
+    },
     async rangeRows(g, from, to) {
       calls.rangeRows += 1
       if (fail) throw fail
@@ -301,7 +308,7 @@ test('range 合法请求回 UsageStatsRange 信封', async () => {
   assert.equal(store.calls.rangeRows, 1)
 })
 
-test('status 回采集快照', async () => {
+test('status 回采集快照并附带回退点元信息', async () => {
   const collector = makeCollector({
     stateOverrides: { running: true, total: 5, done: 2, scannedSessions: 7, lastSessionId: 's1', error: 'boom', recordFailures: 1 },
   })
@@ -310,7 +317,7 @@ test('status 回采集快照', async () => {
   const parsed = JSON.parse(res.body)
   assert.equal(res.statusCode, 200)
   assert.equal(parsed.ok, true)
-  assert.deepEqual(parsed.value, collector.status())
+  assert.deepEqual(parsed.value, { ...collector.status(), backup: { available: false } })
 })
 
 test('minutes 超出保留窗口标注 coveredFrom/coveredTo', async () => {

package/test/stats-line.test.mjs

@@ -35,12 +35,12 @@ const PREFS_COST_ON = { cachePrecision: false, tokenDetail: false, costDisplay:
 const zhT = createTranslator(MESSAGES_ZH)
 const enT = createTranslator(MESSAGES_EN)
 
-// 费用组装配输入:精确规则在前、全通配规则兜底,通配仅全天时段生效
+// 费用组装配输入:精确规则在前、全通配规则兜底,通配仅全天时段(00:00~23:59 双闭)生效
 const COST_RULES = [
   { model: 'p/m', currency: '¥', price: { input: 2, output: 0, cacheRead: 0, cacheWrite: 0 }, conditions: [] },
   {
     model: '*/*', currency: '', price: { input: 1, output: 0, cacheRead: 0, cacheWrite: 0 },
-    conditions: [{ kind: 'dailyWindow', from: '00:00', to: '00:00' }],
+    conditions: [{ kind: 'dailyWindow', from: '00:00', to: '23:59' }],
   },
 ]
 const COST_USAGE = { uncachedInputTokens: 500000, cacheReadTokens: 0, cacheWriteTokens: 0, outputTokens: 0 }
@@ -358,11 +358,11 @@ test('buildCostItem routes 首个 model 精确规则优先于通配', () => {
   assert.equal(buildCostItem(routed, wildcardFirst, PREFS_COST_ON, zhT, COST_NOW), '费用 ≈ ¥1.00')
 })
 
-test('buildCostItem 时间条件按传入时刻评估:窗口外通配不生效', () => {
-  // 通配规则 00:00~00:00 from===to 全天生效;08:00~09:00 与固定时刻不交
-  const midnight = [{ ...COST_RULES[1], conditions: [{ kind: 'dailyWindow', from: '00:00', to: '00:00' }] }]
+test('buildCostItem 时间条件按传入时刻评估:窗口外均不生效', () => {
+  // 双闭下 00:00~00:00 单点仅命中零点整,COST_NOW 10:00 不命中;08:00~09:00 与固定时刻不交
+  const singlePoint = [{ ...COST_RULES[1], conditions: [{ kind: 'dailyWindow', from: '00:00', to: '00:00' }] }]
   const daytime = [{ ...COST_RULES[1], conditions: [{ kind: 'dailyWindow', from: '08:00', to: '09:00' }] }]
-  assert.equal(buildCostItem(COST_USAGE, midnight, PREFS_COST_ON, zhT, COST_NOW), '费用 ≈ 0.50')
+  assert.equal(buildCostItem(COST_USAGE, singlePoint, PREFS_COST_ON, zhT, COST_NOW), '—')
   assert.equal(buildCostItem(COST_USAGE, daytime, PREFS_COST_ON, zhT, COST_NOW), '—')
 })