Skip to content

docs(#2602): pin deferred MINOR intents from the v0.1.190 release review (#2581) - #2603

Merged
ranxianglei merged 3 commits into
masterfrom
2026-10-10_deferred-minor-findings-2581
Oct 10, 2026
Merged

ranxianglei merged 3 commits into
masterfrom
2026-10-10_deferred-minor-findings-2581

Conversation

@ranxianglei

Copy link
Copy Markdown
Owner

Closes #2602

Documentation-only PR: pins the three deferred MINOR findings from the #2581 (v0.1.190) release review at their code sites. No behavior change — every diff line is a comment/docstring; no thresholds, defaults, timing, wire shapes, or output formats move.

Path correction (finding 1): the issue cites src/prompt-cache/budget.ts:243 — that path does not exist in this repo's history (git log --all -- 'src/prompt-cache/*' is empty). The actual site is src/server/budget.ts (the #2490 dsh-compaction-refused ledger floor; nothing to do with prompt caching). The review comment's own citation (src/server/budget.ts:243–244) matches.

Finding 1 — ledger floor never decays + cap<1024 surrender (src/server/budget.ts, src/server/handle.ts)

Verified both behaviors are deliberate, and documented WHY at all three sites:

  • Sticky floor is correct, not a leak. While the nudge 死锁无检测:同一 session 交替收到两种结构互斥的请求流(巨型单消息 ↔ 多轮)时不告警 #1729/fix(#1729): refuse dsh native compaction calls at the proxy gate #1835 guard refuses dsh native compaction, the host's raw ledger only grows — refused checkpoints never land, so the high-water mark bounds every future re-send. A decay probe would re-open the dsh压缩与bili压缩冲突 #2490 kill chain (384K-token/7.5MB turn-37 incident), which is why this PR adds documentation instead of decay. Documented in dshLedgerFloorTokens() (budget.ts) and at the write site (handle.ts).
  • cap<1024 surrender is terminal-regime semantics. When the planning basis is the refused raw ledger, cap < OUTPUT_CLAMP_FLOOR means the host's own counter already sits at the window wall; bili folds cannot shrink it, so no output budget recovers the session — a sub-floor clamp would only starve a terminal turn. Documented in clampOutputBudget() (budget.ts); already test-pinned in tests/issue2490-ledger-floor-doomed-probe.test.ts.
  • Known conservative residue, now named: flipping allowDshCompaction on mid-session lets checkpoints land and shrink the ledger, but the floor stays at its old high until session eviction (fail-closed over-tightening, accepted — noted in the docstring).

Finding 2 — addStaticHosts empty-host guard (src/launcher.ts)

Kept the guard and documented the invariant rather than dropping it or adding a warn log: all eight callers resolve hosts before calling (constant tables or nonEmpty()-gated config values), so the branch is structurally unreachable today. Dropping the guard would make a future unresolved list PUSH "" into the SNI whitelist (worse than skipping), and a warn log doesn't fit this pure discovery helper (no log channel; branch unreachable by construction). The docstring now states both facts so the next reader makes the same call with evidence.

Finding 3 — transport trio (src/loop/core.ts; others informational)

  • Added the requested comment at the truncation re-fetch (core.ts) pinning that roundBody must stay byte-identical: the retry re-issues the SAME logical request, and rebuilding the body would shift prompt-cache leading-edge markers and break prefix cache reuse.
  • Retry targets carrying leading-* markers (cosmetic inefficiency) and the opencode-v2 stale-manifest observation: informational per the issue, no action taken.

Verification

  • npm run typecheck clean.
  • Targeted suites: tests/issue2490-ledger-floor-doomed-probe.test.ts + tests/discover.test.ts → 36/36 pass (the former pins exactly the two behaviors now documented; the latter is the route-discovery differential harness covering the launcher file touched).
  • Full suite left to CI per local-testing discipline.

@github-actions

Copy link
Copy Markdown
Contributor

📦 Built Package Artifact

Branch: 2026-10-10_deferred-minor-findings-2581 (8fd06d9)

Option A — Install this exact build (recommended)

npm install -g billion-context@0.0.2811-pr.2603.20d2f8f

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

[bot] 🏷

PR #2603 review — docs(#2602): pin deferred MINOR intents from the v0.1.190 release review (#2581)

Reviewed the full branch (2026-10-10_deferred-minor-findings-2581, head 8fd06d9, rebased onto current master 8e7bb). Verdict: 可合 — 建议先 re-run 一个 flaky 的 codex e2e lane 到全绿。

核心判定:纯注释改动、零行为变更,且每条文档声明都对照源码逐条核实无误。

逐项核验(不是只看 diff,是把每条声明对照源码验证):

Finding 1(#2490 ledger floor)— 全部属实

  • 路径纠正成立:git log --all -- 'src/prompt-cache/*' 为空,该路径从未存在;实际站点是 src/server/budget.ts。✓
  • Sticky floor:src/server/handle.ts:1493 用 Math.max(prevBytes, inboundBytes) 记高水位、只写不清;guard 在 handle.ts:1476(allowDshCompaction !== true && isDshCompactionCall(...))。docstring「decay 会重开 dsh压缩与bili压缩冲突 #2490 kill chain」准确。✓
  • cap<1024 surrender:OUTPUT_CLAMP_FLOOR = 1024(budget.ts:15),clampOutputBudget 在 cap < FLOOR 时 return undefined(budget.ts:255)。terminal-regime 语义描述准确。✓
  • 「known conservative residue」(mid-session 开 allowDshCompaction 后 floor 不回落直到 session eviction)——fail-closed 过紧、已接受,如实标注。✓

Finding 2(addStaticHosts 空 host guard)— 数字精确

  • 恰好 8 个调用点(launcher.ts:655/664/670/696/736/740/747/764),全部是常量表或 nonEmpty() 门控 → 该分支今日结构性不可达。✓
  • guard 为 host &&(:429);去掉会把 "" push 进 SNI whitelist。选「保留 + 文档化」而非删 guard / 加 warn log 的理由成立(纯 discovery helper 无日志通道、分支本就不可达)。✓

Finding 3(transport trio)— 关键不变量正确钉住

  • core.ts:734 retry 复用同一个 roundBody 变量;上方 gate(:717-725)证明无 client-visible 输出,故 byte-identical 重发正确;rebuild 会移动 prompt-cache leading-edge markers 并破坏 prefix-cache 复用。注释准确,且这正是 AGENTS.md 点名的高危 wire-fidelity 不变量。✓

测试有效性:tests/issue2490-ledger-floor-doomed-probe.test.ts 确实钉住这两个行为——unit:dshLedgerFloorTokens high-water / bytes-4 caliber + incident clamp 384K→55K;e2e:guard 记录 refused replay size(high-water、counted)。断言有牙、非恒真,bug 回归时抓得住。tests/discover.test.ts 覆盖被触碰文件的 route-discovery 差分。✓

CI:22 pass / 4 in-progress(主 npm test 全量 matrix shard 仍在跑)/ 1 fail:codex accepts CODEX_HOME overlay + registers bili MCP。已核实为 flaky:同一 check 在最近 8 个 master commit 上 8/8 success;本 PR 是纯注释 diff,没有任何机制能影响 live-codex binary 的 MCP registration。与本改动无关 → 建议 re-run 该 job 到绿再合。


结构化八问

  1. 是什么问题:非缺陷——是 Deferred MINOR findings from the v0.1.190 release review (#2581) #2602 的文档收尾,把 release v0.1.190 #2581(v0.1.190) release review 中三条 deferred-MINOR 发现按其代码站点钉住意图。
  2. 什么原因导致的:无 bug。根因是三个「已核实为有意」的行为缺就地说明,未来读者易误当缺陷去修,从而重新引入 dsh压缩与bili压缩冲突 #2490 kill chain / SNI-whitelist 污染 / prefix-cache 破坏。
  3. 影响范围与严重程度:仅文档,零运行时/行为影响。严重度:无(纯可维护性加固)。
  4. 怎么修复的:在三个承重站点加解释性 docstring/注释(两个 budget 函数 + 写点、launcher guard、truncation-retry 点);选择「文档化」而非 decay / 删 guard / 加 warn log,与原 review 的处置一致。
  5. 是否有回归问题:无。逐行确认每个 diff 行都在注释内——无可执行代码、阈值、默认值、时序、wire shape、输出格式变动。已 rebase 到当前 master(merge-base == master head)。唯一 CI 红是无关 flake(见上)。
  6. 是否破坏缓存:否。core.ts 注释是钉住既有 roundBody byte-invariance(保护 prefix cache),未改任何缓存/重试/游标/去重键。
  7. 是否改了设计方向:否。只固化既有设计决定(sticky floor=fail-closed 过紧已接受;空 host guard=latent backstop 保留;byte-identical retry=prefix-cache 保护),无架构/边界/数据流转向。
  8. 是否引入了新的配置:否。无新 env/config/默认值。

收工判定:可合。改动干净(4 文件 +32/-4 全注释、线性 3 个 docs: commit、无 lockfile/version 噪音)、基于当前 master、文档内容经源码逐条验证属实。合并前请 re-run 那个 flaky 的 codex-overlay e2e job 到全绿即可(非本 PR 引入)。

@ranxianglei
ranxianglei merged commit 1dfed37 into master Oct 10, 2026
29 of 30 checks passed
@github-actions

Copy link
Copy Markdown
Contributor

📦 Merged Build Published

This merge to master was published as 0.0.223-master.1dfed37 (rolling master tag).

npm install -g billion-context@0.0.223-master.1dfed37  # 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.

@ranxianglei
ranxianglei deleted the 2026-10-10_deferred-minor-findings-2581 branch October 15, 2026 05:33
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.

Deferred MINOR findings from the v0.1.190 release review (#2581)

1 participant