Repository navigation
[PR] persist: wire debounce/max-delay knobs into session-order & prefix-affinity writers - #6066
Conversation
…ion-order and prefix-affinity snapshot writers (#6062) Both sidecar writers kept their own hardcoded 500ms/5s quiesce/max-delay windows while the main session writer honored persist.debounceMs all along (BILI_SNAP_DEBOUNCE_MS from the field report does not exist in the codebase at all). Under sustained traffic the scheduled delay is min(debounce, maxDelay - pendingSince), so the 5s max-delay CAP set the steady-state rewrite rate — making only the debounce tunable would have changed nothing for the reported scenario. - persistDebounceMs() now resolves in order-persist.ts and affinity-persist.ts - new persistMaxDelayMs() (BILI_PERSIST_MAX_DELAY_MS > persist.maxDelayMs > 5000); default equals the former hardcode, so zero behavior drift at defaults - regression tests pin both directions per writer: default cadence unchanged, larger debounce defers the write past the old 500ms point, small max-delay beats a huge debounce under 100ms churn
…tion recipe (#6062) - configuration.md en/zh: persist table row, section Type/Default/Description, env mapping + description rows for BILI_PERSIST_MAX_DELAY_MS - process.yaml: seed entry for persist.maxDelayMs (config-surface-guard) and mech line update - lifecycle.md env ledger row - new smartctl recipe in the persist section (OP #6062 \u00a76.3): diff NVMe SMART 'Data Units Written' around a run + idle re-read to separate background writes; note firmware counter units and that mtime/size scans miss page-level index.db/WAL churn
📦 Built Package ArtifactBranch: Latest build — install this exact versionnpm install -g billion-context@0.0.8866-pr.6066.f1d5d04This exact version is immutable and reproducible. The rolling Recent builds (commit → version)
Download artifact
tar xzf billion-context-pr6066.tgz
npm install -g packageInstall instructions are refreshed on each push. |
…uration.md en+zh (#6062) The persist Description implied the max-delay cap is honored by the main session writer. It is not: src/persist.ts scheduleSave uses a non-restarting debounce (later saves swap the builder but keep the first timer), so it fires within one debounce window and cannot starve, and it never calls persistMaxDelayMs(). Only the two snapshot writers (session-order / prefix-affinity) carry the cap. Reworded en + zh to match the code.
(ai: vllm-qwen/qwen3.8-27b) 查重: 不重复 — #6066 是 #6062 §6.2(把 persist debounce / max-delay 接成可配置旋钮)的唯一在途实现;检索 open PR,其余 5 个命中(#5076/#5915/#4861/#5084/#4046)都是无关的 persist 主题(export 解码、context estimate、handoff、preflight fold)。我没有另开分支/PR,只在同一个 PR 分支上加了一个文档修正 commit(下方第 5 点)。 Reviewing GitHub PR #6066(head
审中发现并已顺手修掉的一处缺陷(独立标注 commit): 结构化八问
判定与建议:代码与测试成立,scope 正确,默认零漂移。CI 现正跑在我推的新 head |
[bot] 🏷 (ai: vllm-qwen/qwen3.8-27b) CI auto-fix run (attempt 1/3): docs-sync fixed and verified green. What was broken:
Fix: ran the generator on the PR head; its output matched the CI failure diff byte-for-byte (same hunks, same blob hashes), so I committed the four regenerated files as Concurrent work handled: while CI was starting, commit Live verification (mirror cache, this run): head Disclosure: my first attempt at this reply was misposted into mirror thread #6066 (a different PR); I left a short disclosure comment there pointing back here. No action needed beyond ignoring/deleting that stray comment. 八问(中文结论)
判定:docs-sync 已绿并实测确认;当前 30 项检查零失败,仅剩 5 个长时 test 分片在跑。本次自动修复任务完成。 |
(ai: vllm-qwen/qwen3.8-27b) CI fix run — PR #6068, head now Verified live state first:
Local verification: both guard scripts pass on the fixed tree ( Total diff over the original head: 3 files, +7/−1 lines. No behavior change: a doc-map line, one 结构化八问
判定:CI 已全绿,可合并。 |
(ai: vllm-qwen/qwen3.8-27b) Stale event — no work needed. The reported |
[bot] 🏷 (ai: vllm-qwen/qwen3.8-27b) CI engineer final report — PR #6068, all checks green. (My earlier reports may not have landed — this one consolidates everything.) Both red gates on this PR are fixed on the branch, verified against live CI:
The branch then advanced past my fixes ( 结构化八问
判定:CI 全绿,可合并。 |
# Conflicts: # src/affinity-persist.ts # src/order-persist.ts
[bot] 🏷 (ai: vllm-qwen/qwen3.8-27b) CI auto-fix run (conflict wake, attempt 1/3): merge conflict resolved, pushed, mergeability verified live. What was broken: master moved ~20 merges ahead of the PR base ( How I resolved it: chose merge over rebase (no history rewrite, no force-push, safe against concurrent agents on the same branch):
Local verification on the final merged tree: Live verification (mirror cache, this run): head 八问(中文结论)
状态:冲突已解除并实测确认(mergeable_state 由 dirty 变为 blocked);新 head 上 CI 已启动、观察点 0 失败、9 个长时测试分片在跑;镜像缓存本轮后半段停止刷新,最终全绿结论待其刷新后确认——若后续有分片变红会触发下一次唤醒处理。 |
…ror number #6062 Every citation this PR added (source comments, test names, configuration.md en+zh, lifecycle.md env ledger, process.yaml seed + regenerated docs) points at GitHub issue #6062, which is the unrelated time-context role:user report. The 31-day QLC SSD field report with the requested knobs (§6.2) and the write-volume observation recipe (§6.3) is upstream issue #6058.
ranxianglei
left a comment
There was a problem hiding this comment.
(ai: vllm-qwen/qwen3.8-27b)
Verdict: APPROVE (posted as a COMMENT review — GitHub blocks approving a PR opened under the same account) — independent end-to-end review of the full diff at head b32638043 plus my fix commit 0813da64, verified against live master. Everything below was re-derived by me from the code; nothing is copied from earlier thread posts. (Heads-up: some CI reports in this thread describe a different PR's heads — 73f222e5…ac622f42, the egress-transforms work — and do not apply to this branch.)
Direction. The upstream field report — GitHub #6058, "Physical Write Volume on QLC SSD: 31-Day Field Test" (the "#6062" cited throughout this PR is the internal mirror number of that same report) — §6.2 asks exactly for this: the two sidecar snapshot writers kept local PERSIST_DEBOUNCE_MS = 500 / PERSIST_MAX_DELAY_MS = 5_000 with no env entry while the main session writer honors persist.debounceMs; the report's own override attempt (BILI_SNAP_DEBOUNCE_MS) was a no-op because that variable exists nowhere in the codebase. Reusing the existing persist.* family (env > file > default via tInt) instead of inventing the report's proposed name is the right call, and the PR correctly notes a debounce-only knob would not have fixed the reported scenario: with delay = min(debounce, maxDelay − pendingSince) and pendingSince set only when null (never reset on reschedule), sustained churn drives the budget to zero and the max-delay cap sets the steady-state rewrite period (~5s at default) — so both windows had to be wired. Out-of-scope carves are correct: N-day eviction would change #1724's deliberate permanence (human-gated); carrier migration is #5757.
Regression audit (touched paths vs pre-change behavior):
src/order-persist.ts/src/affinity-persist.ts: scheduling formula unchanged; the two consts are replaced by knob calls whose defaults equal the old literals ⇒ byte-identical cadence at defaults. One deliberate difference: values now resolve per call instead of once at module load — config hot-reload now affects these writers mid-run, consistent with how the main writer already treatspersist.debounceMs; cost is one page-cachedreadFileSync+ raw-text equality short-circuit per schedule (loadConfigFile()parse-once cache, src/config.ts:2635), negligible against an ~8 MB JSON stringify.- Main per-session writer
src/persist.ts: untouched — importspersistDebounceMsonly, neverpersistMaxDelayMs; its non-restarting debounce has no starvation cap, as documented. plugin-conversations.json's own 300ms debounce: deliberately untouched (avoids silently drifting a third cadence).- flush/hydrate/boot/unified-store paths, including master's #5753/#5757 kv dual-carrier logic merged into this branch: untouched.
No high-risk patterns: no threshold/timing/output-format drift at defaults, no fail-fast→swallow changes.
Code. Knob validation mirrors persistDebounceMs exactly (Number.isFinite(v) && v >= 0 ? v : 5_000); garbage/negative values fall back to the default rather than throwing. maxDelayMs=0 degrades to write-through (immediate write each schedule) — a sane escape hatch, not a bug. Old consts fully removed (grep-clean), comments updated to state why the cap dominates steady state.
Tests. Both directions pinned per writer (#3617 gate discipline): default-cadence negative (no write before the old 500ms point; lands well inside 2s); debounce positive+negative (debounce=1500 defers past the 700ms mark — fails on old code); max-delay positive (cap=400 beats debounce=5000 under 100ms churn within 1.5s — old code's first write lands at ~5s, so this pins exactly the half of the wiring the field report hit). Real-timer polling loops with ≥300ms margins rather than fixed-sleep asserts (Windows-flake precedent). Module-level pendingSince/timer isolation across cases holds: both flushOrderSkeletons() and flushPrefixAffinity() reset them (verified in source). Teeth confirmed by tracing the pre-change code path against each assertion.
Config surface & docs. New key reported per house rules (why the existing surface cannot express it, alternatives considered, compat story). Docs complete in en+zh: index row, section Type/Default/Description, env mapping + description rows, lifecycle ledger, seed + regenerated website artifacts; config-surface-guard green. The §6.3 physical-write-volume observation recipe (smartctl before/after delta + idle re-read + firmware-unit caveat) ships in both languages as requested.
Small finding fixed on the spot: all 21 citations added by this PR pointed at GitHub issue #6062 — which is the unrelated time-context role:user report. The QLC field report is upstream #6058. Corrected in source comments, test names, configuration.md en+zh, lifecycle.md, process.yaml seed, then regenerated docs via tools/gen-config-docs.mjs (output verified consistent, i18n parity ok). Pure reference correction — zero logic touched.
已顺手修:PR 内 21 处 issue 引用写错(#6062 是内部镜像号,上游真实报告是 #6058)——源码注释/测试名/docs en+zh/yaml seed 全部更正并重新生成文档 + commit 0813da6
结构化八问
- 是什么问题:31 天 QLC SSD 实测(上游 #6058)发现 session-order / prefix-affinity 两个边车快照写入器把去抖窗口和 max-delay 上限写死成本地常量、完全没有配置入口;持续流量下 5 秒上限主导稳态重写速率,用户只能改 dist。本 PR 把两个窗口接进配置系统。
- 什么原因导致的:主会话写入器一直走
persist.debounceMs,两个边车写入器却各自留了本地 const、从未读旋钮;且调度公式delay = min(debounce, maxDelay − pendingSince)(pendingSince 只在为空时设置、重排不重置),只放开 debounce 对实测场景无效——必须同时放开上限。 - 影响范围与严重程度:修复前 = 磨损敏感盘用户无法调快照重写频率(体验/perf 缺陷,不影响正确性);默认值下新旧行为完全一致,实际影响面限于主动配置这两个键的用户。
- 怎么修复的:复用既有
persist.*家族与tInt解析链(env > file > default),新增键persist.maxDelayMs(默认 5000 = 原硬编码),两个写入器的两处常量改调旋钮函数;N-day eviction(#1724 永久性的语义变更)与 kv 迁移(#5757)明确 out-of-scope。 - 是否有回归问题:逐项审过——两写入器公式不变且默认等于原常量 ⇒ 默认零漂移;主会话写入器未动(从不调用 maxDelay);plugin-conversations 的 300ms 刻意未动;flush/hydrate/boot/kv 双载体路径未动。无阈值/时序/输出格式漂移,无 fail-fast 变吞错。唯一有意变更:旋钮按调用解析而非模块加载时一次性取值(与主写入器行为一致,支持热重载;代价是每次调度一次页缓存 readFileSync,可忽略)。
- 是否破坏缓存:不涉及——不触及 KV/前缀缓存、重试、增量游标、去重键;两个文件本身是可重算缓存,默认写下时机不变。
- 是否改了设计方向:不涉及——纯可调性增强,架构/边界/数据流不变。
- 是否引入了新的配置:是——
persist.maxDelayMs(number,默认5000,envBILI_PERSIST_MAX_DELAY_MS,group process);未设 ⇒ 与原硬编码一致,无需迁移。(报告里想要的persist.debounceMs原本就存在。)
Verdict: APPROVE — direction matches the upstream report, zero regression surface at defaults, tests pinned in both directions with teeth, config surface properly declared and documented (en+zh), diff clean. One small citation error found and fixed on the spot (commit 0813da64). No kernel/ changes, no authorization gates. CI on the new head 0813da6490: 0 failed, 4 long-running test shards still in flight at last observation — merge when green.
[bot] 🏷 (ai: vllm-qwen/qwen3.8-27b) Review complete — verdict: APPROVE. Review posted on GitHub PR #6066: #6066 (review) What was done (all independent, re-derived from code — not copied from earlier thread posts):
Small finding fixed on the spot: all 21 citations added by this PR pointed at GitHub issue #6062 — which is the unrelated time-context role:user report. The QLC field report is upstream #6058. Corrected in source comments, test names, configuration.md en+zh, lifecycle.md, process.yaml seed, then regenerated docs via 已顺手修:PR 内 21 处 issue 引用写错(#6062 是内部镜像号,上游真实报告是 #6058)——源码注释/测试名/docs en+zh/yaml seed 全部更正并重新生成文档 + commit 0813da6 Note: the APPROVE was posted as a COMMENT review — GitHub rejects approve events on a PR opened under the same account, so the formal approval/merge stays with you. CI on the new head 结构化八问
判定:APPROVE,等 CI 转绿后由你合并。 |
What & why
Field report #6062 (31 days on a QLC SSD) measured sustained snapshot rewrites of
session-order.json/prefix-affinity.jsonand asks in §6.2 for configurable persist debounce/max-delay constants.Root cause found in triage:
persist.debounceMs(BILI_PERSIST_DEBOUNCE_MS) — but the two sidecar writers (src/order-persist.ts,src/affinity-persist.ts) each kept their own hardcodedconst PERSIST_DEBOUNCE_MS = 500; const PERSIST_MAX_DELAY_MS = 5_000and never read the knobs.BILI_SNAP_DEBOUNCE_MSused in the field report does not exist anywhere in the codebase — that override attempt was invalid for this direct reason.min(debounce, maxDelay − pendingSince): under sustained traffic the 5s max-delay CAP dominates, so making only the debounce tunable would not have changed anything for the reported scenario.Changes
persistDebounceMs()into both sidecar writers (replaces the local consts).persistMaxDelayMs():BILI_PERSIST_MAX_DELAY_MS > persist.maxDelayMs > 5000. Default equals the former hardcode ⇒ zero drift at defaults.tests/order-persist.test.ts; two cases added totests/affinity-persist.test.ts.process.yamlseed entry, lifecycle.md env ledger.Config surface
New key:
persist.maxDelayMs(number, default5000, envBILI_PERSIST_MAX_DELAY_MS, groupprocess).persist.debounceMscovers only the quiesce window; the max-delay budget was hardcoded in both sidecar writers, and because delay = min(debounce, maxDelay − pending), a debounce-only knob is ineffective under sustained traffic — exactly the reported scenario.persist.*family and its env > file > default resolution (tInt+filePersist()); no new section invented; deliberately did NOT create the report'sBILI_SNAP_DEBOUNCE_MS(absent from the codebase); deliberately leftplugin-conversations.json's own 300ms debounce untouched (wiring it here would silently drift its default cadence).config-surface-guardgreen).Behavior flag
No behavior change at defaults: old hardcoded 500ms / 5s → new knob defaults are the identical values. The only change is tunability.
Out of scope (stays in the #6062 / #5759 threads)
Verification
Local targeted runs:
tests/order-persist.test.ts+tests/affinity-persist.test.ts16/16 pass,config-surface-guardpass,tsc --noEmitclean. Full-suite verdict = CI on this head.Refs #6062 (addresses OP §6.2 + §6.3; §6.1 — prioritizing merge of #5757 — stays in the #5759 thread)