Skip to content

feat(#2394): raise fork-snapshot retention default from 16 MiB to 100 MiB - #2433

Merged
ranxianglei merged 2 commits into
masterfrom
2026-10-08_snapshot-cap-100mib
Oct 9, 2026
Merged

ranxianglei merged 2 commits into
masterfrom
2026-10-08_snapshot-cap-100mib

Conversation

@ranxianglei

Copy link
Copy Markdown
Owner

What / why

#2394 G3: the public fork API retains a raw wire-history snapshot per plugin session so a forked child can be adopted onto it (identity-hash prefix match). Sessions whose serialization exceeds the cap fail closed (409 SNAPSHOT_UNAVAILABLE) and degrade to a bare fresh session + full raw replay.

The 16 MiB default sits BELOW real long-session sizes: in the incident behind #2383 a ~5M-token dsh session serialized to ~20MB+, so fork adoption could never apply there — every fork degraded to raw replay, which is what fed the preflight storm (#2387 stops that storm at the bottom as the shared degrade backstop).

Owner instruction in the #2383 thread (sign-off for this default change): "调大吧 调成100M?" — this PR implements exactly that: default 16 MiB → 100 MiB.

config surface

Default-value change ONLY:

  • plugin.snapshotCapBytes (config file) / BILI_PUBLIC_SNAPSHOT_CAP_BYTES (env) — fallback tier moves from 16 MiB to 100 MiB.
  • NO new keys, fields, or env vars. Override precedence (env > file > default) unchanged. No migration: anyone who set an explicit override keeps their value.
  • Considered alternatives: leaving 16 MiB and documenting "set the env" (rejected — L0 fork adoption must work out-of-box for long sessions, and the incident proves 16 MiB is below reality); unbounded retention (rejected — the fail-closed bound is the point of feat(plugin): expose isolated forks and attributed context observations #2017 D-B).
  • Why 100 MiB: bounded worst case preserved, ~5× headroom over the largest observed incident session (~20MB+), covers multi-million-token forks with margin.

behavior change (old → new)

  • OLD: any plugin session whose snapshot exceeded 16 MiB was un-forkable (409) → forks degraded to raw replay.
  • NEW: same boundary raised to 100 MiB.
  • Cost: worst-case retained snapshot memory/disk per very-long plugin session ≤ ~100 MB (was ≤ ~16 MB). Fail-closed semantics, 0 = disable-retention, and env parsing are byte-identical otherwise.

tests

  • tests/knobs-config-precedence.test.ts re-pinned to the new default (11/11 green locally)
  • npm run typecheck clean
  • grep audit: zero residual 16 MiB references for the snapshot cap across en/zh docs; the unrelated fakeCompletion.bufCapBytes literal sharing the old value is untouched

@ranxianglei

Copy link
Copy Markdown
Owner Author

🤖 Powered by ework · qwen3.8-27b

[bot] 🏷 收到。这是 #2394 G3 的默认值变更 PR(16 MiB → 100 MiB),已定位到 PR 分支 2026-10-08_snapshot-cap-100mib(1 commit / 5 files / +20 -17)。开始按 review 规范审查:原 issue 方向(#2394/#2383)、diff、CI、回归面。结论稍后按八问体例回复。

@github-actions

github-actions Bot commented Oct 8, 2026 •

Copy link
Copy Markdown
Contributor

📦 Built Package Artifact

Branch: 2026-10-08_snapshot-cap-100mib (672fa84)

Option A — Install this exact build (recommended)

npm install -g billion-context@0.0.2648-pr.2433.9ce61d1

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

Install instructions are refreshed on each push.

… MiB

#2394 G3. The public fork API retains a raw wire-history snapshot per
plugin session for adopt-on-fork; sessions whose serialization exceeds
the cap fail closed (409 SNAPSHOT_UNAVAILABLE) and degrade to a bare
fresh session + full raw replay. The 16 MiB default sits below real
long-session sizes — the #2383 incident's ~5M-token dsh session
serialized to ~20MB+, so fork adoption could never apply there and
every fork degraded to raw replay (the storm #2387 stops at the bottom).

Owner instruction in the #2383 thread (sign-off for this default change):
"调大吧 调成100M?" — implemented exactly as asked.

config surface: default-value change ONLY. plugin.snapshotCapBytes /
BILI_PUBLIC_SNAPSHOT_CAP_BYTES fallback tier moves 16 MiB -> 100 MiB;
no new keys/fields/env vars, override precedence unchanged, no migration
(explicit overrides keep their values). 100 MiB keeps the #2017 D-B
fail-closed bound while giving ~5x headroom over the largest observed
incident session.

behavior change: OLD un-forkable above 16 MiB -> NEW un-forkable above
100 MiB; worst-case retained snapshot per very-long plugin session
<= ~100 MB (was <= ~16 MB). '0' = disable-retention and env parsing are
unchanged.
@ranxianglei

Copy link
Copy Markdown
Owner Author

🤖 Powered by ework · qwen3.8-27b

[bot] 🏷 PR #2433 审查完成 — 方向正确、实现干净;发现并顺手修掉 1 个会挂 CI 的遗漏。结论:CI 绿后可合(需人工合并)。

结构化八问

  1. 是什么问题:fork 协议快照保留上限默认 16 MiB,低于真实长会话规模(DSH 分叉会话后触发大量 preflight overflow compress #2383 事故中 ~5M-token dsh 会话序列化 >20MB)——这类会话的 fork 一律 409 SNAPSHOT_UNAVAILABLE 降级为全量 raw replay。本 PR 按 owner 指示(DSH 分叉会话后触发大量 preflight overflow compress #2383 线程「调大吧 调成100M?」)把默认值提到 100 MiB(全景:派生会话(fork / resume / 子代理 / 辅助人格)的会话身份治理 — 现状盘点与缺口 #2394 G3)。
  2. 什么原因导致的:16 MiB 是 feat(plugin): expose isolated forks and attributed context observations #2017 D-B 定 fail-closed 边界时的初始标定,当时没有长会话数据;L0 fork adoption 落地后(feat(#2399): adopt dsh fork-child state via the plugin fork protocol #2403/feat(#2408): declare claude --fork-session lineage for scoped resume inheritance #2409)真实消费方暴露了上限低于现实。属默认值标定问题,不是代码缺陷。
  3. 影响范围与严重程度:受影响面 = 所有序列化快照 >16 MiB 的 plugin 模式长会话;此前其 fork 只能降级 raw replay(功能可用、丧失继承收益)。特定条件下的功能降级,无数据丢失/崩溃面。
  4. 怎么修复的:只动 src/knobs.ts publicSnapshotCapBytes() 的 fallback 常量 16_777_216 → 104_857_600,同步注释与 en/zh 文档、重钉测试断言。解析链(env > file > default)、NaN/负数回退、空串→0 的历史 quirk、fail-closed 409 语义逐字节未变。
  5. 是否有回归问题:逐项审过——显式 env/file 覆盖不受影响(无需迁移)✅;0=禁用保留路径不变 ✅;cap 每个 plugin 请求重新求值(会话缩回上限内自动恢复 forkable)✅;同值无关字面量 fakeCompletion.bufCapBytes(16 MiB)有意不动 ✅。本地定向验证:tests/knobs-config-precedence.test.ts 9/9 + tests/plugin-fork.test.ts 43/43 全绿(含超 cap 409 集成用例)。无回归。
  6. 是否破坏缓存:不涉及——前缀缓存/重试/去重键均不受影响;快照是 fork 协议独立保留对象。
  7. 是否改了设计方向:否。fail-closed 有界保留设计(feat(plugin): expose isolated forks and attributed context observations #2017 D-B)原样保留,只抬高界值;「无界保留」与「留 16 MiB 靠用户设 env」两个备选已在 PR 正文说明否决理由。
  8. 是否引入新配置:无新 key/env。仅既有 plugin.snapshotCapBytes / BILI_PUBLIC_SNAPSHOT_CAP_BYTES 的 fallback 层移动,优先级链不变。

⚠️ 行为变更披露(旧→新):单个超长 plugin 会话最坏保留快照 ≤ ~16 MB → ≤ ~100 MB(内存/磁盘)。有界、有意为之、owner 已批准(PR 正文已披露,与本审查一致)。

🔧 顺手修复(review 中发现的小问题):PR 更新了 CONFIGURATION.md(en/zh)中的生成区表格行,但漏改源头种子 website/config-reference/process.yaml(default 仍为 "16777216 …"、site_en/site_zh 仍写 16 MiB)——CI 的 docs-sync job(node tools/gen-config-docs.mjs generate 漂移检查)必红,本地复现确认(generator 会把两个 md 的 4 行表格打回 16777216)。已在 PR 分支直接补一个独立标注 commit 修掉:672fa845f fix(docs): sync config-reference seed with raised snapshot cap default (#2433)——种子 3 行 + 重新生成的 website/main.js、website/docs/index.html,共 6 行;修后 generator 输出与 PR 提交的 md 完全一致,零漂移,两份定向测试套件在新 head 上 52/52 全绿。

可合并性核查:分支已 rebase 到当前 master(f8bd942bc),零冲突;不触碰 kernel/、src/update.ts、wire/message shape;回归测试已钉住新默认值。按 §7.4 第 8 条,默认值/fallback 变更属产品决策,不走 auto-merge,需人工合并。等 CI 转绿即可合:#2433

@ranxianglei
ranxianglei merged commit 9129c68 into master Oct 9, 2026
24 checks passed
@github-actions

github-actions Bot commented Oct 9, 2026

Copy link
Copy Markdown
Contributor

📦 Merged Build Published

This merge to master was published as 0.0.164-master.9129c68 (rolling master tag).

npm install -g billion-context@0.0.164-master.9129c68  # 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.

@github-actions github-actions Bot mentioned this pull request Oct 9, 2026
ranxianglei pushed a commit that referenced this pull request Oct 13, 2026
…VAILABLE (#3011)

Client (src/agent/fork-adopt.ts): classify degraded outcomes by structured
verdict instead of a reason-string regex. The regex only matched 'error' /
'http 5xx', so the incident's 'snapshot http 409 SNAPSHOT_UNAVAILABLE' was
treated as terminal after ONE attempt and the child's inheritance was
permanently abandoned in-process. Each result now carries an explicit
retryable flag: snapshot GET retries on network errors, HTTP >=500, and
409 code SNAPSHOT_UNAVAILABLE (a residency gap that self-heals on the
parent's next request); 404 PARENT_NOT_FOUND and other 4xx stay terminal.
Fork POST classification unchanged (network/5xx retryable). Give-up now
logs an explicit 'permanently disabled' line distinct from the transient
'will retry' line.

Server (src/plugin.ts): new forkSourceMessages() selects the raw source
view. The retained copy (pluginSnapshot) stays primary; when it is missing
(the residency gap: LRU eviction or host restart losing an unpersisted
copy) the recent raw view session.lastMessages is served instead — it is
persisted unconditionally and re-stamped by every parent request. A
head-divergent tail wins over a frozen pre-compaction retained copy
(zero-overlap guard case), so the served identities survive native
compaction rebases. Folded tails never serve. The retention-cap refusal
(#2433) stays first. Fork materialization uses the same selection, so a
zero-branchpoint child keeps its legitimate empty snapshot.

Server (src/session.ts): resetSessionCompression clears the stale
publicSnapshot* metadata so a rebased parent cannot fail the list-level
stored-refs check against the old view.
ranxianglei pushed a commit that referenced this pull request Oct 13, 2026
…VAILABLE (#3011)

Client (src/agent/fork-adopt.ts): classify degraded outcomes by structured
verdict instead of a reason-string regex. The regex only matched 'error' /
'http 5xx', so the incident's 'snapshot http 409 SNAPSHOT_UNAVAILABLE' was
treated as terminal after ONE attempt and the child's inheritance was
permanently abandoned in-process. Each result now carries an explicit
retryable flag: snapshot GET retries on network errors, HTTP >=500, and
409 code SNAPSHOT_UNAVAILABLE (a residency gap that self-heals on the
parent's next request); 404 PARENT_NOT_FOUND and other 4xx stay terminal.
Fork POST classification unchanged (network/5xx retryable). Give-up now
logs an explicit 'permanently disabled' line distinct from the transient
'will retry' line.

Server (src/plugin.ts): new forkSourceMessages() selects the raw source
view. The retained copy (pluginSnapshot) stays primary; when it is missing
(the residency gap: LRU eviction or host restart losing an unpersisted
copy) the recent raw view session.lastMessages is served instead — it is
persisted unconditionally and re-stamped by every parent request. A
head-divergent tail wins over a frozen pre-compaction retained copy
(zero-overlap guard case), so the served identities survive native
compaction rebases. Folded tails never serve. The retention-cap refusal
(#2433) stays first. Fork materialization uses the same selection, so a
zero-branchpoint child keeps its legitimate empty snapshot.

Server (src/session.ts): resetSessionCompression clears the stale
publicSnapshot* metadata so a rebased parent cannot fail the list-level
stored-refs check against the old view.
ranxianglei pushed a commit that referenced this pull request Oct 13, 2026
…VAILABLE (#3011)

Client (src/agent/fork-adopt.ts): classify degraded outcomes by structured
verdict instead of a reason-string regex. The regex only matched 'error' /
'http 5xx', so the incident's 'snapshot http 409 SNAPSHOT_UNAVAILABLE' was
treated as terminal after ONE attempt and the child's inheritance was
permanently abandoned in-process. Each result now carries an explicit
retryable flag: snapshot GET retries on network errors, HTTP >=500, and
409 code SNAPSHOT_UNAVAILABLE (a residency gap that self-heals on the
parent's next request); 404 PARENT_NOT_FOUND and other 4xx stay terminal.
Fork POST classification unchanged (network/5xx retryable). Give-up now
logs an explicit 'permanently disabled' line distinct from the transient
'will retry' line.

Server (src/plugin.ts): new forkSourceMessages() selects the raw source
view. The retained copy (pluginSnapshot) stays primary; when it is missing
(the residency gap: LRU eviction or host restart losing an unpersisted
copy) the recent raw view session.lastMessages is served instead — it is
persisted unconditionally and re-stamped by every parent request. A
head-divergent tail wins over a frozen pre-compaction retained copy
(zero-overlap guard case), so the served identities survive native
compaction rebases. Folded tails never serve. The retention-cap refusal
(#2433) stays first. Fork materialization uses the same selection, so a
zero-branchpoint child keeps its legitimate empty snapshot.

Server (src/session.ts): resetSessionCompression clears the stale
publicSnapshot* metadata so a rebased parent cannot fail the list-level
stored-refs check against the old view.
ranxianglei pushed a commit that referenced this pull request Oct 14, 2026
…VAILABLE (#3011)

Client (src/agent/fork-adopt.ts): classify degraded outcomes by structured
verdict instead of a reason-string regex. The regex only matched 'error' /
'http 5xx', so the incident's 'snapshot http 409 SNAPSHOT_UNAVAILABLE' was
treated as terminal after ONE attempt and the child's inheritance was
permanently abandoned in-process. Each result now carries an explicit
retryable flag: snapshot GET retries on network errors, HTTP >=500, and
409 code SNAPSHOT_UNAVAILABLE (a residency gap that self-heals on the
parent's next request); 404 PARENT_NOT_FOUND and other 4xx stay terminal.
Fork POST classification unchanged (network/5xx retryable). Give-up now
logs an explicit 'permanently disabled' line distinct from the transient
'will retry' line.

Server (src/plugin.ts): new forkSourceMessages() selects the raw source
view. The retained copy (pluginSnapshot) stays primary; when it is missing
(the residency gap: LRU eviction or host restart losing an unpersisted
copy) the recent raw view session.lastMessages is served instead — it is
persisted unconditionally and re-stamped by every parent request. A
head-divergent tail wins over a frozen pre-compaction retained copy
(zero-overlap guard case), so the served identities survive native
compaction rebases. Folded tails never serve. The retention-cap refusal
(#2433) stays first. Fork materialization uses the same selection, so a
zero-branchpoint child keeps its legitimate empty snapshot.

Server (src/session.ts): resetSessionCompression clears the stale
publicSnapshot* metadata so a rebased parent cannot fail the list-level
stored-refs check against the old view.
@ranxianglei
ranxianglei deleted the 2026-10-08_snapshot-cap-100mib branch October 15, 2026 05:32
ranxianglei pushed a commit that referenced this pull request Oct 24, 2026
…VAILABLE (#3011)

Client (src/agent/fork-adopt.ts): classify degraded outcomes by structured
verdict instead of a reason-string regex. The regex only matched 'error' /
'http 5xx', so the incident's 'snapshot http 409 SNAPSHOT_UNAVAILABLE' was
treated as terminal after ONE attempt and the child's inheritance was
permanently abandoned in-process. Each result now carries an explicit
retryable flag: snapshot GET retries on network errors, HTTP >=500, and
409 code SNAPSHOT_UNAVAILABLE (a residency gap that self-heals on the
parent's next request); 404 PARENT_NOT_FOUND and other 4xx stay terminal.
Fork POST classification unchanged (network/5xx retryable). Give-up now
logs an explicit 'permanently disabled' line distinct from the transient
'will retry' line.

Server (src/plugin.ts): new forkSourceMessages() selects the raw source
view. The retained copy (pluginSnapshot) stays primary; when it is missing
(the residency gap: LRU eviction or host restart losing an unpersisted
copy) the recent raw view session.lastMessages is served instead — it is
persisted unconditionally and re-stamped by every parent request. A
head-divergent tail wins over a frozen pre-compaction retained copy
(zero-overlap guard case), so the served identities survive native
compaction rebases. Folded tails never serve. The retention-cap refusal
(#2433) stays first. Fork materialization uses the same selection, so a
zero-branchpoint child keeps its legitimate empty snapshot.

Server (src/session.ts): resetSessionCompression clears the stale
publicSnapshot* metadata so a rebased parent cannot fail the list-level
stored-refs check against the old view.
ranxianglei pushed a commit that referenced this pull request Nov 7, 2026
…flict fix)

Conflict resolved by union of intent on the 409 SNAPSHOT_UNAVAILABLE path:
- #3011 raw-view picker (retained copy -> recent raw tail, head-divergence rule)
  gains master's verified storage reconstruction as the last rung;
- master's recon diagnostics (gate-named [reconstruction: ...] suffix,
  waitForReconstructionReplicas) kept verbatim;
- #2433 retention cap stays a hard refusal even when a fresh view exists;
- #4266 signed-thinking acceptance adopted (thinkingTokens rejection dropped);
- fork handler serves child baseline from the SAME picked source view
  (identity-derived fromTail keeps CCR bookkeeping fail-closed);
- test hunk takes master's strict 200 assertion (reconstruction makes the
  cold-restore scenario deterministically servable under unified-full).
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