Skip to content

[PR] feat: verified-incremental prefix fast path for plugin-lane fold reconcile (#3248 phase 1) | [PR] feat: verified-incremental prefix fast path for plugin-lane fold reconcile (#3248 阶段 1) - #3257

Closed
ranxianglei wants to merge 2 commits into
masterfrom
2026-10-15_incremental-prefix-fastpath
Closed

ranxianglei wants to merge 2 commits into
masterfrom
2026-10-15_incremental-prefix-fastpath

Conversation

@ranxianglei

Copy link
Copy Markdown
Owner

关联: #3248(阶段 3 候选项「server-authored-prefix fast path」的 reconcile 半边)/ #3253(阶段 2,增量车道本体)

一句话

plugin 车道里,当重发历史被证明是上一轮的纯尾部追加时,跳过 fold-reconcile 的全量扫描(planReconciliation):每会话在 metadata 维护 derived id 的 {count, hash, clean} 指纹,匹配则代入 planReconciliation 在 missing===0 早退时返回的精确同形 plan;任何失配回退全量对账,语义零变化。

与 #3248 / #3253 的关系

#3248 原阶段 1 措辞是「车道头带我的前缀 hash」。#3253 落地后,增量车道的 canonical 就是 unified messages 表本身(#3007/#3166 从普通流量也在喂它),客户端 hash 阶梯被设计取代。本 PR 做的是不依赖 #3253、独立成立的剩余部分:reconcile 侧快路径——正对应 #3253 列出的 open item「server-authored-prefix fast path(skip the O(full) strip/reconcile walk over the prefix)」中的 reconcile 半边(strip 与其他 per-message 处理不变、照跑)。

机制

  1. 每个 main-lane pass(快或全)后向 session.metadata.incrementalPrefix 写 {count, hash, clean}:count = derived id 数,hash = sha256 链摘要(32 hex),clean = 该 pass 无 claims/unmatched;
  2. 下一 pass 用自己的前 count 个 id 验 count + digest。匹配且前 pass clean ⇒ absence set 必为空(kernel id⇔bytes 不变式:span 内任何身份可见变更都会翻转某个 id 从而翻转 digest),直接代入 missing===0 早退形状的 plan——下游全部 bookkeeping(anchors、order/positions roll、coverage p/r/t/e/z、reap、drift streaks)原样执行;
  3. 任一 gate 失配(count-shrink / hash-mismatch / dirty-predecessor)→ 全量对账 +(session, reason)去重记一条日志并计数;指纹每轮刷新,脏 episode 一次干净 pass 后自动恢复资格。

测试

  • 新增 tests/incremental-prefix.test.ts(13 个):链哈希单元 ×5 + 行为 ×8。核心性质 = lockstep 等价:走快路径的会话必须与每轮强制全量对账的同态会话逐字节一致(metadata 除指纹键外 + blocks deepEqual,5 轮增长逐轮断言);
  • tests/fold-reconcile.test.ts:825 整结果断言补新字段 fastPath: false(result 形状变更的必要跟进,该用例 fixture 无 pluginAgent,字段结构上恒 false);
  • 本地:typecheck clean + fold-reconcile / positional / incremental-prefix 三套 103/103 绿(rebased head effd544 之上);全量回归交 CI。

回归审查(既有行为清点)

行为变更披露

无对外行为变更(纯服务端内部优化,外部行为由 lockstep 测试证明等价)。新增面:stats payload 多一个 incremental 字段。

人工合并(§7.4 auto-merge 不适用:触碰 fold-reconcile identity 域 + feat surface)。与未合并的 #3253 在 admin.ts sendStats 一行可能相邻,先合者为准,后者 rebase 即可。

@ranxianglei

Copy link
Copy Markdown
Owner Author

🤖 Powered by ework · qwen3.8-27b

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

查重: 不重复——本条即 PR #3257 自身的 PR 记录(#3248 阶段 1),与在途 #3253(阶段 2)/#3255/#3256 无同症状同机制条目;正文自述与 #3253 在 admin.ts sendStats 一行相邻,属合并次序关系而非重复。

开始审核:先取全窗 diff 分段通读(server/测试/admin 高危域精读),本地只跑定向套件(fold-reconcile / positional / incremental-prefix),全量回归看 CI。结论按八问体例给出。

@github-actions

github-actions Bot commented Oct 15, 2026 •

Copy link
Copy Markdown
Contributor

📦 Built Package Artifact

Branch: 2026-10-15_incremental-prefix-fastpath (08f295e)

Option A — Install this exact build (recommended)

npm install -g billion-context@0.0.3755-pr.3257.5522037

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-pr3257.tgz
npm install -g package

Install instructions are refreshed on each push.

ranxianglei pushed a commit that referenced this pull request Oct 15, 2026
ranxianglei pushed a commit that referenced this pull request Oct 15, 2026
@ranxianglei
ranxianglei force-pushed the 2026-10-15_incremental-prefix-fastpath branch from 15d382d to ac3cf7a Compare October 15, 2026 06:40
awork added 2 commits October 15, 2026 14:43
…ncile (#3248 phase 1)

Plugin lanes (metadata.pluginAgent set) skip the full planReconciliation scan when the resent history verifies as a pure tail-append of the previous pass: per-session {count, hash, clean} fingerprint over derived ids in metadata (incrementalPrefix); any gate failure (count-shrink / hash-mismatch / dirty-predecessor) falls back to full reconciliation, and the fingerprint refreshes from every pass so dirty episodes self-heal. Fast-path plan is byte-exact with planReconciliation's missing===0 early exit (shared buildOrderAndCanon walk); lockstep-equivalence property test pins it. Water-level stats at GET /__bili/stats under 'incremental'. No wire, config, env, or header surface added; BILI_FOLD_RECONCILE=off escape hatch unchanged.
@ranxianglei
ranxianglei force-pushed the 2026-10-15_incremental-prefix-fastpath branch from ac3cf7a to 08f295e Compare October 15, 2026 06:44
@ranxianglei

Copy link
Copy Markdown
Owner Author

🤖 Powered by ework · qwen3.8-27b

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

审核结论:可合(人工合并)

独立审完(未照抄 issue/PR 描述):逐段读完全部 5 个文件的 diff(核心 src/fold-reconcile.ts 212 行全文精读),对快路径的安全论证做了独立的代码级验证,本地跑定向测试 + typecheck,核对了 CI。先说我在审核中做的两个动作:

  1. 顺手修掉一处小瑕疵(独立标注 commit 08f295e55):本 PR 的 hunk 把无关行 FoldReconcileResult.reaped(src/fold-reconcile.ts:379)的缩进从 4 空格误改成 5 空格——纯 diff 噪声,已恢复原状(用 cat -A 核实该 commit 只动这一行)。
  2. rebase 到最新 master:审核期间 master 前进了一格(db046b2da,wire-exit 早提交时序断言改为相对不变量,消除 Windows CI 偶发误报(#3228) #3233 只动两个 wire-exit 测试文件,与本 PR 零文件重叠),已 rebase 并推回分支,当前 head 08f295e55 = feat + 缩进修复共两格线性提交。rebased head 上本地复验:fold-reconcile / fold-reconcile-positional / incremental-prefix 三套 103/103 绿 + typecheck clean;旧 head 0ff2f396b 上 CI 41 个 check-run 全绿(ubuntu/windows × node 22/24 × 3 shards 全矩阵 + static-gates + e2e + registry e2e + codex/pi/dsh 真客户端车道 + config-surface-guard/lane-guard/docs-coverage);新 head CI 正在重跑(发此评论时 10 完成/6 进行中/9 排队),建议看它转绿后合并。

结构化八问

  1. 是什么问题:plugin 车道(dsh/pi/opencode-native)客户端每轮全量重发历史,fold-reconcile 每轮都对整个前缀做 O(full) 扫描去「证明」前缀没变——这个证明在字节稳定时是白付的。阶段 1 给 reconcile 侧一个跳过全量扫描的快路径 + per-lane 水位计量(为阶段 2/Incremental turns: POST /__bili/plugin/turn — native clients send only the delta (#3248) #3253 选人群提供数据)。
  2. 什么原因导致的(为何快路径成立):kernel id⇔bytes 不变式——span 内任何身份可见变更必然翻转某个 derived id 从而翻转链摘要。我独立验证了两点:① cleanIncrementalPlan 与 planReconciliation missing===0 早退返回的字段集逐一相同(两者共享 buildOrderAndCanon,早退前只有 missing 计算,无其他副作用);② 归纳链——chain-match 意味着前 N 个位置逐元素同 id ⇒ 同字节,上一轮 clean 意味着当时 absence set 为空 ⇒ 本轮 absence set 必空。三个 gate(count-shrink / hash-mismatch / dirty-predecessor)任一失配即回退全量,指纹每轮刷新、脏 episode 一次干净 pass 自愈,语义零变化。
  3. 影响范围与严重程度:仅 plugin 车道内部 CPU 路径;无 wire/config/env/header/CLI 变更;非 plugin 会话零差异(lane gate,:825 用例钉住)。性能优化,无用户可见行为变化;严重度 = 体验/成本层,不涉正确性。
  4. 怎么修复的:每会话 metadata 存 {count, hash, clean} 指纹(hash = derived id 的 sha256 链摘要截 32 hex,NUL 连接防边界歧义);下一 pass 用前 count 个 id 三级验 gate;匹配则代入与全量早退精确同形的 plan,下游全部 bookkeeping(anchors、order/positions roll、coverage p/r/t/e/z、zombie streaks、drift escalation)原样执行;失配记一条 (session, reason) 去重日志 + 水位计数。
  5. 是否有回归问题:逐项清点既有行为——非 plugin 车道:零差异 ✓;plugin 稳态等价:lockstep 测试(A 走快路径 vs B 每轮删指纹强制全量,5 轮增长含 retry-resend/尾部追加变体,metadata 除指纹键外 + blocks 逐轮 deepEqual)✓;drift/churn episode:clean=false 强制全量直至恢复,三种 miss reason 各有测试钉住 ✓;side-request(<10 msgs)/mode-off/no-fold 早退经代码位置确认全部在本逻辑之前(1400/1406/1420 vs 1441),[cache-ledger] netSaved 面板在 fold 覆盖坍缩后继续累计虚增——ledger 与实际重发行为无交叉校验 #2202 语义保持且有「side request 不命中不污染指纹」测试 ✓;reap([Bug][proxy] unframed host-side history deletion leaves zombie fold blocks rendering carriers forever — one carrier flaps in/out every turn (persistent prefix-cache churn) #2695)仅 proxy mode 触发,与 plugin 车道指纹写入时序无交集 ✓;stats payload 纯追加键,既有键不变 ✓;result 形状新增可选 fastPath? 但所有调用点(prepare-openai.ts:157 等)是裸语句不消费返回值,无从破坏 ✓。高危模式(语义漂移/fail-fast 变吞错/阈值时序输出格式漂移):逐项不适用。
  6. 是否破坏缓存:不涉及——缓存/重试/增量游标/去重键均未触碰;快路径 plan 与全量早退字节等价,coverage 记录照跑,cache-ledger 输入不变。
  7. 是否改了设计方向:不转向。这是 Delta lane: native-mode clients send only deltas, server maintains full state + one-time fold, upstream receives snapsho | 增量车道:native 模式客户端只发增量,服务端全量维护+一次折叠,上游只收快照(#2926 的泛化) #3248 阶段 1 的本体、Incremental turns: POST /__bili/plugin/turn — native clients send only the delta (#3248) #3253 增量车道模式在 reconcile 侧的第一个实例([Tracking] SQLite-backed threads-lane compression (endgame for the #2884 cap) #2926 线程里定型的 incremental pattern 泛化到 native 车道),交付物定位与作者 Delta lane: native-mode clients send only deltas, server maintains full state + one-time fold, upstream receives snapsho | 增量车道:native 模式客户端只发增量,服务端全量维护+一次折叠,上游只收快照(#2926 的泛化) #3248 floor 5 自述一致:安全钩子(lockstep 钉死)+ 水位数据(per-lane hits/misses)。
  8. 是否引入了新的配置:无 env/config/CLI/header/新依赖。唯一新增面 = GET /__bili/stats payload 追加 incremental 键(process-local,per-lane hits/misses,不落盘),PR body 已披露,config-surface-guard CI 绿。

测试有效性(质量关)

lockstep 等价是真 property test,断言有牙(逐轮 byte-equality,bug 回归时必抓);gate 三 reason、side-request 非污染、非 lane 排除、损坏指纹静默回退且不计 miss 均单独钉住;链哈希单元覆盖确定性/顺序敏感/内容敏感/截断/NUL 边界。不是为测试而测试。

两个需要知道的预期(不是缺陷,避免日后误读)

  • 稳态命中率会集中在年轻会话:一旦某会话落下第一个 fold,其 covered ids 永久离开重发 wire ⇒ 此后每 pass unmatched>0 ⇒ clean=false sticky ⇒ 该会话快路径不再命中,稳态每轮记一条 dirty-predecessor(计数、日志去重)。真正受益面 = 首次压缩前的 append-only 增长窗口;已折叠长会话正是水位要测出来交给阶段 2(Incremental turns: POST /__bili/plugin/turn — native clients send only the delta (#3248) #3253)的人群。读 stats 时别把稳态低命中当 bug。
  • 理论残留风险(实践不可达,仅观测面):若 block 在 wire 字节稳定的前提下被带外激活、且其 covered id 长期 off-wire,快路径会跳过对这些「幻影 missing」的 drift bookkeeping 直到下一次 chain break。syncBlocks 是 wire 确定性的(kernel/src/sync.ts:active 状态每轮按 wire 存在性重算),该场景实际不可达;即便发生也只是观测缺口(无 unfold/无数据丢失/无缓存影响),下一次真实 churn 即恢复。

判定

可合,人工合并(§7.4 auto-merge 不适用:feat surface + 触碰 fold-reconcile identity 域,PR body 自述正确)。合并时机:等新 head 08f295e55 的 CI 转绿(与未合并的 #3253 在 admin.ts sendStats 一行的相邻问题仍按 PR body 说的处理:先合者为准,后者 rebase)。

@ranxianglei

Copy link
Copy Markdown
Owner Author

🤖 Powered by ework · qwen3.8-27b

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

补充一条:rebased head 08f295e55 的 CI 已全部跑完——41/41 check-run 全绿(ubuntu/windows × node 22/24 × 3 shards 全矩阵 + static-gates + e2e + registry e2e + codex/pi/dsh 真客户端车道 + config-surface-guard/lane-guard/docs-coverage),与旧 head 的结果一致。合并前置条件已齐,等你人工合并。

@ranxianglei ranxianglei changed the title feat: verified-incremental prefix fast path for plugin-lane fold reconcile (#3248 阶段 1) [PR] feat: verified-incremental prefix fast path for plugin-lane fold reconcile (#3248 phase 1) | [PR] feat: verified-incremental prefix fast path for plugin-lane fold reconcile (#3248 阶段 1) Oct 16, 2026
@ranxianglei

Copy link
Copy Markdown
Owner Author

(ai: zhipuai-lb/glm-5.3)

孤儿票清理:标题指向的 issue 已关闭,修复已由其他路径落地。关单;误判请 reopen。

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