Skip to content

fix: plugin fork snapshot O(1) steady-state maintenance + lazy persistence (#2077) - #2088

Merged
ranxianglei merged 2 commits into
masterfrom
2026-10-04_plugin-snapshot-cow
Oct 4, 2026
Merged

ranxianglei merged 2 commits into
masterfrom
2026-10-04_plugin-snapshot-cow

Conversation

@ranxianglei

Copy link
Copy Markdown
Owner

Closes #2077

What

rememberPluginMessages ran two full O(history) walks on every plugin request (structuredClone(original) + stableJson(...).length > cap), and buildRecord wrote pluginSnapshot into every session record (up to the 16 MiB cap of extra JSON per session file, even for users who never fork). Introduced with #2017/#2058.

How

  • Copy-on-write snapshot in rememberPluginMessages: a full-view prefix scan (sameSnapshotView — exactly the field set forkMessageIdentityHash digests plus id). Steady state is now:
    • identical view (retry re-forwarding the same body): zero work — no clone, no serialize, no refs walk, no markDirty (revision cache stays warm);
    • pure extension: clone only the tail + extend an exactly-tracked byte count (len(sj([a,b])) = len(sj(a))+len(sj(b))+1 additivity); measured exact against the full canonical serialization in tests;
    • anything else (compression rewrite, restart divergence): one serialize to measure BEFORE cloning (the over-cap drop path pays one serialize instead of clone+serialize), then clone only if kept.
  • Cap semantics preserved: BILI_PUBLIC_SNAPSHOT_CAP_BYTES is still enforced from the tracked count on every request — a knob shrink drops the snapshot even without history change; over-cap fail-closed (409 SNAPSHOT_UNAVAILABLE) and under-cap recovery unchanged. Legacy records (no byte count) get a one-time remeasure.
  • Why not id-only comparison: raw ids are content hashes, but adapters attach toolIsError outside the CoreMessage interface (forkToolIsError, src/plugin.ts:846); a resent history can flip that flag under unchanged ids (pinned by "HTTP snapshot normalizes tool error flags..."), so the walk compares every field fork matching can see. A maintenance contract comment ties the comparator to forkMessageIdentityHash's field set.
  • Wire comparable verdict: short-circuited by a native sha256 of the request body; parse+walk only when the body actually changed.
  • Lazy persistence (buildRecord): pluginSnapshot is persisted only once it becomes an external contract — a fork receipt exists on the session, or the sticky metadata.publicSnapshotRetained flag set on the parent at successful fork time (eagerly flushed, mirroring the publishForkSession sync-flush precedent; the receipt lives on the child only, so the parent needs its own trigger).
  • Stored-refs list: re-evaluates when the snapshot changed or the content-store object identity changed (store updates are immutable — storeOriginal returns new objects), skipping the walk otherwise. The list remains a union (monotone), so skipping can only under-list refs that resolve today; the fork-time check validates listed refs against the current store, and child creation derives its ref list from store keys — both unaffected by under-listing. The save-time sweep in buildRecord is untouched as backstop.

Behavior changes (old → new)

  1. Per-request cost for plugin sessions: O(history) clone + O(history) canonical serialize (+ unconditional markDirty) → O(history) field scan with no allocation in steady state; O(tail) clone/serialize on growth; zero work on identical-view resend. Intended — this is the fix.
  2. Session files of non-forking plugin sessions: previously carried the full raw snapshot JSON (up to 16 MiB) → now carry none until a fork happens from/into them. After a restart, such a parent answers GET /__bili/plugin/snapshot with 409 "raw snapshot unavailable" until its next model request rebuilds it — self-healing because plugin agents resend their full history every turn; the 409 text is the pre-existing designed recovery contract. Intended.
  3. Status polls after an identical-view resend: revision epoch no longer bumps when nothing changed → sessionRevisionOf cache stays warm (previously every request invalidated it). Consequence only: fewer recomputes; values identical.
  4. New internal metadata fields (persisted, NOT config surface): publicSnapshotBytes (number), publicSnapshotRetained (boolean), publicSnapshotWireHash (string). No config-file/env/CLI changes; legacy files load fine (missing byte count ⇒ one-time remeasure).
  5. Fork path gains one synchronous parent-record flush per successful fork (bounded by record size, rare operation; failure logs a warn and the debounced save retries — the fork itself is unaffected).

Verification

  • npm run typecheck clean; npm run build clean.
  • Targeted local runs: tests/plugin-fork.test.ts 43/43 (incl. 5 new regression tests: in-place extension + exact byte accounting, legacy remeasure + O(1) no-op + cap re-evaluation, lazy-persistence contract, replacement path, restart self-heal), tests/issue1307-side-snapshot.test.ts 2/2, persist roundtrip trio (proxy-persist, affinity-persist, persist-stats-roundtrip) 35/35. Full suite delegated to CI per local-test discipline.
  • The corruption-loop test now pins publicSnapshotRetained before flushing so it still exercises the corrupted-store detection path under lazy persistence (without the pin it would pass vacuously).

…ist it lazily (#2077)

rememberPluginMessages re-cloned and re-serialized the full raw history on
every plugin request (structuredClone + stableJson, two O(history) walks),
and persist.ts wrote the snapshot into every session record even for
sessions that never fork.

- copy-on-write snapshot: full-view prefix scan (sameSnapshotView — the exact
  field set forkMessageIdentityHash digests plus id; ids alone are not enough
  because adapters attach toolIsError outside the CoreMessage interface);
  pure extensions clone only the tail and extend an exactly-tracked byte
  count instead of re-cloning + re-serializing everything
- cap enforced from the tracked count on every request (knob shrink still
  drops the snapshot without history change); legacy records gain their byte
  count with one-time remeasure
- identical-view resends skip clone/serialize/refs/markDirty entirely,
  keeping the revision cache warm for status polls
- wire comparable verdict short-circuited by a native sha256 of the body
- lazy persistence: buildRecord writes pluginSnapshot only once it becomes an
  external contract (fork receipt present, or sticky publicSnapshotRetained
  set on the parent at fork time, flushed eagerly like publishForkSession);
  non-forking sessions pay no disk cost and self-heal on the next model
  request because plugin agents resend full history
- stored-refs list re-evaluates when the snapshot changed or the content-store
  object identity changed (store updates are immutable), skipping the walk
  otherwise

Tests: 5 new regression tests in tests/plugin-fork.test.ts (in-place
extension + exact byte accounting, legacy remeasure + O(1) no-op + cap
re-evaluation, lazy persistence contract, replacement path, restart
self-heal); corruption-loop test pins publicSnapshotRetained so it still
exercises the corrupted-store detection path.
@github-actions

github-actions Bot commented Oct 4, 2026 •

Copy link
Copy Markdown
Contributor

📦 Built Package Artifact

Branch: 2026-10-04_plugin-snapshot-cow (5b7b901)

Option A — Install this exact build (recommended)

npm install -g billion-context@0.0.2125-pr.2088.a45f8cf

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-pr2088.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

[bot] 🏷 收到,开始按 PR Review 规范审查 #2088(对应 issue #2077):① 原 issue 方向 → ② 回归审查 → ③ 代码主审 → ④ 测试有效性 → ⑤ diff 整洁度。分支 2026-10-04_plugin-snapshot-cow 已定位,正在拉取代码核对 + CI 状态。结论稍后按结构化七问给出。

The old wording claimed len(sj([a, b])) = len(sj(a)) + len(sj(b)) + 1,
which is off by two for whole-array serialization (brackets + comma).
The invariant the code actually implements is the incremental form:
appending element e to array A grows len(sj(A)) by len(sj(e)) + 1.
@ranxianglei

Copy link
Copy Markdown
Owner Author

🤖 Powered by ework · qwen3.8-27b

[bot] 🏷 Review 结论:可合(含我直接推上去的一个注释小修,见文末)

结构化七问

1. 是什么问题:plugin fork 快照(pluginSnapshot)的维护放在每个模型请求的热路径上——每次请求做 O(history) 全量 clone + 全量 canonical 序列化(只为 cap 检查)+ 无条件 markDirty,且持久化层把完整 raw 快照 JSON 写进所有插件会话文件(最大 16 MiB/文件),包括从不 fork 的用户。本质是「只有 fork 时才需要的数据」被放在了每请求热路径和默认持久化路径上。

2. 什么原因导致的:#2017/#2058 引入 isolated fork 后快照成为 fork 回放的外部契约,但维护方式仍是「每请求从零重建」的最保守形态:无增量结构、无 dirty 标记、不区分「是否已是外部契约」。

3. 怎么修复的:三个机制都打在根因上(疏而非堵):

  • CoW 前缀扫描(sameSnapshotView,逐字段比较且字段集与 forkMessageIdentityHash 完全一致):identical view(重试重发同 body)→ 零工作;纯扩展 → 只 clone 尾部并按增量公式累加 tracked 字节数;替换 → 先测量后 clone。
  • 字节数跟踪(publicSnapshotBytes):cap 判定改用跟踪值,每个请求仍重评(knob 缩小即 drop,over-cap fail-closed 保持);legacy 记录首次变化时一次性补测。
  • 懒持久化:buildRecord 只在会话有 fork receipt 或父会话有 sticky publicSnapshotRetained(成功 fork 后设置并 eager flushSync)时写快照;refs 列表仅在快照变化或 contentStore 对象身份变化时重算。

关键假设我逐一验证过,全部成立:① stableJson 增量公式正确(测试用独立 oracle 实现按全量序列化断言精确相等);② rememberPluginMessages 在 withSessionLock 下执行(src/server.ts:3261),in-place prev.push 安全;③ kernel store 更新确为 immutable(acp-kernel storeOriginal:无新条目返回同一对象,有新条目返回新对象)——所以 storeChanged 跳过逻辑无 under-listing 风险;④ flushSync 有先例(src/session.ts:570 子侧 throw;父侧仅 warn 合理,self-heal 兜底);⑤ wire-hash 短路对 publicSnapshotTextComparable 结果等价;⑥ 409 SNAPSHOT_UNAVAILABLE 是既有契约文本,非新行为。

4. 是否有回归问题:逐项审过既有行为:

  • cap 语义:等价。knob-shrink / over-cap / under-cap 恢复三条路径都走 tracked 计数,与旧版每请求实测行为一致;fail-closed 未变吞错。
  • fork 流程:子侧逻辑零改动;新增一次同步父 flush(bounded、低频、失败不阻塞 fork)。
  • 持久化格式:PERSIST_VERSION 不变;新字段是 metadata 整对象 spread 的增量,旧文件加载无碍(缺 bytes → 一次性补测,有测试钉住)。
  • revision epoch:值不变,只是少了无谓 bump(revision cache 保热即披露 Use kernel renderTags:"text-only" + forbid tag echoing in prompt #3)。
  • 一个披露之外的边缘情况(非阻塞):升级前已 fork 过、此后没再 fork 的父会话——retained 标志不会回填,升级后下次保存其文件会丢掉已持久化的快照;若此时恰好重启并立刻 fork,会先 409 一次,等 agent 下一个模型请求重建后自愈。窗口 = 一个 agent turn,与披露的行为变更 fix: address all code review findings (condense, routing, session-id, dead code) #2 同类,可接受。
  • 无语义漂移、无阈值/时序漂移、无输出格式变化。

5. 是否破坏缓存:上游 prefix cache 不受影响(wire 内容零变化,快照是代理内部数据)。反而是改善:identical-view 重发不再 bump revision,sessionRevisionOf 缓存保热。CCR store / 去重键不受影响。

6. 是否改了设计方向:没有架构转向。这是既有 fork-snapshot 机制内的性能/持久化优化,边界不变(快照仍是 fork 外部契约,409 契约文本不变,两种压缩模式的分工不变——改动全在 pluginMode 侧的簿记,proxy mode 路径未触碰)。

7. 是否引入了新的配置:无用户可见 config/env/CLI 变更。新增 3 个内部 metadata 字段(publicSnapshotBytes/publicSnapshotRetained/publicSnapshotWireHash)随记录持久化——属内部簿记而非配置面,PR 已披露,符合 Configuration Surface Discipline。

验证证据

  • CI(原 head 057e229a):15/15 全绿——real codex e2e、fake codex、native opencode/pi/dsh lane、hermetic registry e2e(ubuntu+windows)、test matrix(node 22/24 × ubuntu/windows)、version-guard、build-artifact。
  • 本地定向验证(head 5b7b9011):typecheck clean、build 成功、tests/plugin-fork.test.ts 43/43(含 5 个新回归测试)、tests/issue1307-side-snapshot.test.ts 2/2、persist 三件套(proxy-persist / affinity-persist / persist-stats-roundtrip)35/35,合计 80/80,与 PR 描述完全一致。
  • 测试有效性:5 个新测试有牙——字节核算对独立 stableJson oracle 断言精确相等;数组引用同一性断言钉住 CoW 复用(纯扩展不换数组);revisionEpoch 差值断言钉住 O(1) 稳态(legacy 补测恰好 +1、重复重发 +0);restart self-heal 测试覆盖 409→200 全路径。非恒真断言,bug 回归时抓得住。
  • diff 整洁度:3 文件每行都与本 issue 相关;corruption-loop 测试加 publicSnapshotRetained 有注释说明为何必须 pin(否则该用例会空转通过)——是有意的标注修改,不是混入噪声。
  • base 状态:behind master 4 个提交(release v0.1.183 + master-npm-tag workflow),触碰文件与本 PR 零重叠,无语义冲突,不构成阻塞(合并前可选 rebase)。

顺手小修(已直接提交到 PR 分支)

extension 分支注释里的公式写错了:原文称 len(sj([a, b])) = len(sj(a)) + len(sj(b)) + 1,但按整数组序列化应为 +3(两个括号 + 一个逗号);代码实际实现的是增量形式——向数组 A 追加元素 e 使 len(sj(A)) 增长 len(sj(e)) + 1(元素自身序列化 + 一个分隔逗号),代码是对的、注释表述错了。已把注释改为正确的不变量表述:commit 5b7b9011(docs: 前缀,纯注释 3 行,零代码变更),推送后本地 typecheck 复跑通过。该 commit 触发的新一轮 CI 预期绿(纯注释);若红我会跟进。

判定:可合。

@ranxianglei

Copy link
Copy Markdown
Owner Author

🤖 Powered by ework · qwen3.8-27b

[bot] 🏷 跟进:注释修复合并后的新 head 5b7b9011 CI 15/15 全绿(含 real codex e2e、fake codex、native lanes、hermetic registry ubuntu+windows、test matrix node 22/24 × ubuntu/windows)。无遗留问题,维持可合判定。

@ranxianglei
ranxianglei merged commit 2dfb702 into master Oct 4, 2026
15 checks passed
@github-actions

github-actions Bot commented Oct 4, 2026

Copy link
Copy Markdown
Contributor

📦 Merged Build Published

This merge to master was published as 0.0.14-master.2dfb702 (rolling master tag).

npm install -g billion-context@0.0.14-master.2dfb702  # this exact build
npm install -g billion-context@master  # always the newest merged build

npm view billion-context@master prints the current version at any time.

@ranxianglei
ranxianglei deleted the 2026-10-04_plugin-snapshot-cow branch October 15, 2026 05:32
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.

[plugin] fork snapshot maintenance is O(full history) every request + snapshot persisted into every session file

1 participant