Skip to content

fix: body-stability classifier gains a tail class for post-array divergences (#2982) - #2983

Merged
ranxianglei merged 2 commits into
masterfrom
2026-10-13_cache-ledger-tail-class
Oct 13, 2026
Merged

ranxianglei merged 2 commits into
masterfrom
2026-10-13_cache-ledger-tail-class

Conversation

@ranxianglei

Copy link
Copy Markdown
Owner

Closes #2982

Problem

The BODY STABILITY per-pair divergence classifier (src/cache-ledger.ts) only looked at the FIRST diverging byte offset (LCP) plus a 64-byte append tolerance — never at where the messages array ENDS. Two harmless divergence families were therefore labelled mid (=「历史中段重写」):

  1. trailing top-level parameter jitter — hosts computing max_tokens etc. per turn diverge AFTER the message array;
  2. ephemeral tail notes (nudge/imgNote/retrNote) appearing/vanishing between adjacent requests — divergence AT the shorter body's array-closing bracket.

Both leave every shared history byte untouched and the prefix cache intact, yet the label masqueraded harmless jitter as a high-severity symptom (#2980 log: 181/182 adjacent pairs flagged mid while hit rates stayed 90–95%+ and seam forensics found no rebuild seam).

Fix

A fourth class tail: in the would-be-mid branch ONLY (the hot path pays nothing extra), scan the SHORTER full body for the top-level messages/input/contents array's closing bracket (string-aware depth scan over the raw text; same key set as seamLcp's msgsOf). lcp >= arrClose ⇒ tail, else mid exactly as before. No array locatable (unparseable body) keeps the conservative pre-fix class.

Refinement vs the issue proposal: the scan must run on the shorter body. When one side grew the array, the LCP stops at ITS closing bracket (] vs ,), which lies inside the longer side's array — parsing the longer side would misread the pair as mid again.

Behavior changes (disclosure, mandatory)

  • Ledger line bs: pairs whose first divergence sits at/past the message-array end are now "tail" instead of "mid" (additive enum value; already-persisted lines keep their historical values).
  • Report stability: new tail counter — the five classes partition diverged; sessions with dynamic trailing params see their mid count drop into tail.
  • acp-cache text: the divergence-class line gains a tail(params/notes) N column; when N>0 an explanatory line prints WITHOUT ⚠ (benign class, no action needed).
  • Web UI legend: new neutral-gray item tail (params / ephemeral notes) / 尾部参数/尾注; i18n tips updated en+zh in sync.
  • Existing head/append/mid/unknown logic is unchanged — mid still fires when the break lands INSIDE the array, including a rewrite of the latest element (boundary case pinned by test).

Verification

  • New regression suite tests/issue2982-body-stability-tail-class.test.ts (8 cases): trailing-param jitter → tail; ephemeral note APPEARS → tail; ephemeral note VANISHES → tail; Responses-wire input key → tail; last-element rewrite → still mid; mid-history rewrite → still mid; unparseable bodies → fall back to mid without crashing; report + acp-cache text surface the class. On unmodified master (c60c2d1) the three tail families failed with actual: 'mid' — bug reproduced before fixing.
  • Rebased onto current origin/master (9fb79dd); one union conflict resolved in the BiliCacheReport.lines type (upstream codex 命中率问题分析 #2929 added seam/prov fields on the same line — both kept).
  • On the rebased head: typecheck clean; one consolidated pass over all 18 targeted suites (issue2982; issue2131 visibility + seam-capped; cache-ledger + key/prompt/projection-switch; issue1547; seam family: detector/fuzz/probes/abort-rewind/issue1891/responses-fold/refold/seam-probes; web-i18n; acp-cache-diff) = 145 tests pass. Full regression left to CI.

@github-actions

github-actions Bot commented Oct 13, 2026 •

Copy link
Copy Markdown
Contributor

📦 Built Package Artifact

Branch: 2026-10-13_cache-ledger-tail-class (8d66ca2)

Option A — Install this exact build (recommended)

npm install -g billion-context@0.0.3387-pr.2983.a906e0a

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-pr2983.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 #2983 审查完成(独立验证:代码逐行审 + 定向测试 + master 红复现)。

八问结论:

  1. 是什么问题:BODY STABILITY 的 per-pair 分歧分类器只认「首个分歧字节(LCP)+64B append 容差」,从不看 messages 数组在哪结束——于是尾部顶层参数抖动、ephemeral 尾注(nudge/imgNote/retrNote)的出现/消失这两类良性分歧被误标成 mid(历史中段重写),把良性抖动伪装成高危症状。
  2. 什么原因导致的:设计缺口而非数据问题——旧分类器(src/cache-ledger.ts 原 :1185)对「分歧点是否在消息数组之内」无感知;缓存变低,上游还总丢缓存 #2980 日志里 181/182 相邻 pair 被标 mid 而命中率 90–95%+、seam 取证无任何重建缝,正是该缺口的表征。
  3. 影响范围与严重程度:仅诊断/归因面——ledger bs 标签、report stability 计数、acp-cache 文本与 web UI 图例。转发路径零触碰,不影响任何实际缓存行为;属于观测失真(误报),不是功能损坏。
  4. 怎么修复的:新增第四类 tail,且只在 would-be-mid 分支(热路径零额外成本)对较短一侧完整 body 做 string-aware 深度扫描定位顶层 messages/input/contents 数组收尾括号;lcp >= arrClose ⇒ tail,否则 mid 照旧;无法定位数组时保守回落到修复前类别。实现 = issue 建议方案 + 已披露的一处细化(必须扫较短侧:任一侧数组变长时 LCP 停在它的 ] vs , 上,该点落在较长侧数组内部,扫长侧会再次误判为 mid)——该细化经独立推演确认必要且正确。
  5. 是否回归问题:逐项过既有行为——head/append/mid/unknown 判定逻辑逐字未动(append/head 分支顺序保持);持久化为 additive enum,已落盘行保留历史值,无需格式版本变更;wire/消息形状零触碰(纯诊断路径 settleUsageReport,plugin/proxy 双压缩模式均不受影响);acp-cache 文本新增一列 + N>0 时无 ⚠ 的解释行、web UI 新增中性灰图例项,均为已披露的输出格式变化;i18n en+zh 同步更新(已核对两侧);性能上仅在 would-be-mid 分支多一次 O(n) 单程扫描(< BODY_FULL_CAP 的 body),可忽略。未发现回归。
  6. 是否破坏缓存:不涉及——不触碰任何缓存失效/重试/游标逻辑;纯标签面。
  7. 是否改了设计方向:不涉及——在既有四分类框架内加一类,边界不变量(mid = 断点落在数组内,含最新元素重写)保留并由测试钉住。
  8. 是否引入新配置:不涉及——无新 env/config/默认值。

测试有效性:8 个回归用例断言有牙(非恒真)——我在未改动的 origin/master 上跑同一套,6/8 red(三个 tail 家族 actual='mid' 复现 bug;另有 Responses input key、report 字段存在性两条),PR head 上全绿;last-element-rewrite→mid 的边界守卫与 unparseable→mid 回落均有钉住。定向套件(issue2982 + issue2131×2 + cache-ledger + web-i18n + acp-cache-diff)83/83 通过,typecheck clean;全量回归在 CI。

diff 整洁度:单 commit、4 文件、每行都与本 PR 目的相关;无 version bump、无 lockfile churn、无空白噪音;与 #2929 的类型 union 冲突合并正确(seam/prov 字段保留)。

CI:所有门禁 job 绿(static-gates ×3 / build-artifact / version-guard / lock-sync / kernel-guard / lane-guard / pi-subagents-guard / config-surface-guard / unused-exports / docs-coverage / docs-sync / image-billing e2e);test matrix ×4 审查时仍在跑,完成后即齐。

一处核验过的非问题(不立项):扫描器取「文本序中第一个匹配数组 key」,而 seamLcp.msgsOf 按 messages ?? input ?? contents 优先级取值——两者在真实 wire 上不可区分(不存在同时携带两个此类数组 key 的请求体),不构成缺陷。

判定:可合入(等 CI test matrix 收尾;合并由人执行)。

ranxianglei pushed a commit that referenced this pull request Oct 13, 2026
The new tail divergence class reclassifies 11 of 14 persisted
cacheLedger bs values mid->tail in the golden conversations (divergence
sits at the message-array closing bracket: trailing params / ephemeral
notes), changing session.metadata digests. Regenerated via
scripts/update-storage-render-goldens.ts; diff is digests-only
(stateDigest + sectionDigests.metadata) for chat/anthropic/google.
responses wire unaffected (its ledgers keep their classes).

Closes nothing; completes PR #2983's required golden refresh.
@ranxianglei

Copy link
Copy Markdown
Owner Author

🤖 Powered by ework · qwen3.8-27b

[bot] 🏷 更正上一条 review 结论(重要):我此前说「CI red 是 master 既有问题、与本 PR 无关」——这个判断错了,在此撤回。真正原因已查明并已在 PR 分支上修复。

排查过程与自我纠错

我最初的「master 也红」证据来自一组 worktree bisect 运行,但那些命令忘了 cd 进 worktree,全部实际跑在主仓库(PR head)上——bisect 结论整体作废。用正确方式(cd 进 master worktree)重跑后:master 上 storage-render goldens 5/5 全绿 ×3 次。CI 的 3 个失败(chat/anthropic/google 的 storage-render golden)是本 PR 自己引入的,不是既有问题。

真正根因

tests/golden/storage-render/*.json 钉住的是持久化会话的 section digest,其中 metadata 段包含 session.metadata.cacheLedger.lines[*].bs(body-stability 分类)。本 PR 新增 tail 类后,golden 会话里 14 个相邻请求对中 11 个的 bs 从 mid 翻成 tail(这些分歧点恰好落在 messages 数组收尾括号处——尾部参数/临时尾注,正是 #2982 要修的那两类),持久化元数据变了 → metadata digest 漂移 → 三条 wire 红。responses wire 不受影响(其账本分类未变,文件零改动)——与 CI 里恰好 responses 通过完全吻合。

验证闭环:在 PR head 本地驱动同一 golden 会话,重生成后的 chat metadata digest = e9fc6801441604ff,与 CI 失败日志里的 actual 值逐字节一致。

已做修复(提交到 PR 分支)

  • 按 tests/golden-storage-render.test.ts 头部规定的流程跑 scripts/update-storage-render-goldens.ts 重生成;
  • diff 范围极小且纯 digest:chat.json / anthropic.json / google.json 各 2 行(stateDigest + sectionDigests.metadata),无其他字段变化;
  • 重跑 tests/golden-storage-render.test.ts:5/5 绿;
  • 已推送到 PR head:a191244c7 (test: regen storage-render goldens for #2982 tail class),等 CI 在新 head 上全绿。

结构化八问(更正版)

  1. 是什么问题:PR 引入 tail 类后,storage-render goldens 钉住的持久化账本 bs 值发生 mid→tail 翻转,digest 失配导致 3 条 wire 测试红。
  2. 什么原因导致的:行为变更是有意的(正是本 PR 的目的),但 PR 只更新了新增回归套件,漏掉了按 golden 测试头部规则必须同步重生成的 storage-render goldens;我第一轮误判为「master 既有问题」是因为 bisect 命令没切目录,跑的全是 PR head 代码。
  3. 影响范围与严重程度:仅影响 CI 门禁(合并前拦下,无用户面影响);若带红合并,后续所有 storage-render 相关变更都会被这条 stale golden 持续打红。
  4. 怎么修复的:用仓库自带脚本重生成三个受影响 wire 的 golden,确认 diff 仅 digest 行,回归套件复跑全绿,作为独立标注 commit 推到 PR 分支。
  5. 是否有回归问题:golden 内容核对过——只有 stateDigest/sectionDigests.metadata 变,state/blockContents/stats 三段 digest 不变,即消息内容、块内容、统计均未动,变的只是账本分类标签(本 PR 的预期行为)。head/append/mid/unknown 四类逻辑本身仍由 issue2982 套件 8 用例钉住(含 last-element-rewrite→mid 边界)。
  6. 是否破坏缓存:不涉及运行时缓存;golden 是测试夹具,重生成不影响任何线上缓存/重试/游标策略。
  7. 是否改了设计方向:不涉及。
  8. 是否引入了新的配置:不涉及。

另:排查中观察到 master push 事件下 test/static-gates 矩阵被 skip(tier-1 guard 带 if: pull_request,skipped-needs 级联)——查了一下已有 #2901 跟踪且修复分支在途(2026-10-12_ci-push-test-skip, ecdeced),不重复立项。

判定:代码本体 review 结论维持上一轮(实现正确、diff 干净、测试有牙);补上 golden 重生成后,待新 head CI 全绿即可由人合并。

@ranxianglei
ranxianglei force-pushed the 2026-10-13_cache-ledger-tail-class branch from a191244 to 233d9a7 Compare October 13, 2026 05:41
ranxianglei pushed a commit that referenced this pull request Oct 13, 2026
The new tail divergence class reclassifies 11 of 14 persisted
cacheLedger bs values mid->tail in the golden conversations (divergence
sits at the message-array closing bracket: trailing params / ephemeral
notes), changing session.metadata digests. Regenerated via
scripts/update-storage-render-goldens.ts; diff is digests-only
(stateDigest + sectionDigests.metadata) for chat/anthropic/google.
responses wire unaffected (its ledgers keep their classes).

Closes nothing; completes PR #2983's required golden refresh.
@ranxianglei

Copy link
Copy Markdown
Owner Author

🤖 Powered by ework · qwen3.8-27b

[bot] 🏷 冲突已解决并推送 — 新 head 233d9a763,CI 全绿(19/19 check-runs),mergeable: True。

发生了什么:master 从本 PR 原 base(9fb79ddd9)前进到 b597c4ee7,期间多个 storage 相关 PR 落地(#2815 marker-declarative、#2671 unified sidecar shadow 默认、#2845 sqlite engine bootstrap、session-resolve v2 等),其中不止一个重新生成过 tests/golden/storage-render/*.json——与本 PR 的 golden 再生提交撞在同一批文件上。

结构化八问:

  1. 是什么问题:PR 分支与 master 的合并冲突(dirty merge state)。
  2. 什么原因导致的:双方都合法修改了同一组 golden 文件——master 侧因存储结构/计数器变化重生成,PR 侧因 cache-ledger bs 分歧分类缺 tail 类:尾部参数抖动/临时尾注被误标为「历史中段重写」 #2982 的 bs 分类变化(mid→tail)重生成;纯文本冲突,src 代码零冲突(fix 提交 rebase 时干净应用)。
  3. 影响范围与严重程度:仅影响本 PR 的合并状态,无任何用户面影响。
  4. 怎么修复的:rebase 到 b597c4ee7;三个冲突的 golden JSON 不做手工文本合并(拼 digest 值没有意义),而是取 master 新版为基线后在 rebase 后的 head 上重跑官方脚本 scripts/update-storage-render-goldens.ts——两侧意图(master 的存储变更 + 本 PR 的 tail 分类)在再生成的字节里自然合成。
  5. 是否有回归问题:无。rebase 后 head 验证:typecheck 干净;定向套件 60/60(golden-storage-render 5、issue2982 8、cache-ledger、issue2131 visibility、web-i18n)。另注:推送后 master 又前进了一格(fix: #2976 跟进(部分):canonFp lane gate (#2973) + dsh-lane atomic/case (#2972 M1/L3) #2978/[cache-ledger] settleUsageReport 无条件读 canonicalSysFp 槽:responses→其他 wire 切换后投影记账错位(#2867) #2973,动 src/cache-ledger.ts 的 responses-lane gate)——已核实双方 hunk 不重叠(theirs @1124/@1229 区段 vs mine @1256 起)、机制相互独立,GitHub 重算 mergeable: True;按冲突唤醒规则不再重复 rebase,合并提交的 CI 会覆盖组合树。
  6. 是否破坏缓存:不涉及(本 PR 是诊断分类,不触碰缓存/重试/增量游标)。
  7. 是否改了设计方向:不涉及。
  8. 是否引入了新的配置:不涉及。

行为变更披露:无新增——仍为此前两轮回复已披露的内容(bs 枚举加 tail、报告/UI 展示列)。

收工判定:冲突解除、rebase 后 head CI 全绿、无回归,可合入(合并操作留给人)。

ework-agent added 2 commits October 13, 2026 14:43
…rgences (#2982)

The per-call BODY STABILITY divergence classes only looked at the first
diverging byte offset (LCP) plus a 64-byte append tolerance — never at
where the messages array ENDS. Two harmless families were labelled mid
("mid-history rewrite"): trailing top-level param jitter (host-computed
max_tokens/…) and ephemeral tail notes (nudge/imgNote/retrNote) that
appear/vanish between adjacent requests, even though every shared history
byte was untouched and hit rates stayed 90–95%+ (#2980 log: 181/182 pairs
flagged mid, zero seam evidence).

New fourth class tail: in the would-be-mid branch only (hot path pays
nothing extra), scan the SHORTER full body for the top-level
messages/input/contents array closing bracket (string-aware depth scan,
same key set as seamLcp); lcp >= that offset ⇒ tail, else mid as before.
Unparseable bodies keep the conservative pre-fix class. Report aggregate,
acp-cache text and web UI legend (en+zh) surface the new class.
The new tail divergence class reclassifies 11 of 14 persisted
cacheLedger bs values mid->tail in the golden conversations (divergence
sits at the message-array closing bracket: trailing params / ephemeral
notes), changing session.metadata digests. Regenerated via
scripts/update-storage-render-goldens.ts; diff is digests-only
(stateDigest + sectionDigests.metadata) for chat/anthropic/google.
responses wire unaffected (its ledgers keep their classes).

Closes nothing; completes PR #2983's required golden refresh.
@ranxianglei
ranxianglei force-pushed the 2026-10-13_cache-ledger-tail-class branch from 233d9a7 to 8d66ca2 Compare October 13, 2026 06:45
@ranxianglei
ranxianglei merged commit 676f7fd into master Oct 13, 2026
20 checks passed
@github-actions

Copy link
Copy Markdown
Contributor

📦 Merged Build Published

This merge to master was published as 0.0.366-master.676f7fd (rolling master tag).

npm install -g billion-context@0.0.366-master.676f7fd  # 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.

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.

cache-ledger bs 分歧分类缺 tail 类:尾部参数抖动/临时尾注被误标为「历史中段重写」

1 participant