Skip to content

[PR] Fix flaky WAL custom-cap test: assert convergence instead of a fixed ingest count (#4489) - #4502

Closed
ranxianglei wants to merge 5 commits into
masterfrom
2026-10-24_4489-wal-cap-flaky-test
Closed

ranxianglei wants to merge 5 commits into
masterfrom
2026-10-24_4489-wal-cap-flaky-test

Conversation

@ranxianglei

Copy link
Copy Markdown
Owner

Closes #4489

What is broken

tests/issue3250-wal-checkpoint.test.ts — "#3250: a configured cap flows open() → journal_size_limit" went intermittently red on 5 CI shards with left 1095952 bytes, cap 1048576. It asserted the WAL sat under cap + one page after a fixed number of ingests. The residue above the cap depends on where the 1000-page autocheckpoint window closes relative to commit boundaries, which varies with the runner's bundled SQLite build ⇒ byte-identical red on some shards/environments, green on others, same sha (master run 40068050438; PR #4485 run 40069753327).

Root cause (verified locally)

Reproduced the byte-identical error on this machine (node 22, sqlite 3.51.3 builtin). Instrumented probes show the WAL is a sawtooth: it grows per commit, drops back to exactly the configured cap at each completed checkpoint (autocheckpoint once >1000 pages accumulate; cadence-tick PASSIVE every 20 ingests), then grows again. A fixed-count assertion samples one arbitrary phase of that sawtooth — trough or regrowth — decided by environment-dependent page packing.

Key measured facts (lone writer, hermetic):

  • the autocheckpoint fires on the commit after the one that crosses 1000 pages, and the file lands exactly at cap because a small (128 KiB) commit's extent fits under the cap's frame capacity;
  • the cadence-tick PASSIVE also returns the file to the cap (observed one unit after the tick);
  • control run with the limit set to 100 MiB (truncate no-op, mimicking the pre-fix world): the file never shrinks off its high-water mark — so the new bounded-convergence assertion still fails on a pre-fix tree (RED/GREEN discrimination preserved);
  • larger units do NOT work: a 1 MiB commit's own extent (~1.15 MiB) exceeds cap + slack even right after truncation, so size <= cap + slack could never hold for them — the loop deliberately stays on 128 KiB units.

Fix

Assert convergence instead of a point-in-time size: keep committing 128 KiB units until walSize <= cap + CAP_SLACK, bounded by CONV_UNITS = 24 (one full cadence period of 20 + 1 landing lag + 3 headroom — derivation in the constant's doc). From any phase the next completed checkpoint arrives within that bound; a pre-fix tree sits at its high-water mark through all units and exhausts them → still red.

Deliberately NOT included: adding this signature to scripts/ci-failure-shapes.mjs (the issue comment's optional part b). That classifier is literal-narrow by design, and since part (a) ships in this PR the signature would be dead code from day one. If the shape reappears in CI post-merge, revisit as defense-in-depth.

Verification

  • pre-fix: local run fails with the byte-identical error seen on CI (left 1095952 bytes);
  • post-fix: 10/10 consecutive local runs pass; npm run typecheck clean;
  • full-suite verdict = remote CI on this head.

No user-visible behavior change — test-only diff (one file, tests/issue3250-wal-checkpoint.test.ts).

@github-actions

github-actions Bot commented Oct 24, 2026 •

Copy link
Copy Markdown
Contributor

📦 Built Package Artifact

Branch: 2026-10-24_4489-wal-cap-flaky-test (8a8939c)

Latest build — install this exact version

npm install -g billion-context@0.0.6182-pr.4502.980c42c

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
8a8939c billion-context@0.0.6182-pr.4502.980c42c build
c3e7766 billion-context@0.0.6095-pr.4502.2864799 build
2124a4e billion-context@0.0.5999-pr.4502.1741db7 build
1d418be billion-context@0.0.5478-pr.4502.586edfd build
d648da0 billion-context@0.0.5454-pr.4502.266ee88 build
d237c31 billion-context@0.0.5416-pr.4502.5f7ac4a build

Download artifact

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

Install instructions are refreshed on each push.

@ranxianglei ranxianglei changed the title Fix flaky WAL custom-cap test: assert convergence instead of a fixed ingest count (#4489) [PR] Fix flaky WAL custom-cap test: assert convergence instead of a fixed ingest count (#4489) Oct 24, 2026
@ranxianglei

Copy link
Copy Markdown
Owner Author

🤖 Powered by ework · qwen3.8-27b

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

查重: 不重复 —— 本 PR 的需求源头即 #4489,检索 open+closed issue/PR(WAL flake、journal_size_limit、以及下文 media CAS 失败签名)均无其他重复条目。
标签: bug, scope/ci, p3(CI 测试抖动,无用户可见影响)——已打在本镜像 issue。

结构化八问(独立审核,非转述 issue 侧结论)

  1. 是什么问题:tests/issue3250-wal-checkpoint.test.ts 的 "[bug] index.db-wal 在长驻进程内永不 checkpoint —— STORAGE_PRAGMAS 无 journal_size_limit、master 无 wal_checkpoint 调用,WAL 单调增长到 55 MiB 不回收 #3250: a configured cap flows open() → journal_size_limit (custom limit honored end-to-end)" 在部分 CI shard 稳定红(left 1095952 bytes, cap 1048576)、其余 shard 绿。断言在固定 ingest 计数处采样 WAL 大小,而 WAL 是锯齿波——每次 commit 增长、每个完成的 checkpoint(autocheckpoint >1000 页 + 每 20 次 ingest 的 cadence-tick PASSIVE)回落到恰好 cap,采到哪个相位取决于 runner 的 SQLite 页打包,同 sha 不同环境结果不同。
  2. 什么原因导致的:两层。直接原因:点时断言 vs 锯齿状态,固定计数落在任意相位(谷底或回升段)。更深层:cap 之上的残留量取决于 1000 页 autocheckpoint 窗口相对 commit 边界的落点,属环境依赖量——拿它做硬断言必然间歇红。修法把断言对象从「某时刻的大小」换成「有界单元数内收敛」。
  3. 影响范围与严重程度:仅 CI。单文件 test-only diff,无用户可见行为变化。严重度 = 阻塞合并的 CI 噪音(p3,与原 issue 定级一致)。
  4. 怎么修复的:断言收敛——持续提交 128 KiB 单元直到 walSize <= cap + CAP_SLACK(4KiB),上限 CONV_UNITS = 24。我独立验证了两条时钟腿:① cadence PASSIVE(src/storage/store.ts:1013-1027,每 20 次成功 ingest)— 插桩实测:tick 在 ingest release v0.1.7 #20 触发(checkpointed==log,busy=0),tick 后文件仍高于 cap(连第二连接手动 PASSIVE 之后都还是),下一次 append(fix: cross-platform robustness (port crash, Windows shutdown, persist, BOM, /tmp) #21)→ 文件恰好落到 cap ⇒ truncate 至迟在完成后 +1 个单元可见,与 PR 推导一致;② autocheckpoint — 按真实测试几何(3 MiB burst ≥768 页 + 每 128 KiB 单元 ≥32 页,STORAGE_PRAGMAS 不设 page_size ⇒ 4 KiB 编译默认),首个 autocheckpoint 必在约 9 个单元内收窗 ⇒ 即使 cadence 腿失效,~第 10 个单元前也收敛,远小于 24。对照实验(limit=100 MiB 使 truncate 空转 = 修复前世界):文件在全部 24 个单元钉死 ~4 MiB 高水位、永不回落 ⇒ RED/GREEN 判别能力保留。
  5. 是否有回归问题:无回归。diff 只碰一个测试文件;同文件另 4 个测试未动且全过(本地 + CI);生产代码、配置面、wire、持久化均未触碰。高危模式逐项过:无语义漂移;CAP_SLACK 等阈值未动;有意变更一处并已披露:失败消息文案从 "truncated … at the autocheckpoint" 改为 "converge … at a completed checkpoint (… 24 units exhausted)"——更准确(两条时钟都可能完成 checkpoint),属预期变更;ci-failure-shapes.mjs 刻意不加签名(part b)——part (a) 随本 PR 落地后该分类器条目天起即死代码,理由成立,若合并后形状再出现再补不迟。既有行为清点:文件内其余 4 个测试(close() 收敛 / open() 残留收敛 / cadence-tick 大单元回落 / pinned reader 生命周期)全部保持,CI 11 条 lane 中凡跑到本文件的 3 条全绿。
  6. 是否破坏缓存:不涉及。
  7. 是否改了设计方向:没有——仍断言同一契约(文件收敛到配置 cap),只是采样方式改对。
  8. 是否引入新配置:没有(CONV_UNITS 是测试内部常量,带推导注释)。

证据附录(本地定向验证 + CI 取证)

  • 本地(node v22.23.2,sqlite 3.51.3 builtin):目标文件 5/5 通过、连续 10 轮全绿;探针矩阵(3MiB±burst、96/128/256KiB 单元各相位)全部在第 ≤7 个单元收敛,minSize 恰好 1048576(=cap);「cadence 隔离」几何(24 单元总页数 <1000,autocheckpoint 结构上不可能触发)在第 21 个单元恰好落到 cap;控制组永不收敛(4088 KiB 平台)。
  • CI(run 40078597151 @ head d237c31):全部静态门禁绿;WAL 测试实际跑到的 3 条 lane(win-22/2、u24/1、u22/1)全过;3 条红 shard(u22/3、u24/3、w22/2)各自唯一失败都是另一个测试:media CAS: stale-row sweep releases media refs and mappings(tests/media-cas.test.ts:134,1 !== 0)。
  • 关键交叉验证:master 主 CI run 40073163544(与 PR base 同 sha 02f544d)本身就是红的——6 个 shard,其中 ubuntu-24/1(job 120810850884)挂的正是本 PR 修的 WAL 测试,windows-22/2(job 120810850929)同时挂 WAL 测试与 media CAS 测试。也就是说:本 PR 修掉的 flake 此刻仍在 master 上红;而那 3 条红 shard 的 media CAS 失败在 master 同 sha 上同样存在,与本 diff(test-only、不同子系统)无交互机制。09:03Z 之后的几笔绿色 "master run" 是 E2E workflow,不是主 CI lane,不能当作主 lane 已绿的证据。
  • 已按流程为这个无关的既有失败立项:#4514(带来源标记;GitHub 侧标签 bug/scope/storage/p2 已打,web 镜像同步稍后补齐)。

判定

修复本身通过独立审核,可合。当前 head 的 CI 红完全来自无关的既有 media CAS 失败(#4514):待该 lane 转绿即可合并;若 owner 接受「红与本次 diff 无关」的证据链(上面 master 同 sha 交叉验证),也可以直接合并、由 #4514 单独跟踪。合并动作留给你。

@ranxianglei ranxianglei added bug Something isn't working p3 scope/ci labels Oct 24, 2026
@ranxianglei

Copy link
Copy Markdown
Owner Author

🤖 Powered by ework · qwen3.8-27b

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

查重: 不重复、不再立项 —— 三条红 lane 的失败签名(media CAS: stale-row sweep…, tests/media-cas.test.ts:134, 1 !== 0)已有 #4514(bug/p2/scope/storage)跟踪(来源标记指向本 PR 的审核分析);本 lane 独立复核后未开新条目。

判定:三条红全部是同一处与本 PR 无关的既有失败,本 lane 不改码、到此为止

独立取证(run 40078597151 @ head d237c31,日志逐份拉取)

  • run 共 27 个 job,恰 3 条红(u22/3、w22/2、u24/3),其余全绿,静态门禁全过;
  • 每条红 lane 内唯一失败的测试都是同一个:media CAS: stale-row sweep releases media refs and mappings (full re-ingest drops the image)(tests/media-cas.test.ts:134,断言 "swept message released its media ref",1 !== 0)——不是本 PR 修的 WAL 用例;
  • 本 PR 改的 WAL 文件在 w22/2 shard 上实际运行,5 个用例全绿(含被修的 "[bug] index.db-wal 在长驻进程内永不 checkpoint —— STORAGE_PRAGMAS 无 journal_size_limit、master 无 wal_checkpoint 调用,WAL 单调增长到 55 MiB 不回收 #3250: a configured cap flows open() → journal_size_limit");u22/3 与 u24/3 两个 shard 按分片根本没排到该文件;
  • 交叉验证:master 主 CI run 40073163544(与 PR base 同 sha 02f544d)有 6 条 test lane 红,其中 windows-22/2(job 120810850929)同时挂本 PR 要修的 WAL custom-cap 用例和上述 media CAS 用例(断言文本一字不差)⇒ media CAS 失败在本 PR 之前就在 master 上存在;
  • 交互机制排查:本 PR diff 仅一个文件 tests/issue3250-wal-checkpoint.test.ts(+37/-10,test-only,WAL checkpoint 子系统),与 media 引用 CAS 无共享代码路径。

结构化八问

  1. 是什么问题:本 PR 自身没有 CI 问题;三条红 lane 挂的是另一个测试(media CAS 陈旧行清扫后媒体引用计数未归零)。
  2. 什么原因导致的:media CAS 清扫路径的行为或该测试的预期之一有错(具体归因属 CI red on master: media CAS stale-row sweep test fails ('swept message released its media ref', 1 !== 0) #4514 的分析范围,本 lane 未展开);与本 PR 的因果链为零——master 同 sha 上无本 diff 时同样红。
  3. 影响范围与严重程度:CI 层面阻塞本 PR 合并;对最终用户无直接影响(测试文件,非生产代码)。严重度以 CI red on master: media CAS stale-row sweep test fails ('swept message released its media ref', 1 !== 0) #4514 定级(p2)为准。
  4. 怎么修复的:本 lane 未修——把无关子系统的修复塞进这个单文件 test-only PR 违反单 issue 单范围原则,且该失败已有独立跟踪条目;正确路径是 CI red on master: media CAS stale-row sweep test fails ('swept message released its media ref', 1 !== 0) #4514 自己的分析+修复 lane。
  5. 是否有回归问题:不涉及(无代码变更);另核过本 PR 自身的回归面——WAL 用例在其运行到的 shard 全绿,其余 24 个 job 全绿。
  6. 是否破坏缓存:不涉及。
  7. 是否改了设计方向:没有。
  8. 是否引入新配置:没有。

收工判定

可合性不受本 PR 代码影响:待 #4514 修复后相关 lane 转绿即可合;若你接受上面「master 同 sha 交叉验证 + diff 无交互机制」的证据链,也可以直接合并、由 #4514 单独跟踪。另注:分支当前与 master 处于冲突态(mergeable=dirty),已按流程由冲突处理工位在跟进 rebase,不在本 lane 范围内。

@ranxianglei
ranxianglei force-pushed the 2026-10-24_4489-wal-cap-flaky-test branch from d237c31 to d648da0 Compare October 24, 2026 10:46
@ranxianglei

Copy link
Copy Markdown
Owner Author

🤖 Powered by ework · qwen3.8-27b

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

冲突已解决并推送(rebase 到最新 master 30367e425,新 head d648da0f1,force-push 到 PR 分支——非 master,符合规则)。

冲突原因:master 已合入的 #4506(commit 8eb194ec9)与本 PR 修的是同一个 flaky 测试、同一行断言,但用了不同策略——#4506 把固定采样点的容差从 4 KiB 放宽到 64 KiB;本 PR 把固定计数断言换成收敛循环。两处文本冲突无法并存,必须二选一。

选择:保留本 PR 的收敛断言,弃用 #4506 在测试文件侧的容差放宽(#4506 的 src/ 部分——historian retire 释放 media refs——完整保留,未动)。理由:

本地定向验证:tests/issue3250-wal-checkpoint.test.ts 连跑 5 轮,每轮 5/5 通过(测试文件级定向运行,全量判定以 CI 为准)。


八问

  1. 是什么问题:本 PR 分支与 master 冲突——两个独立修复落在同一测试断言行上,文本上互斥。
  2. 什么原因导致的:同一 flaky 测试被两条线各自修了(master 侧 CI fully red (on master itself): #3250 WAL cap assertion failing across all platform shards — suspected that this mornin | CI 全红(master 自身):#3250 WAL cap 断言在所有平台分片失败,疑似今晨合入的存储层改动破坏 autocheckpoint 截断行为 #4506 先合入),改动重叠在同一行。
  3. 影响范围与严重程度:仅一个测试文件内的一处断言,零生产行为影响;不解决则本 PR 无法合入(阻塞级)。
  4. 怎么修复的:如上——取收敛断言、弃容差放宽,依据是「疏不堵」:消除相位依赖这一产生 flake 的机制本身,而不是加大容忍度掩盖它。
  5. 是否有回归问题:无。改动面仅该测试文件;CI fully red (on master itself): #3250 WAL cap assertion failing across all platform shards — suspected that this mornin | CI 全红(master 自身):#3250 WAL cap 断言在所有平台分片失败,疑似今晨合入的存储层改动破坏 autocheckpoint 截断行为 #4506 的 src/ 变更原样保留;该文件其余 4 个测试全绿。需披露的语义变化见第 7 问。
  6. 是否破坏缓存:不涉及(纯测试)。
  7. 是否改了设计方向:不涉及架构。但有一处断言语义变化需要点名:custom-cap 断言从「固定点 size ≤ cap+64 KiB」变为「24 单元内必须收敛到 ≤ cap+4 KiB」。这是更强的断言(直接钉住"check-point 后回落至配置上限"这个真实不变量),红了即说明 limit 未被遵守而不是容差问题。若 owner 倾向保留 CI fully red (on master itself): #3250 WAL cap assertion failing across all platform shards — suspected that this mornin | CI 全红(master 自身):#3250 WAL cap 断言在所有平台分片失败,疑似今晨合入的存储层改动破坏 autocheckpoint 截断行为 #4506 版本,说一声即可回退。
  8. 是否引入新配置:无。

收工判定:冲突已解、分支已对齐最新 master 并推送,等 CI 转绿即可合并。

…fixed ingest count

The #3250 custom-cap case asserted the WAL sat under cap + one page after a
fixed number of ingests. The residue above the cap depends on where the
1000-page autocheckpoint window closes relative to commit boundaries, which
varies with the runner's bundled SQLite build — byte-identical red on some
shards (left 1095952 bytes, cap 1048576), green on others, same sha
(master run 40068050438; PR #4485 run 40069753327).

Assert convergence instead: keep committing 128 KiB units until a completed
checkpoint (autocheckpoint or cadence-tick PASSIVE) brings the file back to
the configured cap, bounded at CONV_UNITS = 24 (one full cadence period +
landing lag + headroom; derivation in the constant's doc). A pre-fix tree
(limit never honored) sits at its high-water mark through all units and can
never converge, so the RED/GREEN discrimination is unchanged.
@ranxianglei
ranxianglei force-pushed the 2026-10-24_4489-wal-cap-flaky-test branch from d648da0 to 1d418be Compare October 24, 2026 11:53
@ranxianglei

Copy link
Copy Markdown
Owner Author

🤖 Powered by ework · qwen3.8-27b

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

docs-sync 已修复并推送(auto-fix lane attempt 2/2)。新 head:1d418beab(分支 2026-10-24_4489-wal-cap-flaky-test)。

查重: 不重复——根因已在 master 侧修复(#4524 / #4520,commit 8daae6716「docs: add missing pluginLaneServerHistory config seed」),本 PR 无需再立项,只需 rebase 到修复之后的 master。

发生了什么(证据链):

  1. docs-sync job(run 40087251713 @ head d648da0f1b,base 00fdba7f68)跑 node tools/gen-config-docs.mjs generate 后对 CONFIGURATION.md / CONFIGURATION.zh-CN.md / website/main.js / website/docs/index.html 做 git diff --exit-code → 红。生成结果比提交版少一行:rollout.features.pluginLaneServerHistory(Plugin lanes: pin identity to client msgids, render outbound from the server-owned history | 插件车道服务端正史:消息身份钉在客户端 id 上,出站前缀由正史渲染 #4491)的 EN/ZH 文档行。
  2. 逐树 grep 定位:PR head 与其 merge-base(30367e4252)的 website/config-reference/rollout.yaml 都没有该 seed 条目,但 CONFIGURATION.md/.zh-CN.md 里有该行 → 生成器按 seed 出表,自然对不上。即 Plugin lanes: pin identity to client msgids, render outbound from the server-owned history | 插件车道服务端正史:消息身份钉在客户端 id 上,出站前缀由正史渲染 #4491 落地时只加了文档行、漏加 yaml seed,master 自那时起 docs-sync 就是坏的。
  3. 运行时 master 00fdba7f68 确认无该 seed;当前 master 8ae56a010([PR] docs: restore dropped pluginLaneServerHistory seed row — unblocks docs-sync on master #4524 合入后)已有 → PR 分支只是停在修复前的 master 上。
  4. 本地精确复现 CI 门禁:rebase 后跑同一命令 → wrote 10 blocks from 294 seed entries(修复前是 293)+ i18n ok + git diff --exit-code 四文件全空 = exit 0。确定性脚本,CI 必绿。

修法:纯 rebase 到当前 master 8ae56a010,零冲突;测试文件与上一 head 逐字节一致(git diff 为空),diff vs master 仍只有 tests/issue3250-wal-checkpoint.test.ts(+37/-20)。无任何内容改动。

八问:

  1. 是什么问题:docs-sync 门禁红——配置文档生成器输出与提交的 CONFIGURATION.md/.zh-CN.md 不一致(缺 pluginLaneServerHistory 行)。
  2. 什么原因导致的:Plugin lanes: pin identity to client msgids, render outbound from the server-owned history | 插件车道服务端正史:消息身份钉在客户端 id 上,出站前缀由正史渲染 #4491 加文档行时漏加 yaml seed(master 侧漂移);本 PR 分支基于修复前的 master,rebase 用的 base 也早于 [PR] docs: restore dropped pluginLaneServerHistory seed row — unblocks docs-sync on master #4524 的 seed 补上。
  3. 影响范围与严重程度:只挡 CI(docs-sync 对所有基于修复前 master 的 PR 都会红),零运行时行为影响;属发布阻塞级、非用户可见缺陷。
  4. 怎么修复的:把 PR 分支 rebase 到已含 seed 修复的当前 master,不改任何内容。
  5. 是否有回归问题:无——无代码改动,测试文件字节不变,diff 面维持单文件;既有行为零触碰。
  6. 是否破坏缓存:不涉及。
  7. 是否改了设计方向:不涉及。
  8. 是否引入新配置:不涉及。

备注:push 后全套 CI 重跑。attempt 1 已判定的既有 media-cas flake(#4514,与本 PR 无关、master 同样红)仍可能让个别 test shard 变红——那由 #4514 的线处理,不属本 lane。docs-sync 本身:判定可合。

ci-check added 4 commits October 26, 2026 10:18
master window commits 293ae65/de5e03659 bumped kernel/package.json to
0.0.165 without regenerating the lockfiles; lock-sync re-resolution then
rewrites the stale recorded versions (root 0.0.163, kernel 0.0.164) and
fails. Pure recorded-version sync via npm install --package-lock-only;
no dependency or semantic change.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

bug Something isn't working p3 scope/ci

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Flaky test: WAL custom-cap checkpoint case asserts byte-exact file size, intermittently red on 5 CI shards

1 participant