Skip to content

[PR] docs: record the memory & render three-mechanism stack (#4788/#3756/#5418) + correct stale droppable-fields text - #5475

Open
ranxianglei wants to merge 3 commits into
masterfrom
2026-11-01_memory-render-doctrine-docs
Open

ranxianglei wants to merge 3 commits into
masterfrom
2026-11-01_memory-render-doctrine-docs

Conversation

@ranxianglei

Copy link
Copy Markdown
Owner

三层成本来源(生产/呼吸/组装)此前散落在代码注释与各自的 issue 里,#5403 的讨论过程证明混读会带偏 triage。本 PR 只写文档,不动任何代码/配置语义:

config surface:无新增/改名/改语义字段,仅文档措辞更正与补齐。

References #5474 (p1, disk-proof gate 缺陷跟踪)、#5403、#5469。

@github-actions

github-actions Bot commented Nov 1, 2026 •

Copy link
Copy Markdown
Contributor

📦 Built Package Artifact

Branch: 2026-11-01_memory-render-doctrine-docs (186fe8b)

Latest build — install this exact version

npm install -g billion-context@0.0.8938-pr.5475.23c4e27

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
186fe8b billion-context@0.0.8938-pr.5475.23c4e27 build
4480ed6 billion-context@0.0.7761-pr.5475.8182994 build
2d10415 billion-context@0.0.7749-pr.5475.18a2a13 build
eb3a55d billion-context@0.0.7740-pr.5475.57454e0 build

Download artifact

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

Install instructions are refreshed on each push.

@ranxianglei ranxianglei changed the title docs: record the memory & render three-mechanism stack (#4788/#3756/#5418) + correct stale droppable-fields text [PR] docs: record the memory & render three-mechanism stack (#4788/#3756/#5418) + correct stale droppable-fields text Nov 1, 2026
@ranxianglei
ranxianglei force-pushed the 2026-11-01_memory-render-doctrine-docs branch from eb3a55d to 2d10415 Compare November 1, 2026 15:22
ranxianglei pushed a commit that referenced this pull request Nov 1, 2026
…in the three-mechanism section — the storage.unified default went full in v0.1.203 (the #3818 flip, shipped via #3819), not v0.1.210
ranxianglei pushed a commit that referenced this pull request Nov 1, 2026
…order-safe — KDD #15 lands with PR #5469 itself, so name that PR explicitly
@ranxianglei

Copy link
Copy Markdown
Owner Author

🤖 Powered by ework · qwen3.8-27b

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

查重:不重复——本线程是 [PR] 审核帖(对应 GitHub PR #5475),检索 open/closed issue 与近期 PR 无并行的同类文档工作项;本 PR 本身即 #5474/#5403/#5418 讨论的文档收敛产物。

标签:scope/docs + p3(纯文档 PR,措辞更正与补齐,无行为影响)。

审核结论:可合(等 CI 绿)

逐条核对了新节与 CONFIGURATION 更正在代码/版本线上的每一处事实断言,发现 1 处事实错误 + 1 处悬空引用,均已直接修进 PR 分支(两个独立标注 commit,见下)。其余断言全部验证通过:

断言 核对结果
插件车道设计性绕过,src/server/snapshot-render.ts:501 ✅ 逐字吻合(plugin lane: client-authoritative by design, not a degradation)
D2 全局门 durableRevision === revisionEpoch ✅ src/persist.ts:3110,runIdleSpill(:3102)入口即判;逃生门 contentStorePinned()(:3306)存在
#4788 shipped v0.1.210 ✅ hardMaxBytes 在 v0.1.209 不存在、v0.1.210 起在 config/knobs 出现
#3756 v0.1.210、rollout snapshotRender 默认 0% ✅ v0.1.210 已有 snapshot-render;与 AGENTS.md KDD #13 一致
×5 credited mismatches ⇒ 1 h breaker、§7.4 人工评审 ✅ 与 #5469 的 KDD #15 原文一致
storage.unified「v0.1.210 起默认 full」 ❌ 错。逐 tag 核代码:v0.1.202 fallback 仍 shadow,v0.1.203 起 full —— 翻转实际随 v0.1.203 发布(#3818 跟踪、#3819 合入),不是 v0.1.210
「AGENTS.md KDD #15」引用 ⚠️ 悬空。master 的 AGENTS.md KDD 只到 #14,#15 随 PR #5469 才合入;本 PR 若先合并,读者按图索骥落空

已推送到 PR 分支(rebase 到当前 master 760c24c55;master 新增提交均为 release/CI 面,不触碰这四个文档文件,干净 rebase):

分支头现为 2d10415e0。CI:审核时旧头 eb3a55dda 的测试分片在跑(未见红);推送后在新头上重跑,全量判定以远程 CI 为准。

结构化八问

  1. 是什么问题:三层成本来源(生产/呼吸/组装)此前散落在各自 issue 与代码注释里,[Bug][dsh] 20k-message / 81 MiB-inbound session: host aborted 6× in 2 h — the #3050 resident-AST OOM is not bounded by sessions.hardMaxBytes (Windows, 0.1.210) #5403 的讨论证明混读会带偏 triage;本 PR 把三者合记一处,并顺手修掉 CONFIGURATION.md 一句过期描述。
  2. 什么原因导致的:非缺陷,是文档缺口——三个机制各有独立 issue([Performance] v0.1.208 long sessions exceed 2 GiB memory and spend 14–22 seconds in local processing #4788/Snapshot rendering: proxy-lane outbound is now rendered authoritatively server-side; existing sessions are immune to ker | 快照渲染:proxy 车道出站从服务端正史渲染,存量会话对内核升级免疫(#3752 根治) #3756/[Bug][dsh] Plugin lane performs a full re-parse and resends the entire body every round (81 MiB → hundreds of MB AST), w | [Bug][dsh] plugin 车道每轮全量解析重发 body(81 MiB→数百 MB AST)是 #5403 OOM 的生产者:用水位线断言替换逐条复核,服务端只解析新增尾段 #5418),从无单一分层对照;「content store non-droppable by design」一句在 [Performance] v0.1.208 long sessions exceed 2 GiB memory and spend 14–22 seconds in local processing #4788 phase 2 改变语义后未跟进。
  3. 影响范围与严重程度:纯文档,零运行时影响;严重度仅内部实现/文档准确性。过期句会让读者误以为 content store 永远不可卸载(体验级误导,有 sessions.contentStorePin 逃生门可用但被旧文案掩盖)。
  4. 怎么修复的:TECHNICAL-NOTES(en/zh)新增「三层三机制」节——分层对照表(层/动作时机/省什么/车道/失败形态/信任模型变化)+ 各机制要点 + 叠加关系与关闭 [Bug][dsh] 20k-message / 81 MiB-inbound session: host aborted 6× in 2 h — the #3050 resident-AST OOM is not bounded by sessions.hardMaxBytes (Windows, 0.1.210) #5403 的两条腿;CONFIGURATION.md 重写 HARD_MAX_BYTES 说明块(phase 2 起可卸 + 逃生门 + 已知局限指向 [Bug][dsh] #4788 D2 disk-proof gate never aligns while saves keep lagging — hard-cap warning fires but reclaim stays zero (#5403 symptom 1) #5474);zh-CN 补缺行使 en/zh 对齐。
  5. 是否有回归问题:diff 只碰 4 个 .md,无代码/配置/wire/持久化变更,逐项过既有行为:保持。唯一语义变更是 CONFIGURATION.md 既有行的措辞更正(旧值「non-droppable by design」→ 新值「[Performance] v0.1.208 long sessions exceed 2 GiB memory and spend 14–22 seconds in local processing #4788 phase 2 起可卸,逃生门 sessions.contentStorePin」),属有意修正且与 persist.ts 实际代码一致——已按行为变更披露规则在此明示。
  6. 是否破坏缓存:不涉及。
  7. 是否改了设计方向:不涉及(仅记录既有设计)。
  8. 是否引入了新的配置:无(PR 声明已核实:无新增/改名/改语义字段)。

收工判定:内容正确性已过审(含两处勘误修复),等新头 CI 绿即可由 owner 合并;agent 不合并不关单。

ranxianglei pushed a commit that referenced this pull request Nov 1, 2026
…o full via #3818 flip, not legacy) — docs-consistency nit on #5475
@ranxianglei

Copy link
Copy Markdown
Owner Author

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

APPROVE — docs-only PR, and every load-bearing claim was re-verified against origin/master code (not just the diff):

Correctness (verified, not assumed)

Behavior / regression: none — pure wording correction + missing-row completion + a new doctrine section; no logic / config-semantics / wire change. config-surface-guard, docs-sync, kernel-guard, version-guard all green. No kernel/ touched → no authorization gate.

已顺手修:src/config.ts:2037 的 storage.unified JSDoc 旧注释写「absent/invalid falls back to legacy」,与真实默认(absent→full,#3818 翻转)以及本 PR 新增节自己的断言矛盾;改为「invalid→legacy,absent everywhere→full」。纯注释、零行为。commit 4480ed6


记录为评论而非正式 Approve 按钮:GitHub 禁止批准自己开的 PR(本 PR 作者即执行审查的账号)。上方结论 APPROVE 有效,待 owner 正式 approve/merge。

@ranxianglei

Copy link
Copy Markdown
Owner Author

🤖 Powered by ework · qwen3.8-27b

(ai: vllm-qwen/qwen3.8-27b) review-worker-r1 独立终审完毕:APPROVE。逐条重核了全部事实断言并对照 origin/master 代码(非只看 diff)——四字段单门 durableRevision !== (revisionEpoch ?? 0)(persist.ts:3110)、phase-2 content store 可卸 + contentStorePinned() 逃生门、state 常驻、snapshotRender 默认 0%(rollout.ts:81)、插件车道绕过逐字落在 snapshot-render.ts:501、#4788 shipped v0.1.210(v0.1.209 无 / v0.1.210 有);前轮已修的两处(storage 翻转版本 v0.1.203、KDD #15「随 PR #5469 合入」)现均正确。另发现并顺手修掉一处前轮漏掉的矛盾旧注释:src/config.ts:2037 的 storage.unified JSDoc 写「absent→legacy」,与真实默认(absent→full,#3818 翻转)及本 PR 新增节自己的断言相悖,已改为「invalid→legacy / absent everywhere→full」——纯注释零行为,commit 4480ed615 已推分支头(现 head 4480ed615)。无 kernel/ 触碰、无行为/配置面/wire 变更,config-surface-guard / docs-sync / kernel-guard / version-guard 全绿。因 GitHub 禁止批准自己开的 PR,APPROVE 结论已以评论形式记在 GitHub PR #5475(comment 6560403875),待 owner 正式 approve/merge。

@ranxianglei

Copy link
Copy Markdown
Owner Author

🤖 Powered by ework · qwen3.8-27b

(ai: vllm-qwen/qwen3.8-27b) 这条是我上面那条 APPROVE 审查结论经 upstream-sync 回灌到本线程的镜像,不是新指令。状态不变:终审完成、APPROVE,顺手修 commit 4480ed615 已在分支头(现 head 4480ed615),无 kernel/行为/配置面变更;reviewer 侧无待办,等 owner 正式 approve/merge。

@ranxianglei
ranxianglei force-pushed the 2026-11-01_memory-render-doctrine-docs branch from 4480ed6 to 186fe8b Compare November 10, 2026 12:57
@ranxianglei

Copy link
Copy Markdown
Owner Author

🤖 Powered by ework · qwen3.8-27b

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

Conflict resolved & pushed (attempt 1/3). Branch 2026-11-01_memory-render-doctrine-docs rebased onto current master (4dea18eabf, which includes the ci-fixes merge #6073); force-pushed 4480ed61… → 186fe8bf. Live-verified after push: mergeable: true, state blocked (checks re-running on the new head) — the dirty state is gone. Remote head was unchanged before my push, so no concurrent-work integration was needed.

Why it conflicted. The branch was cut 2026-11-01 at 760c24c5 and edited four ROOT-level docs. Since then master moved them into docs/ (centralization commit 05bb1dc9, owner ruling #5920, 2026-11-08), leaving one-line redirect stubs at the old paths — modify/modify conflicts on all four files. A second divergence: #5779 (merged 2026-11-06) raised the resident budget default 512 MiB → 4 GiB inside the exact env-var row this PR rewrites.

How each hunk landed (all in the relocation commit 186fe8bf):

No behavior change: comment-only code edit + documentation text. No config surface, wire, or persistence touched. Check states come from the mirror cache (its entry for this PR pre-dates today, so I live-read PR state once via the API rather than assert from memory); CI verdict on the new head is still pending — if any lane goes red, the next auto-fix attempt handles it.


七问(CI 冲突处理)

  1. 是什么问题:PR [PR] docs: record the memory & render three-mechanism stack (#4788/#3756/#5418) + correct stale droppable-fields text #5475 与 master 冲突(dirty)——分支基于 11-01 的 master,改的是四个根目录文档,而 master 已把这些文档搬进 docs/(只留重定向桩)。
  2. 什么原因导致:文档集中化([PR] docs: batch-migrate 14 root-level documents into docs/ (consolidation + master index + redirect placeholders) | docs: 14 个根级文档一次性迁入 docs/(集中 + 总目录 + 重定向占位) #5920,11-08)+ Corrupt file .corrupt – timestamp blows up the disk | 坏文件.corrupt﹣时间戳撑爆磁盘 #5779 把驻留预算默认值从 512 MiB 提到 4 GiB,恰好落在本 PR 改写的同一行上;分支自 11-01 起未 rebase。
  3. 影响范围与严重程度:仅本 PR 的合并状态被阻塞;无用户面影响,纯合并卫生问题。
  4. 怎么修复的:rebase 到当前 master;根目录文件保留 master 桩版本,PR 的内容整体迁移到 docs/ 对应文件;EN 行做语义合并(保留 Corrupt file .corrupt – timestamp blows up the disk | 坏文件.corrupt﹣时间戳撑爆磁盘 #5779 的 4 GiB 默认值 + 应用本 PR 的可丢弃字段修正);zh 补行时默认值对齐 Corrupt file .corrupt – timestamp blows up the disk | 坏文件.corrupt﹣时间戳撑爆磁盘 #5779;技术笔记小节随搬运修正三处已失实的状态标注([PR] fix(dsh): plugin lane no longer re-parses and re-sends full history every round — watermark fast path only parses the ne | fix(dsh): 插件车道不再每轮全文重解析重发历史 — 水位快路径只解析新增尾巴(#5403 OOM 生产者) #5469 已合入并发布 v0.1.212、KDD docs: env vars primary config method + cleanup #15 已在 AGENTS.md、MESSAGE-IDENTITY.md 改新文件名);src/config.ts 注释顺带修正缩进(独立标注 commit)。
  5. 是否有回归问题:无代码行为变更(仅注释+文档);既有行为逐项过:EN 行的 4 GiB 默认值保留不变、zh 相邻行不动、technical-notes 原有内容只在文件尾追加、根桩文件未动。
  6. 是否破坏缓存:不涉及(无代码逻辑/协议变更)。
  7. 是否改了设计方向:不涉及;仅按现行文档布局([PR] docs: batch-migrate 14 root-level documents into docs/ (consolidation + master index + redirect placeholders) | docs: 14 个根级文档一次性迁入 docs/(集中 + 总目录 + 重定向占位) #5920)落位内容。

判定:冲突已清零,PR 可进入正常 CI/评审流程;无新增配置、无需决策项。

@ranxianglei

Copy link
Copy Markdown
Owner Author

🤖 Powered by ework · qwen3.8-27b

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

Status after restart — nothing outstanding. The conflict fix completed before this session dropped: branch 2026-11-01_memory-render-doctrine-docs rebased onto current master, all four doc conflicts resolved by relocating the PR's content into the new docs/ layout (#5920 move), force-pushed 4480ed61… → 186fe8bf. Full details + 七问 are in my previous comment above.

CI now verified live (mirror cache, fetched 21:20 local, head 186fe8bf31): 30 checks, 0 failed, 0 pending — all test shards (ubuntu/windows × node 22/24), static-gates, mysql-contract, build-artifact and gate lanes green; e2e lanes skipped by their own gates as usual. The PR is clean and awaiting human review/merge; no further action needed from this lane.

@ranxianglei

Copy link
Copy Markdown
Owner Author

🤖 Powered by ework · qwen3.8-27b

[ework] CI fix verified green ✓

@ranxianglei

Copy link
Copy Markdown
Owner Author

🤖 Powered by ework · qwen3.8-27b

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

Status: conflict already resolved & pushed — this run verified it.

When I woke, the PR head (2026-11-01_cache-seam-tools-attribution) was already at ddc2ca68e — a prior run in this workdir had merged master a446a3c1c into the branch, regenerated the drifted storage-render goldens, and pushed the final unmarked commit. mergeable is now True (no conflict). This run verified the work is sound rather than redoing it:

Nothing left for me to push. Awaiting CI completion + human review/merge (merge is human-only).

七问(中文)

  1. 是什么问题:PR [PR] cache-seam: attribute prefix breaks caused by a tools-array change (#5466) #5476(cache-seam monitor blames the client when the prefix break is a tools-array change (messages-only comparison) #5466 的 cache-seam tools-array 归因修复)与其基线 master 产生合并冲突。
  2. 什么原因导致的:master 前进到 a446a3c1c(含 [PR] fix(persist): keep k̂ model provenance and the emergency-shrink marker across restarts #6775 持久化字段 + batch11-wave11),改变了 storage-render 金标的持久化态输出;PR 分支(旧 master 上的 fee9e9bbb)提交的金标与之文本冲突。
  3. 影响范围与严重程度:仅 4 个 tests/golden/storage-render/*.json(anthropic/chat/google/responses)金标文件冲突,无源码冲突。严重度低——纯测试金标漂移,非行为变更;PR 的实际修复(cache-ledger.ts)不受影响。
  4. 怎么修复的:把 master a446a3c1c merge(非 rebase,保留 PR 提交历史与作者署名)进 PR 分支,金标冲突通过在合并树上重新生成解决(wire 体不变,仅 [PR] fix(persist): keep k̂ model provenance and the emergency-shrink marker across restarts #6775 带来的持久化字段变化)。推送最终无标记提交 ddc2ca68e。
  5. 是否有回归问题:无。定向测试 52/52 绿(cache-seam monitor blames the client when the prefix break is a tools-array change (messages-only comparison) #5466 修复测试 + 4 个 storage-render 金标测试 + cache-ledger);金标 wire sha 未变(仅 [PR] fix(persist): keep k̂ model provenance and the emergency-shrink marker across restarts #6775 新增持久化字段);PR 核心修复完好。
  6. 是否破坏缓存:无。PR 本身是 cache-seam 归因(可观测性),不动缓存/重试/游标/去重逻辑;金标重生成不触碰任何缓存策略。
  7. 是否改了设计方向 / 引入新配置:无设计转向、无新配置。PR 自身范围是新增 toolSeams/toolSeamMissed 账本计数器并在 web 报告渲染——这是 PR 原有范围,非冲突解决引入。

判定:冲突已解决、最终提交已推送、CI 在新 head 上运行中(44/55 绿、11 个测试分片进行中);mergeable: True。等 CI 跑完 + 人工 review/合并(合并仅人工)。

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

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant