Skip to content

[PR] Snapshot-table compression foundation proposal (design, refs #5643) - #5873

Open
ranxianglei wants to merge 6 commits into
masterfrom
2026-11-07_proposal-snapshot-foundation
Open

ranxianglei wants to merge 6 commits into
masterfrom
2026-11-07_proposal-snapshot-foundation

Conversation

@ranxianglei

@ranxianglei ranxianglei commented Nov 7, 2026 •

Copy link
Copy Markdown
Owner

What this is

A design proposal (docs only, no code) for the new snapshot-table compression foundation line that #5643 was re-positioned into on 2026-11-07: replace today's parallel state sources (process memory + kstate JSON + table spread) with ONE snapshot table set as the storage truth, with every model request walking one fixed chain:

raw bytes → protocol conversion (canonical cores) → rewrite/compression → apply to snapshot tables → egress mapping → outbound

The compression kernel stays untouched. Sessions whose host supplies session id + per-element msgids run fully on the new chain; hosts without msgids degrade to order-then-hash identity and write into the same tables. Any mismatch falls back to today's legacy full-resend path (degrade, never guess). Rollback = DROP the four new tables + flip the flag off = byte-identical return to today.

Contents (docs/proposals/snapshot-compression-foundation/)

  • README.zh-CN.md / README.md — full design, zh/en mirrors (§0–§16): stage-by-stage design, DDL skeleton (4 tables), invariants, red-gate degradation matrix (R1–R4), coexistence routing with existing lanes (v5 watermark / incremental plugin-turn / D-lane Snapshot rendering: proxy-lane outbound is now rendered authoritatively server-side; existing sessions are immune to ker | 快照渲染:proxy 车道出站从服务端正史渲染,存量会话对内核升级免疫(#3752 根治) #3756), rollout & config surface (owner-gated, no new env knobs), observability, test matrix T1–T12, P0–P3 phasing, and the pending owner rulings table (A–L + D3–D5)
  • assets/arch-current.{svg,png} — current architecture (four lanes patching independently, kstate JSON as parallel source, three structural pain points)
  • assets/arch-target.{svg,png} — target full view, pixel-aligned one-to-one with arch-current so the changed area and blast radius read at a glance (grey untouched · cyan new path/tables · amber role changes · red-dashed fallback; impact boxes on the right, one-line scope on the bottom strip)
  • assets/arch-stages.{svg,png} — stage-by-stage expansion of the six-stage chain (commit primitive / DDL chips / red gates R1–R4 / coexistence routing & rollback)
  • assets/arch-migration.{svg,png} — component migration map (every current component → its disposition under the new foundation: keep / replace / role-change / retired-pending-ruling; the three structural pain points mapped one-to-one to their fixes)

Current architecture:

current

Target architecture:

target

Stage expansion (inside of the six-stage chain):

stages

Component migration map (today's components → where they land under the new foundation):

mapping

Why now / sequencing

#5854 fully reverted the v6 line out of master; #5842 (identity wiring) is already merged. Timing dependency: this plan's P0 DDL stacks on top of #5855's transaction skeleton — #5855 should land first, then P0 starts. This proposal intentionally leaves config key names un-named until the P0 config-surface section, per the owner-gated config surface discipline.

Scope check

Design proposal per owner re-positioning on #5643: six-stage fixed chain
(raw bytes -> protocol conversion -> rewrite -> snapshot tables -> egress
mapping -> outbound) with ONE snapshot table set as the storage truth.
Kernel zero-change. Includes zh+en design docs, current/target architecture
diagrams (svg+png), DDL skeleton, red-gate/degradation matrix, test matrix,
P0-P3 phasing, and pending owner rulings table (A-L + D3-D5).

Docs only: no code, no config surface changes (config keys intentionally
left un-named pending P0 config-surface section).
@github-actions

github-actions Bot commented Nov 7, 2026 •

Copy link
Copy Markdown
Contributor

📦 Built Package Artifact

Branch: 2026-11-07_proposal-snapshot-foundation (0aee319)

Latest build — install this exact version

npm install -g billion-context@0.0.8512-pr.5873.0e06357

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
0aee319 billion-context@0.0.8512-pr.5873.0e06357 build
43e2c48 billion-context@0.0.8503-pr.5873.edb8355 build
bdcbcfe billion-context@0.0.8502-pr.5873.3e79acd build
9f36374 billion-context@0.0.8488-pr.5873.2005400 build
b305d90 billion-context@0.0.8485-pr.5873.d9b8d62 build
fb603bc billion-context@0.0.8483-pr.5873.713722f build

Download artifact

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

Install instructions are refreshed on each push.

…t lands (refs #5643)

Per owner request: the current-architecture picture viewed under the new
foundation — ten components mapped one-to-one to their disposition
(keep/reuse, role-change, replace/converge, yield-pending-ruling), plus
the three structural pain points mapped to their fixing anchors.
@ranxianglei ranxianglei added documentation Improvements or additions to documentation p3 scope/docs labels Nov 7, 2026
@ranxianglei

Copy link
Copy Markdown
Owner Author

🤖 Powered by ework · qwen3.8-27b

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

PR #5873 审核结论(设计提案,docs-only)

先给判定:这是一份方向正确、对现状描述准确、结构完整的设计提案,零行为变更,可作为讨论稿合并。逐项如下(八问体例)。

① 是什么问题 / 要做什么:把今天三处并行状态源(进程内存 lastMessages + kstate JSON + SQLite 表族)收敛成一套快照表作为唯一存储真源;每个模型请求走一条固定六段链(原始字节→协议转换通用核→改写/压缩→应用快照表→出站映射→出站);压缩内核零改动;有 session+msgid 的宿主全走新链,无 msgid 降级到「顺序>hash」写同一套表;任何失步整轮回退 legacy(降级不猜)。回滚 = DROP 表 + 关 flag。

② 什么原因导致的(现状根因):三个结构性根因点得准——(1) 状态存三处形成双写分叉(#5403 OOM 的直接生产者就是 lastMessages 整包钉住);(2) 宿主 (sess_raw,msgid) 入站即剥、只在单轮在途、落不了盘,跨进程/重启无法回答「见过这个元素吗」;(3) v5/增量/D-lane 三条快路径各自补补丁、没有共同存储底座。这是根因层判断而非症状修补。方向成立。

③ 影响范围与严重程度:本 PR 零行为变更(纯文档,src//kernel//tests/ 零改动),对用户面影响 = 无。它只是把 #5643 重定位后的方向落成一份可评审的设计契约。真正的行为面在后续 P0+(P0 明确「零行为变更」,P1 shadow 只写不读)。

④ 怎么修复的(方案思路):单一提交原语(单事务 upsert snap_rows → append snap_log → compact snap_ckpt)作为唯一写入口;ckpt.meta_json 三元组承载内核态序列化 + 覆盖图 + S4 校验和;红门 R1–R4 任一命中整轮回落 legacy;P0→P1→P2→P3 分期、每期独立 PR + 人审关卡。

⑤ 是否有回归问题:无。docs-only,不存在可被破坏的既有行为;我额外确认了没有任何测试引用 proposals/ 或扫描仓库文件树,连测试套件都不受影响。提案对现状的描述我逐条核对了 origin/master,全部准确(见下方核对清单)。

⑥ 是否破坏缓存:不涉及——本 PR 不改任何运行时代码,缓存路径零触碰。提案本身反而冲着「稳定前缀缓存」去(egress 前缀字节跨轮稳定是结构性保证,非巧合)。

⑦ 是否改了设计方向:不改现有方向,是新增一条底层线。它与 #5643 owner 2026-11-07 的重定位逐点对齐(六段链原文一致、内核零改动、msgid 全走 / 无 msgid 降级同表、#5855 只是工程基底非终态、三个待裁定项都收进了 §14 裁定表)。配置面纪律守住了:key 命名推迟到 P0 config-surface 章节、不新增 env knob、owner-gated、web 三态开关 + i18n + registry dead-key guard + yaml seed 全套到位。

⑧ 是否引入新配置:本 PR 引入零配置(刻意留白到 P0),符合 owner-gated config surface 纪律,是对的。

准确性核对(我对 origin/master 实测,非照抄提案文案):

  • STORAGE_SCHEMA_VERSION = 11(src/storage/schema.ts:86)、MYSQL_SCHEMA_VERSION = 11 ✓(提案称 baseline schema v11)
  • POST /__bili/plugin/tool 就在 src/server/admin.ts:797 ✓(§4.2 landing timing 引用精确到行)
  • UPSTREAM_HOP_HEADERS(src/server/headers.ts:14)✓
  • messages.msgId append-only 列(src/storage/ingest.ts:99)✓
  • mergeState() kstate hydration(src/state-hydration.ts 等)✓
  • lastMessages 钉住(src/session.ts / src/server/fastpath.ts)✓
  • lane-decisions 四车道:resolveLaneDecisions + watermarkGateAllowed(src/server/lane-decisions.ts)✓,v5≈5% / D-lane≈0% 与 KDD#15/fix: cache health — remove condense, fix isTitleGen, preserve cache_control #13 灰度值一致
  • zh/en 镜像:两文件各 353 行、§0–§16 结构逐节对齐 ✓
  • 两张架构图为真实 PNG(1560×984 / 1560×964)+ 合法 SVG;target 图含 snap_rows/snap_log/snap_ckpt/l1_world/red-gate/egress ✓

给 P0 / 裁定的几个补充角度(非阻塞,建议并入 §14 裁定与 P0 契约吸收):

  1. 散列子集 span 解析(§4.1)是字节级一致的头号风险——ClusterCounter 按调用内次序编号,解析散落 NEW 子集必须复现整数组调用的编号上下文,否则 egress 字节漂移 = 前缀缓存断。提案已诚实标为 P2 entry(T5 pin)。建议 T4 A/B 字节钉必须覆盖散列位置 + 跨协议族模型切换两种情形,不能只测连续尾窗。
  2. 裁定 F 把底座耦合到内核态序列化格式——ckpt.meta_json 存的是 CompressionState 序列化。现在内核零改动没问题,但一旦将来内核态 shape 变化,hydration 会触发 R1(校验和不符 = 该 sid plane CLOSED FOREVER)永久回落 legacy。建议在 §15 诚实边界里显式记一笔这个前向耦合。
  3. R1「CLOSED FOREVER」需补恢复语义——一次误判/瞬时损坏会让该 sid 永久降级 legacy 直到会话结束。fail-safe 方向对,但运营侧「一个被误关的会话怎么恢复」应写明(是否有显式 resync / re-arm 出口)。
  4. 裁定 H 写模型要与既有的多进程本地 WAL 支持对齐——README 明确「多进程写同一本地 index.db 是受支持拓扑(A second process was detected writing to the same index.db — another process (pid 435075) is writing to the database in | 检测到第二个进程在写同一个 index.db 另一个进程(pid 435075)正在写入本会话目录的数据库——两个进程写同一个库会损坏数据(#3923/#3959)。请关闭多余实例:一个会话目录只能由一个实例服务。 #5082/[PR] Second process opening index.db falsely reports "will corrupt data" — change to a shared-mode warning (#5082) | 第二个进程打开 index.db 误报「会损坏数据」——改为共享形态的提示(#5082) #5091)」;SQLite WAL 串行化的是 DB 写、不串行化各进程的内存视图(resident core arrays / metadata cache)。H 项默认单进程,需说明多进程本地共存时谁做内存视图失效,否则与既有支持面冲突。
  5. §8 非 cohort 流量的 v5-watermark 与新底座要确认「每会话互斥」——措辞「v5 watermark keeps serving … same tables, different lane」读起来像两条车道可能对同一 sid 并发写,那会违反不变量 i(单会话单写者)。应钉死为 flag 级每会话互斥(新底座开则 v5 让位),而非并发双写。
  6. 小勘误:TL;DR/T1 说「DROP three tables」但 §5 定义了四张表——l1_world 的回滚处置(保留还是随删)应一句话讲清;若保留,重新启用时 L1 命中但行已空的语义也值得点一句。

CI 状态(读镜像缓存,未用 gh 轮询):static-gates 全绿;test 分片在跑,最近一次快照无 failure(11 skipped / 7 success / 12 in_progress);早期 windows-latest/22/1 那个孤红在本次快照已不在失败列表。本 PR 是 docs-only 且无任何测试引用新目录,test 分片结果与本 diff 无关。mergeable_state=blocked 只是因为 required checks 还在跑。

交付完整性:已按本 PR 自身 diff 打上标签 documentation + p3 + scope/docs(纯文档设计稿、零运行时影响 → p3)。

收工判定:可合并(作为讨论稿发布)——零行为变更、方向正确、现状描述经实测准确、zh/en 完整、配置面纪律到位。真正的实现在 P0+,以 §14 裁定(至少 F/G/B 定表骨架)+ #5855 先落地为前提;上面 6 个角度建议并入对应裁定 / P0 契约,不构成发布阻塞。是否合并由 owner 拍板。

…5643)

All markdown references (READMEs, PR description, discussion) already point
at arch-migration.{svg,png}; the generated files were named arch-mapping.*,
so the migration map 404'd everywhere.
@ranxianglei
ranxianglei force-pushed the 2026-11-07_proposal-snapshot-foundation branch from 79cb2f3 to bdcbcfe Compare November 7, 2026 11:27

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

documentation Improvements or additions to documentation p3 scope/docs

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant