Skip to content

fix: classify tail-append body pairs by prefix+suffix coverage (#2866) - #2872

Closed
ranxianglei wants to merge 2 commits into
masterfrom
2026-10-12_cache-stability-append
Closed

ranxianglei wants to merge 2 commits into
masterfrom
2026-10-12_cache-stability-append

Conversation

@ranxianglei

Copy link
Copy Markdown
Owner

Closes #2866

Root cause (verified empirically, not by assumption)

The issue hypothesized that token-estimate churn in ACP tag attributes polluted the BODY STABILITY mid-history bucket. A minimal repro driving 4 append-only turns through the real in-process proxy (chat wire, default config) shows the misclassification is universal and independent of tags:

pair 0->1: prev=22230B cur=27506B lcp=16164 -> old rule: mid
gap = 6066B = exactly the "tools" + "stream_options" fields that follow the messages array
all previous messages-array elements byte-identical; cur added exactly 2 elements

Real wire bodies serialize fields AFTER the message array on every lane (tools ~6KB with injectTool, plus stream_options). The ledger's append test compared LCP reach against minLen - 64 — anchored at the payload END — so a pure tail-append diverges at the array's close, far short of the end, and every growth pair of an append-only session landed in mid → /acp-cache printed "N mid-history divergence(s) — real prefix rewrites" for sessions nobody rewrote. This explains #2863's "267 pairs: 0 byte-identical · 266 mid" on an append-only session.

The tag hypothesis is refuted as the dominant cause on two counts: snapshot rendering freezes per-ref token values (kernel renderWithSnapshot), and the repro misclassifies even when message content carries no rendered tags at all.

Fix

src/cache-ledger.ts: the append class now also accepts prefix+suffix coverage under the same ±64B tolerance — new byteLcs proves the trailing bytes (the fields after the message array) survived verbatim, which is what "the whole shorter payload survives" actually means when the payload doesn't end where the history ends. Order preserved: fast path unchanged; head pairs (lcp < 1KiB) are never suffix-rescued, so model switches on small bodies stay head. The slow path stores the suffix reach in a new sparse bls field (exported as bodyLcs in the report JSON) — additive, ledger stays v:1.

Genuine mid-history rewrites (length-changing edits anywhere in history) still classify mid; identical bodies still be=1; capped bodies still unknown.

Behavior change disclosure (old → new)

  • Report bucket counts shift: healthy growth pairs in any session whose wire body carries post-array fields (i.e. effectively all real sessions) move from mid-history to tail-append. The warning line wording is unchanged; it now fires only for genuine rewrites. This is the intended fix — the old counts were false positives.
  • New sparse field bls on ledger lines / bodyLcs in the exported report object: omitted unless the slow path ran. No persistence version bump.
  • Known residual (unchanged, documented): length-preserving rewrites with ≤64B total delta remain unresolvable by any byte-coverage rule (pre-existing blind spot, same order as before). Opt-in chainEgressStamp users still see mid for their declared volatile carrier — correct, because those bytes really do change between calls and really truncate the provider prefix cache there.

Verification

  • New regression tests pin the realistic wire shape both directions + head asymmetry; the append test fails on the old classifier (stash-verified) and passes with the fix.
  • All 20 cache-ledger consumer test files: 197/197 pass (incl. cache-proof, seam detector, capped-body attribution).
  • typecheck clean, build clean.
  • E2E through the real proxy: default scenario now reports tail-append 3 · mid-history 0 (was mid-history 3 + phantom warning); chainstamp scenario unchanged (mid, justified above).

No config surface changes. No kernel/ or pi-subagents/ changes.

@github-actions

github-actions Bot commented Oct 12, 2026 •

Copy link
Copy Markdown
Contributor

📦 Built Package Artifact

Branch: 2026-10-12_cache-stability-append (f8d3dfe)

Option A — Install this exact build (recommended)

npm install -g billion-context@0.0.3338-pr.2872.675a7ff

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

Install instructions are refreshed on each push.

@ranxianglei
ranxianglei force-pushed the 2026-10-12_cache-stability-append branch from a5a73e6 to 36b2dad Compare October 12, 2026 05:34
@ranxianglei

Copy link
Copy Markdown
Owner Author

🤖 Powered by ework · qwen3.8-27b

[bot] 🏷 Review 完成 — 独立复核(非转述作者自述),结论:可合,待新 head CI 绿。

先说两件我在 review 过程中实际动手的事:

  1. 抓到并修掉一个 CI 红灯:tests/golden-storage-render.test.ts 四条 lane 全红——本 PR 的新 sparse 字段 bls(及 mid→append 重分类)改变了持久化 session 的 metadata section digest。已按测试自身规定的流程 scripts/update-storage-render-goldens.ts 重新生成 4 个 golden(每个仅 2 行 hash 变化:stateDigest + metadata sectionDigest,无 wire/block-content 变化),本地 5/5 绿,作为标注 commit ed23d0bf0 推到分支(注意:我操作期间分支被 rebase 到 master,我验证了 fix 内容逐字节未变、master 未触碰 PR 文件与 golden、regen 值跨 sync 零漂移后才推)。
  2. 旧分类器反证:把 master 版 src/cache-ledger.ts 换入跑新测试,append 用例如预期失败(8/9 过),证明回归测试有牙。

结构化八问

  1. 是什么问题:/acp-cache BODY STABILITY 把健康的 append-only 会话全部误报为 mid-history divergence("real prefix rewrites"),[bug] acp_status 把自家 GET /__bili/stats 计入 UNRECOGNIZED PATHS 告警,模板示例(/health×1)与 Exact counts 不一致 #2863 实测 267 对中 266 中 mid。
  2. 什么原因导致的:append 判据 lcp >= minLen - 64 以载荷末尾为锚,但真实 wire body 在 messages 数组之后还有序列化字段(injectTool 下 ~6KB tools + stream_options)——纯尾部追加在数组闭合处就分叉,lcp 永远够不到末尾,于是每对增长都落进 mid。issue 原假设(tag token 估算抖动)被实证排除:kernel renderWithSnapshot 冻结 per-ref token 值(kernel/src/render-refs.ts:127,首次渲染后按 ref 复用),且无 tag 内容的最小复现同样误分类(prev=22230B cur=27506B lcp=16164,gap=6066B 恰等于 tools+stream_options)。方向判断:PR 修的是根因不是症状 ✓。
  3. 影响范围与严重程度:诊断面——所有带数组后字段的会话(实际=几乎所有真实会话)的稳定性计数与告警失真;不碰 wire、不碰计费、不碰压缩行为。属于"报告误导"级,非功能损坏。
  4. 怎么修复的:慢路径(1KiB≤lcp<minLen−64)加 byteLcs 后缀覆盖证明:lcp + lcs >= minLen - 64 才许判 append——即"较短载荷整体存活"在载荷不以历史结尾时的正确含义。快路径字节不变;head 对(lcp<1KiB)永不被后缀救援(小 body 换模型保持 head);bls 只存慢路径,sparse,ledger 保持 v:1。单分支内单位一致(与 master 的 byteLcp 同为 charCodeAt UTF-16)。
  5. 是否有回归问题:五个既有桶逐项清点——be=1 相同体:分支未动 ✓;head:条件未动 + 新测试钉死"不因尾部相同而升级"✓;append 快路径:判据逐字节同 ✓;mid:真·长度变改写仍落 mid(新测试钉住过度救援边界,+200B 中段改写)✓;unknown/capped:else 分支未动 ✓;chainEgressStamp 用户继续见 mid(PR 已披露且正确——那些字节确实在变)。另发现一处披露精度问题:≤64B 总 delta 的不可分辨盲区从"仅载荷末 64 字节内"扩大到任意位置(lcp+lcs=L−delta≥L−64),PR 称"pre-existing blind spot, same order as before"低估了位置泛化——净收益为正(消灭普遍假阳性换极稀有真阳性漏报),可接受,但措辞应改准。小问题,不拦;若作者不顺手改措辞我会按惯例补一个 follow-up。
  6. 是否破坏缓存:不涉及。纯 settle 期分类,不动 provider 缓存、重试、游标、去重键;持久化格式向后兼容(sparse 字段,同既有 bl/bs 模式)。
  7. 是否改了设计方向:没有。留在既有 byte-coverage 框架内,没有采纳 issue 提议的 tag 掩码方案(该假设已被证伪,弃之正确)。
  8. 是否引入新配置:没有 config/env/CLI 变更。报告对象新增 bodyLcs 导出字段、ledger 行新增 sparse bls——均为加法且 PR 已披露。

跨 PR 依赖(需 owner 排程决策):#2870(byte-lcp-utf8)把 SeamSlot.full 从 string 改成 Buffer、byteLcp 改按字节索引——与本 PR 同一文件同一区域。若 #2870 先合,本 PR 的 byteLcs(a: string, b: string) + charCodeAt 会 typecheck 失败且单位混算;若 #2872 先合,#2870 rebase 时适配 byteLcs(Buffer 索引)并重跑 cache-ledger 套件即可。建议顺序:先合 #2872(更小、自包含、直接解掉 #2866),再 rebase #2870。

本地验证清单(定向,全量交给 CI):17 个 cache-ledger 消费方测试文件 135/135 绿;golden-storage-render 5/5 绿(regen 后);旧分类器 stash 反证如上。typecheck/build 由 CI 把关。

判定:可合——待 ed23d0bf0 的 CI 全绿(推送刚触发,含之前红的 ubuntu 22/24 test job 与 windows 四平台)。合并顺序请留意上面 #2870 一节。

@ranxianglei

Copy link
Copy Markdown
Owner Author

🤖 Powered by ework · qwen3.8-27b

[bot] 🏷 CI 全绿确认:ed23d0bf0(fix + golden regen)上 15 个 check 全部 success——test ubuntu/windows × node 22/24 四平台(含之前因 storage-render golden 变红的 ubuntu 22/24)+ lock-sync / lane-guard / unused-exports / docs-coverage / docs-sync / pi-subagents-guard / kernel-guard / version-guard / config-surface-guard / real-image billing e2e / build-artifact。

最终判定维持:可合。合并顺序提醒仍有效——#2870(byte-lcp-utf8)与本 PR 同区硬依赖,建议先合本 PR 再 rebase #2870(适配 byteLcs 到 Buffer 索引)。PR 合并由人来操作:#2872

@ranxianglei
ranxianglei force-pushed the 2026-10-12_cache-stability-append branch from ed23d0b to 94b7220 Compare October 12, 2026 15:20
ework-agent added 2 commits October 13, 2026 08:34
Real wire bodies serialize fields AFTER the message array (tools,
stream_options), so a pure tail-append diverges at the array's close,
far short of the payload end. The ledger's append test compared LCP
reach against payload length minus 64B, which misclassified every
growth pair of an append-only session as mid-history divergence and
made /acp-cache report phantom 'real prefix rewrites'.

The append class now also accepts prefix+suffix coverage under the same
tolerance: byteLcs proves the trailing bytes (the fields after the
message array) survived verbatim. Head pairs are never suffix-rescued
so model switches on small bodies stay head. The slow path stores the
suffix reach in a new sparse bls field (also exported as bodyLcs).

Genuine mid-history rewrites (length-changing edits anywhere in history)
still classify mid; identical bodies still be=1; capped bodies still
unknown. Regression tests pin the realistic wire shape in both
directions plus the head asymmetry.
The new sparse bls field (and the mid->append reclassifications) change the persisted session metadata section; only stateDigest/metadata sectionDigest drift per lane, no wire or block-content changes. Regenerated with scripts/update-storage-render-goldens.ts.
@ranxianglei
ranxianglei force-pushed the 2026-10-12_cache-stability-append branch from 94b7220 to f8d3dfe Compare October 13, 2026 00:37
@ranxianglei

Copy link
Copy Markdown
Owner Author

Closing: superseded by #2983 (already merged to master).

While this PR was in flight, the same root cause — trailing top-level fields (tools/stream_options/…) serialize AFTER the messages array, so pure tail growth diverges at the array's closing bracket and the LCP-only classifier labelled it "mid-history divergence" — was fixed structurally via #2980 → #2983: a fourth tail class that, in the would-be-mid branch only, locates the shorter body's message-array closing bracket and classes tail when the first divergence sits at/past it.

Verified empirically on master e74ed8990 with the original #2866 repro (chat wire, 4-turn append-only, ~6KB tools tail): all 3 pairs now classify tail, report reads mid-history 0 · tail(params/notes) 3 with the correct "shared history bytes untouched, prefix cache unaffected" wording (was mid-history 3 + phantom "real prefix rewrites" warning). The opt-in chainstamp scenario stays mid — correct, its volatile carrier genuinely breaks the prefix.

My prefix+suffix-coverage approach is subsumed by the structural check (which also catches trailing-param jitter beyond any byte budget). The only remaining unique delta here was a bls audit field; keeping a second competing heuristic on this hot file adds conflict/review cost without proportional benefit. Details and follow-up options in #2866.

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.

[bug] acp_cache BODY STABILITY 把 bili 自注入标签字节计入 mid-history divergence,无法区分自注入差异与宿主真实前缀改写

1 participant