Skip to content

[PR] fix(storage): Node-upgrade hint on the recurring sidecar-open degrade warn (#3489) - #3531

Closed
ranxianglei wants to merge 1 commit into
masterfrom
2026-10-17_shadow-warn-node-hint
Closed

ranxianglei wants to merge 1 commit into
masterfrom
2026-10-17_shadow-warn-node-hint

Conversation

@ranxianglei

Copy link
Copy Markdown
Owner

What / why

Post-merge supplement to #3485 (merged 1d4dcfc05, directives 2+3 of #3338). Item B of tracking issue #3489 names TWO surfaces for the Node-upgrade hint:

  1. diagnostics/web degrade reason (src/storage/runtime-status.ts) — covered by fix(storage): builtin npm+npmmirror mirror fallback + Node upgrade hint for the SQLite engine download (#3338) #3485 ✓
  2. the recurring [storage] unified sidecar failed to open ... warn line (src/storage/shadow.ts) — missed by fix(storage): builtin npm+npmmirror mirror fallback + Node upgrade hint for the SQLite engine download (#3338) #3485 ✗

That warn fires on every boot while degraded (the #3385 logs show 7 occurrences over several days), while the bootstrap-failure log line #3485 added only fires once per 6h cooldown window — so users normally never saw the upgrade hint in their logs. This completes item B's second named surface.

How

  • New exported pure helper sidecarOpenFailHint(errText, nodeVersion?) in src/storage/shadow.ts: appends nodeSqliteUpgradeHint() only when the error text matches the missing-engine condition (same /no SQLite engine available/i marker regex runtime-status.ts already uses); empty suffix for every other failure.
  • The warn line appends that helper's verdict. No other call sites, no config, no new env vars.

Behavior change (disclosed)

The [storage] unified sidecar failed to open ... warn line gains an ADDITIVE suffix, and only under a narrow condition: running Node < 22.5 AND the open failure is the missing-engine condition. Old → new:

…staying legacy-only; delete the file to reset the index
→ …delete the file to reset the index — node:sqlite needs Node.js >= 22.5; upgrade Node.js for the builtin engine (engine tarball mirrors tried in order: npm + npmmirror; set BILI_UPDATE_REGISTRY or update.registry to pin one)

Corrupt-index (and any other) failures keep the line byte-identical to before; on Nodes ≥ 22.5 the helper returns "" so the line is unchanged there too. In production the gated branch can only fire when the builtin is absent, so the hint is always actionable when shown.

Tests

tests/storage-engine-proofs.test.ts (+2 tests, suite now 14/14):

  • gate × version matrix: pre-22.5 Node + engine error → full hint; corrupt-index error → empty; modern Node + engine error → empty;
  • behavioral warn-line capture via setLogCapture: no-engine maybeOpen warn carries exactly the helper's verdict for its own captured error text; corrupt-index warn ends byte-identical to the pre-change line.

Local targeted runs green: storage-engine-proofs 14/14, storage-engine-bootstrap + storage-ingest-watermark 43/43, npm run typecheck clean. Full-suite verdict = CI on this head.

Closes #3489 (item A landed via #3485; item B completed here).

… warn (#3489)

Follow-up to #3485 (directives 2+3 of #3338): item B of #3489 names TWO
surfaces for the upgrade hint — the diagnostics/web degrade reason (covered
by #3485 in runtime-status.ts) AND the recurring '[storage] unified sidecar
failed to open ...' warn line (src/storage/shadow.ts) that fires on EVERY
boot while degraded. The bootstrap-failure log line #3485 added only fires
once per 6h cooldown window, so users normally never saw the hint.

The hint is gated on the missing-engine error condition (same marker regex
as runtime-status.ts), so corrupt-index.db warns keep their byte-stable
recovery instruction; on Nodes that ship node:sqlite (>= 22.5) the suffix
is empty and the line is unchanged.

Tests: gate x version matrix pin + behavioral warn-line capture (no-engine
warn carries exactly the helper's verdict for its own error text;
corrupt-index warn byte-identical to pre-change).
@github-actions

Copy link
Copy Markdown
Contributor

📦 Built Package Artifact

Branch: 2026-10-17_shadow-warn-node-hint (23e30b2)

Option A — Install this exact build (recommended)

npm install -g billion-context@0.0.4173-pr.3531.363a911

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

Option B — Download artifact

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

Install instructions are refreshed on each push.

@ranxianglei

Copy link
Copy Markdown
Owner Author

🤖 Powered by ework · qwen3.8-27b

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

查重: 不重复 —— open PR 中只有 #3531 实现 #3489 item B(sidecar-open warn 的 Node 升级提示),无其他在途工作触碰该 warn 行或该提示机制。

这是本 agent 已完成的 [PR],未重做,按规范核对代码与 CI 后报告。独立复审结论如下(八问):

  1. 是什么问题:tracking issue feat: multi-mirror fallback for SQLite engine self-download + Node-upgrade hint in degrade output #3489 item B 点名两个展示面,fix(storage): builtin npm+npmmirror mirror fallback + Node upgrade hint for the SQLite engine download (#3338) #3485 只做了 diagnostics/web 的 degrade reason;每次启动都出现的 [storage] unified sidecar failed to open … warn(SQLite unified storage degraded to legacy-only (bili v0.1.197, node v20.20.2, win32-x64) #3385 日志里数天出现 7 次)没带升级提示——用户天天看到这条 warn,却拿不到可操作的修复线索。
  2. 什么原因导致的:范围缺口而非缺陷——fix(storage): builtin npm+npmmirror mirror fallback + Node upgrade hint for the SQLite engine download (#3338) #3485 落地时漏了 item B 点名的第二个面(shadow.ts 的周期性 warn)。
  3. 影响范围与严重程度:仅体验瑕疵(日志信息完整性)——Node < 22.5 且缺引擎的用户从最高频的 warn 里看不到升级路径;degrade→legacy-only 的功能行为不变,无使用阻断。
  4. 怎么修复的:新增纯函数 sidecarOpenFailHint(errText, nodeVersion?)(src/storage/shadow.ts:52),仅当错误文本匹配 /no SQLite engine available/i 时追加 nodeSqliteUpgradeHint(),其余失败返回空串;唯一调用点是 maybeOpen catch 里的 warn 行(src/storage/shadow.ts:111)。
  5. 是否有回归问题:审过的既有行为逐项——(a) corrupt-index/磁盘错误等非缺引擎失败:后缀为空,warn 行字节级不变(test 13 钉住);(b) Node ≥ 22.5:nodeSqliteUpgradeHint 返回 ""(engine-bootstrap.ts:292-299 版本门槛 major>22 || 22.5+),行不变;(c) persist.ts:431 的 DISABLED 行、engine-bootstrap.ts:253 的 bootstrap-failure 行、recordSidecarOpenFailure(String(err)) 收到的原始错误文本均未触碰。无语义漂移、无阈值/时序/格式漂移(披露的 additive 后缀除外)。
  6. 是否破坏缓存:不涉及——纯日志行变更。
  7. 是否改了设计方向:不涉及——复用 fix(storage): builtin npm+npmmirror mirror fallback + Node upgrade hint for the SQLite engine download (#3338) #3485 的同一机制(nodeSqliteUpgradeHint),仅补齐第二展示面。
  8. 是否引入了新的配置:不涉及——无新 env/config/默认值。

验证证据(独立重做,非复读 issue):

  • 代码核对:gate 正则与 runtime-status.ts:87(fix(storage): builtin npm+npmmirror mirror fallback + Node upgrade hint for the SQLite engine download (#3338) #3485 面)一致;driver 抛出的错误格式 [storage:node:sqlite] no SQLite engine available(driver.ts:61-65, 226/251)确实命中该正则;setLogCapture 存在于 logger.ts:149;全仓仅此一个调用点。
  • 测试有效性:test 12(gate×version 矩阵)有牙——gate 放宽则 corrupt-index 用例红,去掉版本门槛则 modern-node 用例红;test 13 经 setLogCapture 捕获真实 warn 行,断言后缀 == 该捕获错误的 helper 判定值,且 corrupt 行以变更前原文结尾。本机 runner 是 Node 22.23.2(≥22.5),行为测试里 no-engine 后缀为 "",完整提示路径由 test 12 的单测矩阵覆盖,两者合起来闭环。
  • 本地定向:storage-engine-proofs 14/14、storage-engine-bootstrap + storage-ingest-watermark 43/43、typecheck 干净、build OK(commit=23e30b238)。
  • 远程 CI:head 23e30b2 全绿(ubuntu/windows × node 22/24 全部 test shard + static-gates + config-surface-guard/lane-guard/kernel-guard/lock-sync/build-artifact 等;skipped 项为常规 gated e2e 车道)。
  • base 新鲜度:分支落后 master 22 个提交,但 master 侧对 shadow.ts 的唯一改动在 close() 方法(~453 行,close 失败补 warn),与本 PR 触碰区(import 块 + maybeOpen catch)不相交;git merge-tree 三方合并干跑干净,无语义冲突。BEHIND 不是 blocker,不强制 rebase。

diff 整洁度:单 commit、2 文件、+83/-2,每行都与目的相关,无空白/重排噪音。

判定:可合。 PR: #3531

@ranxianglei

Copy link
Copy Markdown
Owner Author

Superseded: #3489 landed the multi-mirror fallback chain for the self-downloaded engine (npmjs → npmmirror …, engine-bootstrap retry ladder), which is the durable fix for the recurring sidecar-open degrade after Node upgrades; the extra hint polish here rides the same code path that now succeeds. Closing as superseded.

@ranxianglei ranxianglei changed the title fix(storage): Node-upgrade hint on the recurring sidecar-open degrade warn (#3489) [PR] fix(storage): Node-upgrade hint on the recurring sidecar-open degrade warn (#3489) Oct 20, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

feat: multi-mirror fallback for SQLite engine self-download + Node-upgrade hint in degrade output

1 participant