Skip to content

fix: fold several preflight ranges in ONE external-summary call (#2678, #2667) - #2723

Closed
ranxianglei wants to merge 4 commits into
masterfrom
wt-2678-ework-daemon
Closed

ranxianglei wants to merge 4 commits into
masterfrom
wt-2678-ework-daemon

Conversation

@ranxianglei

@ranxianglei ranxianglei commented Oct 11, 2026 •

Copy link
Copy Markdown
Owner

What

Two facets of one mechanism: external-summary requests serialize on the user-request critical path.

Executor half (#2667). ExternalSummaryExecutor.executeBatch awaited each work item end-to-end before starting the next, so the pool bounded cross-session calls but never a single batch: k ranges in one summarize() call still cost k sequential round trips. v0.1.191 evidence from the issue: batch wall time scaled linearly with range count (4→62s, 6→85s, 7→88s, 9→180s ceiling) while per-range completions were spaced 10–17s apart.

Driver half (#2678). The preflight fold pass submitted ONE external-summary request per range, sequentially, awaited inside the session lock on the user-request path: 23s/request → a k-range pass cost k×20–40s of user-visible stall, capped by the shared per-pass deadline of 180s that then cut the rest off (batch=deadline, whole ranges never dispatched). v0.1.191 bili.log: 390 ranges / 211 passes ≈ 1.85/pass; folded requests waited 30–180s vs 77–97ms normal; the log line was hardcoded completed (preflight) 1/1 range(s).

This is the filer's option B for #2678 (several requests, submitted together so the pool runs them concurrently) combined with the #2667 fix it depends on — without concurrent executeBatch, a single N-item summarize() call would have run serially inside the executor and gained nothing. Option A (one concatenated request + response splitting) is deliberately NOT in this PR: it changes the summary prompt/response contract against arbitrary external models and needs its own design discussion; #2678 stays open for it.

How

  1. src/external-summary.ts — executeBatch now dispatches up to concurrency workers pulling indices from a shared counter. Results stay index-aligned with work: the reported list is the dense prefix of settled ranges (downstream zips entries with their work slot); an early stop (caller abort / any item hitting the shared deadline) latches the workers so unstarted ranges are never dispatched and are reported as absent, not fabricated. executeUntil itself is untouched — per-item target-timeout fallback, credential rotation, invalid-summary classification all unchanged.
  2. src/preflight.ts — each round now nominates up to MAX_PREFLIGHT_SUMMARY_BATCH = 4 disjoint viable ranges (oldest first, OLDEST FULL-BUDGET CHUNK per range — the same first choice the serial walk makes, byte-identical preview/content/chunking gates) into a SINGLE plan.summarize(workItems, signal) call. Successful summaries commit through the same apply path as the walk (the old inline success tail was hoisted into commitFold, used by both). Ranges the batch cannot summarize stay OUT of the skipSet: later rounds re-nominate them while siblings keep folding, and once the batch applies nothing in a round the serial walk takes them over with its halving / transient retries. A rejected preview or an empty render never poisons the rest of a multi-chunk range (walk parity). Gated on the external lane and ≥2 viable ranges.
  3. Log line now reports real sizes: completed (preflight) N/M range(s); calls=C; …; describeExternalSummaryFailure reports the first failing slot instead of slot 0 (single-range output identical).

Behavior changes (old → new)

area old new why
executeBatch intra-batch execution strictly serial, k items = k round trips up to pool size (default 4) concurrent the fix; single-item callers byte-identical
preflight external lane folds/round exactly 1 (then re-process turn) up to 4 when ≥2 viable ranges the fix; legacy-streaming and emergency-digest paths unchanged
user-visible preflight stall k × ~20–40s sequential ≈ slowest chunk of the parallel batch the fix
summaryCalls accounting for nominated ranges counted just before each call tracked during nomination, committed against the budget only when the batch actually fires (≥2 nominations) conservative direction only — under-spends a round, never over-spends; no double-booking when a sub-batch set falls through to the walk
a range failing in the batch n/a re-nominated into later batches every round while siblings fold; the serial walk takes it over (halving / transient retries) once the batch applies nothing in a round bounded by existing per-range retry logic; no new failure mode
log format completed (preflight) 1/1 range(s) hardcoded real N/M range(s); calls=C honest reporting (#155 discipline)

No change to: wire/message shape, config schema, persistence, kernel, summary prompt wording, per-call retry/backoff semantics (transient-empty retries, replay backoffs, target-timeout fallbacks), or the shared per-pass deadline contract (still one deadline per plan; #2646's fresh-budget-per-call composes with this — a single N-item call gets one fresh budget, which is exactly what batching needs).

Config surface

None. No new fields, env vars, or CLI flags. MAX_PREFLIGHT_SUMMARY_BATCH = 4 is a private constant sized at the executor pool's default concurrency (extra work items beyond it would only queue inside the same pass — they still run in this PR's concurrent executor, just after the first wave).

Tests

  • NEW tests/external-summary-executor-parallel.test.ts (4 tests): bounded concurrency (third item starts only after a slot frees), index alignment under out-of-order completion, caller-cancellation dense prefix + stop latch (unstarted range never dispatched), shared-deadline dense prefix under pool 1.
  • tests/external-summary-batch.test.ts: the 'ordered fallback chain' assertion pinned cross-range call serialization (it pinned exactly the bug [Bug][external-summary] ranges in one batch are summarized sequentially — concurrency only applies across batches (6 ranges = 85 s on the request path) #2667 removes) — rewritten parallel-safe (per-target subsequence order preserved, cross-range interleaving allowed); all other contract assertions untouched and green.
  • NEW tests/issue2678-preflight-batch-fold.test.ts (e2e, hermetic mock upstreams, 4 tests): (1) ≥2 ranges fold in one pass with measured summary-lane overlap (peak concurrency ≥2 via interval sweep-line) and ≥2 active blocks; (2) a batch-failed range (500 on its content) is retried across later rounds instead of dropped silently (≥2 attempts); (3) a multi-chunk kernel range (same-role run with an over-budget message plus a sub-minimum tail) carries its OLDEST full-budget chunk in the first batch wave and keeps folding chunk by chunk (≥5 blocks) — red under the previous tail-first + poison-once nomination, green as-is; (4) a batch-failed range accumulates ≥3 retries across rounds while siblings keep folding.
  • Targeted verification on this head: typecheck clean; executor/batch/e2e suites 18/18; full tests/preflight-* + tests/external-summary* + issue1372/1615/1841/1933/1987/1993/2189 neighbor set = 306 tests, 305 pass / 0 fail / 1 skipped (live-gated). Rebased onto current master (zero file overlap with the intervening commits); global suite left to CI per local testing discipline.

Review fixes (landed as follow-up commits on this branch)

A code-level review of this PR found three defects in the new nomination path; all fixed here (fix(preflight) + test(preflight) commits):

  1. Span selection (must-fix). Nomination took spans[0] of the REVERSED worklist — the newest tail chunk. It was neither the "largest span" the original description claimed nor the walk's oldest-full-chunk-first choice. For single-chunk ranges (the common case) the two agree; for multi-chunk ranges (>0.6×window) the batch then summarized the smallest newest piece instead of the biggest oldest chunk. Now spans.pop(), byte-identical to the walk.
  2. SkipSet poisoning (same root). Nomination added the WHOLE range to skipSet on preview-reject / empty-render, where the walk only continues to the next span. Combined with (1), a sub-minimum newest tail (token regime, minUnits = 0) killed a range whose older chunks were perfectly foldable for the rest of the pass — zero-progress passes where the payload stays over window until content changes. Both adds removed (walk parity); pinned by e2e test (3).
  3. Call accounting. Nominations reserved summaryCalls before knowing whether the batch would fire; a sub-batch set (<2 nominations) falls through to the walk, which reserves its own calls — double booking could trip budgetHit early (effective budget roughly halved in that edge). Reservations now commit only when the batch fires. Also deduped rangesTried (was incremented at both sites; feeds only the failure-detail string).

Deltas introduced by these fixes versus this PR's ORIGINAL head: span selection now matches the walk exactly (older-first); preview-reject / empty-render no longer poison a range (strictly more folds available per pass); summaryCalls in the <2-nomination edge is now what the walk alone accounts (lower than the original head's double booking). Everything else in this PR is unchanged.

Hot-file contention notes

Closes #2667. Part of #2678 (option B interim; option A remains there).

@github-actions

github-actions Bot commented Oct 11, 2026 •

Copy link
Copy Markdown
Contributor

📦 Built Package Artifact

Branch: wt-2678-ework-daemon (fe8d498)

Option A — Install this exact build (recommended)

npm install -g billion-context@0.0.2971-pr.2723.5668846

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-pr2723.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 Review 规范审查 #2723(方向关 → 回归 → 代码 → 测试有效性 → diff 整洁度),完成后给八问结论。

ework-agent added 4 commits October 11, 2026 12:02
…2667)

executeBatch awaited each work item end-to-end, so the pool bounded cross-session calls but never a single batch: k ranges in one summarize() call still cost k sequential round trips, and the shared per-pass deadline cut multi-range passes off with whole ranges never dispatched. Workers now pull indices from a shared counter so up to `concurrency` items are in flight; results stay index-aligned as the dense prefix of settled ranges, and an early stop (caller abort / any range hitting the shared deadline) latches the workers so unstarted ranges are never dispatched.
The preflight fold pass submitted one external-summary request per range, sequentially, inside the session lock: k viable ranges cost k x ~20-40s of user-visible stall before the shared 180s pass deadline cut the rest off (v0.1.191 evidence: fold passes median 59s, max 180365ms, ~1.85 ranges/pass). A round now nominates up to MAX_PREFLIGHT_SUMMARY_BATCH=4 disjoint ranges (oldest first, largest span each, same preview/content/chunking gates as the walk) into a SINGLE plan.summarize() call that the concurrent executor runs in parallel; successful summaries commit through the same apply path as the walk (commitFold), failed ranges fall through to the serial walk unchanged and get their halving/transient retries there. Log line reports real batch sizes (was hardcoded '1/1 range(s)'). Gated on the external lane and >=2 viable ranges; single-range, legacy-streaming, and emergency-digest paths stay byte-identical.
…nk ranges (#2678)

Review findings on the #2678/#2667 batch-fold change, corrected in place:

- Span selection: nomination took spans[0] of the REVERSED worklist — the
  newest tail chunk — while the mirrored walk pops the oldest full-budget
  chunk first. Now identical (spans.pop()).
- SkipSet poisoning: a rejected preview or empty render during nomination
  added the WHOLE range to skipSet, where the walk only continues to the
  next span. A sub-minimum newest tail therefore killed a range whose older
  chunks were foldable for the rest of the pass. Removed both adds.
- Call accounting: nominations reserved summaryCalls before knowing whether
  the batch would fire (≥2 nominations); a sub-batch set falls through to
  the walk, which reserves its own calls — double booking could trip
  budgetHit early. Reservations now commit only when the batch fires.
- rangesTried counted a range at both sites (nomination AND walk); now
  deduped per range key so the failure detail reports distinct ranges.
…2678)

- New E2E: a multi-chunk kernel range (same-role run with an over-budget
  message and a sub-minimum tail) must carry its OLDEST full-budget chunk in
  the first batch wave and keep folding chunk by chunk (≥5 blocks). Under
  the previous tail-first + poison behavior this fails: the range never
  enters any batch and only the tail range folds.
- New E2E: a batch-failed range is retried across later rounds (≥3
  attempts) while siblings keep folding.
- Corrected the header/test comments claiming every batch-failed range
  'falls through to the serial walk': while siblings fold, retries are
  re-nominations into later batches; the walk takes over only once the
  batch applies nothing in a round.
@ranxianglei

Copy link
Copy Markdown
Owner Author

🤖 Powered by ework · qwen3.8-27b

[bot] 🏷 ## PR #2723 审查结论(结构化八问)

审查方式:通读全量 diff;src/preflight.ts 在 pr-2723 上逐段精读(nomination 块与 serial walk 双路径对照);5 个 hermetic 运行时探针(复现 e2e 几何 + 多 chunk 范围几何)实测行为;新增回归测试做了 red-check(修复前代码上失败、修复后通过)。CI 在原始 head 26e88f15b 上全绿(14 checks)。

1. 是什么问题

PR 本身是 #2678 option B + #2667 executor 并发化(方向正确、已按 issue 方案实现)。审查在其新 nomination 路径里发现 3 个真实缺陷 + 描述/测试注释过度声称。

2. 什么原因导致的

  • F1(必修):nomination 取 spans[0],而 spans 已被 .slice().reverse() —— 拿到的是最新尾部 chunk,既不是描述所称的 "largest span",也不是 walk 的 oldest-full-chunk-first(spans.pop())。单 chunk 范围(多数情况)两者一致;多 chunk 范围(>0.6×window)时 batch 总结的是最小最新片而非最大最老片。
  • F2(同根因,必修):nomination 在 preview-reject / empty-render 时把整个 range 加入 skipSet,而 walk 只 continue 到下一个 span。与 F1 叠加:token 制下 minUnits=0,sub-minimum 的尾部 tail 被内核拒绝 → 整段 range 本次 pass 全部作废,其可折叠的老 chunk 永远轮不到 → 零进展 pass,payload 持续超窗直到内容变化(窄触发带,但命中即 session-brick 级)。
  • F3:summaryCalls 在 nominations < 2(batch 不触发、走回 walk)时双重记账(nomination 预留 + walk 再预留),该边缘下有效预算约减半、可能提前 trip budgetHit;另 rangesTried 两处重复计数(仅影响失败详情串)。
  • F4(诚实性):PR 描述/注释称 "every range the batch cannot apply falls through to the serial walk unchanged… exactly as before" —— 不成立:batch 只要成功应用过任一 fold,当轮 appliedThisRound > 0,walk 循环条件直接不进入;实际重试路径是后续轮次的 batch 重新提名(同一 span、无 halving),只有 batch 当轮零进展时 walk 才接管。探针 A 实测:e2e test-2 场景里 walk 一轮都没跑,failedAttempts≥2 由第 2/3 轮 batch 重提名满足——test-2 注释声称的 "retried by the walk AFTER the batch (halving cascade)" 与其断言不匹配。
  • F5(接受,已文档化):commit 循环无 signal.aborted 检查,abort 后有效 fold 仍会落盘——内容有效且 session 持久化,无害偏有益。

3. 影响范围与严重程度

F1+F2 组合:触发需「多 chunk 可行范围 + 最新 chunk 低于 minCompressRange」(生产大 range 数据见 #2678/#726;代码层面证明可达,合成探针中 kernel 分段规则会把 user 连发 ≥3 条切开,需 assistant-only 连发才成单一大段)。命中时:该 pass 对该 range 零进展、每轮空转烧预算,用户侧表现为折叠停滞 + payload 超窗直至内容变化。高严重度、窄触发带。F3:中等偏低(预算边缘)。F4:低(诚实性/测试质量)。

4. 怎么修复的

以 walk 为基准对齐 nomination:spans.pop()(逐字节同 walk 首选);删除两处 skipSet 投毒(与 walk 的 continue 语义对齐,附防回归注释);预留改为局部累计、仅在 batch 真正触发(≥2 nominations)时计入 pass 预算;triedKeys 去重 rangesTried;修正 PR 描述与测试注释为准确语义;新增 2 个 e2e 回归:test-3 = 多 chunk 范围首波 batch 必须携带最老全量 chunk 且逐 chunk 继续折叠(≥5 blocks,red-check 确认修复前红)、test-4 = 批内失败 range 在多轮中累积 ≥3 次重试(钉住生产主重试路径)。两个 follow-up commit 落在 PR 分支(fix(preflight) + test(preflight)),已 rebase 到当前 master(与中间 7 个提交零文件重叠,rebase 干净)。

5. 是否回归问题

无。逐项核查:typecheck 干净;定向套件 18/18(executor parallel 4 + batch contract 10 + e2e 4);模块邻域全套(preflight-* + external-summary* + issue1372/1615/1841/1933/1987/1993/2189)= 306 tests,305 pass / 0 fail / 1 skipped(live-gated);rebase 后定向复跑 18/18。单 range 旧路径字节不变(gate 要求 ≥2 viable ranges);legacy-streaming 与 emergency-digest 通道未触碰;kernel 未触碰;walk 本体除遥测去重外未改。相对 PR 原始 head 的行为差已在 PR 正文 "Review fixes" 节披露:span 选择改为 oldest-first(与 walk 一致)、preview-reject/empty-render 不再投毒(严格更多可折叠量)、<2-nomination 边缘 summaryCalls 更低(消除双重记账)。

6. 是否破坏缓存

不涉及。apply 路径复用原 commitFold 同源逻辑,身份/去重键/前缀缓存均未触碰。

7. 是否改了设计方向

不变。是把 PR 自身机制修正到真正的 walk parity;option A(拼接请求+响应切分)仍在 #2678 待议,本 PR 范围不变。

8. 是否引入了新的配置

无。MAX_PREFLIGHT_SUMMARY_BATCH = 4 仍为私有常量(=executor pool 默认并发),无新 env/config/CLI。

披露:① PR 分支已 rebase 到当前 master 并 push(force-with-lease 仅限该 bot-authored 分支——原两提交作者均为 ework-agent,authorship 保留,master 未动,§7.2 要求 rebase-to-current-master);② PR 正文已 patch:修正 F4 相关不实表述、更新 behavior-change 表与 Tests 节、新增 "Review fixes" 节(含 vs 原始 head 的行为差清单);③ CI 已在新 head fe8d49813 上重新触发(回帖时尚未入队,绿了我会补报)。

判定:可合 —— 待 CI 在新 head 上转绿后由人合并;#2667 随合并关闭,#2678(option A)保持打开。

@ranxianglei

Copy link
Copy Markdown
Owner Author

🤖 Powered by ework · qwen3.8-27b

[bot] 🏷 补报 CI:新 head fe8d49813(rebase + review fixes 后的分支)全部 15/15 checks 绿(test ubuntu/windows × node 22/24、real-image billing e2e、lane-guard、lock-sync、config-surface-guard、docs-sync、pi-subagents-guard、unused-exports、docs-coverage、version-guard、build-artifact、kernel-guard)。

PR 当前状态:open / mergeable / base master,正文已含修正后的行为变更表与 "Review fixes" 节。结论维持:可合,请人合并(合并后 #2667 自动关闭,#2678 option A 保持打开)。

@ranxianglei

Copy link
Copy Markdown
Owner Author

Superseded by the consolidated stack in #2806 (this PR's commits cherry-picked + conflict-resolved on current master, plus the cross-PR fusion fixes — see its description). Prefer reviewing/merging #2806 and closing this one to avoid double-landing the same three files.

@ranxianglei

Copy link
Copy Markdown
Owner Author

🤖 Powered by ework · qwen3.8-27b

[bot] 🏷 已按指示处理,关闭前先验证了取代关系(不凭描述直接关):

#2806 确实完整包含本 PR:其分支(2026-10-12_external-summary-consolidated @ a47b574b6)含本 PR 全部 4 个提交的 cherry-pick——bd7f0474(executor 并发,#2667)、8bc2626f9(batch nomination)、c0d4a66e(review fixes:span 选择/skipSet 投毒/预算双重记账)、1d0bd94d(回归测试)。对其树中 src/preflight.ts 做了标记核查:spans.pop() 提名、reservedCalls 延迟记账、triedKeys 去重、no-poison 注释、commitFold hoist、真实 batch log 格式全部在位,spans[0] 零残留。

#2806 状态:open / mergeable / head a47b574b6 CI 15/15 全绿;正文 Fixes #2667 → 合并后 #2667 自动关闭;#2678(option A)不在其 fixes 列表,保持打开 ✓。

已执行:PR #2723 已关闭(closed, not merged),避免与 #2806 在同一批三个文件上 double-land。本线程工作到此收工;后续审查/合并以 #2806 为准。

ranxianglei added a commit that referenced this pull request Oct 11, 2026
…-consolidated

external-summary: consolidate #2646 + #2661 + #2723 + #2761 (fresh budgets, pool knob, concurrent batches, Go session header)
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