Skip to content

[PR] fix: cap x-bili-pf-tail-ids at 160 ids and decouple the pf-seq stamp from the fastpath gate (#7367) - #7381

Merged
ranxianglei merged 1 commit into
masterfrom
2026-11-20_pf-tail-ids-cap-and-stamp-decouple
Nov 21, 2026
Merged

ranxianglei merged 1 commit into
masterfrom
2026-11-20_pf-tail-ids-cap-and-stamp-decouple

Conversation

@ranxianglei

Copy link
Copy Markdown
Owner

What

With rollout.features.pluginFullResendWatermark gated off, the watermark fastpath never evaluated, so the x-bili-pf-seq response stamp (the client's watermark advance) was never emitted. The client's k2 froze while its captured msgid list kept growing, so x-bili-pf-tail-ids grew unbounded and eventually overflowed Node's 16 KB header limit — the proxy's HTTP parser dropped the connection before any handler ran, and the session was wedged on every retry.

Two-part fix:

  1. Client safety net (src/agent/pf-channel.ts): cap the tail-ids list at the newest 160 ids. The capped tail still ends at the true window origin; a delta wider than 160 degrades to a conservative server-side miss (the width check fails) instead of a header overflow. 160 ids ≈ 5.8 KB for UUIDs, well under the limit.

  2. Server root fix (src/server/fastpath.ts + src/server/prepare-openai.ts): emit the x-bili-pf-seq stamp via a structural scan even when the fastpath gate is off. The stamp is the client's watermark advance, not fastpath-only state — decoupling it from the gate keeps k2 advancing, which is what bounds the tail list at its natural width.

Behavior change (disclosed per owner policy 2026-09-22)

  • Old: with pluginFullResendWatermark OFF, the proxy never emitted x-bili-pf-seq; the client's x-bili-pf-tail-ids grew unbounded from a frozen k2.
  • New: with pluginFullResendWatermark OFF, the proxy emits x-bili-pf-seq on plugin-lane non-title-gen openai responses (whenever the structural scan measures T). The client-visible x-bili-pf-tail-ids is now capped at the newest 160 ids.
  • Why: both changes are the fix — the stamp decoupling keeps k2 advancing (root cause), and the cap is a safety net that would have prevented the outage on its own.

Tests

All targeted suites green: tests/fastpath.test.ts + tests/pf-channel.test.ts (36/36), tests/issue5403-watermark-fastpath.test.ts + tests/watermark-cache-eviction.test.ts + tests/issue6752-watermark-output-budget-restore.test.ts + tests/native-intercept.test.ts (96/96), tests/openai-plugin-postfold-seam.test.ts + tests/lane-decisions-matrix.test.ts + tests/side-lane-invariants.test.ts (130/130). npm run typecheck clean.

Closes #7367

…from the fastpath gate (#7367)

With pluginFullResendWatermark gated off, the watermark fastpath never
evaluated, so the x-bili-pf-seq response stamp (the client's watermark
advance) was never emitted. The client's k2 froze while its captured
msgid list kept growing, so x-bili-pf-tail-ids grew unbounded and
eventually overflowed Node's 16 KB header limit — the proxy's HTTP
parser dropped the connection before any handler ran, and the session
was wedged on every retry.

Two-part fix:

1. Client safety net (src/agent/pf-channel.ts): cap the tail-ids list
   at the newest 160 ids. The capped tail still ends at the true window
   origin; a delta wider than 160 degrades to a conservative
   server-side miss (the width check fails) instead of a header
   overflow. 160 ids ≈ 5.8 KB for UUIDs, well under the limit.

2. Server root fix (src/server/fastpath.ts + prepare-openai.ts): emit
   the x-bili-pf-seq stamp via a structural scan even when the
   fastpath gate is off. The stamp is the client's watermark advance,
   not fastpath-only state — decoupling it from the gate keeps k2
   advancing, which is what bounds the tail list at its natural width.

Behavior change (disclosed per owner policy 2026-09-22): with
pluginFullResendWatermark OFF, the proxy now emits x-bili-pf-seq on
plugin-lane non-title-gen openai responses (old: never emitted). The
client-visible x-bili-pf-tail-ids is now capped at the newest 160 ids
(old: unbounded from a frozen k2). Both changes are the fix.

Fixes #7367
@ranxianglei ranxianglei changed the title fix: cap x-bili-pf-tail-ids at 160 ids and decouple the pf-seq stamp from the fastpath gate (#7367) [PR] fix: cap x-bili-pf-tail-ids at 160 ids and decouple the pf-seq stamp from the fastpath gate (#7367) Nov 20, 2026
@ranxianglei ranxianglei added bug Something isn't working p1 scope/kernel labels Nov 20, 2026
@ranxianglei

Copy link
Copy Markdown
Owner Author

🤖 Powered by ework · qwen3.8-27b

PR Review: cap x-bili-pf-tail-ids at 160 ids and decouple the pf-seq stamp from the fastpath gate

Duplicate screening: Not a duplicate. The PR targets a specific bug (#7367) where the x-bili-pf-tail-ids header grows unbounded when the pluginFullResendWatermark flag is off. Checked open [PR] rows — #7352 (head check for pinned sessions), #7358 (window save retiring prefix), #5427 (foundation increment) are all different watermark topics. No parallel PR targets this same bug.

Direction (方向关): The PR targets a real bug. When the pluginFullResendWatermark flag is off, the x-bili-pf-seq stamp is never emitted, so the client's watermark (k2) freezes, and the x-bili-pf-tail-ids header grows unbounded until it crosses Node's 16 KB header limit. The fix addresses the root cause (decouple the stamp from the gate) and adds a safety net (cap the tail-ids at 160). The direction is correct — it fixes the producer (the frozen stamp), not just the symptom (the oversized header).

Regression review (回归审查): I reviewed the existing behaviors touched by the diff:

  1. Client-side cap (src/agent/pf-channel.ts:142): The cap only kicks in when the tail is wider than 160 (i.e., the stamp froze). In the normal case (stamp advancing), the tail is narrow (a few ids), so the cap has no effect. The capped tail still ends at the true window origin (ids.length - 1), which is what the fastpath needs. No regression.
  2. Server-side stamp emission (src/server/fastpath.ts:515 + src/server/prepare-openai.ts:681): The stamp is now emitted when the flag is off. This is a new behavior, but it's harmless — the x-bili-pf-* headers are all in UPSTREAM_HOP_HEADERS (src/server/headers.ts:37-39, stripped before forwarding to the upstream), so they never reach a model endpoint. When the flag is off, the server ignores the client's count and tail-ids (the fastpath returns "gate-off" before reading them). No regression.
  3. Transition from off→on: When the flag flips on, the first turn is a miss (unseeded — the in-memory seed was never set while the flag was off), then finalizeWatermarkTurn reseeds and the next turn can hit. This is the same as a cold start. No regression.
  4. Stamp value consistency: stampOnlyWatermarkTurn emits scan.total (the measured element count T), which is the same T that finalizeWatermarkTurn emits (via outcome.measuredT). So the stamp value is consistent between the flag-on and flag-off paths. No regression.

Code review (代码审查): The code is clean and correct. The cap is a simple Math.max(k - 1, ids.length - MAX_TAIL_IDS) calculation. The stampOnlyWatermarkTurn function is a simple delegation to scanMessagesSpans (the same zero-allocation structural scan the fastpath uses). The else if branch in prepare-openai.ts is the exact logical complement of the flag-on condition (line 138), so the two branches are mutually exclusive and exhaustive for the plugin-lane non-title-gen case. The comments are clear and explain the rationale.

Test effectiveness (测试有效性): The tests are focused and verify the key behaviors:

  • tests/pf-channel.test.ts: Verifies the cap behavior — 200 ids captured with k2=2 → tail capped to 160 ids (id40..id199), ends at the true window origin; a narrow delta (10 ids) is sent whole (9 ids). Real assertions, not tautologies.
  • tests/fastpath.test.ts: Verifies the stamp emission — 5 elements → stamp "5"; unscannable body ("not-json-at-all", "") → no stamp. Real assertions, not tautologies.

The tests would catch a regression in the cap or the stamp emission.

Diff cleanliness (diff 整洁度): The diff is clean. 5 files, 75 insertions, 3 deletions. Every line relates to the PR's purpose. No unrelated changes, no mass whitespace/reformat, no generated or lock-file churn.

Code quality (代码整洁): The code is clean. Naming is clear (MAX_TAIL_IDS, stampOnlyWatermarkTurn). No dead code. No duplication. Error handling is complete (unscannable body → no stamp, the client's cap is the backstop). No magic numbers (160 is a named constant with a comment explaining the 16 KB header limit rationale). Comments explain the why (the #7367 rationale). Style is consistent with the existing code.

Verification:

  • All targeted tests pass locally: 36/36 (fastpath + pf-channel), 96/96 (watermark + native-intercept), 130/130 (openai-plugin-postfold-seam + lane-decisions-matrix + side-lane-invariants).
  • npm run typecheck clean.
  • CI is green on the PR head (0 failed, 0 pending; 12 success, 18 skipped — the skipped are gated e2e lanes).
  • The PR is 7 commits behind master, but none of those commits touch the PR files, so the rebase is clean.

结构化八问

  1. 是什么问题: When the pluginFullResendWatermark flag is off, the x-bili-pf-seq stamp (the client's watermark advance) is never emitted, so the client's k2 freezes while its captured msgid list keeps growing, and the x-bili-pf-tail-ids header grows unbounded until it crosses Node's 16 KB header limit — the proxy drops the connection before any handler runs, wedging the session on every retry.
  2. 什么原因导致的: The stamp was only emitted when the fastpath gate was on (finalizeWatermarkTurn is only called when the flag is on). When the gate is off, the stamp stops, the client's k2 freezes at its last learned value, and the tail-ids slice [k-1..] grows one id per turn with no bound.
  3. 影响范围与严重程度: Affected: plugin-lane openai sessions whose k2 froze (flag flips off mid-session, a restart where the client state persists, or a scan miss). Severity: high — the session is wedged on every retry (unusable) once the header crosses 16 KB.
  4. 怎么修复的: Two-part fix: (1) client safety net — cap the tail-ids at the newest 160 ids (Math.max(k-1, ids.length-160)), so a frozen k2 can't grow the header past ~5.8 KB; the capped tail still ends at the true window origin, and a delta wider than 160 degrades to a conservative server-side miss (the width check fails). (2) server root fix — emit the x-bili-pf-seq stamp via the structural scan even when the fastpath gate is off (stampOnlyWatermarkTurn), so k2 keeps advancing and the tail stays bounded at its natural width.
  5. 是否有回归问题: No. The cap only kicks in when the tail is wider than 160 (frozen stamp); in the normal case it's a no-op. The stamp emission when the flag is off is new but harmless — the x-bili-pf-* headers are all in UPSTREAM_HOP_HEADERS (never reach a model endpoint), and the server ignores the client's count/tail-ids when the flag is off. The off→on transition is a clean cold start (first turn miss, then reseed + hit). No threshold/timing/output-format drift.
  6. 是否破坏缓存: No. The fix doesn't touch the cache, retry, incremental cursor, or dedup key. The stamp is a bili-internal header (stripped before forwarding upstream).
  7. 是否改了设计方向: No. The fix doesn't change the architecture, boundary, or data flow. It's a bugfix scoped to the watermark fastpath mechanism. The stamp is reclassified from "fastpath-only state" to "client watermark advance" — a semantic clarification, not a design pivot.
  8. 是否引入了新的配置: No. The fix doesn't introduce any new config, env, or default. MAX_TAIL_IDS = 160 is a code-level constant, not a config knob.

结论

The PR is ready to merge. The fix is correct (verified by tracing the control flow and running the targeted tests), the tests are sufficient (real assertions that would catch a regression), and the CI is green. The two-part fix (client cap + server stamp decoupling) addresses both the root cause and the safety net, and the behavior change is properly disclosed in the PR body.

@github-actions

Copy link
Copy Markdown
Contributor

📦 Built Package Artifact

Branch: 2026-11-20_pf-tail-ids-cap-and-stamp-decouple (6b7f66f)

Latest build — install this exact version

npm install -g billion-context@0.0.11067-pr.7381.642e759-a2

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
6b7f66f billion-context@0.0.11067-pr.7381.642e759-a2 build

Download artifact

  1. Download the artifact from the Actions run
  2. Extract the tarball and install:
tar xzf billion-context-pr7381.tgz
npm install -g package

Install instructions are refreshed on each push.

@ranxianglei ranxianglei left a comment

Copy link
Copy Markdown
Owner Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Approved — this is the complete fix for the pf-tail-ids 16 KB overflow (#7367, same root cause as #7212). It handles both legs:

  1. Bounded tail (src/agent/pf-channel.ts, MAX_TAIL_IDS = 160): pfRequestHeaders now slices from Math.max(k-1, ids.length-160), so a frozen stamp can't grow the header unbounded, and the tail still ends at the true window origin (ids.length-1). A wider delta degrades to a conservative server-side miss.
  2. Stamp decoupling (src/server/fastpath.ts stampOnlyWatermarkTurn + src/server/prepare-openai.ts:679 else-if): when pluginFullResendWatermark is off the fastpath never runs, so x-bili-pf-seq stopped and the client's k2 froze — the exact #7367 wedge. Now the stamp is emitted on its own (T from the same zero-allocation scanMessagesSpans pass) so the watermark keeps advancing and the window self-heals. The else-if is the correct complement of the fastpath-evaluated branch (I checked the if/else structure) and is gated to plugin / non-title / flag-off.

This supersedes #7219: both edit the same pfRequestHeaders lines, so only one can land. #7219 (byte-cap + drop the header) only prevents the overflow — it does NOT decouple the stamp, so on the #7367 flag-off path the watermark stays frozen (permanent full-parse, no self-heal). Recommend closing #7219 in favor of this one.

One optional hardening (nit, not a blocker): the cap is id-count-based (160), not byte-based. Real msgids are short content-hashes so 160 × ~30 B ≈ 4.8 KB sits safely under the 16 KB limit, but #7219's byte-cap idea is more rigorous. If you want belt-and-braces, cap at min(160, 2 KB encoded) — happy to add it on this branch.

Housekeeping: 52 behind master (update); build-artifact is the stale pre-token-fix 404, re-running.

@ranxianglei
ranxianglei merged commit bf778d9 into master Nov 21, 2026
92 of 133 checks passed
@github-actions

Copy link
Copy Markdown
Contributor

📦 Merged Build Published

This merge to master was published as 0.0.1246-master.bf778d9 (rolling master tag).

npm install -g billion-context@0.0.1246-master.bf778d9  # 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 21, 2026
…-decouple)

Conflicts resolved:
1. src/server/prepare-openai.ts: union of fastpath imports (PR's
   DeltaReanchorError/PF_TAIL_IDS_HEADER/evaluateDeltaResend/parseTailIdsForPin
   + master's stampOnlyWatermarkTurn).
2. tests/fastpath.test.ts: union of fastpath imports (PR's
   evaluateDeltaResend/PF_DELTA_HEADER + master's stampOnlyWatermarkTurn).
3. src/agent/pf-channel.ts: kept PR's TAIL_MAX_BYTES byte-budget (supersedes
   master's MAX_TAIL_IDS count-cap; the byte check is stricter and
   tailPayloadFor is the single source of truth for both header emit AND
   full-form suppression).
4. src/server/fastpath.ts: kept BOTH evaluateDeltaResend (PR #6785 delta arm)
   AND stampOnlyWatermarkTurn (master #7367 stamp-only turn).
5. src/storage/shadow.ts: kept master's fileJsonWriter parameter (new in
   master, not in PR branch).
6. tests/pf-channel.test.ts: updated #7367 tail-cap test to match PR branch's
   byte-budget behavior (full slice under 8 KB, not capped to 160).
ranxianglei pushed a commit that referenced this pull request Nov 21, 2026
…lict at 0.0.202

Master advanced 122 commits past the PR base (batch-seam double-claim fix
#7428 -> kernel 0.0.201, storage backup/repair #7156/#7431, ingest-band
default-off #7426, pf-tail-ids cap #7381, OpenAI reasoning alias #7432,
dsh-mneme scan #7430, and more). Content hunks auto-merged (kernel/src/
compress.ts, all four storage-render goldens); the only conflicts were the
three kernel version lines, resolved at 0.0.202 = master's 0.0.201 + this
PR's kernel/src change, per the CI-enforced kernel version discipline.

Targeted local verification: tests/golden-storage-render.test.ts +
tests/storage-state-fields.test.ts 7/7, kernel issue6116/issue3769/
hide-consumed suites 27/27.
ranxianglei pushed a commit that referenced this pull request Nov 21, 2026
Two conflicts, both in the shared pf-plane client/server seam where master's #7381 (pf-tail-ids cap + stamp decouple) crossed the lane's v6 re-land:
- src/agent/pf-channel.ts: kept the lane's v6 fixed-window tail form (last PF_TAIL_WINDOW=64 ids, F1 owner ruling) — the merged function body has no k binding, so master's origin-slice form would not compile; the fixed window is inherently bounded, superseding the #7367 160-cap (removed the dead MAX_TAIL_IDS constant).
- src/server/prepare-openai.ts: union import — kept the lane's v6 imports and added master's stampOnlyWatermarkTurn (#7367 root fix: stamp advances even with the fastpath gate off).
- tests/pf-channel.test.ts: the auto-merged #7367 test asserted the superseded v5 cap-160 form (contradicted the lane's fixed-window test); updated it to pin the #7367 intent (bounded header on a frozen stamp) under the v6 form: 200 ids -> 64, 10 ids -> 10.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

bug Something isn't working p1 scope/kernel

Projects

None yet

1 participant