@mzzsfy/dsh-usage-dash 0.1.0 → 0.2.0

package/src/collector.js

@@ -9,11 +9,15 @@ const UNKNOWN_SESSION_ID = '(unknown-session)'
 const SEQ_UNKNOWN = -1
 const DEFAULT_BACKFILL_CONCURRENCY = 4
 const MARK_BATCH = 32
+const SCAN_LOG_MAX_ENTRIES = 200
 
 // 会话内单 pass 折叠:跟踪每个 (turn,step) 槽的最新报告,只把首次发射交 store
 export class UsageFold {
   constructor() {
     this.seen = new Map()
+    // (turn,step) 最近一次模型启动时刻:retry-started 覆盖重置,时长与首样本
+    // token 同源配对(分子只含最终尝试,分母不含失败尝试,避免速度被污染)
+    this.starts = new Map()
   }
 
   keyOf(event) {
@@ -37,6 +41,8 @@ export class UsageFold {
     if (event.type === 'step/start' || event.type === 'llm/retry-started') {
       // step/start 恰开一次模型调用,retry-started 标记每次实际启动的重试;
       // 请求只由标记计数,与 token 样本双计
+      const key = this.keyOf(event)
+      if (key !== null) this.starts.set(key, event.time)
       return {
         time: event.time,
         inputTokens: 0,
@@ -69,6 +75,13 @@ export class UsageFold {
       cacheReadTokens: usage.cacheReadTokens ?? 0,
       cacheWriteTokens: usage.cacheWriteTokens ?? 0,
     }
+    // 模型时长口径与官方 session-stats 投影 llmMs 同构(step/start → 汇报时刻),
+    // 附加到交 store 的首样本;未观测起点或时刻倒挂(时钟回拨)不附,0 视为无
+    const start = key !== null ? this.starts.get(key) : undefined
+    if (start !== undefined) {
+      const durationMs = Math.max(0, event.time - start)
+      if (durationMs > 0) sample.durationMs = durationMs
+    }
     if (key === null) return sample
     const prev = this.seen.get(key)
     this.seen.set(key, sample)
@@ -93,6 +106,10 @@ export class UsageCollector {
   constructor(ctx, store) {
     this.ctx = ctx
     this.store = store
+    // store 写合并周期落盘的失败行接入扫描异常日志,面板可观测
+    store.onFlushError = (error) => {
+      this.pushLog('record', error instanceof Error ? error.message : String(error))
+    }
     this.folds = new Map()
     this.routes = new Map()
     this.started = false
@@ -108,16 +125,33 @@ export class UsageCollector {
       scannedSessions: 0,
       lastSessionId: undefined,
       error: undefined,
-      recordFailures: 0,
-      skippedSessions: 0,
+      log: [],
     }
-    // error 保留给采集器自身故障;单会话读取失败走 skippedSessions 跳过计数
+    // error 保留给采集器自身故障;单会话读取失败走日志 skipped 条目,计数由日志派生
   }
 
   #state
 
   status() {
-    return { ...this.#state }
+    const log = [...this.#state.log]
+    return {
+      running: this.#state.running,
+      total: this.#state.total,
+      done: this.#state.done,
+      scannedSessions: this.#state.scannedSessions,
+      lastSessionId: this.#state.lastSessionId,
+      error: this.#state.error,
+      skippedSessions: log.filter((entry) => entry.kind === 'skipped').length,
+      recordFailures: log.filter((entry) => entry.kind === 'record').length,
+      log,
+    }
+  }
+
+  // 扫描异常日志:供面板明细展示,超上限丢最旧
+  pushLog(kind, detail) {
+    const log = this.#state.log
+    log.push({ time: Date.now(), kind, detail })
+    if (log.length > SCAN_LOG_MAX_ENTRIES) log.splice(0, log.length - SCAN_LOG_MAX_ENTRIES)
   }
 
   get running() {
@@ -148,8 +182,8 @@ export class UsageCollector {
       if (!sample) return
       // turn 标记落合成行不归因;其余样本先取本调用 source,再取会话路由
       if (!sample.turn) sample.model = fromSource ?? this.routeFor(sid)
-      void this.store.record(sample).catch(() => {
-        this.#state.recordFailures += 1
+      void this.store.record(sample).catch((error) => {
+        this.pushLog('record', error?.message ?? String(error))
       })
     })
     // 释放销毁会话的内存桶,防长跑宿主按会话数累积
@@ -192,8 +226,8 @@ export class UsageCollector {
       const batch = [...this.liveMarkBuffer.entries()]
       this.liveMarkBuffer.clear()
       if (batch.length > 0) {
-        void this.store.markLiveSequences(batch).catch(() => {
-          this.#state.recordFailures += 1
+        void this.store.markLiveSequences(batch).catch((error) => {
+          this.pushLog('record', error?.message ?? String(error))
         })
       }
     })
@@ -252,7 +286,7 @@ export class UsageCollector {
       const targets = headers.filter((header) => !seen.has(header.id))
       this.#state.total = targets.length
       this.#state.done = 0
-      this.#state.skippedSessions = 0
+      this.#state.log = []
       const workerCount = Math.min(DEFAULT_BACKFILL_CONCURRENCY, Math.max(1, targets.length))
       let next = 0
       const completed = []
@@ -310,9 +344,9 @@ export class UsageCollector {
             completed.push(header.id)
             if (completed.length >= MARK_BATCH) await flushCompleted()
             this.#state.scannedSessions += 1
-          } catch {
-            // 读取失败(如宿主报会话日志损坏)按定案跳过:计数并继续,不中断回扫、不挂错误横幅
-            this.#state.skippedSessions += 1
+          } catch (error) {
+            // 读取失败(如宿主报会话日志损坏)按定案跳过:记日志并继续,不中断回扫、不挂错误横幅
+            this.pushLog('skipped', error?.message ? `${header.id} ${error.message}` : header.id)
           } finally {
             this.#state.done += 1
           }

package/src/index.js

@@ -7,7 +7,7 @@ import schemastery from '@deepseek-ai/schemastery'
 import { UsageCollector } from './collector.js'
 import { CURRENCIES, CONDITION_KINDS, UNIT_PER_MILLION } from './pricing.js'
 import { registerUsageRoutes } from './routes.js'
-import { DEFAULT_MINUTE_RETENTION_DAYS, sharedStore } from './store.js'
+import { DEFAULT_MINUTE_RETENTION_DAYS, MINUTE_RETENTION_MAX_DAYS, sharedStore } from './store.js'
 // 顶层 inject 仅声明 web profile 必然存在的四个服务;settings 在 apply 内
 // 嵌套 inject(通道级静默不激活),构成干净禁用。
 export const inject = ['webServer', 'sessionPersistence', 'sessions', 'storageDomain']
@@ -50,7 +50,7 @@ const PRICING_RULE_SCHEMA = schemastery.object({
 
 const SETTINGS_SCHEMA = schemastery.object({
   minuteRetentionDays: schemastery.number().min(0).step(1).default(DEFAULT_MINUTE_RETENTION_DAYS)
-    .description('分钟桶保留天数(上限 48h),0 表示禁用分钟桶'),
+    .description(`分钟桶保留天数(上限 ${MINUTE_RETENTION_MAX_DAYS} 天),0 表示禁用分钟桶`),
   pricing: schemastery.object({ rules: schemastery.array(PRICING_RULE_SCHEMA) })
     .description('定价规则(wire 由 /api/usage-dash/pricing 读写)'),
 })

package/src/pricing.js

@@ -7,6 +7,12 @@ export const CONDITION_KINDS = ['dailyWindow', 'weekdays', 'monthDays', 'dateRan
 export const TOKENS_PER_MILLION = 1000 * 1000
 
 const MODEL_WILDCARD = '*'
+const SEGMENT_SEPARATOR = '/'
+// 请求侧无斜杠时的 vendor 段缺省值,与存储行 provider 口径同源
+export const PROVIDER_UNSET = 'default'
+// 档位权重:vendor 段通配 1 档、model 段通配 2 档,和越小越优先(模型名精确档恒优于供应商精确档)
+const VENDOR_WILDCARD_TIER = 1
+const MODEL_WILDCARD_TIER = 2
 const MINUTES_PER_HOUR = 60
 const DAY_PART_WIDTH = 2
 const ISO_DAY_PATTERN = /^\d{4}-\d{2}-\d{2}$/
@@ -79,12 +85,31 @@ const isRuleShaped = (rule) =>
   && !!rule.price && typeof rule.price === 'object' && !Array.isArray(rule.price)
   && Array.isArray(rule.conditions)
 
-const firstMatchingPrice = (rules, date, modelFilter) => {
-  for (const rule of rules) {
-    if (!isRuleShaped(rule) || !modelFilter(rule)) continue
-    if (rule.conditions.every((condition) => conditionMatches(condition, date))) return rule.price
-  }
-  return null
+// 规则模型键必须两段式:首个 / 前 vendor 段、后模型段(允许含 /),首位斜杠或无斜杠均非法
+export const splitRuleSegments = (pattern) => {
+  const slash = pattern.indexOf(SEGMENT_SEPARATOR)
+  return slash > 0 ? [pattern.slice(0, slash), pattern.slice(slash + SEGMENT_SEPARATOR.length)] : null
+}
+
+// 段须非空且不含空白:含空白的模型键永不匹配真实请求
+const SEGMENT_PATTERN = /^\S+$/
+
+export const isTwoSegmentModel = (pattern) => {
+  const segments = splitRuleSegments(pattern)
+  return segments !== null && segments.every((segment) => SEGMENT_PATTERN.test(segment))
+}
+
+// 请求侧模型键按同构规则分段,无 / 或首位斜杠时 vendor 段缺省归 default(与存储行口径一致)
+export const splitRequestSegments = (model) => splitRuleSegments(model) ?? [PROVIDER_UNSET, model]
+
+// 段级比对:规则段为通配或与请求段相等;两段全过才成立,通配段按各自档位计权
+const matchTier = (ruleSegments, requestSegments) => {
+  const [ruleVendor, ruleModel] = ruleSegments
+  const [requestVendor, requestModel] = requestSegments
+  if (ruleVendor !== MODEL_WILDCARD && ruleVendor !== requestVendor) return null
+  if (ruleModel !== MODEL_WILDCARD && ruleModel !== requestModel) return null
+  return (ruleVendor === MODEL_WILDCARD ? VENDOR_WILDCARD_TIER : 0)
+    + (ruleModel === MODEL_WILDCARD ? MODEL_WILDCARD_TIER : 0)
 }
 
 const toLocalDate = (timestamp) => {
@@ -92,12 +117,25 @@ const toLocalDate = (timestamp) => {
   return Number.isNaN(date.getTime()) ? null : date
 }
 
-// 精确子集按数组序取首个命中;无精确子集或全不命中回落 '*' 子集;仍无命中为 null(调用方计 unpriced)
+// 匹配链:全名 > 模型名(vendor 通配)> 供应商(model 通配)> '*/*' 全通;
+// 档位最小者胜,同档按数组序取首个;高档条件不满足自然落低档;无命中为 null(调用方计 unpriced)
 export const matchPrice = (rules, model, timestamp) => {
   const date = toLocalDate(timestamp)
   if (!Array.isArray(rules) || !date || typeof model !== 'string') return null
-  return firstMatchingPrice(rules, date, (rule) => rule.model === model)
-    ?? firstMatchingPrice(rules, date, (rule) => rule.model === MODEL_WILDCARD)
+  const requestSegments = splitRequestSegments(model)
+  let bestTier = Infinity
+  let bestPrice = null
+  for (const rule of rules) {
+    if (!isRuleShaped(rule)) continue
+    const ruleSegments = splitRuleSegments(rule.model)
+    if (!ruleSegments) continue
+    const tier = matchTier(ruleSegments, requestSegments)
+    if (tier === null || tier >= bestTier) continue
+    if (!rule.conditions.every((condition) => conditionMatches(condition, date))) continue
+    bestTier = tier
+    bestPrice = rule.price
+  }
+  return bestPrice
 }
 
 const BUCKET_PRICE_KEYS = [

package/src/query.js

@@ -7,6 +7,7 @@ export const MAX_SLOTS = 2000
 
 const PAD_WIDTH = 2
 const PERCENT_SCALE = 100
+const MS_PER_SECOND = 1000
 
 const GRANULARITY_DAILY = 'D'
 const GRANULARITY_HOURLY = 'H'
@@ -115,8 +116,18 @@ export function aggregateRange(rows, g, from, to) {
     slot.byModel[row.model] = (slot.byModel[row.model] ?? 0) + tokens
     slot.byProvider[row.provider] = (slot.byProvider[row.provider] ?? 0) + tokens
     const modelTotal = modelTotals.get(row.model)
-    if (modelTotal) modelTotal.tokens += tokens
-    else modelTotals.set(row.model, { provider: row.provider, tokens })
+    if (modelTotal) {
+      modelTotal.tokens += tokens
+      modelTotal.speedDurationMs += row.durationMs ?? 0
+      modelTotal.speedOutputTokens += row.durationMs ? row.outputTokens : 0
+    } else {
+      modelTotals.set(row.model, {
+        provider: row.provider,
+        tokens,
+        speedDurationMs: row.durationMs ?? 0,
+        speedOutputTokens: row.durationMs ? row.outputTokens : 0,
+      })
+    }
     providerTotals.set(row.provider, (providerTotals.get(row.provider) ?? 0) + tokens)
   }
   const totals = { tokens: 0, requests: 0, turns: 0, cacheHit: 0, cacheMiss: 0 }
@@ -127,8 +138,16 @@ export function aggregateRange(rows, g, from, to) {
     totals.cacheHit += slot.cacheHit
     totals.cacheMiss += slot.cacheMiss
   }
+  // speed = 配对口径的输出 token ÷ 模型时长秒;仅时长>0 的行计入分子分母,
+  // 存量旧格式行只进 tokens 不进分母,无时长数据条目不挂 speed 字段
   const models = [...modelTotals.entries()]
-    .map(([model, agg]) => ({ model, provider: agg.provider, tokens: agg.tokens, percent: percentOf(agg.tokens, totals.tokens) }))
+    .map(([model, agg]) => ({
+      model,
+      provider: agg.provider,
+      tokens: agg.tokens,
+      percent: percentOf(agg.tokens, totals.tokens),
+      ...(agg.speedDurationMs > 0 ? { speed: agg.speedOutputTokens / (agg.speedDurationMs / MS_PER_SECOND) } : {}),
+    }))
     .sort((a, b) => b.tokens - a.tokens)
   const providers = [...providerTotals.entries()]
     .map(([provider, tokens]) => ({ provider, tokens, percent: percentOf(tokens, totals.tokens) }))

package/src/routes.js

@@ -7,7 +7,7 @@
 import { z } from 'zod'
 
 import { aggregateRange, attachCosts } from './query.js'
-import { CURRENCIES, CONDITION_KINDS, UNIT_PER_MILLION } from './pricing.js'
+import { CURRENCIES, CONDITION_KINDS, UNIT_PER_MILLION, isTwoSegmentModel } from './pricing.js'
 import {
   GRANULARITY_DAILY,
   GRANULARITY_HOURLY,
@@ -75,7 +75,8 @@ const conditionSchema = z.union(
 
 const pricingRulesSchema = z.array(
   z.object({
-    model: z.string(),
+    // 模型键强制两段式 vendor/model(段可通配),单段旧形态提交即拒
+    model: z.string().refine(isTwoSegmentModel),
     unit: z.literal(UNIT_PER_MILLION).optional(),
     currency: z.enum(CURRENCIES).nullable(),
     price: z.object({

package/src/store.js

@@ -1,28 +1,33 @@
 // 用量统计存储:usage_stats 域,单表 buckets,行键 <粒度>|<桶串>|<provider>|<model>。
-// 写入走 update 的原子读改写,缺键时 put 种子后重试一次;同一样本三粒度三行
-// 全部尝试后聚合上抛,单粒度失败不造成其余粒度缺失。游标读写全部串行在
-// 同一条 promise 链上,防 global 整值覆写的 lost update。进程级单例挂
-// globalThis,防 HMR 热重载后重复开域。
+// single 布局每次持久化写都全量重发布 unit 文档,故写入侧做合并(write-behind):
+// record 同步累加进内存 pending,按周期 flush 批量落盘,同桶多样本折叠为一次
+// update;flush 失败的行留在 pending 下轮重试,错误经 onFlushError 上抛。
+// 游标读写与 flush 全部串行在同一条 promise 链上,防 lost update。进程级单例
+// 挂 globalThis,防 HMR 热重载后重复开域。
 
 import { defineDomain, domainTable } from '@deepseek-ai/dsh-storage-domain'
 import { z } from 'zod'
 
+import { PROVIDER_UNSET, splitRequestSegments } from './pricing.js'
+
 export const GRANULARITY_DAILY = 'D'
 export const GRANULARITY_HOURLY = 'H'
 export const GRANULARITY_MINUTE = 'M'
 
-export const PROVIDER_DEFAULT = 'default'
 export const MODEL_TURNS = '(turns)'
 export const MODEL_UNKNOWN = '(unknown)'
 
-export const DEFAULT_MINUTE_RETENTION_DAYS = 2
+export const DEFAULT_MINUTE_RETENTION_DAYS = 7
 
 // 分钟桶对齐粒度(分钟);小时/天桶不受影响
 export const MINUTE_BUCKET_SPAN_MINUTES = 10
 
-// 保留上限:小时桶固定 15 天,分钟桶可配置但最大 2 天(48h)
+// 保留上限:小时桶固定 15 天,分钟桶可配置但最大 7 天(与分钟视图选择上限一致)
 export const HOUR_RETENTION_DAYS = 15
-export const MINUTE_RETENTION_MAX_DAYS = 2
+export const MINUTE_RETENTION_MAX_DAYS = 7
+
+// 写合并周期:pending 样本最长延迟该时长落盘;统计可由会话重扫重建,容忍窗口内丢失
+export const FLUSH_INTERVAL_MS = 2000
 
 const DAY_MS = 24 * 60 * 60 * 1000
 const PAD_WIDTH = 2
@@ -64,9 +69,9 @@ export const GRANULARITIES = [
   [GRANULARITY_MINUTE, minuteKey],
 ]
 
+// vendor 段推导与定价匹配同源:首个 / 前段,无 / 或首位斜杠归 default
 export function providerOf(modelRef) {
-  const slash = modelRef.indexOf('/')
-  return slash > 0 ? modelRef.slice(0, slash) : PROVIDER_DEFAULT
+  return splitRequestSegments(modelRef)[0]
 }
 
 export const usageRowSchema = z.object({
@@ -77,6 +82,8 @@ export const usageRowSchema = z.object({
   outputTokens: z.number(),
   cacheReadTokens: z.number(),
   cacheWriteTokens: z.number(),
+  // 模型时长累计(毫秒):optional 兼容存量记录(域 open 逐记录 parse)
+  durationMs: z.number().optional(),
   requests: z.number(),
   turns: z.number(),
   lastSeen: z.number(),
@@ -110,12 +117,47 @@ function emptyRow(bucket, provider, model, nowMs) {
     outputTokens: 0,
     cacheReadTokens: 0,
     cacheWriteTokens: 0,
+    durationMs: 0,
     requests: 0,
     turns: 0,
     lastSeen: nowMs,
   }
 }
 
+// 样本折叠为计数增量:turn/request 只计次,token 样本累加四类桶
+function deltaOf(sample, nowMs) {
+  const delta = emptyRow('', '', '', nowMs)
+  delete delta.bucket
+  delete delta.provider
+  delete delta.model
+  if (sample.turn) delta.turns = 1
+  else if (sample.request) delta.requests = 1
+  else {
+    delta.inputTokens = sample.inputTokens
+    delta.outputTokens = sample.outputTokens
+    delta.cacheReadTokens = sample.cacheReadTokens
+    delta.cacheWriteTokens = sample.cacheWriteTokens
+    delta.durationMs = sample.durationMs ?? 0
+  }
+  return delta
+}
+
+// 增量累加:行与 pending 条目同构,恒等字段取 base,计数逐项相加,时刻取较新
+function addDelta(base, delta) {
+  return {
+    ...base,
+    inputTokens: base.inputTokens + delta.inputTokens,
+    outputTokens: base.outputTokens + delta.outputTokens,
+    cacheReadTokens: base.cacheReadTokens + delta.cacheReadTokens,
+    cacheWriteTokens: base.cacheWriteTokens + delta.cacheWriteTokens,
+    // base 侧 ?? 0 容存量旧格式行(缺字段);delta 侧经 deltaOf 恒为数值
+    durationMs: (base.durationMs ?? 0) + delta.durationMs,
+    requests: base.requests + delta.requests,
+    turns: base.turns + delta.turns,
+    lastSeen: Math.max(base.lastSeen, delta.lastSeen),
+  }
+}
+
 function isMissingRecord(err) {
   return err instanceof Error && MISSING_RECORD_PATTERN.test(err.message)
 }
@@ -124,11 +166,16 @@ export class UsageStore {
   constructor(facility, options = {}) {
     this.now = options.now ?? Date.now
     this.retentionDays = options.retentionDays ?? (() => DEFAULT_MINUTE_RETENTION_DAYS)
+    this.flushIntervalMs = options.flushIntervalMs ?? FLUSH_INTERVAL_MS
+    // flush 行级失败上抛缝:采集器注入后接入扫描异常日志
+    this.onFlushError = options.onFlushError
     this.table = null
     this.domain = null
     this.openError = undefined
     this.lastPruneDay = ''
     this.markChain = Promise.resolve()
+    this.pending = new Map()
+    this.flushTimer = undefined
     // ready 永远 resolve:打开失败转降级,操作按调用失败,逃逸拒绝会拖垮宿主
     this.ready = this.initialize(facility).catch((err) => {
       this.openError = err
@@ -173,16 +220,73 @@ export class UsageStore {
     return this.readCursor() ?? {}
   }
 
+  // 同步合并进 pending,不等待持久化;崩溃丢失窗口 = flush 周期
   async record(sample) {
     await this.ready
-    const table = this.requireTable()
-    await this.pruneOncePerDay()
+    this.requireTable()
     const nowMs = this.now()
-    const outcomes = await Promise.allSettled(
-      GRANULARITIES.map(([g, bucketOf]) => this.recordRow(table, g, bucketOf(sample.time), sample, nowMs)),
-    )
-    const failures = outcomes.flatMap((outcome) => (outcome.status === 'rejected' ? [outcome.reason] : []))
-    if (failures.length > 0) throw new AggregateError(failures, 'usage store record failed')
+    const model = sample.turn ? MODEL_TURNS : sample.model ? sample.model : MODEL_UNKNOWN
+    const provider = sample.turn ? PROVIDER_UNSET : providerOf(model)
+    const delta = deltaOf(sample, nowMs)
+    for (const [g, bucketOf] of GRANULARITIES) {
+      const bucket = bucketOf(sample.time)
+      const entry = { ...delta, bucket, provider, model }
+      const existing = this.pending.get(rowKey(g, bucket, provider, model))
+      this.pending.set(rowKey(g, bucket, provider, model), existing ? addDelta(existing, entry) : entry)
+    }
+    this.scheduleFlush()
+  }
+
+  scheduleFlush() {
+    if (this.flushTimer !== undefined) return
+    this.flushTimer = setTimeout(() => {
+      this.flushTimer = undefined
+      void this.flushNow()
+    }, this.flushIntervalMs)
+  }
+
+  // pending 批量落盘:每脏行一次原子读改写,失败的行并回 pending 下轮重试,
+  // 错误聚合后经 onFlushError 上抛;与游标写同链串行
+  flushNow() {
+    const run = this.markChain.then(async () => {
+      await this.ready
+      if (this.pending.size === 0) return
+      try {
+        await this.flushBatch()
+      } catch (err) {
+        this.onFlushError?.(err)
+      }
+    })
+    this.markChain = run.then(() => {}, () => {})
+    return run
+  }
+
+  async flushBatch() {
+    await this.pruneOncePerDay()
+    const table = this.requireTable()
+    const batch = this.pending
+    this.pending = new Map()
+    const outcomes = await Promise.allSettled([...batch].map(([key, delta]) => this.applyDelta(table, key, delta)))
+    const failures = outcomes.flatMap((outcome, index) => {
+      if (outcome.status !== 'rejected') return []
+      const key = [...batch.keys()][index]
+      const [entryKey, entry] = [key, batch.get(key)]
+      const existing = this.pending.get(entryKey)
+      this.pending.set(entryKey, existing ? addDelta(existing, entry) : entry)
+      return [outcome.reason]
+    })
+    if (failures.length > 0) throw new AggregateError(failures, 'usage store flush failed')
+  }
+
+  async applyDelta(table, key, delta) {
+    const apply = (current) => addDelta(current ?? emptyRow(delta.bucket, delta.provider, delta.model, delta.lastSeen), delta)
+    try {
+      await table.update(key, apply)
+    } catch (err) {
+      if (!isMissingRecord(err)) throw err
+      await table.put(key, emptyRow(delta.bucket, delta.provider, delta.model, delta.lastSeen))
+      await table.update(key, apply)
+    }
   }
 
   async pruneOncePerDay() {
@@ -220,33 +324,8 @@ export class UsageStore {
     }
   }
 
-  async recordRow(table, g, bucket, sample, nowMs) {
-    const model = sample.turn ? MODEL_TURNS : sample.model ? sample.model : MODEL_UNKNOWN
-    const provider = sample.turn ? PROVIDER_DEFAULT : providerOf(model)
-    const key = rowKey(g, bucket, provider, model)
-    const apply = (current) => {
-      const base = current ?? emptyRow(bucket, provider, model, nowMs)
-      if (sample.turn) return { ...base, turns: base.turns + 1, lastSeen: nowMs }
-      if (sample.request) return { ...base, requests: base.requests + 1, lastSeen: nowMs }
-      return {
-        ...base,
-        inputTokens: base.inputTokens + sample.inputTokens,
-        outputTokens: base.outputTokens + sample.outputTokens,
-        cacheReadTokens: base.cacheReadTokens + sample.cacheReadTokens,
-        cacheWriteTokens: base.cacheWriteTokens + sample.cacheWriteTokens,
-        lastSeen: nowMs,
-      }
-    }
-    try {
-      await table.update(key, apply)
-    } catch (err) {
-      if (!isMissingRecord(err)) throw err
-      await table.put(key, emptyRow(bucket, provider, model, nowMs))
-      await table.update(key, apply)
-    }
-  }
-
   async rangeRows(g, from, to) {
+    await this.flushNow()
     await this.ready
     const table = this.requireTable()
     const prefix = `${g}|`
@@ -295,6 +374,7 @@ export class UsageStore {
 
   reset(boundaries) {
     return this.enqueueGlobalWrite(async () => {
+      await this.flushBatch()
       const table = this.requireTable()
       for (const key of [...table.keys()]) await table.delete(key)
       const liveFirstSeq = {}

package/test/client-eval.mjs

@@ -0,0 +1,23 @@
+// client.js 书挡契约:首行 IIFE 开、末行 IIFE 闭;求值前剥壳得可整源求值的函数体。
+// 供整源求值类测试统一取数,形态由 client-scope.test.mjs 守卫。
+import { readFileSync } from 'node:fs'
+import { fileURLToPath } from 'node:url'
+import { dirname, join } from 'node:path'
+
+const IIFE_OPEN = '(() => {'
+const IIFE_CLOSE = '})()'
+
+export const CLIENT_SOURCE = readFileSync(join(dirname(fileURLToPath(import.meta.url)), '..', 'src', 'client.js'), 'utf8')
+
+const source = CLIENT_SOURCE.trimEnd()
+if (!source.startsWith(IIFE_OPEN) || !source.endsWith(IIFE_CLOSE)) {
+  throw new Error(`client.js 书挡契约破坏:应以 ${IIFE_OPEN} 开、${IIFE_CLOSE} 闭`)
+}
+
+export const CLIENT_BODY = source.slice(IIFE_OPEN.length, -IIFE_CLOSE.length).trim()
+
+export const DECLARATION_NAMES = [
+  ...new Set(
+    [...CLIENT_BODY.matchAll(/^(?:const|function|let) ([A-Za-z_$][\w$]*)/gm)].map((match) => match[1])
+  ),
+]

package/test/client-scope.test.mjs

@@ -0,0 +1,60 @@
+// client.js 求值形态守卫:宿主以经典 script 整源求值,顶层词法声明落页面全局词法环境,
+// 跨 bundle 同名即整脚本 SyntaxError 拒载;整文件 IIFE 书挡保证顶层零词法声明。
+// Given/When/Then 场景内嵌于用例描述;vm.runInContext 与浏览器经典 script 同语义(全局词法环境跨脚本共享)。
+import { test } from 'node:test'
+import assert from 'node:assert/strict'
+import { readFileSync } from 'node:fs'
+import { fileURLToPath } from 'node:url'
+import { dirname, join } from 'node:path'
+import vm from 'node:vm'
+
+const CLIENT_SOURCE = readFileSync(join(dirname(fileURLToPath(import.meta.url)), '..', 'src', 'client.js'), 'utf8').trimEnd()
+const DECLARATION_NAMES = [
+  ...new Set(
+    [...CLIENT_SOURCE.matchAll(/^(?:const|let|var|class|(?:async )?function\*?) ([A-Za-z_$][\w$]*)/gm)].map((match) => match[1])
+  ),
+]
+const BUNDLE_ID = '@mzzsfy/dsh-usage-dash'
+
+test('Given 同 context 已有外部 CHART_PAD 声明(宿主经典 script 全局词法环境), When 整源求值 client.js, Then 双源共存不拒载且外部声明原值不变', () => {
+  const ctx = vm.createContext({})
+  vm.runInContext('const CHART_PAD = 1', ctx)
+  vm.runInContext(CLIENT_SOURCE, ctx)
+  assert.equal(vm.runInContext('CHART_PAD', ctx), 1)
+})
+
+test('Given client.js 已整源求值, When 同 context 再声明外部 CHART_PAD, Then 双源共存不拒载', () => {
+  const ctx = vm.createContext({})
+  vm.runInContext(CLIENT_SOURCE, ctx)
+  vm.runInContext('const CHART_PAD = 1', ctx)
+})
+
+test('Given client.js 整源求值完成, When 逐名以 const 重声明探针行首声明名, Then 全局词法环境零泄漏', () => {
+  const ctx = vm.createContext({})
+  vm.runInContext(CLIENT_SOURCE, ctx)
+  const leaked = DECLARATION_NAMES.filter((name) => {
+    try {
+      vm.runInContext(`const ${name} = null`, ctx)
+      return false
+    } catch {
+      return true
+    }
+  })
+  assert.deepEqual(leaked, [])
+})
+
+test('Given 宿主 loader 就绪, When 整源求值 client.js, Then 自注册照常发生且 id 不变', () => {
+  const registrations = []
+  const ctx = vm.createContext({ window: { __ModuleLoader__: { load: (registration) => registrations.push(registration) } } })
+  vm.runInContext(CLIENT_SOURCE, ctx)
+  assert.equal(registrations.length, 1)
+  assert.equal(registrations[0].id, BUNDLE_ID)
+  assert.equal(typeof registrations[0].factory, 'function')
+})
+
+test('Given 书挡契约, When 校验首末行, Then 首行 IIFE 开、末行 IIFE 闭且声明收集非空', () => {
+  const lines = CLIENT_SOURCE.split('\n')
+  assert.equal(lines[0], '(() => {')
+  assert.equal(lines[lines.length - 1], '})()')
+  assert.ok(DECLARATION_NAMES.length > 0)
+})