@mzzsfy/dsh-usage-dash 0.10.4 → 0.10.5

package/README.md

@@ -27,7 +27,7 @@
 
 规则存于设置存储域,经 `GET/POST /api/usage-dash/pricing` 读写(响应含单调 revision);设置面板编辑器为常规入口。单页内价格请求合并为一个在途请求,缓存有效期内复用;保存成功会同步更新已挂载底栏/费用芯片,并重取面板日范围、热力图及当前时/分数据。迟到的低 revision 不覆盖新价格,其他编辑器未保存草稿保持独立;价格不存本机持久缓存。
 
-规则形态:`{ model, currency, price: { input, output, cacheRead, cacheWrite }, conditions }`,单价单位固定「每百万 token」。货币为编辑器级全局设置:「定价规则」标题右侧切换,仅 ¥/$ 两档(无「空」档),打开编辑器即按首个非空货币归一显示(无非空回落 ¥),切换或保存后整表统一;wire 形态不变(仍为逐规则字段),存量空货币规则经编辑器保存后归一。费用显示为全局价格定位:汇总卡/趋势悬浮/模型列表/底栏费用项/回合费用芯片的货币符号统一取规则表首个非空货币(数值仍按命中规则单价计算),切换并保存后全部显示点随之变更。
+规则形态:`{ model, currency, price: { input, output, cacheRead, cacheWrite }, conditions }`,单价单位固定「每百万 token」。货币为编辑器级全局设置:「定价规则」标题右侧切换,仅 ¥/$ 两档(无「空」档),打开编辑器即按首个非空货币归一显示(无非空回落 ¥),切换或保存后整表统一;wire 形态不变(仍为逐规则字段),存量空货币规则经编辑器保存后归一。**服务端单币约束**:pricing POST 整表替换时非空 currency 全表必须一致,混币提交 400 拒绝——费用聚合按数值直接相加,混币相加无意义。费用显示为全局价格定位:汇总卡/趋势悬浮/模型列表/底栏费用项/回合费用芯片的货币符号统一取规则表首个非空货币(数值仍按命中规则单价计算),切换并保存后全部显示点随之变更。**计价时点口径**:时间条件按「估算时点」匹配当前规则表——面板聚合以小时桶时点,回合费用芯片以回合结束事件被观测时刻(用量首达即冻结,重渲染不漂移);规则表变更后按当前规则重算历史为既定选择,不做价格版本化存储。
 
 - 模型匹配:`model` 为两段式 `vendor/model`(首个 `/` 分段,模型段允许含 `/`),两段各自可 `*` 通配;匹配链为 全名精确 > 模型名精确(`*/model`,跨供应商同模型名同价)> 供应商精确(`vendor/*`,同供应商多模型同价)> `*/*` 全通,档位相同按数组序取首个命中,高档条件不满足逐层落低档;全链无命中不计费用并计 unpriced。提交(编辑器保存与 pricing POST)强制两段式,单段旧形态(`*` 或裸名)不再合法
 - 同模型多规则(分时段定价):组内附加计费规则从上到下首个「条件全过」者生效,全不命中落组内默认价(无条件规则,恒兜底);附加规则卡带 ↑/↓ 调序。注意同一模型的多条规则请使用相同的模型键写法——不同写法(如 `*/model` 与 `vendor/model`)分属不同档位,按档位优先级而非数组序取胜

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@mzzsfy/dsh-usage-dash",
   "description": "用量统计面板:天/小时/分钟三粒度 token 与请求统计,26 周活跃热力图、缓存命中率/生成速度/首 token 延迟曲线、模型占比与四桶明细,会话底栏官方数据后追加增强项与官方动作行回合费用芯片,多条件分时段定价规则与费用估算,en/zh 双语;复刻自 github.com/HaoyueQin/dsh-usage-statistics-panel,感谢原作者 HaoyueQin",
-  "version": "0.10.4",
+  "version": "0.10.5",
   "type": "module",
   "main": "src/index.js",
   "exports": {

package/src/client.js

@@ -2701,8 +2701,13 @@ if (typeof window !== 'undefined' && window.__ModuleLoader__) {
       useEffect(() => statsLineState.subscribe(() => setPrefs(statsLineState.get())), [])
       const { rules: pricingRules } = usePricing()
       const matched = usageSourceBuckets(usageSource)
-      const price = matched && prefs.costDisplay && pricingRules !== null
-        ? matchPrice(pricingRules, turnModelOf(matched), new Date())
+      // 计价时点 = 回合结束事件被观测的时刻(F15 决策:统一用当时价格、按回合
+      // 事件时点匹配当前规则表)。官方 tokenUsage 无事件时间戳,以用量首次到
+      // 达的观测时刻冻结:后续规则重渲染不再漂移,同一回合计价时点恒定
+      const observedAtRef = useRef(null)
+      if (matched && observedAtRef.current === null) observedAtRef.current = Date.now()
+      const price = matched && prefs.costDisplay && pricingRules !== null && observedAtRef.current !== null
+        ? matchPrice(pricingRules, turnModelOf(matched), new Date(observedAtRef.current))
         : null
       // 0 元(全零价/全零桶)与价未命中同不渲染,无占位符
       const cost = matched && price ? turnCostAmountOf(matched, price) : null
@@ -3201,6 +3206,9 @@ if (typeof window !== 'undefined' && window.__ModuleLoader__) {
       const heatGenerationRef = useRef(0)
       const panelRef = useRef(null)
       const [heatDays, setHeatDays] = useState(null)
+      // 热力图重取信号(F23):手动刷新/回扫完成即 bump,独立请求随之重取
+      const [heatFetchTick, setHeatFetchTick] = useState(0)
+      const bumpHeatFetch = () => setHeatFetchTick((tick) => tick + 1)
       // 费用展示货币来源:价格规则异步首帧未回时空串即不带符号
       const { rules: pricingRules, tick: pricingTick } = usePricing()
 
@@ -3226,7 +3234,7 @@ if (typeof window !== 'undefined' && window.__ModuleLoader__) {
           }))
         })
         return () => { heatGenerationRef.current++ }
-      }, [pricingTick])
+      }, [pricingTick, heatFetchTick])
 
       const load = useCallback(async () => {
         const request = range === 'custom'
@@ -3305,6 +3313,9 @@ if (typeof window !== 'undefined' && window.__ModuleLoader__) {
 
       const refresh = () => {
         setError('')
+        // 手动刷新同触热力图重取(F23):重建后热力图口径随日桶更新,
+        // 独立请求此前只随挂载/价格变更重取,重建产物不进热力图
+        bumpHeatFetch()
         if (view === 'day') load()
         else refreshPoints()
       }
@@ -3335,9 +3346,18 @@ if (typeof window !== 'undefined' && window.__ModuleLoader__) {
               baseDone = value.done
               scheduleRefresh()
             }
+            wasRunning = true
             schedule(STATUS_POLL_FAST_MS)
+          } else if (wasRunning) {
+            // running→idle 转换补最终刷新(F23):reset 同步等回扫,响应时 running 已 false,
+            // done 增长分支永不触发——回扫产物的最终态靠此转换收尾(含热力图重取)
+            wasRunning = false
+            scheduleRefresh()
+            bumpHeatFetch()
+            schedule(STATUS_POLL_SLOW_MS)
           }
         }
+        let wasRunning = false
         tick()
         statusMachineRef.current = { restart: () => { baseDone = 0; schedule(STATUS_POLL_FAST_MS) } }
         return () => {

package/src/routes.js

@@ -73,20 +73,25 @@ const conditionSchema = z.union(
   CONDITION_KINDS.map((kind) => z.object({ kind: z.literal(kind), ...CONDITION_FIELD_SCHEMAS[kind] })),
 )
 
-const pricingRulesSchema = z.array(
-  z.object({
-    // 模型键强制两段式 vendor/model(段可通配),单段旧形态提交即拒
-    model: z.string().refine(isTwoSegmentModel),
-    unit: z.literal(UNIT_PER_MILLION).optional(),
-    currency: z.enum(CURRENCIES).nullable(),
-    price: z.object({
-      input: z.number().min(0),
-      output: z.number().min(0),
-      cacheRead: z.number().min(0),
-      cacheWrite: z.number().min(0),
-    }),
-    conditions: z.array(conditionSchema),
+const pricingRuleShape = z.object({
+  // 模型键强制两段式 vendor/model(段可通配),单段旧形态提交即拒
+  model: z.string().refine(isTwoSegmentModel),
+  unit: z.literal(UNIT_PER_MILLION).optional(),
+  currency: z.enum(CURRENCIES).nullable(),
+  price: z.object({
+    input: z.number().min(0),
+    output: z.number().min(0),
+    cacheRead: z.number().min(0),
+    cacheWrite: z.number().min(0),
   }),
+  conditions: z.array(conditionSchema),
+})
+
+const pricingRulesSchema = z.array(pricingRuleShape).refine(
+  // 表级单币约束(F15):定价聚合按数值直接相加,混币相加无意义;
+  // 非空币种全表必须同一种(null 视为未指定,不参与币种一致对账)
+  (rules) => new Set(rules.map((rule) => rule.currency).filter((c) => c !== null)).size <= 1,
+  { message: '定价表必须单币种:非空 currency 全表一致' },
 )
 
 // 桶串形态锚定 + 本地时区分量回读,回滚形(13 月/25 时/60 分)当场拒绝,

package/src/store.js

@@ -37,6 +37,7 @@ const TABLE_BUCKETS = 'buckets'
 const MISSING_RECORD_PATTERN = /no record .* to update/
 const MINUTE_KEY_PREFIX = `${GRANULARITY_MINUTE}|`
 const HOUR_KEY_PREFIX = `${GRANULARITY_HOURLY}|`
+const DAILY_KEY_PREFIX = `${GRANULARITY_DAILY}|`
 
 // 保留值归一:非法回落默认,超出上限截到上限;0(禁用)合法保留
 export function clampMinuteRetentionDays(days) {
@@ -70,6 +71,16 @@ export const GRANULARITIES = [
   [GRANULARITY_MINUTE, minuteKey],
 ]
 
+// 档保留资格(F14):样本桶 ≥ 该档 cutoff 即可写入。日档无上限恒写;
+// 小时档固定留存;分钟档走可配置天数(0 = 分钟档关闭,一律不写)
+function withinRetention(g, bucket, nowMs, minuteRetentionDays) {
+  if (g === GRANULARITY_DAILY) return true
+  if (g === GRANULARITY_HOURLY) return bucket >= hourKey(nowMs - HOUR_RETENTION_DAYS * DAY_MS)
+  const retention = clampMinuteRetentionDays(minuteRetentionDays)
+  if (retention === 0) return false
+  return bucket >= minuteKey(nowMs - retention * DAY_MS)
+}
+
 // vendor 段推导与定价匹配同源:首个 / 前段,无 / 或首位斜杠归 default
 export function providerOf(modelRef) {
   return splitRequestSegments(modelRef)[0]
@@ -259,7 +270,9 @@ export class UsageStore {
     return this.readCursor() ?? {}
   }
 
-  // 同步合并进 pending,不等待持久化;崩溃丢失窗口 = flush 周期
+  // 同步合并进 pending,不等待持久化;崩溃丢失窗口 = flush 周期。
+  // 入队按档保留资格过滤(F14):超出该档留存期的样本不写入——
+  // 写后即被 prune 删除是纯 IO 浪费;回扫历史导入经同一通道自动受控
   async record(sample) {
     await this.ready
     this.requireTable()
@@ -268,6 +281,7 @@ export class UsageStore {
     const provider = sample.turn ? PROVIDER_UNSET : providerOf(model)
     const delta = deltaOf(sample, nowMs)
     for (const [g, bucketOf] of GRANULARITIES) {
+      if (!withinRetention(g, bucketOf(sample.time), nowMs, this.retentionDays())) continue
       const bucket = bucketOf(sample.time)
       const entry = { ...delta, bucket, provider, model }
       const existing = this.pending.get(rowKey(g, bucket, provider, model))
@@ -310,6 +324,9 @@ export class UsageStore {
       if (outcome.status !== 'rejected') return []
       const key = [...batch.keys()][index]
       const [entryKey, entry] = [key, batch.get(key)]
+      // 重排前复核保留资格(F14):失败重试期间样本可能已滑出留存期,不再重排
+      const g = key.startsWith(DAILY_KEY_PREFIX) ? GRANULARITY_DAILY : key.startsWith(HOUR_KEY_PREFIX) ? GRANULARITY_HOURLY : GRANULARITY_MINUTE
+      if (!withinRetention(g, entry.bucket, this.now(), this.retentionDays())) return []
       const existing = this.pending.get(entryKey)
       this.pending.set(entryKey, existing ? addDelta(existing, entry) : entry)
       return [outcome.reason]

package/test/routes.test.mjs

@@ -453,6 +453,8 @@ test('pricing POST 非法规则拒绝 400 且不写入', async () => {
     { rules: [{ ...PRICING_RULE, conditions: [{ kind: 'unknown' }] }] },
     { rules: [{ ...PRICING_RULE, conditions: [{ kind: 'weekdays', days: [7] }] }] },
     { rules: [{ ...PRICING_RULE, currency: '€' }] },
+    // F15 表级单币:非空币种混用整表拒绝;null 与单币并存合法
+    { rules: [{ ...PRICING_RULE, currency: '¥' }, { ...PRICING_RULE, model: 'openai/gpt-x', currency: '$' }] },
   ]
   for (const payload of invalidPayloads) {
     const res = await invokeJson(routes, PATH_PRICING, { payload })

package/test/store.test.mjs

@@ -81,9 +81,13 @@ function fakeDomain({ failUpdate = () => null } = {}) {
   }
 }
 
+// F14 契约:record 按档保留资格过滤。夹具时钟固定在样本日次日,样本全部
+// 落在留存期内;超期丢弃语义由专项用例验证
+const FIXED_NOW = local(2026, 8, 3, 0, 0)
 const facilityOf = (domain, backupDomain) => ({
   open: async (definition) => (definition?.name === 'usage_stats_backup' ? (backupDomain ?? domain) : domain),
 })
+const makeStore = (domain, options = {}) => new UsageStore(facilityOf(domain), { now: () => FIXED_NOW, ...options })
 
 const tokenSample = (time, extra = {}) => ({
   time,
@@ -134,7 +138,7 @@ test('跨日跨时跨分边界:毫秒推进即换桶', () => {
 
 test('token 样本同刻落三粒度三行,行内无 g 字段', async () => {
   const domain = fakeDomain()
-  const store = new UsageStore(facilityOf(domain))
+  const store = makeStore(domain)
   await store.record(tokenSample(local(2026, 8, 2, 14, 37)))
   await store.flushNow()
   const keys = ['D|2026-08-02', 'H|2026-08-02T14', 'M|2026-08-02T14:30'].map(
@@ -156,7 +160,7 @@ test('token 样本同刻落三粒度三行,行内无 g 字段', async () => {
 
 test('turn 样本落合成行:provider default 与 model (turns)', async () => {
   const domain = fakeDomain()
-  const store = new UsageStore(facilityOf(domain))
+  const store = makeStore(domain)
   await store.record({ time: local(2026, 8, 2, 14, 37), turn: true })
   await store.flushNow()
   const seen = domain.rows.get('D|2026-08-02|default|(turns)')
@@ -167,7 +171,7 @@ test('turn 样本落合成行:provider default 与 model (turns)', async () => {
 
 test('request 样本只计请求数,无归因落 (unknown)', async () => {
   const domain = fakeDomain()
-  const store = new UsageStore(facilityOf(domain))
+  const store = makeStore(domain)
   await store.record({ time: local(2026, 8, 2, 14, 37), request: true, model: 'deepseek-chat' })
   await store.record({ time: local(2026, 8, 2, 14, 38), request: true })
   await store.flushNow()
@@ -182,7 +186,7 @@ test('request 样本只计请求数,无归因落 (unknown)', async () => {
 
 test('token 样本时长落三粒度累加,request 与 turn 行时长恒 0', async () => {
   const domain = fakeDomain()
-  const store = new UsageStore(facilityOf(domain))
+  const store = makeStore(domain)
   const at = local(2026, 8, 2, 14, 37)
   await store.record(tokenSample(at, { durationMs: 6500 }))
   await store.record(tokenSample(at + 1000, { durationMs: 2500 }))
@@ -204,7 +208,7 @@ test('token 样本时长落三粒度累加,request 与 turn 行时长恒 0', asy
 
 test('老行缺 durationMs 字段:增量求和不产 NaN', async () => {
   const domain = fakeDomain()
-  const store = new UsageStore(facilityOf(domain))
+  const store = makeStore(domain)
   const at = local(2026, 8, 2, 14, 37)
   const key = 'D|2026-08-02|deepseek|deepseek/deepseek-chat'
   await store.record(tokenSample(at))
@@ -221,7 +225,7 @@ test('老行缺 durationMs 字段:增量求和不产 NaN', async () => {
 
 test('decode 配对与首字样本落三粒度累加,timing 样本不重复计 token', async () => {
   const domain = fakeDomain()
-  const store = new UsageStore(facilityOf(domain))
+  const store = makeStore(domain)
   const at = local(2026, 8, 2, 14, 37)
   // chunk 先发 token 样本:只有 token 桶
   await store.record(tokenSample(at, { durationMs: undefined }))
@@ -245,7 +249,7 @@ test('decode 配对与首字样本落三粒度累加,timing 样本不重复计 t
 
 test('timing 缺失样本:decodeTokens 与 ttft 字段按零累计', async () => {
   const domain = fakeDomain()
-  const store = new UsageStore(facilityOf(domain))
+  const store = makeStore(domain)
   const at = local(2026, 8, 2, 14, 37)
   await store.record(tokenSample(at))
   await store.flushNow()
@@ -258,7 +262,7 @@ test('timing 缺失样本:decodeTokens 与 ttft 字段按零累计', async () =>
 
 test('老行缺 decode/ttft 字段:增量求和不产 NaN', async () => {
   const domain = fakeDomain()
-  const store = new UsageStore(facilityOf(domain))
+  const store = makeStore(domain)
   const at = local(2026, 8, 2, 14, 37)
   const key = 'D|2026-08-02|deepseek|deepseek/deepseek-chat'
   await store.record(tokenSample(at))
@@ -279,7 +283,7 @@ test('老行缺 decode/ttft 字段:增量求和不产 NaN', async () => {
 
 test('missing-record 首写竞态:put 种子后重试写入真值', async () => {
   const domain = fakeDomain()
-  const store = new UsageStore(facilityOf(domain))
+  const store = makeStore(domain)
   await store.record(tokenSample(local(2026, 8, 2, 14, 37)))
   await store.flushNow()
   assert.equal(domain.stats.puts, 3)
@@ -296,7 +300,7 @@ test('flush 中单粒度失败:错误经 onFlushError 上抛,失败行留 pendin
       return new Error('simulated hour failure')
     },
   })
-  const store = new UsageStore(facilityOf(domain))
+  const store = makeStore(domain)
   const errors = []
   store.onFlushError = (err) => errors.push(err)
   await store.readyPromise()
@@ -317,7 +321,7 @@ test('非 missing 错误不触发种子重试', async () => {
   const domain = fakeDomain({
     failUpdate: (candidate) => (candidate === key ? new Error('backend write failed') : null),
   })
-  const store = new UsageStore(facilityOf(domain))
+  const store = makeStore(domain)
   const errors = []
   store.onFlushError = (err) => errors.push(err)
   await store.readyPromise()
@@ -331,7 +335,7 @@ test('非 missing 错误不触发种子重试', async () => {
 
 test('rangeRows 按粒度前缀与桶串闭区间扫描', async () => {
   const domain = fakeDomain()
-  const store = new UsageStore(facilityOf(domain))
+  const store = makeStore(domain)
   const table = domain.table()
   await table.put('D|2026-07-31|a|m', rowOf('2026-07-31', 'a', 'm'))
   await table.put('D|2026-08-01|a|m', rowOf('2026-08-01', 'a', 'm'))
@@ -348,7 +352,7 @@ test('rangeRows 按粒度前缀与桶串闭区间扫描', async () => {
 
 test('pruneMinutes 按保留窗口清理分钟桶且不碰其他粒度', async () => {
   const domain = fakeDomain()
-  const store = new UsageStore(facilityOf(domain), { now: () => local(2026, 8, 10, 12, 0) })
+  const store = makeStore(domain, { now: () => local(2026, 8, 10, 12, 0) })
   const table = domain.table()
   await table.put('M|2026-08-08T11:00|a|m', rowOf('2026-08-08T11:00', 'a', 'm'))
   await table.put('M|2026-08-08T12:00|a|m', rowOf('2026-08-08T12:00', 'a', 'm'))
@@ -365,7 +369,7 @@ test('pruneMinutes 按保留窗口清理分钟桶且不碰其他粒度', async (
 
 test('保留窗口为 0 时分钟桶全部清理', async () => {
   const domain = fakeDomain()
-  const store = new UsageStore(facilityOf(domain), { now: () => local(2026, 8, 10, 12, 0) })
+  const store = makeStore(domain, { now: () => local(2026, 8, 10, 12, 0) })
   const table = domain.table()
   await table.put('M|2026-08-10T11:00|a|m', rowOf('2026-08-10T11:00', 'a', 'm'))
   await table.put('D|2026-08-10|a|m', rowOf('2026-08-10', 'a', 'm'))
@@ -376,7 +380,7 @@ test('保留窗口为 0 时分钟桶全部清理', async () => {
 
 test('分钟保留超上限时 clamp 到 7 天窗口', async () => {
   const domain = fakeDomain()
-  const store = new UsageStore(facilityOf(domain), { now: () => local(2026, 8, 10, 12, 0) })
+  const store = makeStore(domain, { now: () => local(2026, 8, 10, 12, 0) })
   const table = domain.table()
   // clamp 后窗口起点 = 08-03T12:00,7 天前的桶一律清理,即使注入 30 天
   await table.put('M|2026-08-01T00:00|a|m', rowOf('2026-08-01T00:00', 'a', 'm'))
@@ -388,7 +392,7 @@ test('分钟保留超上限时 clamp 到 7 天窗口', async () => {
 
 test('pruneHours 固定 15 天窗口清理小时桶且不碰其他粒度', async () => {
   const domain = fakeDomain()
-  const store = new UsageStore(facilityOf(domain), { now: () => local(2026, 8, 10, 12, 0) })
+  const store = makeStore(domain, { now: () => local(2026, 8, 10, 12, 0) })
   const table = domain.table()
   await table.put('H|2026-07-25T00:00|a|m', rowOf('2026-07-25T00:00', 'a', 'm'))
   await table.put('H|2026-07-26T12:00|a|m', rowOf('2026-07-26T12:00', 'a', 'm'))
@@ -404,7 +408,7 @@ test('pruneHours 固定 15 天窗口清理小时桶且不碰其他粒度', async
 test('每日本地日首次 flush 触发清理,同日后续 flush 不重复触发', async () => {
   let clock = local(2026, 8, 10, 12, 0)
   const domain = fakeDomain()
-  const store = new UsageStore(facilityOf(domain), { now: () => clock, retentionDays: () => 0 })
+  const store = makeStore(domain, { now: () => clock, retentionDays: () => 0 })
   const table = domain.table()
   await table.put('M|2026-08-01T00:00|a|m', rowOf('2026-08-01T00:00', 'a', 'm'))
   await store.record(tokenSample(local(2026, 8, 10, 12, 0)))
@@ -422,7 +426,7 @@ test('每日本地日首次 flush 触发清理,同日后续 flush 不重复触
 
 test('并发 markSeenSessions 不丢 id', async () => {
   const domain = fakeDomain()
-  const store = new UsageStore(facilityOf(domain))
+  const store = makeStore(domain)
   await Promise.all([
     store.markSeenSessions(['a']),
     store.markSeenSessions(['b']),
@@ -433,7 +437,7 @@ test('并发 markSeenSessions 不丢 id', async () => {
 
 test('游标链串行:reset 排在先前 markSeen 之后,行与游标一致重置', async () => {
   const domain = fakeDomain()
-  const store = new UsageStore(facilityOf(domain))
+  const store = makeStore(domain)
   const pending = store.markSeenSessions(['a'])
   await store.record(tokenSample(local(2026, 8, 2, 14, 37)))
   await store.reset(new Map([['live-a', 7]]))
@@ -444,7 +448,7 @@ test('游标链串行:reset 排在先前 markSeen 之后,行与游标一致重
 
 test('reset 不带边界时游标清空', async () => {
   const domain = fakeDomain()
-  const store = new UsageStore(facilityOf(domain))
+  const store = makeStore(domain)
   await store.markLiveSequences([['s', 5]])
   await store.reset()
   assert.deepEqual(domain.global.get(), { backfilledSessions: [], liveFirstSeq: {} })
@@ -452,7 +456,7 @@ test('reset 不带边界时游标清空', async () => {
 
 test('markLiveSequences 保留最小 seq 且无变化不写 global', async () => {
   const domain = fakeDomain()
-  const store = new UsageStore(facilityOf(domain))
+  const store = makeStore(domain)
   await store.markLiveSequences([['s', 5]])
   assert.deepEqual(await store.liveSequences(), new Map([['s', 5]]))
   await store.markLiveSequences([['s', 3], ['t', 9]])
@@ -474,7 +478,7 @@ test('游标写单次失败不断链', async () => {
     }
     return originalSet(value)
   }
-  const store = new UsageStore(facilityOf(domain))
+  const store = makeStore(domain)
   await assert.rejects(store.markSeenSessions(['a']))
   await store.markSeenSessions(['b'])
   assert.deepEqual([...(await store.seenSessions())].sort(), ['b'])
@@ -483,7 +487,7 @@ test('游标写单次失败不断链', async () => {
 test('启动时游标为空且已有行则清空待重建', async () => {
   const domain = fakeDomain()
   await domain.table().put('D|2026-08-02|a|m', rowOf('2026-08-02', 'a', 'm'))
-  const store = new UsageStore(facilityOf(domain))
+  const store = makeStore(domain)
   await store.readyPromise()
   assert.equal(domain.rows.size, 0)
 })
@@ -492,7 +496,7 @@ test('启动时游标非空则既有行保留', async () => {
   const domain = fakeDomain()
   await domain.table().put('D|2026-08-02|a|m', rowOf('2026-08-02', 'a', 'm'))
   await domain.global.set({ backfilledSessions: ['old'], liveFirstSeq: {} })
-  const store = new UsageStore(facilityOf(domain))
+  const store = makeStore(domain)
   await store.readyPromise()
   assert.equal(domain.rows.size, 1)
 })
@@ -500,7 +504,7 @@ test('启动时游标非空则既有行保留', async () => {
 test('reset 前自动快照,restore 整体回退到快照态', async () => {
   const domain = fakeDomain()
   const backup = fakeDomain()
-  const store = new UsageStore(facilityOf(domain, backup))
+  const store = new UsageStore(facilityOf(domain, backup), { now: () => FIXED_NOW })
   await store.record(tokenSample(local(2026, 8, 2, 14, 0)))
   await store.markSeenSessions(['s1', 's2'])
   assert.equal(store.backupInfo().available, false)
@@ -521,7 +525,7 @@ test('reset 前自动快照,restore 整体回退到快照态', async () => {
 test('restore 前先快照当前态:回退动作自身可再回退', async () => {
   const domain = fakeDomain()
   const backup = fakeDomain()
-  const store = new UsageStore(facilityOf(domain, backup))
+  const store = new UsageStore(facilityOf(domain, backup), { now: () => FIXED_NOW })
   await store.record(tokenSample(local(2026, 8, 2, 14, 0)))
   await store.reset()
   await store.record(tokenSample(local(2026, 8, 3, 14, 0), { inputTokens: 99 }))
@@ -544,7 +548,7 @@ test('备份域不可用:重建照常,backupInfo 标记不可用,restore 报错'
       return domain
     },
   }
-  const store = new UsageStore(facility)
+  const store = new UsageStore(facility, { now: () => FIXED_NOW })
   await store.record(tokenSample(local(2026, 8, 2, 14, 0)))
   await store.reset()
   assert.equal(domain.rows.size, 0)
@@ -631,7 +635,7 @@ for (const withCode of [true, false]) {
 test('UO1 Given old owner with seen cursor and pending tokens, When new generation opens, Then old owner flushes every bucket once', async () => {
   __resetSharedStoreForTests()
   const facility = facilityWithReserved()
-  const old = new UsageStore(facility)
+  const old = new UsageStore(facility, { now: () => FIXED_NOW })
   await old.readyPromise()
   await old.markSeenSessions(['s1'])
   await old.record(tokenSample(local(2026, 8, 2, 14, 37)))
@@ -681,7 +685,7 @@ test('get 缝在场但孤儿已不存在:维持降级,不逃逸', async () => {
 
 test('record 只入 pending 不产生持久化写,flushNow 后每脏行恰一次 update', async () => {
   const domain = fakeDomain()
-  const store = new UsageStore(facilityOf(domain))
+  const store = makeStore(domain)
   await store.readyPromise()
   await store.record(tokenSample(local(2026, 8, 2, 14, 37)))
   assert.equal(domain.rows.size, 0)
@@ -693,7 +697,7 @@ test('record 只入 pending 不产生持久化写,flushNow 后每脏行恰一次
 
 test('同桶多样本合并:pending 累加,一次 update 落全部计数', async () => {
   const domain = fakeDomain()
-  const store = new UsageStore(facilityOf(domain))
+  const store = makeStore(domain)
   await store.readyPromise()
   await store.record(tokenSample(local(2026, 8, 2, 14, 37)))
   await store.record(tokenSample(local(2026, 8, 2, 14, 38)))
@@ -706,7 +710,7 @@ test('同桶多样本合并:pending 累加,一次 update 落全部计数', async
 
 test('flush 周期自动落盘', async () => {
   const domain = fakeDomain()
-  const store = new UsageStore(facilityOf(domain), { flushIntervalMs: 5 })
+  const store = makeStore(domain, { flushIntervalMs: 5 })
   await store.readyPromise()
   await store.record(tokenSample(local(2026, 8, 2, 14, 37)))
   await new Promise((resolve) => setTimeout(resolve, 30))
@@ -715,7 +719,7 @@ test('flush 周期自动落盘', async () => {
 
 test('rangeRows 前自动 flush,读己之写', async () => {
   const domain = fakeDomain()
-  const store = new UsageStore(facilityOf(domain))
+  const store = makeStore(domain)
   await store.readyPromise()
   await store.record(tokenSample(local(2026, 8, 2, 14, 37)))
   const rows = await store.rangeRows('D', '2026-08-02', '2026-08-02')
@@ -725,7 +729,7 @@ test('rangeRows 前自动 flush,读己之写', async () => {
 
 test('reset 前 pending 先落盘再清表', async () => {
   const domain = fakeDomain()
-  const store = new UsageStore(facilityOf(domain))
+  const store = makeStore(domain)
   await store.readyPromise()
   await store.record(tokenSample(local(2026, 8, 2, 14, 37)))
   await store.reset(new Map())
@@ -738,3 +742,21 @@ test('降级态 record 仍按调用失败', async () => {
   await store.readyPromise()
   await assert.rejects(store.record(tokenSample(local(2026, 8, 2, 14, 37))), /usage store degraded/)
 })
+
+// ── F14: 入队保留资格过滤 ──────────────────────────────────────────────────
+test('F14: 超出档留存期的样本不入 pending 不落盘,回扫同通道受控', async () => {
+  const domain = fakeDomain()
+  // 时钟"今天" = 样本日次日 + 8 天:8/2 样本对分钟档(7 天)超期、小时档(15 天)与日档在期
+  const now = local(2026, 8, 10, 0, 0)
+  const store = new UsageStore(facilityOf(domain), { now: () => now })
+  await store.record(tokenSample(local(2026, 8, 2, 14, 37)))
+  await store.flushNow()
+  const prefixes = [...domain.rows.keys()].map((key) => key.split('|').slice(0, 2).join('|'))
+  assert.ok(!prefixes.some((p) => p.startsWith('M|')), `分钟档超期不得落行: ${prefixes.join(',')}`)
+  assert.ok(prefixes.some((p) => p.startsWith('D|')), '日档无留存上限恒写入')
+  assert.ok(prefixes.some((p) => p.startsWith('H|')), '小时档 15 天内在期')
+  // 分钟档保留 0(关闭):分钟样本一律不入队
+  const offStore = new UsageStore(facilityOf(fakeDomain()), { now: () => local(2026, 8, 2, 14, 38), retentionDays: () => 0 })
+  await offStore.record(tokenSample(local(2026, 8, 2, 14, 37)))
+  assert.equal(offStore.pending.size, 2, '关闭分钟档后仅日/小时两行入队')
+})