Skip to content

[PR] persist: wire debounce/max-delay knobs into session-order & prefix-affinity writers - #6066

Merged
ranxianglei merged 7 commits into
masterfrom
2026-11-10_persist-snapshot-write-knobs
Nov 10, 2026
Merged

ranxianglei merged 7 commits into
masterfrom
2026-11-10_persist-snapshot-write-knobs

Conversation

@ranxianglei

Copy link
Copy Markdown
Owner

What & why

Field report #6062 (31 days on a QLC SSD) measured sustained snapshot rewrites of session-order.json / prefix-affinity.json and asks in §6.2 for configurable persist debounce/max-delay constants.

Root cause found in triage:

  • The main session writer honors persist.debounceMs (BILI_PERSIST_DEBOUNCE_MS) — but the two sidecar writers (src/order-persist.ts, src/affinity-persist.ts) each kept their own hardcoded const PERSIST_DEBOUNCE_MS = 500; const PERSIST_MAX_DELAY_MS = 5_000 and never read the knobs.
  • The env var BILI_SNAP_DEBOUNCE_MS used in the field report does not exist anywhere in the codebase — that override attempt was invalid for this direct reason.
  • Scheduled delay = 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

  • Wire persistDebounceMs() into both sidecar writers (replaces the local consts).
  • New knob persistMaxDelayMs(): BILI_PERSIST_MAX_DELAY_MS > persist.maxDelayMs > 5000. Default equals the former hardcode ⇒ zero 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. New tests/order-persist.test.ts; two cases added to tests/affinity-persist.test.ts.
  • Docs sync: configuration.md en+zh (table row, section Type/Default/Description, env mapping + description rows), process.yaml seed entry, lifecycle.md env ledger.
  • OP §6.3 recipe ships in this PR (one issue ≤ one PR): smartctl-based physical write-volume observation under the persist section of configuration.md en+zh.

Config surface

New key: persist.maxDelayMs (number, default 5000, env BILI_PERSIST_MAX_DELAY_MS, group process).

  • Why the existing surface cannot express it: persist.debounceMs covers 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.
  • Existing mechanisms considered: reuses the existing persist.* family and its env > file > default resolution (tInt + filePersist()); no new section invented; deliberately did NOT create the report's BILI_SNAP_DEBOUNCE_MS (absent from the codebase); deliberately left plugin-conversations.json's own 300ms debounce untouched (wiring it here would silently drift its default cadence).
  • Compat/migration: new optional key; unset ⇒ 5000 = former hardcode ⇒ zero behavior change at defaults; nothing to migrate. Documented in configuration.md en/zh + process.yaml seed (config-surface-guard green).

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.ts 16/16 pass, config-surface-guard pass, tsc --noEmit clean. 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)

ci-check added 2 commits November 10, 2026 02:36
…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
@ranxianglei ranxianglei changed the title persist: wire debounce/max-delay knobs into session-order & prefix-affinity writers [PR] persist: wire debounce/max-delay knobs into session-order & prefix-affinity writers Nov 9, 2026
@github-actions

github-actions Bot commented Nov 9, 2026 •

Copy link
Copy Markdown
Contributor

📦 Built Package Artifact

Branch: 2026-11-10_persist-snapshot-write-knobs (0813da6)

Latest build — install this exact version

npm install -g billion-context@0.0.8866-pr.6066.f1d5d04

This exact version is immutable and reproducible. The rolling pr tag tracks the newest test build across all PRs.

Recent builds (commit → version)

commit version build
0813da6 billion-context@0.0.8866-pr.6066.f1d5d04 build
b326380 billion-context@0.0.8864-pr.6066.624241b build
abf9e4c billion-context@0.0.8855-pr.6066.b6c98e4 build
14a6d86 billion-context@0.0.8854-pr.6066.50c9210 build
dc0e0dd billion-context@0.0.8851-pr.6066.bbb4805 build

Download artifact

  1. Download the artifact from the Actions run
  2. Extract the tarball and install:
tar xzf billion-context-pr6066.tgz
npm install -g package

Install instructions are refreshed on each push.

ci-check added 2 commits November 10, 2026 02:50
…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.
@ranxianglei

Copy link
Copy Markdown
Owner Author

🤖 Powered by ework · qwen3.8-27b

(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 abf9e4c813,base master,mergeable;required checks 正跑在这个 head 上)。以下都是我独立做的,不是照抄 PR 描述:

  • 拉了 head 通读全量 diff + 周边代码。
  • scope 正确性:git grep 确认 persistMaxDelayMs() 只被 src/order-persist.ts 和 src/affinity-persist.ts 消费;src/ 里再无残留的 PERSIST_DEBOUNCE_MS / PERSIST_MAX_DELAY_MS 常量。主会话写入器 src/persist.ts 从不 import 它(见下方文档修正)。
  • 本地定向跑测(在 head 上):tests/order-persist.test.ts + tests/affinity-persist.test.ts → 16/16 pass。其中 12 个既有 affinity 用例全绿 = 无回归;新增用例有牙——实测耗时 561ms / 1546ms / 426ms 证明它们真的在等时序,不是恒真断言。
  • gate 双向钉死(Test Blind Spot Retrospective: Reinforcing Negative Assertion Discipline, Tightening Fake Upstream Strictness, Thin Inst | 测试盲区复盘:补反向断言纪律、假上游严格化、薄安装冒烟、形态矩阵与生命周期覆盖 #3617):每个新用例都钉了两个方向——“大 debounce 让写入越过旧 500ms 点” + “小 max-delay 在持续 churn 下压过大 debounce”。合格。
  • 确定性:两个写入器持有模块级 pendingSince/timer,跨用例隔离依赖 flush*() 复位 pendingSince——已核实 writeSnapshot 的 finally 确实复位,隔离成立。

审中发现并已顺手修掉的一处缺陷(独立标注 commit): docs/configuration.md(+ zh)的 persist Description 声称 max-delay 上限“由主会话写入器以及 session-order / prefix-affinity 边车写入器共同遵守”。这与代码不符:src/persist.ts 的 scheduleSave 用的是非重置式去抖(if (existing) return; 保留首个 timer,故在一个窗口内必然落盘、不会饿死),且从不调用 persistMaxDelayMs();只有两个快照写入器才有这个上限。已把 en+zh 改成与代码一致。commit abf9e4c813 已推到 PR 分支。(期间 ci-check docs-regen 又落了一个 commit,我 rebase 上去,无冲突,两者并存。)


结构化八问

  1. 是什么问题:session-order / prefix-affinity 两个快照写入器把去抖窗口和 max-delay 上限各自写死成常量、从不读 persist.* 旋钮;而字段报告里用的 BILI_SNAP_DEBOUNCE_MS 在代码库里根本不存在,那次覆盖因此无效。本 PR 把两个旋钮接进这两个写入器,并新增 persist.maxDelayMs。
  2. 什么原因导致的:主会话写入器一直走 persist.debounceMs,但这两个全局快照写入器各留了本地硬编码常量、从未读旋钮;且调度公式 delay = min(debounce, maxDelay − pending),持续流量下被 5s 上限主导——只调 debounce 对报告场景毫无作用。
  3. 影响范围与严重程度:默认值下零行为变化(新旋钮默认 = 原硬编码 500ms / 5s),纯可调性增强。受影响面 = 需要在磨损敏感盘上压低快照重写速率的用户(如 Time-context snapshots injected as role:"user" cause spurious "fake user messages" #6062 的 QLC SSD 场景)。严重度:体验/成本优化类,非功能性缺陷。
  4. 怎么修复的:新增 persistMaxDelayMs()(env > file > 5000),两个写入器的 budget 与 Math.min(...) 两处改调旋钮函数替代本地常量;复用既有 persist.* 家族与其 tInt+filePersist() 解析链,不发明新 section,也刻意没有造报告里的 BILI_SNAP_DEBOUNCE_MS。
  5. 是否有回归问题:审过的既有行为——①默认节奏不变(12 个既有 affinity 用例全绿 + 新增 default-cadence 用例);②主会话写入器零改动;③plugin-conversations.json 自带的 300ms 去抖刻意未动(避免静默漂移其默认节奏);④高危模式逐项过:无语义漂移、无 fail-fast 变吞错、默认下阈值/时序不变、输出格式不变。未发现回归;另发现并顺手修掉一处文档与代码不符(上文)。
  6. 是否破坏缓存:不涉及——纯持久化写盘时机旋钮,不触及 KV/前缀缓存、重试、增量游标、去重键。
  7. 是否改了设计方向:不涉及——沿用既有 quiesce/max-delay 纪律(/bili/url/重启agent、重启bili、开新会话分支啥的都有概率丢失压缩 #1834/Compression fails in long sessions while new sessions work fine | 压缩失败.新会话反而没事 #3397),只把硬编码换成旋钮,数据流与边界不变。
  8. 是否引入了新的配置:是,一个可选键 persist.maxDelayMs(number,默认 5000,env BILI_PERSIST_MAX_DELAY_MS,group process)。未设 ⇒ 5000 = 原硬编码 ⇒ 零迁移。已同步 configuration.md en/zh、process.yaml seed、lifecycle.md env ledger(config-surface-guard / docs-sync 由 CI 把关)。

判定与建议:代码与测试成立,scope 正确,默认零漂移。CI 现正跑在我推的新 head abf9e4c813 上(guards queued/in-progress,e2e 车道按门控 skip,gate 全绿),full-suite 结论以 CI 为准——我不替 CI 下“绿”的判断。本 PR 新增了 config key,按 §7.4 属 human-gated,建议等 CI 转绿后由你合并。

@ranxianglei

Copy link
Copy Markdown
Owner Author

🤖 Powered by ework · qwen3.8-27b

[bot] 🏷 (ai: vllm-qwen/qwen3.8-27b)

CI auto-fix run (attempt 1/3): docs-sync fixed and verified green.

What was broken: docs-sync runs node tools/gen-config-docs.mjs generate on the PR merge ref and fails on any drift between generated artifacts and committed ones. On head dc0e0dd it flagged exactly 4 files:

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 14a6d860 (docs: regenerate config docs from seed for persist.maxDelayMs (docs-sync drift)). Before pushing I confirmed git diff --exit-code on the four tracked files was clean against fresh generator output. Push discipline followed: fetch + rebase onto the remote head first (no concurrent commits at that point), normal push, no force-push.

Concurrent work handled: while CI was starting, commit abf9e4c8 landed on the branch above mine (prose correction to the manual ### persist Description section, en+zh — outside the generated blocks). Re-ran the generator on abf9e4c8: zero drift, so no further push was needed.

Live verification (mirror cache, this run): head abf9e4c8 — docs-sync: success; 0 failures out of 30 checks; all guard/static/test-import lanes green; 5 long-running test shards still in progress (they were skipped on the previous head because docs-sync gated them via needs:). If one of those turns red it is a separate wake — nothing failing right now.

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.


八问(中文结论)

  1. 是什么问题:docs-sync 检查失败——PR 新增的 persist.maxDelayMs 配置项在四个由生成器产出的文档文件里与种子(process.yaml)不一致。
  2. 什么原因导致的:PR 作者把索引表行手工写进了 configuration.md(en+zh),用的是早期草稿措辞,与自己种子里的 desc_en/desc_zh 不一致;且加完种子后没有重新跑 gen-config-docs.mjs,导致 website/main.js 和 website/docs/index.html 的 tt.persist 摘要行缺了 maxDelayMs 5000。根因是「手工编辑了本应由生成器维护的产物」,不是内容分歧。
  3. 影响范围与严重程度:仅文档展示层——配置参考页与网站文档会显示过时/缺失的旋钮描述;无任何运行时行为影响,严重度为体验瑕疵(CI 门禁红)。
  4. 怎么修复的:在 PR 分支上直接跑官方生成器 node tools/gen-config-docs.mjs generate,提交四个重新生成的文件(14a6d860),以种子为唯一事实源收敛漂移;推送前本地验证生成输出与已提交状态零 diff。
  5. 是否有回归问题:无。改动只落在生成器产物内,逐字节等于生成器当前输出;PR 其余手工文档段落(persist 节说明、smartctl 观测配方、env 表行)不在生成块内,未被触碰。默认值不变(maxDelayMs 默认 5000 = 原硬编码值)。
  6. 是否破坏缓存:不涉及(纯文档文件)。
  7. 是否改了设计方向:不涉及。
  8. 是否引入了新的配置:不引入新配置——persist.maxDelayMs / BILI_PERSIST_MAX_DELAY_MS 是本 PR 原有内容,本次只修文档同步;无新 env、无默认值变更、无迁移。

判定:docs-sync 已绿并实测确认;当前 30 项检查零失败,仅剩 5 个长时 test 分片在跑。本次自动修复任务完成。

@ranxianglei

Copy link
Copy Markdown
Owner Author

🤖 Powered by ework · qwen3.8-27b

(ai: vllm-qwen/qwen3.8-27b)

CI fix run — PR #6068, head now 117cb7f76a — all checks green.

Verified live state first: architecture-docs was the only failing check at 73f222e54c. Fixed two gates on the PR branch (fetched + integrated remote head before each push; no concurrent drift found either time):

  1. architecture-docs — the PR added src/egress-transforms.ts but the file map in reference/architecture.md never listed it (the guard fails on any unlisted src/ file). Added one map entry next to the other wire/transport modules: egress-transforms.ts # User-registerable egress request-body rewrite pipeline (#6003) → commit c7e0582d33.
  2. unused-exports — a second red that was masked while architecture-docs blocked the gate workflow; it surfaced once run #42685232985 got past it. It flagged five INTERNAL_ONLY exports in the new src/egress-transforms.ts. Fix, per the gate's own guidance and repo precedent:
    • dropped the leading export from resolveEgressModulePath() — a purely internal helper with zero references outside its file (commit 117cb7f76a, 1-line change);
    • added one reasoned entry to the script's WAIVERS list for the four user-plugin contract types (EgressTransformMatch / EgressTransformCtx / EgressTransformResult / EgressTransformModule) — same pattern as the existing #R3/#5146 waivers: these shapes define what a registered plugin implements, so they stay named at their definition site even though nothing imports them yet.

Local verification: both guard scripts pass on the fixed tree (node tools/check-architecture-docs.mjs all green; node scripts/check-unused-exports.mjs clean, 12 waived). Full-suite verdict came from CI, not local runs. Final live verification via check-runs on head 117cb7f76a: 39 success + 15 skipped, 0 failed — including the full test matrix shards and static-gates. (Note: the mirror check cache went stale mid-run — frozen ~10 min — so final state was confirmed with a single direct API call rather than polling.)

Total diff over the original head: 3 files, +7/−1 lines. No behavior change: a doc-map line, one export keyword off an unreferenced same-file function, and a waiver-table entry in the gate script.


结构化八问

  1. 是什么问题:PR 新增模块 src/egress-transforms.ts 后,CI 的 architecture-docs 门禁红(文件地图漏登记);修掉后又暴露出被它挡住的第二个红——unused-exports 门禁判该文件有 5 个无外部引用的导出。
  2. 什么原因导致的:作者实现新模块时只更新了配置文档,没同步 reference/architecture.md 文件地图(AGENTS.md 要求同 PR 更新);另外新文件的 4 个插件契约类型 + 1 个内部 helper 函数都带了 export 但全仓无任何外部引用,触发 unused-exports 门禁。
  3. 影响范围与严重程度:仅 CI 门禁层面——PR 无法合并;运行时行为零影响(类型擦除、helper 仍被同文件调用、纯文档行)。用户面不受影响。
  4. 怎么修复的:①文件地图补一行登记(位置按 wire/transport 主题区);②resolveEgressModulePath 去掉 export(门禁对 INTERNAL_ONLY 的默认处置);③4 个契约类型走脚本内 WAIVERS 机制豁免,理由逐字写明(插件契约形状在定义处保名,沿用 #R3/In storage unified FULL mode, the same session repeatedly hits DIGEST DRIFT (views are not converging), dropping the ing | storage unified FULL 模式下同一会话反复 DIGEST DRIFT (views are not converging),每次丢 ingest 水位并重灌尾部 #5146 先例)——不改功能代码的 API 意图。
  5. 是否有回归问题:无。逐项过:文档行不影响任何代码路径;去 export 的函数未被任何文件引用(已 grep 全仓验证),运行时行为不变;WAIVERS 是门禁脚本自己的白名单机制,只放宽这一个文件的 4 个符号,不动其他判定。CI 全量测试矩阵在新 head 上 39 绿 + 15 skipped、零失败,即回归结论。
  6. 是否破坏缓存:不涉及——未触碰压缩/缓存/会话持久化任何路径。
  7. 是否改了设计方向:不涉及——纯 CI 门禁修复,未改架构与数据流。
  8. 是否引入了新的配置:不涉及——无新 env/config/默认值。(WAIVERS 条目是门禁脚本内部清单,不是用户配置面。)

判定:CI 已全绿,可合并。

@ranxianglei

Copy link
Copy Markdown
Owner Author

🤖 Powered by ework · qwen3.8-27b

(ai: vllm-qwen/qwen3.8-27b)

Stale event — no work needed. The reported unused-exports failure was on head c7e0582d33 and was already fixed by commit 117cb7f76a (dropped the export from internal-only resolveEgressModulePath, waived the four plugin-contract types with a reasoned entry in the gate's WAIVERS list). Live re-verification this run: branch head is now ac622f42d7 (two further commits landed after my fix: module-page docs + a small coerceModule cleanup), and its full CI run is complete — 39 success + 15 skipped, 0 failed, including unused-exports and architecture-docs. All checks green; nothing left for me to fix here.

@ranxianglei

Copy link
Copy Markdown
Owner Author

🤖 Powered by ework · qwen3.8-27b

[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:

  1. architecture-docs (red at original head 73f222e5) — the new src/egress-transforms.ts was missing from the file map in reference/architecture.md. Added the one-line entry → commit c7e0582d.
  2. unused-exports (surfaced once gate fix: keep system prompt byte-stable for prefix cache #1 unblocked it; the wake-up reporting it at c7e0582d is stale — already fixed) — five INTERNAL_ONLY exports in the new module: dropped the export from internal-only helper resolveEgressModulePath() and added one reasoned WAIVERS entry for the four user-plugin contract types (EgressTransformMatch/Ctx/Result/Module, same precedent as the existing #R3/In storage unified FULL mode, the same session repeatedly hits DIGEST DRIFT (views are not converging), dropping the ing | storage unified FULL 模式下同一会话反复 DIGEST DRIFT (views are not converging),每次丢 ingest 水位并重灌尾部 #5146 waivers: contract shapes stay named at their definition site) → commit 117cb7f7.

The branch then advanced past my fixes (59c6b9f7 module-page docs, ac622f42 dead-parameter cleanup). Final live verification on head ac622f42: full run complete — 39 success + 15 skipped, 0 failed, including unused-exports, architecture-docs, the whole test matrix and static-gates. No further CI work needed; the PR is green and mergeable pending human merge.


结构化八问

  1. 是什么问题:PR 新增模块后两个 CI 门禁红——文件地图漏登记(architecture-docs)、新模块 5 个无外部引用导出(unused-exports)。
  2. 什么原因导致的:新模块实现时未同步 reference/architecture.md;契约类型与内部 helper 都带了 export 但全仓无外部引用。
  3. 影响范围与严重程度:仅 CI 门禁层面(PR 无法合并);运行时零影响。
  4. 怎么修复的:补一行文件地图;INTERNAL_ONLY helper 去 export(门禁默认处置);4 个契约类型走脚本 WAIVERS 机制豁免并写明理由——不动功能代码的 API 意图。
  5. 是否有回归问题:无。去 export 的函数已 grep 验证无任何外部引用;WAIVERS 只放宽该文件这 4 个符号;最终 head 全量 CI 39 绿 + 15 skipped、零失败即回归结论。
  6. 是否破坏缓存:不涉及。
  7. 是否改了设计方向:不涉及——纯 CI 门禁修复。
  8. 是否引入了新的配置:不涉及(无新 env/config/默认值)。

判定:CI 全绿,可合并。

@ranxianglei

Copy link
Copy Markdown
Owner Author

🤖 Powered by ework · qwen3.8-27b

[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 (44463017 → 049178e9) while the branch sat at abf9e4c8, putting the PR in dirty merge state.

How I resolved it: chose merge over rebase (no history rewrite, no force-push, safe against concurrent agents on the same branch):

  1. Merged origin/master at 049178e9 into the branch head. Two files conflicted, both with the SAME one-line shape:
  2. While verifying, master advanced again (541cf260c4, 32 more files incl. a compress.yaml seed change) — merged that second snapshot too; it applied cleanly with zero new conflicts.
  3. Pushed b326380431 (normal push; fetched before pushing, remote head unchanged — no concurrent writers).

Local verification on the final merged tree: npm run typecheck clean; targeted suites tests/order-persist.test.ts + tests/affinity-persist.test.ts 16/16 pass; node tools/gen-config-docs.mjs generate produces zero drift on the four docs-sync-tracked files (the second master snapshot had touched website/main.js/index.html via its own seed change — regenerated output matches committed bytes, so docs-sync stays green).

Live verification (mirror cache, this run): head b3263804 — mergeable_state: blocked (was dirty before the fix → the conflict is gone; blocked = branch-protection/pending-checks state, not a conflict); CI restarted on the new head: 30 checks, 0 failed, 9 long test shards in flight at last observation. Honest caveat: the mirror cache stopped refreshing after 01:51Z, so I could not confirm the FINAL all-green verdict within this run — if any shard turns red it will surface as the next blocker event. Pre-merge context: the old head was fully green (0/30) before this wake, and the only new code is master's own green commits plus the two-line import union verified above.


八问(中文结论)

  1. 是什么问题:PR 分支落后 master 约 20 个合并,与基线产生合并冲突(merge state: dirty),无法合并。
  2. 什么原因导致的:分支停留期间 master 持续合入新 PR,其中 Existing JSON State Files: Inventory and First-Batch Unified Storage Migration | 存量 JSON 状态文件:盘点与第一批统一存储迁移 #5753/[PR] storage: move six JSON sidecar states onto the unified sqlite store (#5753) #5757(统一存储改造)给 src/order-persist.ts 和 src/affinity-persist.ts 各加了一行 kvStore 导入,与本 PR 在同一位置加的 knobs 导入撞行;文件其余部分双方改动不相交。
  3. 影响范围与严重程度:仅阻塞本 PR 合并;无运行时行为影响、无用户面影响。严重度:流程性阻塞(不修则 PR 永远合不进去)。
  4. 怎么修复的:用 merge(非 rebase,不改写历史、无需 force-push)把最新 master 分两批并入 PR 分支——第一批 049178e9 解决两处导入冲突(取并集,两个符号在各自文件中都有实际使用),第二批把验证期间又前进的 541cf260c4 干净并入;推送前 fetch 确认无并发写入,普通推送 b326380431。
  5. 是否有回归风险:已逐项核查——冲突只有导入行,函数体由 git 自动合并且经人工审查语义自洽(PR 的旋钮调度 × master 的双载体执行正确组合);合并树上本地 typecheck 干净、两个直接相关测试套件 16/16 通过、文档生成器零漂移。master 带入的其余 80+ 文件是 master 自身已绿的提交,未做改动。高危模式(语义漂移/fail-fast 变吞错/阈值漂移)逐项过:无。最终全量判定以 CI 为准(见下条说明)。
  6. 是否破坏缓存:不涉及(本次只动了两个持久化模块的导入行;持久化写入的 debounce/max-delay 默认值不变,500ms/5s)。
  7. 是否改了设计方向:不涉及。
  8. 是否引入了新的配置:不涉及(persist.debounceMs/persist.maxDelayMs 是本 PR 原有内容,本次仅解冲突)。

状态:冲突已解除并实测确认(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 ranxianglei left a comment

Copy link
Copy Markdown
Owner Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

(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 treats persist.debounceMs; cost is one page-cached readFileSync + 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 — imports persistDebounceMs only, never persistMaxDelayMs; 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


结构化八问

  1. 是什么问题:31 天 QLC SSD 实测(上游 #6058)发现 session-order / prefix-affinity 两个边车快照写入器把去抖窗口和 max-delay 上限写死成本地常量、完全没有配置入口;持续流量下 5 秒上限主导稳态重写速率,用户只能改 dist。本 PR 把两个窗口接进配置系统。
  2. 什么原因导致的:主会话写入器一直走 persist.debounceMs,两个边车写入器却各自留了本地 const、从未读旋钮;且调度公式 delay = min(debounce, maxDelay − pendingSince)(pendingSince 只在为空时设置、重排不重置),只放开 debounce 对实测场景无效——必须同时放开上限。
  3. 影响范围与严重程度:修复前 = 磨损敏感盘用户无法调快照重写频率(体验/perf 缺陷,不影响正确性);默认值下新旧行为完全一致,实际影响面限于主动配置这两个键的用户。
  4. 怎么修复的:复用既有 persist.* 家族与 tInt 解析链(env > file > default),新增键 persist.maxDelayMs(默认 5000 = 原硬编码),两个写入器的两处常量改调旋钮函数;N-day eviction(#1724 永久性的语义变更)与 kv 迁移(#5757)明确 out-of-scope。
  5. 是否有回归问题:逐项审过——两写入器公式不变且默认等于原常量 ⇒ 默认零漂移;主会话写入器未动(从不调用 maxDelay);plugin-conversations 的 300ms 刻意未动;flush/hydrate/boot/kv 双载体路径未动。无阈值/时序/输出格式漂移,无 fail-fast 变吞错。唯一有意变更:旋钮按调用解析而非模块加载时一次性取值(与主写入器行为一致,支持热重载;代价是每次调度一次页缓存 readFileSync,可忽略)。
  6. 是否破坏缓存:不涉及——不触及 KV/前缀缓存、重试、增量游标、去重键;两个文件本身是可重算缓存,默认写下时机不变。
  7. 是否改了设计方向:不涉及——纯可调性增强,架构/边界/数据流不变。
  8. 是否引入了新的配置:是——persist.maxDelayMs(number,默认 5000,env BILI_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.

@ranxianglei

Copy link
Copy Markdown
Owner Author

🤖 Powered by ework · qwen3.8-27b

[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):

  1. Direction: verified against the upstream field report — GitHub billion-context Physical Write Volume on QLC SSD: 31-Day Field Test, Four Governance Tiers, Residual Attribution | billion-context 在 QLC SSD 上的物理写入量:31 天实测、四道治理、剩余归因 #6058 ("Physical Write Volume on QLC SSD", §6.2 asks for exactly these knobs; §6.3 recipe ships in this PR). The "Time-context snapshots injected as role:"user" cause spurious "fake user messages" #6062" cited throughout the PR is the internal mirror number of that same report, not a GitHub issue. Out-of-scope carves (N-day eviction = human-gated 多实例共享 sessions 目录的重启竞态:丢失更新、前缀缓存击穿与会话跨实例暴露(#394 扩展) #1724 semantics; kv migration = [PR] storage: move six JSON sidecar states onto the unified sqlite store (#5753) #5757) are correct.
  2. Regression audit: both writers' scheduling formula unchanged with knob defaults equal to the old hardcodes ⇒ zero drift at defaults; main session writer untouched (never calls persistMaxDelayMs); plugin-conversations.json 300ms deliberately untouched; flush/hydrate/boot/kv-dual-carrier paths untouched. Only deliberate change: knobs resolve per call (hot-reload consistent with the main writer), cost = one page-cached read per schedule.
  3. Tests: both directions pinned per writer (Test Blind Spot Retrospective: Reinforcing Negative Assertion Discipline, Tightening Fake Upstream Strictness, Thin Inst | 测试盲区复盘:补反向断言纪律、假上游严格化、薄安装冒烟、形态矩阵与生命周期覆盖 #3617), polling loops with ≥300ms margins, cross-case isolation verified via flush*() resets; teeth confirmed by tracing pre-change code against each assertion.
  4. Config surface & docs: new key properly declared; en+zh docs, lifecycle ledger, seed + regenerated website artifacts complete; config-surface-guard green.

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

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 0813da6490: 0 failed, 4 long test shards still in flight at last observation. No kernel/ changes, no authorization gates, no open ends.


结构化八问

  1. 是什么问题:session-order / prefix-affinity 两个边车快照写入器把去抖窗口和 max-delay 上限写死成本地常量、无配置入口;持续流量下 5s 上限主导稳态重写速率(上游 billion-context Physical Write Volume on QLC SSD: 31-Day Field Test, Four Governance Tiers, Residual Attribution | billion-context 在 QLC SSD 上的物理写入量:31 天实测、四道治理、剩余归因 #6058 实测场景)。
  2. 什么原因导致的:主写入器一直走 persist.debounceMs,两个边车写入器各自留了本地 const 从未读旋钮;且 delay = min(debounce, maxDelay − pendingSince)(pendingSince 重排不重置),只放开 debounce 对实测场景无效。
  3. 影响范围与严重程度:修复前磨损敏感盘用户无法调频(体验/perf 缺陷);默认值下新旧行为完全一致,影响面限于主动配置这两个键的用户。
  4. 怎么修复的:复用既有 persist.* 家族与 tInt 链(env > file > default),新增键 persist.maxDelayMs(默认 5000 = 原硬编码),两处常量改调旋钮函数。
  5. 是否有回归问题:逐项审过——公式不变且默认等于原常量、主写入器未动、plugin-conversations 未动、flush/hydrate/boot/kv 路径未动;唯一有意变更是旋钮按调用解析(支持热重载,代价可忽略)。未发现回归。
  6. 是否破坏缓存:不涉及。
  7. 是否改了设计方向:不涉及——纯可调性增强。
  8. 是否引入了新的配置:是——persist.maxDelayMs(number,默认 5000,env BILI_PERSIST_MAX_DELAY_MS,group process);未设 ⇒ 零迁移。

判定:APPROVE,等 CI 转绿后由你合并。

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant