Skip to content

[PR] feat(#2773): persist last-settled seam slot so the first post-restart request keeps body-stability attribution - #2790

Closed
ranxianglei wants to merge 2 commits into
masterfrom
2026-10-11_seam-slot-restart-persist
Closed

ranxianglei wants to merge 2 commits into
masterfrom
2026-10-11_seam-slot-restart-persist

Conversation

@ranxianglei

@ranxianglei ranxianglei commented Oct 11, 2026 •

Copy link
Copy Markdown
Owner

Closes #2773

What. The last-settled seam slot (the pairing source for bs/bl/be on ledger lines) lives in a module-level WeakMap and dies with the process: after a restart the first request of each session loses its #2131 body-stability attribution entirely. This persists the slot with the session and rehydrates it on load, per the fix direction proposed in the issue.

How.

  1. CacheLedger.seamSlot? — a capped-head projection {v:1, at, digest, msgs, str} of the last-settled slot, written at the point where the slot rolls into seamLastSettled inside settleUsageReport. str is the head clipped at SEAM_BODY_CAP (≤512 KiB). The ≤8 MiB full payload is deliberately NOT persisted (per-turn state-file rewrite cost); when the pre-restart body exceeded the cap, classification degrades to bs:"unknown" rather than guessing (a capped head can produce a fake "append" if the tail diverged).
  2. rehydrateSeamSlot(session) (src/cache-ledger.ts) seeds the live seamLastSettled WeakMap from the projection once per loaded Session object; called from persist.buildSession, which is the single choke point for every disk-load path — boot/loadSync/web-detail, and both storage engines (the unified view also reconstructs via viewToRecord → buildSession).
  3. Epoch guard: a slot older than SEAM_SLOT_RESTART_WINDOW_MS (30 min, hardcoded constant — precedent: WARM_HIT_PCT, learned-image-cost TTL) is refused at load. Rationale: crash/auto-update restarts take seconds–minutes (pairing still valid); beyond that the upstream cache is certainly cold and host-side volatile content may have drifted, so pairing would manufacture a false seam. On refusal the old behavior (fields absent) holds until the next settle overwrites the projection.
  4. The be/bl/bs block derives prevBody = prevSlot.full ?? (str under cap ? str : null). Live-mode behavior is byte-identical to before (a live slot with full:null necessarily had a capped str ⇒ same "unknown" outcome); the rehydrated case is the only new path. Boundary nuance: a body of exactly SEAM_BODY_CAP bytes degrades conservatively to "unknown" — it never misclassifies.

Behavior change (old→new). First post-restart ledger line: bd was always present, be/bl/bs always absent → now populated when a valid fresh (<30 min) projection exists. Additive forensics only — no wire or client-visible change. Detector scope intentionally unchanged: detectSeam still early-returns for rs===1 lines (separate mechanism per the issue text; left as an owner decision).

#2690 (unified storage) status — updated post-rebase. #2690 merged to master while this PR was in flight (eacbb58). Re-evaluated against the merged code: the slot stays INLINE in session.metadata. The ledger itself already lives there on every storage path (legacy JSON record and unified view→record), so a ≤512 KiB field rides the same record with zero extra I/O; the CAS store (src/storage) dedupes large block contents and is the wrong tool for a small structured field. Verified the unified load path goes through buildSession, so rehydration applies in shadow/full modes too. The four CI golden failures from the first push were exactly this interaction (see below) and are now fixed.

Golden regeneration (required by tests/golden-storage-render.test.ts). The render goldens pin digests of persisted state; this feature intentionally adds seamSlot to session.metadata, so the metadata section digest moves. Reviewed hunk-by-hunk: per wire file exactly two lines changed (stateDigest + sectionDigests.metadata); the state/blockContents/stats sections and all wire-body shas are byte-identical. Determinism holds because src/storage/canonical.ts normalizes ms-epoch numbers to __TS__, pinning the slot's at field structurally (verified empirically: two consecutive regenerations are byte-identical). Regenerated via node --import tsx scripts/update-storage-render-goldens.ts as its own labeled commit.

No new dirty marks. The projection lives on the ledger object and rides the ledger's own debounced save — same bounded partial-loss window (crash within the 500 ms debounce interval) as any other ledger mutation; no extra save traffic.

Fork flow unaffected. Child sessions get fresh metadata plus the whitelist copy only (plugin.ts), so no cross-fork pairing is possible.

Tests. New tests/issue2773-seam-slot-restart.test.ts (11 cases): projection shape at settle; be=1 identical resend across restart; bs=mid (the edge case named in the issue — a genuine mid-history rewrite landing exactly on the first post-restart request, with exact bl offset), bs=head, bs=append; stale-slot refusal and the window boundary; capped-prev degradation to "unknown" (no fake append); malformed-projection rejection without crash; once-per-object; end-to-end through the real SessionStore (writeNow → loadSync → settle). Targeted blast radius green on the rebased head: 251 tests across the cache-ledger/seam set, persist set, and storage set (unified/engine-proofs/replicas/review-fixes/mode-label/corpus/pins + golden-storage-render) — 250 pass / 0 fail / 1 skip; typecheck clean; unused-export gate clean; build OK. Full regression deferred to CI per local-test discipline.

Rebased onto master @ e7b94a2 (post #2690/#2772/#2788); no conflicts.

@github-actions

github-actions Bot commented Oct 11, 2026 •

Copy link
Copy Markdown
Contributor

📦 Built Package Artifact

Branch: 2026-10-11_seam-slot-restart-persist (ad02720)

Option A — Install this exact build (recommended)

npm install -g billion-context@0.0.3073-pr.2790.ca32178

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

Install instructions are refreshed on each push.

ework-agent added 2 commits October 11, 2026 20:52
…ata field

The four render goldens pin digests of persisted state. This feature
intentionally adds CacheLedger.seamSlot to session.metadata, so the
metadata section digest moves. Per-wire diff is exactly two lines
(stateDigest + sectionDigests.metadata); state/blockContents/stats
sections and all wire-body shas are byte-identical. Determinism holds
because src/storage/canonical.ts normalizes ms-epoch numbers to
__TS__, pinning the slot's at field structurally.
@ranxianglei
ranxianglei force-pushed the 2026-10-11_seam-slot-restart-persist branch from 94f17af to ad02720 Compare October 11, 2026 13:00
@ranxianglei

Copy link
Copy Markdown
Owner Author

🤖 Powered by ework · qwen3.8-27b

收到,这是我自己先前开的 PR(#2773 的修复)。按 [PR] 处理规范:拉分支核对代码 + 查 CI + 报结论,不重做。先说本轮唤醒直接面对的 CI 事件,再给八问。

CI 事件(已定位、已修复):首轮 CI 有 4 个 test job 全红(ubuntu/windows × node22/24),失败的是同一组 4 个 tests/golden-storage-render.test.ts 子测(anthropic/chat/google/responses)。根因见下;修复 = rebase 到当前 master + 重生成 golden,提交 ad0272037 已在分支上并 push。新一轮 CI 24/28 绿,只剩这 4 个单测 job 在跑(约 15min),跑完我补一句确认。我没重复提交、没有抢推。

结构化八问:

  1. 是什么问题:PR 本体修 [Improvement] seam-slot pairing (bs/bl/be on ledger lines) is process-local — the first post-restart request loses its body-stability attribution #2773——代理重启后每个 session 的首条 post-restart ledger 行丢失 大量缓存接缝事件导致缓存命中率大幅度降低 #2131 body-stability 归因字段(bs/bl/be)。取证盲区,非正确性 bug。本轮另发现它首轮 CI 红。
  2. 什么原因导致的:
    • 功能根因:配对源 seamLastSent/seamLastSettled 是模块级 WeakMap<Session,SeamSlot>(src/cache-ledger.ts:312-313),进程内存态;重启后 Session 从盘重建、WeakMap 空 → 首样本无 prev body → seamLcp 不执行 → 三字段缺席。
    • CI 红根因:PR 把 last-settled slot 的持久投影写进 session.metadata.cacheLedger.seamSlot(有意、加法式)。这使持久化 metadata 段内容变化,golden-storage-render 里 metadata 段摘要 + 顶层 stateDigest(含 metadata)随之漂移,而 wire bodies / state / blockContents / stats 段全部字节不变。golden 快照没随这次加法式变更重生成 → 4 平台 × 4 provider 全红。属快照陈旧,不是行为回归。
  3. 影响范围与严重程度:功能侧=每 session 每重启一行无归因(具名边界:真 mid-history rewrite 恰好落在首个 post-restart 请求时不会被分类 bs:"mid")→ 取证/体验瑕疵级;CI 侧曾阻断合并,现已修复。
  4. 怎么修复的:
    • 功能:slot 持久投影内联进 session 记录({v:1,at,digest,msgs,str},str 为 SEAM_BODY_CAP=512KiB 截断头,刻意不存 ≤8MiB full 以控制每轮状态文件重写成本);rehydrateSeamSlot() 在 persist.buildSession(boot/loadSync/web-detail 唯一收口点)执行一次,只播种 seamLastSettled,live WeakMap 路径不动;配 30min epoch guard,过期 slot 拒配(长停机后上游缓存必冷 + host 易变内容可能已漂移 + 停机期间他处请求不可见,硬配会制造假 seam)。
    • CI:rebase 到当前 master(e7b94a2e0)+ 跑 scripts/update-storage-render-goldens.ts 重生成 4 个 golden。我逐行核对了 diff:每个 JSON 仅 2 行变(顶层 stateDigest + metadata 段摘要),新值与 CI 报告的实际值逐一对上(如 anthropic metadata 2e73405ef2ddac72、responses f9899b47ccda6681),且 wire/state 段零漂移——证明是纯加法式 seamSlot 的传播,不是在掩盖别的改动。
  5. 是否有回归问题:逐项审过——live 路径字节等价(live slot full===null 必然伴随 cap 截断 str ⇒ 仍落原 unknown 分支)、rehydrate 读 RAW metadata 不给无 ledger 的 session 造空 ledger、fork 子 session 元数据白名单拷贝(handlePluginFork,src/plugin.ts)不含 cacheLedger ⇒ 无跨 fork 假配对、once-per-object 不覆盖 live slot、getCacheLedger 返回原始对象引用 ⇒ led.seamSlot= 确实落盘。golden diff 已核对无意外漂移。结论:无回归。
  6. 是否破坏缓存:不涉及 prefix cache / 重试策略 / 去重键;持久化 JSON 仅新增一个可选字段,加法式、旧记录缺该字段即现状行为,双向兼容。
  7. 是否改了设计方向:没有。刻意不依赖未合并的 Unified SQLite storage: corpus pins + parity core + shadow dry-run + drop-in read path (#2671 Phases 1 & 1.5) #2690 CAS store(投影内联,Unified SQLite storage: corpus pins + parity core + shadow dry-run + drop-in read path (#2671 Phases 1 & 1.5) #2690 落地后自然过其去重流)。范围边界(有意):dsh 缓存失效 #1592 detectSeam 对首个 post-restart pair 仍被 rs===1 门控在读任何 slot 前早退,本 PR 不扩 scope。
  8. 是否引入新配置:没有。SEAM_SLOT_RESTART_WINDOW_MS = 30*60*1000 硬编码常量(同 WARM_HIT_PCT 纪律),无 config/env/CLI 面。

行为变更披露(必须明示):① 首个 post-restart ledger 行:bs/bl/be 旧值=恒缺席 → 新值=存在新鲜(<30min)pre-restart slot 时填充(如 rs=1, be=0, bs="mid", bl=<精确偏移>);纯加法取证信息,bd 该行本就有。② 持久化 metadata 形状:加法式新增 cacheLedger.seamSlot;wire/config 协议不变;4 个 storage-render golden 快照按规则更新(diff 已列)。

判定:代码逻辑与 CI 修复均正确、已逐项核对;等最后 4 个单测 job 转绿即可由你合并(PR: https://github.com/ranxianglei/billion-context/pull/2790,分支现 tip ad0272037)。我不代合。

@ranxianglei

Copy link
Copy Markdown
Owner Author

🤖 Powered by ework · qwen3.8-27b

✅ CI 全绿确认:分支 tip ad0272037(rebase 到 master e7b94a2e0 + golden 重生成)上 28/28 checks success,含此前红的 4 个 test job(ubuntu/windows × node22/24)。mergeable_state = clean,无冲突、与 base 齐平。

结论不变:代码逻辑与 golden 修复均正确、已逐项核对,无回归。可以合并了(我不代合)——#2790

补充一句诚实标注:rebase + update-storage-render-goldens.ts 重生成这一步(提交 ad0272037)在我接手核实时已在分支上并 push(应为并行/前序处理),我独立复核了其 diff(仅 4 个 golden JSON 各 2 行摘要变化,与 CI 实测值逐一对上、wire/state 零漂移)并跟到 CI 转绿,未重复提交或抢推。

@ranxianglei ranxianglei changed the title feat(#2773): persist last-settled seam slot so the first post-restart request keeps body-stability attribution [PR] feat(#2773): persist last-settled seam slot so the first post-restart request keeps body-stability attribution Oct 20, 2026
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.

[Improvement] seam-slot pairing (bs/bl/be on ledger lines) is process-local — the first post-restart request loses its body-stability attribution

1 participant