Skip to content

fix: reject stale in-memory snapshots that would roll back persisted session state (#405) - #517

Merged
ranxianglei merged 1 commit into
masterfrom
2026-09-04_persist-rollback-guard
Sep 7, 2026
Merged

ranxianglei merged 1 commit into
masterfrom
2026-09-04_persist-rollback-guard

Conversation

@ranxianglei

@ranxianglei ranxianglei commented Sep 4, 2026 •

Copy link
Copy Markdown
Owner

Closes #598 — tracking issue for this PR.

Split from #514 (fix 5 of 5, the other piece still unique — see review there). Addresses the dual-instance count fork (计数分叉) symptom at the heart of #403/#394 — persist-side only; the write-side was already fixed by the instance registry (#419). (Note: #514's body cited #405, but that issue is the unrelated ACP_PASSTHROUGH observability bug; no auto-close intended.)

Problem

When two proxy processes share BILI_SESSIONS_DIR (the misconfiguration #394 warns about), whoever saves last wins. An instance holding a stale in-memory copy silently rolls the monotonic counters back — e.g. disk requests: 3 gets overwritten with requests: 2, and block cursors regress the same way. Restarting the healthy instance then loads the regressed state.

Fix

Every write entry point (scheduleSave / writeNow / flushSync in src/persist.ts) now builds through guardedBuild:

  1. staleDiskPayload loads the current disk record via the same envelope probe as loadSync (namespaced path, _unknown/ fallback, kernel flat-legacy probe) and compares the two monotonic signals: stats.requests (v1 flat fallback included), then state.nextBlockId on a tie. Either being strictly smaller proves the in-memory copy is stale.
  2. On staleness the write proceeds with the disk's own payload — a content-identical no-op that satisfies the write chain while preserving the newer state — plus a per-session warning throttled to once per 60s (STALE_WARN_THROTTLE_MS).
  3. flushSync of a stale snapshot still returns true: the disk already holds newer state, so memory eviction stays safe.

Read paths are factored through a shared loadEnvelope helper so the guard and loadSync can never disagree about where the record lives.

Tests

tests/persist-rollback-guard.test.ts (6 tests): stale writeNow keeps disk + warns; tie-on-requests with older nextBlockId rejected; fresh snapshots pass through with no warning; stale flushSync returns true; warning throttled to once per window; debounced scheduleSave guarded too.

Pre-flight

typecheck ✅ · full suite 1036/1038 (2 known plugin-agent env fails, unchanged baseline; +6 new tests) · build ✅

@github-actions

github-actions Bot commented Sep 4, 2026 •

Copy link
Copy Markdown
Contributor

📦 Built Package Artifact

Branch: 2026-09-04_persist-rollback-guard (85f0780)

Option A — Install from npm PR tag (recommended)

npm install -g billion-context@pr-517

Each push to this PR publishes a new version under the pr-517 npm tag.

Option B — Download artifact

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

This comment is automatically updated on each push.

@ranxianglei

Copy link
Copy Markdown
Owner Author

🤖 ework agent · qwen3.8-27b

收到。这是 #514 拆出的 persist 半边(拒绝回档快照),按规范先审核再下结论:先在 clean master 上核实回档问题真实存在、再逐行审 diff、跑完整 pre-flight(typecheck / test / build),结论稍后回贴。合并仍由人工操作。

@ranxianglei

Copy link
Copy Markdown
Owner Author

🤖 ework agent · qwen3.8-27b

审核通过(LGTM)。按规范先验证后下结论,过程与证据如下。

1. 问题审核:真实存在,且描述即根因

2. 方案评估:打到核心,且优于原建议

#405 原建议比较 savedAt/createdAt;本 PR 改用两个单调计数器(stats.requests,tie 时 state.nextBlockId)——更对:wall-clock 跨实例不可比(时钟漂移),createdAt 每 session 恒定无区分度,只有单调信号能证明"严格更小 ⇒ 过期"。

3. 逐点核查(均对照 acp-kernel 0.0.51 源码验证,非只看 diff)

  • builder 时机:kernel scheduleSave 把 builder 存进 pending、debounce 触发时才经 writeNow → writeInner → build() 执行;writeChains 按 id 串行。guard 的盘读发生在写链内部,读到的就是即将落盘的记录,单进程内无竞态。✅
  • 单调性:stats.requests 四处自增(server.ts:1404/1502/1625/1911);唯一回退点 server.ts:2254(runPrepare 重增后的补偿 -1)与其自增同步相邻、中间零 await,persist builder 不可能观察到过冲中间态——持久化快照序列仍单调。✅
  • flushSync stale 返回 true:kernel 语义确认成功写盘即 true;盘上已是更新状态,驱逐内存副本安全(自愈)。✅
  • loadEnvelope 一致性:guard 与 loadSync 共用同一探测链(namespaced → _unknown/ → kernel discovered/flat-legacy),"guard 和 loadSync 不会关于记录在哪产生分歧"成立。✅
  • 单实例零行为变化:guard 仅在盘上计数器严格更新时触发,单实例下盘永远滞后于内存,不可能误伤。✅
  • 两种压缩模式:纯持久层改动,不碰 wire(injection/suppression/preflight/nudge 均未动),模式无关。✅
  • 补充探针(测试未覆盖的两条路,手动脚本实测):① 新记录位于 _unknown/(旧版写入位置)而 incoming 带 protocol meta —— 正确检出并保盘 + warn;② v1 flat 预 envelope 文件(顶层 requests 字段)—— 正确经 fallback 读出并拒绝回档。两条均 PASS。✅

4. Pre-flight(PR head b5bd813 本地实测)

5. 小问题(仅报告,不阻塞,按规范不另开 issue)

  1. migrateLegacyIds(src/persist.ts:255)直接走裸 this.store.writeNow(label, () => buildRecord(session)),绕过 guardedBuild。实际无害:迁移数据启动时取自盘上自身,单实例下不存在更新副本;仅双实例 + 一次性 legacy rekey 的理论边缘。后续可顺手统一走 guard。
  2. staleWarnAt Map 只增不清(每个曾被拒的 session 留一条)。仅在持续误配场景增长、条目极小,非实际泄漏风险;可考虑成功写后清理或设上限。
  3. 测试可补 _unknown/ 与 v1-flat 两条 stale 检出用例(我已手动验证通过),让未覆盖路径也有回归保护。

结论

问题属实、根因判断正确、实现打到核心且设计优于原建议,pre-flight 全绿。LGTM,等人工 merge(合并是人工操作):#517

@ranxianglei

Copy link
Copy Markdown
Owner Author

Review vs master 3cd85b6: ✅ concept sound + tests good — needs rebase (conflicts with #587's rewrite of src/persist.ts), I'll rebase it.

Findings from the review pass:

  • Guard logic is correct and cheap: monotonic signals (stats.requests, then state.nextBlockId tiebreak) read via the shared loadEnvelope probe at write time, debounced. Dual-instance rollback (requests 5→4) is rejected and the disk payload is rewritten content-identically to keep the write chain happy.
  • The STALE_WARN_THROTTLE_MS = 60s per-session warn throttle prevents log spam.
  • Orthogonal to fix #401: persist bounded folded-view snapshot instead of full raw history #587's bounded folded snapshot: the guard compares counters only, buildRecord now emits messages: boundedFoldedSnapshot(session) + messagesFolded — the two changes compose cleanly once the textual conflict is resolved.
  • Tests are well-formed (withTempStore harness, warnings capture, reload-and-assert).

Rebase notes (for me): buildRecord signature/PersistedSession shape changed in #587; defaultLogger import needs re-verification after merge.

(tracking: #598)

…session state

Dual-instance rollback guard (#405 fix #4, tracked in #598): when two bili
processes share BILI_SESSIONS_DIR, the instance holding an older in-memory
copy must not overwrite the fresher on-disk state. Monotonic signals
(stats.requests, state.nextBlockId) prove staleness; a stale save is turned
into a content-identical rewrite of the disk payload (keeping the newer
state) with a throttled one-minute warn.

Rebased onto master (v0.1.92 era): loadEnvelope() probe extracted from
loadSync keeps the #408 negative-clamp reload path; constructor unifies
this.log with the #373 PersistEpermAlert baseLog.

Fixes #598
@ranxianglei
ranxianglei force-pushed the 2026-09-04_persist-rollback-guard branch from b5bd813 to 85f0780 Compare September 7, 2026 09:32
@ranxianglei

Copy link
Copy Markdown
Owner Author

Rebased onto master (single commit 85f0780, mergeable) and resolved the one conflict by union:

Pre-flight: typecheck ✓ · persist suites 34/34 (rollback-guard 8, tail 5, eperm 11, proxy-persist 10) ✓ · full suite 1231/1233 (2 known plugin-agent env fails) ✓ · build ✓.

Fixes #598 (rollback guard tracked there since the #405 split).

@ranxianglei

Copy link
Copy Markdown
Owner Author

🤖 Powered by ework · qwen3.8-27b

[bot] 🏷 On it — re-verifying the rebased head 85f0780 against current master: checking the two union resolutions (this.log vs #373 PersistEpermAlert, #408 clamp path over loadEnvelope), the 2 added rollback-guard tests, and re-running the full pre-flight locally. Will report back shortly.

@ranxianglei

Copy link
Copy Markdown
Owner Author

🤖 Powered by ework · qwen3.8-27b

[bot] 🏷 Re-verification of rebased head 85f0780 complete — LGTM, ready to merge (merge stays with you, as always).

Structure: compare API confirms exactly 1 commit ahead of master, 0 behind; diff is precisely 2 files (+191/−21): src/persist.ts, tests/persist-rollback-guard.test.ts.

Union resolutions verified against source:

A diff-of-diffs (pre-rebase contribution vs post-rebase contribution) shows only those two union points changed; staleDiskPayload / guardedBuild / throttle logic and the test file are byte-identical to the state I reviewed before — so my earlier edge probes (_unknown/ legacy location and v1 flat-fallback records both correctly detected as stale) remain valid without re-running.

Local pre-flight at 85f0780: typecheck ✅ · persist suites 45/45 ✅ · full suite 1232/1233 ✅ · build ✅. The single full-suite failure is the known env-dependent resolveClientCommand: codex/claude resolve to themselves launcher PATH test (fails on clean master too; this diff doesn't touch the launcher). CI on the head is all green: build-artifact, version-guard, ubuntu+windows × Node 22/24.

One minor non-blocking note: your quoted counts don't reproduce from the pushed artifact — tests/persist-rollback-guard.test.ts contains 6 tests (not 8) and proxy-persist has 23 (not 10), so the four persist files total 45/45 passing, and my full-suite run showed 1 env-dependent fail rather than 2. Nothing wrong in code — just flagging that the numbers likely came from a different local state.

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.

persist: a stale in-memory snapshot can roll back persisted session state

1 participant