Skip to content

[PR] fold idle session content stores between requests (#4788 phase 2) - #5292

Merged
ranxianglei merged 3 commits into
masterfrom
2026-10-31_session-content-resident
Oct 31, 2026
Merged

ranxianglei merged 3 commits into
masterfrom
2026-10-31_session-content-resident

Conversation

@ranxianglei

Copy link
Copy Markdown
Owner

一句话

长会话的「内容原文库」(每块折叠块/消息原文的内存副本)以前一旦加载就终身常驻——会话越大,bili 进程越胖,7k 消息级会话光这部分就是 GB 级。本 PR 让它和其余三个可卸载字段一样:已证明落盘后就从内存里放下,用的时候透明读回来。

背景 / 为什么现在做

#4788(长会话内存失控分析)+ 决策 #4792 D1-A(一期,已在 master:BILI_SESSION_RESIDENT_HARD_MAX_BYTES 单会话硬上限 + 请求间隙溢写)落地后,一期把「可丢弃字段」做到了 3 个:折叠块原文、元数据账本、尾部原始消息。content store 是第 4 个、也是最后一个无界驻留字段——它保存每个内容块的完整原文,buildRecord 全量持久化、persist.ts 零删除,内存侧同样只进不出。

改了什么

文件 改动
src/session.ts lazyContentStore()——与现有 lazyMetadata/LazyBlockContents 完全同形的懒代理;拒绝提供空物化(读不到就抛,与另两个瘦化视图一样由请求边界捕获,绝不静默降级为空串)
src/persist.ts dropResidentContentStore() + 落盘证明门:只在磁盘上能证明有副本时才放手(统一索引镜像行 或 伴生 sidecar 文件存在);6 个既有泄载站点统一追加调用;增长经 contentStoreDirty 一票否决再放手;BILI_SESSION_CONTENT_STORE_PIN=1 整体禁用
src/knobs.ts contentStorePinned() env 旋钮
docs sessions.contentStorePin 登记(env tier),CONFIGURATION.md/.zh-CN.md 重新生成零手改

落盘证明门是本 PR 抓到的真 bug 防线:fork 子会话的内容库随 envelope 的 forkContentStore 字段走、没有自己的 sidecar——若无脑放手,下一次触摸就会在读不到副本时抛错,直接打挂 fork 快照请求(回归测试里已经真实复现过一次:child snapshot 的 parentRevision 变 undefined)。门判不出 = 保持驻留,宁多花几 KB。

行为矩阵

场景 之前 现在
空闲会话 + 上次保存已证明落盘 content store 终身驻留 请求间隙放下,下轮按需窄读重建(用户不可见)
store 在途增长中 — inFlight/dirty 一票否决,绝不中途抽走
fork 子会话(副本只在 envelope) 驻留 仍驻留(门自动拦下)
统一 full 模式 驻留 镜像行即证明,正常放下(镜像丢失=损坏,抛错拒空而非静默)
legacy 模式 驻留 sidecar 文件为证明来源
逃生门 — BILI_SESSION_CONTENT_STORE_PIN=1 回到旧行为

验证

  • TSC 干净(pretypecheck + noEmit)
  • 190 tests 绿:批一 37(memory/lazy-read/issue4788/bounded/web-fallback 等 11 件)+ 批二 91(plugin-fork 56/multi-instance-live/orphan-recovery/diagnostics…)+ CCR/fork/export 核心 62;新增 tests/memory-contentstore-lazy.test.ts 7 facet(透明读回、dirty 否决、毁源拒空、pin 逃生门、镜像优先、fork-child 驻留)
  • 文档 coverage rc=0(192 env + 59 top-level keys 全覆盖,零新增 notice)

基线:origin/master @ c0fa5b2(已合并最新 master fc0c086,零冲突)。

不做的事(另一决策)

翻默认 jsonWriter=off(持久副本从两份变一份磁盘文件)是独立的 D2 项,前置条件(D1-A)虽已满足但属于默认行为翻转,单独开单拍板,不在本 PR。

ranxianglei-devbox added 2 commits October 31, 2026 10:22
Phase 2 of the #4788 resident-minimal policy (decision #4792 D1-A landed in
phase 1): after every proven-landed save, a settled idle session's content
store is folded away from RAM at the same request-boundary sites as the
other three droppable fields, and re-reads transparently on demand from the
unified index mirror or the sidecar file. The store was the last unbounded
resident field -- every full block original stays loaded for life while
messages themselves were already tail-bounded.

- session.ts: lazyContentStore -- same proxy shape as lazyMetadata/
  LazyBlockContents; refuses to serve an empty materialization (never
  degrades silently; the throw is caught by the request boundary like the
  other thinned views).
- persist.ts: dropResidentContentStore + landing gate. A fold only happens
  when a durable copy is PROVABLY present (unified mirror row or sidecar
  file) -- fork children ride their store inside the envelope's
  forkContentStore with no sidecar of their own, so they stay resident.
  Growth vetoes via contentStoreDirty; BILI_SESSION_CONTENT_STORE_PIN=1
  disables the fold entirely.
- docs: sessions.contentStorePin knob registered (env tier).

Verification: TSC clean; 190 tests green across the memory/lazy-read/fork/
CCR/export/multi-instance batches (incl. new memory-contentstore-lazy
suite, 7 facets: transparent re-read, dirty veto, refuse-empty on destroyed
source, pin escape hatch, mirror preference, fork-child residency).

Baseline: origin/master @ c0fa5b2.
@ranxianglei ranxianglei changed the title fold idle session content stores between requests (#4788 phase 2) [PR] fold idle session content stores between requests (#4788 phase 2) Oct 31, 2026

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

#5292(#4788 二期:content store 落盘证明后卸驻留)评审结论:代码通过,无阻塞项;三个非阻塞小问题列在下面。同步状态干净——分支对当前 master(已含 #5253)零冲突(本地实测合并通过),无 kernel 改动(不需要版本 bump、不走 Kernel Boundary 人工门),CI 绿即可合并。

核验过的设计点(均成立)

  1. 证明门与 loader 无正向空窗:contentStoreLanded()(src/persist.ts:3224)的候选路径集与真实读取路径 readContentStoreRels()(src/persist.ts:642-690)构造完全同形(sourceCcr 派生 + 两个 rel + diskFiles 扫描)。探到存在 ≠ 读不出的唯一窗口是文件损坏——而 boundedReads 下损坏会抛、legacy 直接调用降级 fresh store 后 ensure() 也照样拒物化(byRef 为空即抛),"绝不静默降级为空串"在两条路都守得住(#2674 payload-first 纪律延伸到泄载侧)。
  2. 泄载时机:inFlight 一票否决、contentStoreDirty(adoptContentStore 见 ref 即置脏)否决未落盘增长、BILI_SESSION_CONTENT_STORE_PIN 逃生门、空 store 不折;6 个既有泄载站点全部统一追加,durableRevision==epoch 门复用一期逻辑,注释三处字段数(three→four)同步更新到位。
  3. 懒代理形状与 lazyMetadata/LazyBlockContents 完全同形(src/session.ts:201-267):透明 Proxy 全 trap 先 ensure,WeakSet 记账随物化清除,读不到就抛。
  4. 文档:CONFIGURATION.md/.zh-CN/process.yaml 为生成器产物,sessions.contentStorePin 登记完整(env tier、默认 false、fork-child 自动驻留行为写进了 desc)。

非阻塞问题(建议顺手修或择期)

  1. knobs.ts 插入位拆断了 hardMax 的 JSDoc(src/knobs.ts:437-449):BILI_SESSION_RESIDENT_HARD_MAX_BYTES 的整段注释现在悬在 contentStorePinned 自己的 docblock 之上,sessionResidentHardMaxBytes() 实际变成无文档函数,读者会把那段误认为新旋钮的说明。把新函数挪到 sessionResidentHardMaxBytes() 之后一行即可。
  2. "fork-child 自动驻留"没有测试钉住:行为矩阵和 body 都承诺了这条(fork 子会话的库只骑 envelope 的 forkContentStore,无 sidecar/无 unified ccr 行 → 门拦下),但 tests/memory-contentstore-lazy.test.ts 的 7 个 facet 里没有覆盖它——运行时保护存在,可一旦有人日后改证明集去信任 envelope,没有任何用例会变红。建议补第 8 个 facet:父会话 fork 出子会话 → 两侧 idle save → 断言子会话 store 仍驻留且 child snapshot 正常(parentRevision 不丢)。
  3. (可选)contentStoreLanded 与 readContentStoreRels 逐字重复了路径集构造(sourceCcr 派生 + rels + diskFiles 两处各一份)。今天同形,明天易漂;抽一个 candidateContentStorePaths(id, rels): string[] 共用最稳。

本地确认性验证

  • tsc --noEmit 绿(pretypecheck 口径);
  • 相关套件 48 个文件 339/339 全绿(含新增 7-facet 文件、memory-lazy-read/issue4788/bounded/web-fallback/plugin-fork/multi-instance-live/orphan-recovery/diagnostics/CCR/fork/export);
  • 正式验证留给 CI。

@github-actions

github-actions Bot commented Oct 31, 2026 •

Copy link
Copy Markdown
Contributor

📦 Built Package Artifact

Branch: 2026-10-31_session-content-resident (ae7e507)

Latest build — install this exact version

npm install -g billion-context@0.0.7334-pr.5292.177acbb

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
ae7e507 billion-context@0.0.7334-pr.5292.177acbb build
55cf169 billion-context@0.0.7321-pr.5292.2b1b824 build

Download artifact

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

Install instructions are refreshed on each push.

@ranxianglei

Copy link
Copy Markdown
Owner Author

三条评审意见已按建议处理(commit 见本分支 head):

① knobs.ts 文档块归位:contentStorePinned 整块移到 sessionResidentHardMaxBytes 之后,hardMax 的 JSDoc(含 // ---- 注释行)与函数重新相邻,不再被拆断。

③ 抽出共享候选路径构造器:新增 private candidateContentStorePaths(id, rels)——sourceCcr 派生 + contentStoreRelPathFor 映射 + diskFiles 扫描(#3399/#3765 的顺序依据随迁);readContentStoreRels 与 contentStoreLanded 现在都消费它,两份字面重复消除,证明侧和加载侧不可能再漂移。

② fork-child 驻留补上测试钉:tests/memory-contentstore-lazy.test.ts 新增第 8 facet,把证明门两侧都钉死:

  • A 段:子会话干净态(非脏、无自身 sidecar / 索引行,只有 envelope 携带的父库副本)→ runIdleSpill 后仍驻留,直接断言 contentStoreLanded === false。用非脏态是为了隔离证明门本身而非脏否决;
  • B 段:子会话在自身 id 下长出真实内容并保存后,sidecar 落地 = 证据成立 → 正常折叠且 31 refs 经自己的 sidecar 往返完整。

验证:新文件 8/8 绿;相关回归批(memory-contentstore / lazy-read / #4788 / bounded / web-fallback / plugin-fork / multi-instance-live / orphan-recovery / storage-corpus / storage-review-fixes 共 48 套件)114/114;根 tsc 干净。功能行为零变化——纯重排、去重与测试加固。

@github-actions

Copy link
Copy Markdown
Contributor

📦 Merged Build Published

This merge to master was published as 0.0.937-master.30ec63b (rolling master tag).

npm install -g billion-context@0.0.937-master.30ec63b  # 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 pushed a commit that referenced this pull request Oct 31, 2026
ranxianglei added a commit that referenced this pull request Oct 31, 2026
…surface

Fixes master red in lifecycle-ledger-guard. #5303 added BILI_SPAWN_FINGERPRINT (spawn entry-script sha256 fingerprint channel) and #5292 added BILI_SESSION_CONTENT_STORE_PIN (session CCR store resident opt-in), neither was recorded. Pure doc insertion, zero code change.
ranxianglei pushed a commit that referenced this pull request Oct 31, 2026
- LIFECYCLE.md: register BILI_SESSION_CONTENT_STORE_PIN (#5292 phase-2 pin)
  and BILI_SPAWN_FINGERPRINT (#4125 spawner-script hash channel)
- codex-models.ts: drop leading export from CodexWindowSource (no external
  reader after the #5175 cleanup landed on master)
- regenerate CONFIGURATION{,.zh-CN}.md for the promptPack seed change merged
  to master without its generated-docs refresh
ranxianglei added a commit that referenced this pull request Oct 31, 2026
…t before (#5292)

#5292 folds the resident CCR content store into a lazy proxy once its save lands. This test deleted the envelope and replaced it with a directory BEFORE adoptContentStore(turnTwo); the adopt touches prev.byRef through the proxy, which re-materializes from the already-broken disk and throws by design (#2674 payload-first discipline). Move the disk sabotage to just before scheduleSave — the synchronous write attempt the test name describes ('retries ... after a transient write failure') — preserving every assertion unchanged. Throws-on-unrecoverable-drop stays intact.
ranxianglei added a commit that referenced this pull request Oct 31, 2026
Previous head conflicted (add/add on src/pack-install.ts): this branch pre-dated PR #5331, which added that file to master while the branch carried its own copy. Sandbox cannot clone full objects, so the branch is reconstructed as one clean commit on today's master via the Git data API. Contents unchanged from the reviewed work:

workflows
- ci-janitor: feed the sweep loop its run list (it was never wired up — zombie cancels were dead code since 10-30); add backlog breaker (starvedQueueLimit warn + starvedQueuedMaxMinutes pruning, push-to-master exempt)
- concurrency groups: master-build, release, release-kernel (no-cancel), theorem (skip-lane suffix per house rules)
- timeout-minutes on six workflows left on the 6h default (release 90, release-kernel 90, release-bugfix 90, release-manual 90, advisories 30, pages 30, ci-gate-plugins 30)

master-reds fixed here so every gate passes
- LIFECYCLE.md: register BILI_SPAWN_FINGERPRINT (#5303/#4125) and BILI_SESSION_CONTENT_STORE_PIN (#5292 phase2)
- src/codex-models.ts: drop unused `export` on CodexWindowSource (zero named references; tsconfig has no declaration emit)
- CONFIGURATION{,.zh-CN}.md: restore promptPack row to generator output ("chat" is host-shipped, not builtin; follow-up for #5320: add chat to website/config-reference/compress.yaml and regenerate)
- src/pack-install.ts: PackInstallOptions -> internal (callers pass options structurally)

latent test fixes (surfaced once gates went green)
- src/launcher.ts: #4125 rewrite dropped the phrase tests/issue5103 asserts verbatim; restored
- tests/store.test.ts: move fault injection to the real write point so adopt() runs before the disk sabotage
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.

1 participant