Skip to content

[PR] fix(generation-boundary): arm the native-compaction rebase on a proven ref-ledger reset - #6362

Closed
sorasoras wants to merge 1 commit into
ranxianglei:masterfrom
sorasoras:fix/auto-rebase-on-ref-reset
Closed

sorasoras wants to merge 1 commit into
ranxianglei:masterfrom
sorasoras:fix/auto-rebase-on-ref-reset

Conversation

@sorasoras

Copy link
Copy Markdown
Contributor

Problem

A ref-ledger reset that arrives without a client-side compaction signature leaves the session permanently split: acp_status advertises the live generation while compress validates against the stale map, so it rejects every live ref.

Captured on 0.1.212 (ZCode client, single session id):

  • acp_status → live ledger, highest allocated ref m00314.
  • compress → session highest allocated ref=m159141 … session history=586 compression(s), 586 block(s), replying every ref is unknown to this session [cause: stale-ref].
  • 20 consecutive failures, circuit breaker armed, and the nudge re-offering the same unreachable ranges.
  • Store: refs 2,994 rows spanning ref_num 134828..159141, blocks 586 (78 active) in that namespace, messages 23,031 rows over seq 134550..159223, and sessions.metadata_json (52 keys) with no nativeCompactionBoundary.

Why it never healed

detectGenerationBoundary() already proves the ledger belongs to a previous generation (≥2 distinct above-frontier citations at request #1, #4305), but by design it only records a note — no storage rewrite, no ref-space surgery. reconcileNativeCompactionBoundary() is the repair, and it returns early forever unless something armed pendingRebase:

if (!boundary || typeof boundary !== "object" || !boundary.pendingRebase) return false;

Every existing arming site sits behind a client-side compaction signature (dsh/codex branches), which a plain model or upstream switch never produces.

Change (2 files, +26/−6)

  1. src/generation-boundary.ts — when the detector latches, also markNativeCompactionBoundary(session). Its verdict is precisely the evidence the rebase has always required; the module header is updated so it no longer claims to be display-only.
  2. src/server/prepare-anthropic.ts — honour a pending boundary at the head of the lane. Without this, the armed boundary would wait forever here, because this lane's reconcileNativeCompactionBoundary() call sits inside the dsh branch.

Next request after arming runs resetSessionCompression() + reserveRefsThrough(), re-anchoring the map onto the generation the client is actually minting. Cost: pre-reset archive blocks are dropped — they are already unreachable, since the client's refs restarted at m00001.

Verification

  • npm run typecheck → clean (kernel + pi-subagents rebuilt from this tree).
  • node --import tsx --test tests/generation-boundary.test.ts → 12/12 pass.

Notes

…n ref-ledger reset

detectGenerationBoundary() already proves that the persisted ref ledger belongs
to a previous generation: >=2 distinct above-frontier citations at request ranxianglei#1
(ranxianglei#4305). It only recorded a standing note, so the compression ledger was never
repaired. Observed on 0.1.212 with a ZCode client (ranxianglei#6061, ranxianglei#5589): acp_status
advertised the current generation (highest allocated ref m00314) while compress
validated against the stale map (highest allocated ref m159141, 586 blocks) and
rejected every live ref with "every ref is unknown to this session
[cause: stale-ref]" — 20 consecutive failures, circuit breaker armed, and the
nudge kept offering the same unreachable ranges.

The detector's verdict is exactly the evidence the native-compaction rebase has
always required, so arm it there: markNativeCompactionBoundary() sets
pendingRebase, and the next request runs resetSessionCompression() +
reserveRefsThrough(), re-anchoring the map onto the generation the client is
actually minting.

Also honour a pending boundary at the head of the anthropic lane. Its rebase
call sits behind the dsh/codex client-side-compaction signature, which a plain
model or upstream switch never produces, so an armed boundary would otherwise
wait forever on that lane (openai/google/responses reach reconcile through their
own branches; responses already reconciles unconditionally).

Verified: npm run typecheck clean; tests/generation-boundary.test.ts 12/12.
@sorasoras

Copy link
Copy Markdown
Contributor Author

Verified locally on 0.1.212 that the second hunk is load-bearing: stopping the daemon, setting \pendingRebase\ and restarting left the session untouched (blocks 586 -> 586, refs 2,994 -> 3,004 rows still in the old namespace, \compress\ diagnostics unchanged), because the anthropic lane had no consumer for the armed boundary. Evidence and the probe table are in #6061.

@ranxianglei ranxianglei changed the title fix(generation-boundary): arm the native-compaction rebase on a proven ref-ledger reset [PR] fix(generation-boundary): arm the native-compaction rebase on a proven ref-ledger reset Nov 12, 2026
@ranxianglei

Copy link
Copy Markdown
Owner

🤖 Powered by ework · qwen3.8-27b

[bot] 🏷 (ai: vllm-qwen/qwen3.8-27b)

Duplicate screening (查重): not a duplicate.

I searched open PRs and issues for the same fix — arming reconcileNativeCompactionBoundary from the generation-boundary detector on the plain model/upstream-switch path. No existing PR does this. The closest, all different mechanism:

This PR is the first to arm the rebase from detectGenerationBoundary(). The cited issues are correctly referenced: #6061 (the mechanism — "Compression nudges reference a different ledger than compress tool") and #5589 (digest drift on 0.1.212).

Mechanism analysis (initial):

I verified the two-file diff and the underlying repair mechanics:

  1. src/generation-boundary.ts — detectGenerationBoundary() already proves the ledger belongs to a previous generation (≥2 distinct above-frontier citations on request fix: keep system prompt byte-stable for prefix cache #1, Switching model mid-conversation restarts the ref ledger, but the rendered transcript still shows the old refs — the model keeps aiming compress at dead ranges until the circuit breaker fires | 切模型后消息编号整体换账本,但渲染历史仍显示旧编号,模型对着死区间反复压缩直至熔断 #4305). The PR adds markNativeCompactionBoundary(session) after the latch, so the detector's verdict now also ARMS the rebase. This is correct: the detector's evidence is precisely what the rebase has always required.

  2. src/server/prepare-anthropic.ts — the PR inserts a head-of-lane reconcileNativeCompactionBoundary(session) call. This is necessary because the anthropic lane's existing reconcile sits inside the dsh branch (which a plain model/upstream switch never hits). Without this, the armed boundary would wait forever on this lane.

Key mechanic I verified: the rebase (resetSessionCompression + reserveRefsThrough) does NOT re-anchor the ref map onto m00001. It pins the pre-rebase high-water mark as the ref floor (reserveRefsThrough → byRaw[REF_FLOOR_RAW_ID]), wipes the stale state, and lets new messages mint fresh refs above the floor. The PR's phrase "re-anchoring the map onto the generation the client is actually minting" is loose — the actual effect is "wipe stale state + reserve old number space + mint fresh refs above the floor." This is consistent with the existing behavior pinned by tests/issue2592-rebase-floor.test.ts.

Timing: on request #1 the detector latches + arms the boundary (after processTurn); on request #2 the head-of-lane reconcile fires (before processTurn), wiping state and reserving refs. This matches the existing pattern in prepare-responses.ts:76 (unconditional head-of-lane reconcile firing on the next request after arming).

Main gap I've identified so far: the PR changes only the 2 source files — no new test asserts the new arming behavior (that detectGenerationBoundary now sets metadata.nativeCompactionBoundary.pendingRebase=true). The 12 existing tests in tests/generation-boundary.test.ts are all pre-existing #4305 detection tests. I'm checking whether I should add a regression test for the arming behavior per the review discipline.

I'll post the full structured 8-question review conclusion next.

@ranxianglei

Copy link
Copy Markdown
Owner

🤖 Powered by ework · qwen3.8-27b

[bot] 🏷 (ai: vllm-qwen/qwen3.8-27b)

Code review — PR #6362

Verdict: mechanism is sound and consistent with the existing repair pattern; one gap — no regression test for the new arming behavior. I've written and verified the test locally (14/14 pass, typecheck clean) but cannot push it to your fork (no push permission). Recommend adding the test before merge.

① Direction (原 issue)

The PR fixes a real, well-documented defect (#6061): a ref-ledger reset that arrives without a client-side compaction signature (plain model/upstream switch) leaves the session permanently split — acp_status advertises the live generation while compress validates against the stale map. The root cause is correct: detectGenerationBoundary() already proves the ledger belongs to a previous generation (≥2 distinct above-frontier citations on request #1), but it only records a display note — it never arms the repair (reconcileNativeCompactionBoundary), which returns early forever unless something set pendingRebase. Every existing arming site sits behind a client-side compaction signature (dsh/codex branches) that a plain switch never produces.

The fix is the right shape: arm the rebase from the detector (whose verdict is precisely the evidence the rebase has always required), and add a head-of-lane reconcile on the anthropic lane (whose existing reconcile is buried in the dsh branch). This is the same repair, armed from a new, evidence-based site.

② Regression review (回归)

I traced the call order in prepare-anthropic.ts:

  • Head reconcile (PR's new code, ~line 323) runs before processTurn (line 363) and before detectGenerationBoundary (line 491, inside injectSystem).
  • Request fix: keep system prompt byte-stable for prefix cache #1 (plain switch): head reconcile sees no armed boundary → returns false. processTurn runs on old state. detectGenerationBoundary latches + arms the boundary (after processTurn).
  • Request fix: address all code review findings (condense, routing, session-id, dead code) #2: head reconcile fires (before processTurn) → resetSessionCompression + reserveRefsThrough wipe state and pin the ref floor. processTurn runs on wiped state. detectGenerationBoundary short-circuits (already latched).

This matches the existing pattern in prepare-responses.ts:76 (unconditional head-of-lane reconcile firing on the next request after arming). The dsh branch (line 337-338) is untouched — it still arms + reconciles in the same request when the client-side signature is present. No existing behavior is broken.

I ran the existing rebase-floor suite (tests/issue2592-rebase-floor.test.ts, 6/6 pass) to confirm the rebase mechanics (floor pin, empty-map reset, reserveRefsThrough guard) are unchanged.

One subtlety worth noting (not a bug): if both the head reconcile and the dsh branch could fire on the same request, the head reconcile fires first (it's earlier in the function) and sets pendingRebase to false, so the dsh branch's reconcile would be a no-op. In practice this can't happen — the dsh branch requires a client-side compaction signature that a plain switch doesn't produce, and the detector only latches on request #1. So the double-fire path is unreachable. No action needed.

③ Code review (代码)

Both changes are minimal and correct:

  1. src/generation-boundary.ts — markNativeCompactionBoundary(session) added after the latch (record + markDirty). The module header comment is updated to reflect that detection now also arms the rebase (no longer "deliberately display-only"). Import line updated.
  2. src/server/prepare-anthropic.ts — head-of-lane reconcileNativeCompactionBoundary(session) call with an info log. reconcileNativeCompactionBoundary was already imported (line 19).

Minor phrasing note (not a functional issue): the PR says the rebase "re-anchors the map onto the generation the client is actually minting." The actual mechanic is more subtle: the rebase does not re-anchor onto m00001. It pins the pre-rebase high-water mark as the ref floor (reserveRefsThrough → byRaw[REF_FLOOR_RAW_ID]), wipes the stale state, and lets new messages mint fresh refs above the floor. The client's mNNNNN tags are display-only — the proxy's refs are independent (assigned by raw content-hash id, not the client's tag). The net effect is correct (acp_status and compress agree on the proxy's refs), but the phrasing overstates the re-anchoring. Consider softening the comment to "wipe stale state + reserve old number space + mint fresh refs above the floor."

④ Test effectiveness (测试) — the gap

The PR changes only the 2 source files — no new test asserts the new arming behavior. The 12 existing tests in tests/generation-boundary.test.ts are all pre-existing #4305 detection tests (detect/read/note/injectSystem); none assert that detectGenerationBoundary now sets metadata.nativeCompactionBoundary.pendingRebase=true.

Per the review discipline (a gate/arming change needs both directions asserted: "triggers when it should" AND "does NOT trigger when it should not"), I wrote two tests and verified them locally:

test("#6061: detection arms the native-compaction rebase (pendingRebase=true)", () => {
    const s = sessionWithFrontier(10);
    const messages = [
        msg("a", "Compressed b7 covering m00042–m00051, summary attached."),
        msg("b", "The earlier acp_status report listed range m00060–m00071 as compressible."),
    ];
    const active = detectGenerationBoundary(s, messages);
    assert.equal(active, true, "note rides the request that detected the residue");
    const boundary = s.metadata?.nativeCompactionBoundary as Record<string, unknown> | undefined;
    assert.ok(boundary, "rebase armed on detection");
    assert.equal(boundary?.pendingRebase, true, "pendingRebase set so the next request's reconcile fires");
});

test("#6061: no detection → no rebase armed (negative)", () => {
    const s = sessionWithFrontier(10);
    const messages = [msg("a", "compress m00003–m00007 please")];
    assert.equal(detectGenerationBoundary(s, messages), false);
    assert.equal(s.metadata?.nativeCompactionBoundary, undefined, "no rebase armed without detection");
});

Local verification (targeted):

  • node --import tsx --test tests/generation-boundary.test.ts → 14/14 pass (12 existing + 2 new).
  • node --import tsx --test tests/issue2592-rebase-floor.test.ts → 6/6 pass (rebase mechanics unchanged).
  • npx tsc --noEmit → clean (kernel + pi-subagents rebuilt from this tree).

I cannot push these to your fork (the token has push: false on sorasoras/billion-context). Recommendation: add the two tests above to tests/generation-boundary.test.ts before merge. They're small, self-contained, and follow the existing test patterns in that file.

⑤ Diff cleanliness

Clean: 2 files, +26/−6. Every line relates to the PR's purpose. No unrelated changes, no whitespace churn, no lock-file drift.

⑤b Code quality

Passes the bar: naming is clear, no dead code, no magic numbers, comments explain why (the #6061/#5589 provenance), style matches the surrounding code, no new dependencies.


结构化八问(中文)

  1. 是什么问题:ref 账本在「无客户端压缩签名」的代际重置(纯模型/上游切换)后永久分裂——acp_status 报活代、compress 按旧表校验,所有活 ref 全被拒。
  2. 什么原因导致的:detectGenerationBoundary() 已证明账本属于上一代(请求 fix: keep system prompt byte-stable for prefix cache #1 上 ≥2 个不同的越界引用),但按设计只记展示性 note、从不武装修复;而 reconcileNativeCompactionBoundary() 的每个既有武装点都藏在 dsh/codex 客户端压缩签名分支里,纯切换根本不会触发 → pendingRebase 永远为 false,修复永远早退。
  3. 影响范围与严重程度:受影响面 = 所有「单 session id + 纯模型/上游切换导致 ref 账本重置」的会话(ZCode 等客户端实测 20 连败、熔断、nudge 反复推不可达区间)。严重程度 = p1(该会话的压缩能力完全不可用,acp_status 与 compress 永久不一致,属「核心承诺失灵」)。
  4. 怎么修复的:在检测器 latch 时同时 markNativeCompactionBoundary()(其判决正是 rebase 一直要求的证据);并在 anthropic 车道头部加一次 reconcileNativeCompactionBoundary()(该车道原 reconcile 埋在 dsh 分支里,纯切换够不到)。下一请求即跑 resetSessionCompression + reserveRefsThrough,把状态清掉、把旧号段钉成 floor、让新消息在 floor 之上铸新 ref。
  5. 是否有回归问题:审过的既有行为——dsh 分支武装+reconcile(同请求内,未动)、rebase 机制(floor 钉死/空表重置/reserveRefsThrough 守卫,issue2592-rebase-floor 6/6 过)、检测器原有判决(12 个 Switching model mid-conversation restarts the ref ledger, but the rendered transcript still shows the old refs — the model keeps aiming compress at dead ranges until the circuit breaker fires | 切模型后消息编号整体换账本,但渲染历史仍显示旧编号,模型对着死区间反复压缩直至熔断 #4305 测试全过)——均保持。头部 reconcile 只在检测器武装后才触发(新路径),dsh 场景下 pendingRebase 已被同请求内的 dsh 分支消费掉,不会双触发(且该路径实际不可达)。无回归。
  6. 是否破坏缓存:rebase 本身会清掉 pre-reset 的 archive blocks(这些 block 已不可达——客户端 ref 已从 m00001 重启),属预期代价。检测器仍在请求 fix: keep system prompt byte-stable for prefix cache #1 一次性 latch(不改 standing system prompt 的时机),prefix-cache 行为与 Switching model mid-conversation restarts the ref ledger, but the rendered transcript still shows the old refs — the model keeps aiming compress at dead ranges until the circuit breaker fires | 切模型后消息编号整体换账本,但渲染历史仍显示旧编号,模型对着死区间反复压缩直至熔断 #4305 原设计一致。无额外缓存破坏。
  7. 是否改了设计方向:没有。复用的是既有 rebase 修复机制,只是新增一个证据驱动的武装点 + 一个车道头部消费点,与 prepare-responses.ts:76 的既有模式同构。
  8. 是否引入了新的配置:无。没有新 env/config/默认值。

合并判定:机制正确、无回归、diff 干净;唯一缺口是缺一条针对新武装行为的回归测试(我已写好并本地验证 14/14 + typecheck 干净,但无 fork push 权限推不上去)。建议把上面两条测试补进 tests/generation-boundary.test.ts 后即可合。另有一处注释措辞("re-anchoring onto the generation the client is actually minting")略过强,实际是「清状态 + 钉 floor + 在 floor 上铸新 ref」,非功能性,可顺手改可不改。

@ranxianglei

Copy link
Copy Markdown
Owner

🤖 Powered by ework · qwen3.8-27b

[bot] 🏷 (ai: vllm-qwen/qwen3.8-27b)

CI status (verified live via mirror cache): green — 30 checks, 0 failed, 0 pending. All test lanes (ubuntu/windows × node 22/24 × shards) pass; static-gates, mysql-contract, gate, lifecycle-ledger-guard pass; e2e lanes skipped (gated). The PR's base is 85 commits behind master, but both touched files are byte-identical between base and master, so the diff applies cleanly — the staleness is not a blocker for these 2 files. Per §7.2 a rebase to current master before merge is still the clean path.

So the only outstanding item is the missing regression test (provided in my review above, verified locally 14/14 + typecheck clean). Once that's added, this is ready to merge.

@ranxianglei

Copy link
Copy Markdown
Owner

🤖 Powered by ework · qwen3.8-27b

[bot] 🏷 (ai: vllm-qwen/qwen3.8-27b)

Thanks — that local probe confirms exactly what the code analysis shows: the anthropic lane's only existing reconcileNativeCompactionBoundary call sits inside the dsh branch (line 337-338), which requires a client-side compaction signature (carriesDshLocalCompactionSummary / carriesBiliSnapshotCheckpoint). A plain model/upstream switch never produces that signature, so even a manually-armed pendingRebase has no consumer on this lane and the session stays split (blocks 586→586, refs still in the old namespace, compress diagnostics unchanged). The second hunk is indeed load-bearing — without it the first hunk (arming in the detector) would be a no-op on the anthropic wire.

This matches the prepare-responses.ts:76 pattern (unconditional head-of-lane reconcile firing on the next request after arming), which is why the responses lane doesn't have this gap.

The only outstanding item remains the missing regression test for the arming behavior (provided in my review above, verified locally 14/14 + typecheck clean). Once that's added, this is ready to merge.

@ranxianglei

Copy link
Copy Markdown
Owner

Landed via batch PR #6482 (merged) — closing as superseded.

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.

2 participants