Skip to content

fix(fork): close the derived-blocks gate only on real block adoption (#3351) - #3374

Merged
ranxianglei merged 1 commit into
masterfrom
2026-10-16_fork-weak-link-gate
Oct 17, 2026
Merged

ranxianglei merged 1 commit into
masterfrom
2026-10-16_fork-weak-link-gate

Conversation

@ranxianglei

Copy link
Copy Markdown
Owner

What & why

A weak-link (plugin-register) fork child permanently lost block inheritance when its registered parent had no folded blocks at first contact. In a multi-hop fork P→C→G, if grandchild G's first request missed the byte-exact prefix match (weak path) while intermediate parent C was still young (zero folds), maybeAdoptDerivedFork closed metadata.derivedBlocksAdopted = true unconditionally right after maybeAdoptResume. Because the request-time link lands exactly once (handle.ts gates that block on derivedFromSessionId === undefined), the prematurely-persisted marker made every later boot sweep (reconcileDerivedLineage) skip G — so G could never adopt the blocks C folded afterwards, and kept replaying its full raw history each turn (the #2807 "~480K session rejected as ~1.4M" symptom, recurring in a multi-hop topology).

Fix

maybeAdoptResume now returns { adoptedActive, seededRefs }, and maybeAdoptDerivedFork closes the gate only when adoptedActive > 0 — the same discipline reconcileDerivedLineage already applies (it sets the marker solely on a successful adoption). Ref-only seeding against a young, block-less parent leaves the door open so a later boot can adopt the blocks the parent folds afterwards.

Note: the issue's suggested close-condition was adoptedActive > 0 || seededRefs > 0. That would not fix the reported case — at first contact a young parent already has refs (so seededRefs > 0) but no blocks, so the gate would still close. Closing must track block adoption specifically (the flag is named derivedBlocksAdopted); mirroring the sweep's exact condition is what actually restores eligibility. This also matches the issue's stated principle ("share the same gating discipline as the boot sweep") more faithfully than the literal formula.

Behavior change (old → new)

  • Old: a weak-link child's derivedBlocksAdopted was set unconditionally at first contact, whether or not any block was adopted.
  • New: it is set only when at least one block is actually adopted; otherwise it stays unset (eligible for retry).
  • This is a relaxation (restores the intended fix(sessions): wire-neutral affinity hashing for cross-protocol continuity (#2791) #2807 per-boot convergence), not a tightening. No config/env surface change; no wire/message-shape, persistence-format, or kernel/ change.
  • Cost of the extra retries is negligible: the request-time path runs once per session anyway (gated externally on derivedFromSessionId === undefined), so the only added work is a cheap boot-sweep re-scan for children whose parent remains empty.

Tests

  • New regression tests in tests/derived-fork-block-inheritance.test.ts:
    • the gate stays OPEN when the registered parent has no blocks at first contact (refs-only inheritance still happens) — fails under the old unconditional set, passes now;
    • the gate CLOSES when the parent carries fully-present blocks (guards against over-correction).
  • Verified locally (targeted, per repo testing discipline): typecheck clean; derived-fork-block-inheritance 4/4; related suites fork-adoption-plan, fork-ccr-adoption, pi-omp-fork-adopt, lineage-reconcile-boot (AC9–AC12) all green (35/35). Full-suite verdict is the remote CI on this head.

Fixes #3351

…3351)

maybeAdoptDerivedFork set metadata.derivedBlocksAdopted = true unconditionally
right after maybeAdoptResume, even when the registered parent had zero folded
blocks at first contact. Because the request-time link lands exactly once
(handle.ts gates it on derivedFromSessionId === undefined), that prematurely-
persisted marker made every later boot sweep skip the session — so a multi-hop
grandchild whose intermediate parent was still young (no folds yet) permanently
lost block inheritance and kept replaying its full raw history (#2807 symptom
recurrence in a P->C->G topology).

maybeAdoptResume now returns { adoptedActive, seededRefs } and the gate closes
only when adoptedActive > 0 — the same discipline reconcileDerivedLineage
already applies (it sets the marker solely on a successful adoption). Ref-only
seeding against a young, block-less parent leaves the door open so a later boot
can adopt the blocks the parent folds afterwards.

Regression tests pin both directions: the gate stays OPEN when the registered
parent has no blocks at first contact (fails under the old unconditional set),
and CLOSES when the parent carries fully-present blocks.
@github-actions

Copy link
Copy Markdown
Contributor

📦 Built Package Artifact

Branch: 2026-10-16_fork-weak-link-gate (b7c090d)

Option A — Install this exact build (recommended)

npm install -g billion-context@0.0.3975-pr.3374.eb76cbc

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

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

查重:不重复。按本机制(弱链接 derivedBlocksAdopted 门关闭纪律)检索 open+closed issue 与 PR,无并行工作;最接近的 #3336/#3339 是测试侧重启时序竞态(已由 #3345 修复合入)、#3039 是 fork 首请求竞态——与本条症状、机制均不同。在途分支亦无针对本机制的改动。

方向判定(独立重核,非照抄 issue):原 issue #3351 方向正确,根因定位准确。我对 master 逐条复核了机制链:

  • src/server/handle.ts:1552-1561:弱链接记录与 maybeAdoptDerivedFork 同一次调用执行,由 derivedFromSessionId === undefined 门控——每会话只落一次;
  • 旧代码 src/fork-adoption.ts:384-387(master):调完 maybeAdoptResume 无条件置 derivedBlocksAdopted = true;
  • boot sweep reconcileDerivedLineage 见到标记直接 skip,而它自己只在成功采纳(plan.adoptedActive > 0)后置标记——两条路径纪律不一致即为本 bug。
    另核实了修复闭环成立的关键前提:planForkAdoption 的 includeBlocks 默认 true,sweep 重试时确实会采块(不是只采 refs),「留门→后续 boot 采纳」链路端到端有效。
    一个关键点:issue 建议的关条件 adoptedActive > 0 || seededRefs > 0 其实修不好这个 bug——首触时年轻父会话已有 refs(seededRefs > 0)但无块,按该条件门照样关。PR 采用仅 adoptedActive > 0,与 sweep 既有纪律一致,是正确选择;我用下面的回归测试实测确认了这个判断。

回归审查(既有行为逐项):

既有行为 结论
强路径(#1486 resume 继承,handle.ts:1520 调 maybeAdoptResume) 保持——返回类型 void→{adoptedActive, seededRefs},调用方忽略返回值,逻辑未动
匿名 fork(#629 maybeAdoptForkBlocks) 未触碰
boot sweep(reconcileDerivedLineage) 一行未动——本 PR 是把请求时路径对齐到它的纪律,不是反向
refs-only 继承(对年轻父会话仍发生 refs 播种) 保持——只改关门条件,播种逻辑不变;新测试第 3 条专门钉住这点
catch 分支(采纳抛错→继续 fresh、不置标记) 保持——新旧语义一致(抛错时标记本来就不会被置)
持久化格式 / wire / 配置面 无变化——无新字段、无新 env/config;标记只是有时不置位,而「不置位」本就是 sweep 一直产生的形态
高危模式逐项过:无 fail-fast 变吞错、无阈值/时序漂移;输出面仅新增一条 info 日志(additive)。

代码与测试有效性:

  • diff 干净:2 文件 1 commit(src/fork-adoption.ts +24/-8;tests/derived-fork-block-inheritance.test.ts +90/-1),每行都与目的相关;分支与 master 同步(base = master HEAD),mergeable。
  • 新接口 AdoptionOutcome { adoptedActive, seededRefs } 命名达意;注释讲「为什么留门」,与仓库风格一致;无死代码、无魔法值。
  • 测试有牙:我独立做了反证实验——把修复前的 fork-adoption.ts 换回跑新测试文件,「gate stays OPEN」如预期失败(3/4);恢复 PR 代码后 4/4 通过。重启收敛的端到端由 lineage-reconcile-boot 的 AC12(多跳孙会话在中间父为空时保持 eligible)兜底。
  • 本地定向验证(按仓库测试纪律,全量以 CI 为准):derived-fork-block-inheritance 4/4;相关套件 fork-adoption-plan + fork-ccr-adoption + pi-omp-fork-adopt + lineage-reconcile-boot 共 35/35 绿。

CI:head b7c090d 远程 CI 全绿(static-gates、ubuntu/windows × node 22/24 共 6 个 test shard、kernel-guard、config-surface-guard、docs-sync、version-guard、pi-subagents-guard、build-artifact 等全部 success;real-client e2e lane 按环境门控 skipped,属正常)。

结构化八问

  1. 是什么问题:多跳 fork(P→C→G)里,孙会话 G 首次请求未命中字节级强匹配(走弱链接路径)且注册父 C 当时还没有折叠块时,G 的块继承资格被永久关掉——之后 C 再怎么折叠 G 都采不到,每轮继续重放全量原始历史(fix(sessions): wire-neutral affinity hashing for cross-protocol continuity (#2791) #2807「~480K 被当 ~1.4M 拒绝」在多跳拓扑下的复发形态)。
  2. 什么原因导致的:弱链接路径在首触时无条件关门(无论是否采到块),而「记链接」与「关门」同生共死、每会话只跑一次;提前落盘的门标记让此后每次 boot sweep 直接跳过。根因 = 两条采纳路径的关门纪律不一致(sweep 只在真实采纳后关门,请求时路径无条件关门)。
  3. 影响范围与严重程度:所有插件宿主的 identified-fork 多跳场景(dsh/opencode/pi 的 RLM/subagent 拓扑);单跳且父已有块的常规 fork 不受影响。严重度 = 特定条件下继承能力完全丢失(非数据丢失,只读 decompress/search 回退仍可用),下游后果是上下文持续膨胀直至上游超限拒绝。
  4. 怎么修复的:maybeAdoptResume 返回 { adoptedActive, seededRefs },maybeAdoptDerivedFork 仅在 adoptedActive > 0 时关门——把弱链接路径对齐到 boot sweep 已实现的正确纪律;refs-only/无块场景留门,后续 boot 自然重试。刻意未用 issue 字面公式(|| seededRefs > 0),理由见上(那个公式修不好本 bug)。
  5. 是否有回归问题:没有。既有行为逐项判定见上表;本地定向验证 + 远程 CI 全量绿。
  6. 是否破坏缓存:不涉及——未触碰缓存/重试/增量游标/去重键。
  7. 是否改了设计方向:不涉及——一致性缺陷修复,把两条本应一致的路径对齐到既有正确纪律,数据流不变。
  8. 是否引入了新的配置:不涉及——无新 env/config/默认值。

行为变更披露(旧→新):旧 = 弱链接子会话首触即无条件关 derivedBlocksAdopted 门;新 = 仅当真正采到 ≥1 个块才关门,否则保持 eligible 供后续 boot 重试。性质:放宽(恢复 #2807 预期的每 boot 收敛),不是收紧;代价仅是「父长期为空」的子会话每次 boot 多一次轻量父会话扫描。PR 正文已披露。

收工判定:可合入。一个决策点提请 owner:原 issue #3351 标注「需 owner 拍板——属行为变更」,本修复为放宽且已完整披露,合并即视为批准该关条件;若坚持 issue 字面公式一行即可回退,但该公式修不好本 bug,不建议。

@ranxianglei
ranxianglei merged commit 269accd into master Oct 17, 2026
40 checks passed
@github-actions

Copy link
Copy Markdown
Contributor

📦 Merged Build Published

This merge to master was published as 0.0.510-master.269accd (rolling master tag).

npm install -g billion-context@0.0.510-master.269accd  # 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.

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

Labels

None yet

Projects

None yet

1 participant