Skip to content

[PR] fix(#5303): restore the costUsd spend ledger on session reload - #5338

Merged
ranxianglei merged 1 commit into
masterfrom
2026-10-31_costusd-restore
Oct 31, 2026
Merged

ranxianglei merged 1 commit into
masterfrom
2026-10-31_costusd-restore

Conversation

@ranxianglei

Copy link
Copy Markdown
Owner

Related: #5303 (persistence half of the reported family — the projection silently dropping costUsd; sister-lane presentation semantics are a product decision, tracked in #5336)

What / why

buildRecord persists stats by spread, so costUsd (the USD spend ledger from #4899/#4916) always reaches disk — in BOTH the JSON v3 snapshot and the index.db stats_json projection, since one record feeds both writers. But buildSession, the single restore funnel for every cold load (process restart, LRU eviction under sessions.max, legacy + unified paths alike), rebuilt stats from a hand-picked whitelist that omitted costUsd. Every cold load therefore silently zeroed the historical spend ledger — and the next save wrote that zero into both stores again, making the loss permanent.

Net effect on v0.1.209+ (where billing shipped): after any restart or eviction, panels/ledger show post-restart spend only; pre-restart cost is unreconstructable from either store. This is the "two stores disagree / no durable retention" findings in #5303: the db is not losing fields at write time — the field is dropped at reload and the drop is then propagated.

Fix

  • src/billing.ts: export validCostUsd() — the validator the panel already ran locally, now shared by writer-side consumers. Object gate; each lane finite ≥ 0; all-four-invalid reads as no-ledger (undefined); partially-valid blobs zero-fill missing lanes (lossless: the settlement writer always emits all four lanes initialized to 0).
  • src/persist.ts: restore costUsd: validCostUsd(stats.costUsd) through the buildSession whitelist (+ documented field on PersistedSession.stats). Absent stays absent — pre-billing files gain no fabricated ledger.
  • src/web/sessions-data.ts: delete the local duplicate validator, import the shared one.

Behavior change (disclosed per repo policy)

  • OLD: session.stats.costUsd silently reset on every cold load; the next save persisted the reset into the JSON snapshot AND the db projection ⇒ cumulative historical cost destroyed.
  • NEW: cumulative historical spend survives restarts/eviction; settlement accumulates onto the restored base instead of starting from zero. Panels for long-lived sessions will show MORE than before — the true cumulative sum. Intended correction, not drift.
  • Unchanged: billing stays report-only (never enters trigger decisions, Add model billing feature | 增加模型计费功能 #4899); no wire shape, config surface, cache key, or persistence-format change; corrupt ledgers are dropped, never poisons counters.

Tests

New tests/issue5303-costusd-restore.test.ts (4 tests, pinned to the legacy envelope path exactly like the #2129 restart test): round-trip survival of a realistic lane ledger; continuity (restored base + price stamp + fresh usage accumulates onto, not resets); corrupt-blob handling (all-invalid dropped / partial zero-filled / sibling counters survive); absent-stays-absent. Adjacent suites green locally: billing-web, billing-prices, issue2129-restart-measurement-state (27/27 with the new file); typecheck clean; full suite = CI on this head.

查重: 不重复 — no prior issue/PR covers the costUsd restore gap; nearest neighbors are #2478/#2482 (savings display pricing source) and #4700/#4723 (tokensSaved on tool-driven folds) — different fields, different mechanisms.

@github-actions

github-actions Bot commented Oct 31, 2026 •

Copy link
Copy Markdown
Contributor

📦 Built Package Artifact

Branch: 2026-10-31_costusd-restore (550a687)

Latest build — install this exact version

npm install -g billion-context@0.0.7522-pr.5338.3c62cda

This exact version is immutable and reproducible. The rolling pr tag tracks the newest test build across all PRs.

Recent builds (commit → version)

commit version build
550a687 billion-context@0.0.7522-pr.5338.3c62cda build
f07cf76 billion-context@0.0.7480-pr.5338.84bd8db build

Download artifact

  1. Download the artifact from the Actions run
  2. Extract the tarball and install:
tar xzf billion-context-pr5338.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

(ai: vllm-qwen/qwen3.8-27b)

查重:不重复。 #5343 是 #5312(外来折叠块永生)唯一在途的修复 PR;它实现的是宿主侧 Option A,与 Option B(内核血缘字段,挂在 #5312 等拍板)机制不同、刻意分开。无并列实现。

我独立审了这条 PR(没有照抄 issue 结论),并把分支 rebase 到当前 master、解掉冲突后推回。下面按结构化八问答。

结构化八问

1. 是什么问题
#5312:≤v0.1.208「共享父会话 id」时代产生的外来折叠块,升级到 v0.1.209 后仍永久留在父会话——每轮都被重新渲染进父会话的出站 wire,一旦进客户端持久化历史代理就删不掉,父上下文被无关摘要持续撑大、只增不减。本 PR 加一个可逆的宿主侧清扫 bili sessions foreign-blocks [--apply] [--restore <sid>:<bid>]:把「覆盖 id 与会话全量持久化转录零交集」的块识别为外来块并归档。

2. 什么原因导致的(我在当前 master 逐行验证过)
两个机制互相加固:① zombie-reap 的 e-gate(src/fold-reconcile.ts)对「覆盖 id 从不出现在当前 wire」的块永远不累计死亡连击 → 外来块 e 恒为 0、永不被 reap;② syncBlocks 的 stillPresent(kernel/src/sync.ts)只要有一个覆盖 id hash 撞上会话里某条消息就保持激活——父/子读同一批文件会产生相同的内容哈希 msg id,所以这个碰撞是结构性的、必然发生。两者都漏掉「哪怕只有一个反复碰撞」的块。

3. 影响范围与严重程度
p1。受影响面:跑过 ≤v0.1.208 又升级的用户,其父会话带着这些残留块。严重度:特定条件下有问题——不是所有用户,而是经历过共享 id 时代的旧会话;后果是父上下文无界增长(缓存/成本类失控)。注意两点:这是恢复工具不是自动修复(需手动跑命令,未跑前仍会涨);且 Option A 只能清「真·零交集」的块,带碰撞的要靠 Option B。

4. 怎么修复的
清扫对每个持久化块用其会话的全量持久化转录(live + retired 行;统一存储只 retire 不删,#4390)判定:零交集 ⇒ 可证外来 ⇒ 走新的块级可逆归档原语(archiveBlock/restoreBlock,row+content 字节级往返,落 block-archive.jsonl);有交集 ⇒ 报 collision 不动它。安全护栏(各有测试钉住):默认 dry-run 只打印不改;空转录会话跳过(绝不清空);空覆盖块不可判定→永不归档;跨模型 base-id 匹配(带 #suffix 变体也算存在)→ 宁可少报不误归档。

5. 是否有回归问题
审过的既有行为:核心安全不变量成立——健康折叠的覆盖 id 永远留在会话转录里(messages.retired_at 可空且 UNIQUE 跨 live+retired;historian sweep 是 tombstone 非 delete;唯一物理 DELETE 是同 content_hash 的 dedup、保留一条规范行),所以健康折叠 overlap≥1 被结构性放过,零交集才是真外来。纯增量改动,未改任何既有路径。master 同期给 cli.ts 加了 pack 命令(#5319),和本 PR 的 foreign-blocks 在同一 return/destructure 行冲突,已按并集解决、两功能都在。三个非阻塞小发现(见下),均不影响既有行为。

6. 是否破坏缓存
否。只归档「零转录交集」的外来块——它们不属于本会话合法前缀,移除不会碰健康折叠的前缀缓存接缝;健康折叠被结构性放过、锚点不动。归档在下次加载/重启生效,不在飞行中改。

7. 是否改了设计方向
没有转向架构。加一个宿主侧恢复面 + 一个可逆存储原语,契合现有 doctor/sessions 维护车道和「retire 不删」存储模型;不碰 kernel/。带碰撞块的根治(Option B:给块加创建期会话血缘字段、syncBlocks 只激活血缘匹配的块)刻意不在本 PR,仍是 #5312 上挂着的内核变更决策请求(按来源链规则不再三级立项)。

8. 是否引入了新的配置
无新 config key / env var。仅在现有 bili sessions 子命令上加了增量的 --apply / --restore <sid>:<bid>(外加 --json),复用现有会话存储。

冲突收敛 & 验证

  • 原 head 054510c2c 落后 master 且 mergeable=dirty(冲突)。已 rebase 到 master 485c5eaff、解掉 cli.ts 唯一冲突(并集保留 pack + foreign-blocks)、推回;现 head 9727b4a62,mergeable=True/blocked(干净,等 CI/保护规则),3 commits。
  • 本地定向验证全绿:typecheck rc=0;tests/foreign-block-sweep.test.ts 6/6;CLI smoke(未知动作守卫 exit2、缺值守卫 exit2、dry-run 渲染计划)正常。全量回归以远程 CI 为准(新 head 已触发;我读镜像 check 缓存时套件尚未回填)。
  • 审查顺手做的两处改动(各自独立标注 commit):
    • test(#5312):原测试 fix: keep system prompt byte-stable for prefix cache #1 名叫 "live + retired" 却只造了 live 行;补了一条 rewind(completeLog 重灌让 A 被 retire)断言 allMessageIds 仍返回 A/B/C——把整个安全不变量对「未来有人把 retire 改成 delete」钉死。仅测试,无生产改动。
    • fix(#5312):--restore <sid>:<bid> 原来按第一个冒号切分,sessionId 含 : 会切错;改成按最后一个冒号切(block id 是纯 bNN、不含冒号),对所有正常输入字节级等价。一行加固。

非阻塞发现(留 owner 定夺,未另开 issue——来源链受限)

  1. restoreBlock refcount 边缘泄漏:先 putContent 再 INSERT … ON CONFLICT DO NOTHING;若目标块本就 live(冲突→不插入),summary/one 的 refcount 会多计 1,对应 content 行永远到不了 0(慢泄漏)。触发条件窄(恢复一个已存在的块),修法是把插入放前、仅在实际插入时才 putContent,但动的是承载性存储原语的 tx 顺序、需配套测试——没把握就地稳妥修,故报出来等你拍板要不要现在收。
  2. 全局 flag 解析:--apply / --restore 在主 parseArgs 循环里,任意命令都能带上、仅在 sessions foreign-blocks 下生效。无害,属风格观察项。

判定

代码正确、安全不变量经端到端验证成立、纯增量、冲突已收敛到当前 master。建议:CI 在新 head 转绿后由你合并(我无权 merge)。上面发现 1 若你想现在收,我可以直接补一个带测试的修复 commit;发现 2 可忽略。

…whitelist

buildRecord persists stats via spread (costUsd rides to disk), but
buildSession rebuilt stats from a hand-picked whitelist that dropped
costUsd — every cold load (restart, LRU eviction) silently zeroed the
historical USD ledger, and the next save wrote that loss into BOTH
stores (JSON envelope + index.db stats_json projection).

Restore it through a shared validator (billing.validCostUsd, also used
by the panel): finite non-negative fields survive, partially-valid
blobs zero-fill missing lanes, all-invalid reads as no-ledger. Absent
stays absent for pre-billing files.
@ranxianglei
ranxianglei force-pushed the 2026-10-31_costusd-restore branch from f07cf76 to 550a687 Compare October 31, 2026 12:10
@ranxianglei
ranxianglei merged commit 85d46ac into master Oct 31, 2026
75 of 76 checks passed
@github-actions

Copy link
Copy Markdown
Contributor

📦 Merged Build Published

This merge to master was published as 0.0.959-master.85d46ac (rolling master tag).

npm install -g billion-context@0.0.959-master.85d46ac  # 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 pushed a commit that referenced this pull request Nov 1, 2026
…e environment (corrects 9eb1aa3)

9eb1aa3 regenerated outside the suite's preload chain, so it captured the
display-gate ON bytes (default since #5368) while every CI leg pins
BILI_MESSAGE_TIMESTAMPS=0 via tests/preload-test-env.mjs — the committed
digests could never match the pinned runners.

This run uses the exact CI invocation
(node --import ./tests/preload-storage-baseline.mjs --import ./tests/preload-test-env.mjs --import tsx),
so wire bodies are back on the pre-flip gate-off values and the
stateDigest fields pick up the persisted-state contract moves that landed
on master after the goldens' last refresh (#5338 cost ledger, #5412 async
latch parity, #5343 block archive). Turns=15/foldAt=9 unchanged; verified
green locally under the same preloads (storage-engine-proofs +
golden-storage-render).
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.

1 participant