Skip to content

fix: count all post-fold requests in cache ledger turnsToNextFold (#1286) - #1289

Merged
ranxianglei merged 1 commit into
masterfrom
2026-09-25_fix-cache-ledger-k-cap
Sep 25, 2026
Merged

ranxianglei merged 1 commit into
masterfrom
2026-09-25_fix-cache-ledger-k-cap

Conversation

@ranxianglei

Copy link
Copy Markdown
Owner

Closes #1286

Root cause

recordCacheSample (src/cache-ledger.ts) used consumedFoldSeq for two different jobs:

  1. gating the decomposeSample pending list — compRepay attribution, where each fold must fire exactly once (correct semantics);
  2. driving the per-fold requestsAfter += 1 counter — but each fold left pendRefs after its FIRST post-fold sample, so requestsAfter froze at 1 and pushFold's k = requestsAfter freeze capped turnsToNextFold at 1 for every fold.

The kernel batch reference path (buildCacheReport) counts ALL samples after a fold into requestsAfter, and the inter-fold window into turnsToNextFold. So for any fold followed by >= 2 requests the two paths diverged. Measured on the issue's repro timeline (cold req -> F1 S=12140 sigma=1000 -> 3 full-hit reqs -> F2):

field (fold F1) batch incremental before incremental after
turnsToNextFold 3 1 3
paidBack (breakevenTurns = 2.5009 both paths) true false true
savedSoFar 33420 11140 (= x(N-1) understated) 33420

breakevenTurns was identical on both paths — pricing was never wrong; only k was capped, so paidBack was systematically false for ALL providers and savedSoFar/grossSaved/netTokens were understated by ~(N-1)x.

Fix

Decouple the two concerns (the approach suggested by the issue):

  • the counting loop now iterates every elapsed fold (f.at <= s.at) — no seq gate;
  • the consumedFoldSeq gate remains on the pending list only, so compRepay/T attribution semantics are unchanged;
  • with counting fixed, the EXISTING pushFold freeze k = requestsAfter becomes exactly the batch-path window under chronological sample arrival — no new persistent field, no ledger format change, no migration.

Behavior change (disclosed, per issue requirement)

This ships as its own PR — deliberately NOT folded into #1279 / PR #1285's priceProfile pass-through. Reported values in /acp_cache fold economics change:

  • turnsToNextFold: old min(1, actual cadence) -> new = actual inter-fold request count;
  • paidBack: flips false -> true wherever measured cadence actually reaches breakevenTurns (this is the bug being corrected — old values were systematically false);
  • savedSoFar / grossSaved / netTokens: scale up from the x(N-1)-understated figures to the true values.

No wire-protocol, config-schema, or persistence-format change. Both compression modes unaffected (ledger math only).

Regression test

New fixture with THREE full-hit samples between folds (S=12140/sigma=1000 -> breakevenTurns ~2.5): asserts field-for-field parity between the incremental ledger and the kernel batch report across every economics field (seq/at/S/sigma/Vprime/hPct/T/requestsAfter/savedSoFar/turnsToNextFold/netTokenDelta/oneTimeCostUnits/perTurnSavingUnits/breakevenTurns/paidBack) plus the economics summary, with hand-computed expectations. Before the fix it fails with k=1/paidBack=false vs batch k=3/paidBack=true. The pre-existing single-sample fixture could not catch the bug because k=1 coincides on both paths there — this is the direct gap the issue calls out.

Pre-flight (branch head bacfbb4, base master 088bb34)

  • npm run typecheck — clean
  • npm test — 2448 pass / 3 fail; all 3 failures are pre-existing env-dependent tests/claude-native.test.ts live-process e2e tests (kill ESRCH / 60s spawn timeouts), verified to fail identically with the two changed files reverted to their 088bb34 state
  • npm run build — success

@github-actions

github-actions Bot commented Sep 24, 2026 •

Copy link
Copy Markdown
Contributor

📦 Built Package Artifact

Branch: 2026-09-25_fix-cache-ledger-k-cap (99ef653)

Option A — Install from npm PR tag (recommended)

npm install -g billion-context@pr-1289

Each push to this PR publishes a new version under the pr-1289 npm tag.

Option B — Download artifact

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

收到,这是我在 #1286 里开的 PR,按自审流程处理:拉分支核对代码 → 对齐当前 master(master 已前进 12 个 commit,PR 处于 behind 状态,我会 rebase 后重跑 pre-flight)→ 确认 CI → 报告结论。稍后更新。

The consumedFoldSeq gate served two roles in recordCacheSample: gating the
decomposeSample pending list (compRepay attribution — must fire once per
fold) AND driving the per-fold requestsAfter counter. Because each fold left
pendRefs after its first post-fold sample, requestsAfter froze at 1 and
pushFold's k = requestsAfter freeze capped turnsToNextFold at 1 for every
fold regardless of actual cadence. The kernel batch reference path
(buildCacheReport) counts ALL samples after a fold into requestsAfter and
the inter-fold window into turnsToNextFold, so the incremental ledger diverged
from batch for any fold followed by >= 2 requests: paidBack was systematically
false (breakeven is usually >= 2) and savedSoFar/grossSaved/netTokens were
understated by ~(N-1)x for every provider.

Decouple the concerns: the counting loop now iterates every elapsed fold
(f.at <= s.at); the consumedFoldSeq gate remains on the pending list only,
so compRepay/T attribution semantics are unchanged. With counting fixed, the
existing pushFold freeze of k = requestsAfter becomes exactly the batch-path
turnsToNextFold window under chronological sample arrival — no new persistent
field, no ledger format change.

Adds a regression fixture with three full-hit samples between folds
(S=12140/sigma=1000 -> breakevenTurns ~2.5): asserts field-for-field parity
between incremental and kernel batch reports (turnsToNextFold, paidBack,
requestsAfter, savedSoFar, economics summary), plus hand-computed values.
Before the fix this fixture failed with k=1/paidBack=false vs batch
k=3/paidBack=true; the existing single-sample fixture could not catch the
bug because k=1 coincides on both paths there.

Behavior change (disclosed): turnsToNextFold in /acp_cache fold economics
goes from min(1, actual cadence) to the true inter-fold request count;
paidBack flips false->true where measured cadence actually reaches
breakevenTurns; savedSoFar/grossSaved/netTokens scale up accordingly.

Fixes #1286
@ranxianglei
ranxianglei force-pushed the 2026-09-25_fix-cache-ledger-k-cap branch from bacfbb4 to 99ef653 Compare September 24, 2026 16:44
@ranxianglei

Copy link
Copy Markdown
Owner Author

🤖 Powered by ework · qwen3.8-27b

自审完成,结论:可以合并。以下是按 review 规范走下来的完整结论。

① 原 issue 方向(#1286)

复现已在 #1286 审核阶段实测确认(增量 k=1/paidBack=false/savedSoFar=11140 vs 批量 k=3/paidBack=true/savedSoFar=33420,breakevenTurns≈2.5009 两路一致)。根因是 consumedFoldSeq 一身二职:既门控 decomposeSample 的 pending 列表(compRepay 归属,一次性语义正确),又错误地掐断了 requestsAfter 轮次计数。本 PR 的解耦方案打到根因,不是治标。

② 回归审查(既有行为清点)

diff 只碰 src/cache-ledger.ts(+10/-1)+ tests/cache-ledger.test.ts(+54):

  • consumedFoldSeq 门控对 decomposeSample pending 列表原样保留 → compRepay/T 归属语义不变;
  • hPct 仍由 fold 后第一个样本经 f.hPct === null 守卫设置 → 语义不变;
  • requestsAfter/k/turnsToNextFold 全仓消费点仅在 src/cache-ledger.ts(:27 定义、:116 pushFold 冻结、:190 累加、:248-249 报告输出)→ 唯一外显影响就是 /acp_cache 报告的数值,已按披露要求写明 old→new;
  • 无 wire/config/持久化格式变更;两种压缩模式均不受影响(纯台账数学)。

③ 代码审查

计数循环改为遍历所有 f.at <= s.at 的 fold,与内核批量路径的 s.at > f.at 全量计数等价;样本按请求逐个到达(时序保证),pushFold 冻结瞬间 k = requestsAfter 恰好等于两 fold 间窗口——零新增字段、零迁移。逻辑成立。

④ 测试有效性

新 fixture(fold 间 3 个全命中样本)断言增量 vs 批量 15 个 economics 字段 + 8 个 summary 键逐字段一致,外加手算期望(breakevenTurns≈2.5008976660682225、savedSoFar=33420)。我实测了反向验证:把 src/cache-ledger.ts 还原到 master 状态后该测试失败(not ok 2),加回修复后通过——是真回归测试,抓得住这个 bug。

⑤ Rebase + pre-flight(head 99ef653f,base master 8e5eb582)

master 在 PR 开出后前进了 12 个 commit(含 #1257 output-side compression、#1248 claude-native e2e gate 等),与 diff 无文件交集,rebase 干净无冲突。rebase 后重跑:

  • npm run typecheck — 干净
  • npm test — 2502 tests / 2493 pass / 0 fail / 9 skipped(PR body 里提到的 3 个 claude-native 环境性失败已被 master 上的 tests/claude-native.test.ts linux live-E2E subtests fail/hang in shared multi-agent sandboxes #1248 修掉,现在全绿)
  • npm run build — 成功
  • CI(rebase 后的新 head)— 9 项全绿:test ubuntu/windows × node 22/24、real codex e2e、real pi package-native lane e2e、codex CODEX_HOME overlay + MCP、version-guard、build-artifact

PR 状态:open / mergeable / mergeable_state=clean。

一句话中文摘要:修复了增量缓存台账把 turnsToNextFold 结构性钉死在 1 导致 paidBack 系统性误判 false 的 bug(consumedFoldSeq 双职责解耦),已与当前 master rebase 并全量验证(本地 0 失败 + CI 9 项全绿 + 回归测试反向验证有效),可以合并。

@ranxianglei
ranxianglei merged commit 6b9c41a into master Sep 25, 2026
9 checks passed
ranxianglei pushed a commit that referenced this pull request Oct 4, 2026
- ci.yml test job: run the kernel's own unit suite (npm --prefix kernel
  test) on every PR — AGENTS.md Kernel Boundary rule 5 requires BOTH test
  layers green, but only release-kernel.yml ran the kernel suite.
- ci-image.yml / ci-e2e.yml: track kernel/** in the path filters (a
  kernel change IS a pipeline change, same #1289-class rationale the old
  registry-pin bump triggered on) and refresh the stale 'pinned exactly'
  comment wording.
@ranxianglei
ranxianglei deleted the 2026-09-25_fix-cache-ledger-k-cap branch October 15, 2026 05:32
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: incremental cache ledger caps turnsToNextFold (k) at 1 — paidBack verdicts systematically false for ALL providers

1 participant