Skip to content

[PR] kernel: wire byte fidelity — anthropic unknown-block passthrough + openai/google stability pins (#3410) - #3961

Merged
ranxianglei merged 2 commits into
masterfrom
2026-10-20_3939-prc-wire-fidelity
Oct 20, 2026
Merged

ranxianglei merged 2 commits into
masterfrom
2026-10-20_3939-prc-wire-fidelity

Conversation

@ranxianglei

@ranxianglei ranxianglei commented Oct 20, 2026 •

Copy link
Copy Markdown
Owner

kernel-change: wire byte fidelity (#3938 / #3939⑥, absorbs #3547 kernel hunks)

Part of #3938 · implements #3939 item ⑥ · kernel-side fix for #3410 (issue completes when #3547's host lane lands)

What changed

Rebased onto current master (post-#3941 stubs, post-#3944 invariant judge, post-MySQL-backend landings, post-#3969 config-docs regen); per-commit lockfiles synced for the lock-sync lane.

Commit 1 — 42147ec anthropic unknown top-level block passthrough (#3410)

  • kernel/src/wire/anthropic.ts: new default case in the per-block switch. Unknown block types (document/PDF, future types) now ride the existing rawAnthropicBlock sidecar exactly like image/redacted_thinking and are re-emitted VERBATIM by coreToAnthropic (block-internal cache_control included). Previously they were silently dropped at parse — repro on master: [text, document] rebuilds as [text], the payload is gone from every later request and from any fold touching that message.
  • kernel/src/protected.ts: absorbed verbatim from [PR] fix: preserve unknown anthropic top-level blocks verbatim in the anthropic wire codec #3547 — an unknown anthropic sidecar block now counts as media AND unrecoverable (the payload exists only in the sidecar; bili archives images only, so folding it = permanent loss). Parity preserved: base64/url image, redacted_thinking and plain text keep their exact old verdicts (pinned).
  • kernel/tests/issue3410-wire-passthrough.test.ts: round-trip byte-exactness incl. cache_control, order preservation both directions, multiple unknown types, assistant-side blocks, predicate matrix, id determinism, parse∘rebuild fixed point.
  • Intentionally moved pin: kernel/tests/issue3939-wire-unknown-parts-pins.test.ts ("anthropic silently drops…") rewritten to pin the NEW contract (document survives round trip byte-exact), as that file's own header planned ("update the anthropic pins IN THE SAME PR"). Its google/responses pins are untouched and still green.
  • Lockfiles: root package-lock.json + kernel/package-lock.json regenerated to match the bump (lock-sync lane). Version 0.0.137 → 0.0.138.

Commit 2 — cfc3b96 openai/google byte-stability contract + pins
The "convention-stable" rows of #3938's root-cause table (openai leading-opaque reorder, google fixed part-order normalization) become an EXPLICIT contract:

  • coreToOpenai JSDoc: emission is a pure function of the core array; the canonical user-run shape is fixed (lone plain text → string, else parts in CORE order, text first then rawOpenaiContentParts); the leading-opaque PREPEND makes [opaque,text,opaque] emit [text,opq1,opq2] deterministically.
  • coreToGoogle JSDoc: for alternating-role histories emission is pure in the core array; the canonical orders ARE the merge rules (model reasoning→text→tool-call, user functionResponse-then-content); same-role merging is required normalization and its output order is canonical.
  • kernel/tests/issue3939-wire-byte-stability.test.ts: golden rebuild shapes per line plus cross-request prefix byte-identity (same shape re-sent on consecutive requests ⇒ identical request bytes) and id determinism on both lines. Same-role google merging is pinned as behavior, not chased as a bug (reachable only with client-invalid non-alternating input).
  • No runtime change (comments + tests). Lockfiles regenerated. Version 0.0.138 → 0.0.139.

Behavior change disclosure

surface old new why
anthropic unknown top-level blocks (document/PDF/future) silently dropped at parse passed through verbatim (sidecar); counted media+unrecoverable for protection fidelity restoration (#3410): upstream starts receiving the blocks IT sent; folds no longer permanently lose their payload
openai/google request bytes stable by convention (unproven) same shape ⇒ same bytes every request, pinned by test the prefix-cache core promise; a regression here goes red in CI instead of surfacing in production

No other behavior changes: hidden-content sets, truncation, ref allocation, summary texts are untouched — those are items ①–⑤, delivered by #3956. Golden pins tests/golden/wire-contract/kernel.json unchanged. Semantics-unchanged commitment per #3939 holds: what gets changed is identical, only the wire now keeps what it was always supposed to keep.

Config surface

None. No new env vars, config fields or CLI flags.

Coordination

Verification

@ranxianglei ranxianglei changed the title kernel: wire byte fidelity — anthropic unknown-block passthrough + openai/google stability pins (#3410) [PR] kernel: wire byte fidelity — anthropic unknown-block passthrough + openai/google stability pins (#3410) Oct 20, 2026
@ranxianglei
ranxianglei force-pushed the 2026-10-20_3939-prc-wire-fidelity branch 2 times, most recently from 9803bb8 to e04faee Compare October 20, 2026 12:39
@github-actions

github-actions Bot commented Oct 20, 2026 •

Copy link
Copy Markdown
Contributor

📦 Built Package Artifact

Branch: 2026-10-20_3939-prc-wire-fidelity (477f3d7)

Option A — Install this exact build (recommended)

npm install -g billion-context@0.0.4754-pr.3961.5859e31

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

Install instructions are refreshed on each push.

@ranxianglei
ranxianglei force-pushed the 2026-10-20_3939-prc-wire-fidelity branch from e04faee to cfc3b96 Compare October 20, 2026 13:01
awork added 2 commits October 20, 2026 21:19
anthropicToCore's block switch had no default case: unknown top-level
block types (in the wild today: document/PDF) fell out silently and their
payload vanished on every rebuild with no warning. Unknown blocks now ride
rawAnthropicBlock exactly like image/redacted_thinking — coreToAnthropic
re-emits them byte-exact (cache_control included) and never renders the
label text; protected.ts classifies them as media AND unrecoverable so a
fold can never destroy a payload the host archives nowhere.

Absorbs the kernel-side hunks of PR #3547 (adapted to master's #3642
canonical identity); #3547 keeps its host-side notice/billing surface.

kernel-change: wire保真(#3938 / #3939⑥, 吸收#3547)
…ion (#3938 / #3939⑥)

The openai leading-opaque reorder and the google part-order normalization are
the "convention-stable" rows of #3938's root-cause table: they rewrite bytes
on every request by convention rather than by state. This commit makes that
stability an EXPLICIT contract and pins it:

- coreToOpenai JSDoc: emission is a pure function of the core array; the
  canonical user-run shape is fixed (lone plain text -> string, else parts in
  CORE order, text first then rawOpenaiContentParts); the leading-opaque
  PREPEND exists so [opaque,text,opaque] emits [text,opq1,opq2] deterministically.
- coreToGoogle JSDoc: for alternating-role histories emission is pure in the
  core array; the canonical orders ARE the merge rules (model
  reasoning->text->tool-call, user functionResponse-then-content); same-role
  merging is required normalization and its output order is canonical.
- issue3939-wire-byte-stability.test.ts: golden rebuild shapes per line plus
  cross-request prefix byte-identity (same shape re-sent on consecutive
  requests must produce identical request bytes) and id determinism on both
  lines. Same-role google merging is pinned as behavior, not chased as a bug
  (reachable only with client-invalid non-alternating input).

No runtime change: comments + tests only. The goldens fail if a future edit
turns either normalization into a shape-dependent or order-dependent rewrite.
@ranxianglei
ranxianglei force-pushed the 2026-10-20_3939-prc-wire-fidelity branch from cfc3b96 to 477f3d7 Compare October 20, 2026 13:29
@ranxianglei

Copy link
Copy Markdown
Owner Author

🤖 Powered by ework · qwen3.8-27b

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

冲突已解除:PR 分支 rebase 到当前 master(74090acca)后 push,merge state dirty → blocked(只剩新 head 的 CI checks 在跑)。

八问

  1. 是什么问题:本 PR(kernel wire byte fidelity,Closes anthropic wire silently drops unknown top-level blocks (incl. PDF document) when rebuilding history #3410)与 master 冲突(merge state dirty),暂时无法合并。
  2. 什么原因导致的:PR 分叉点(e01238e6a)之后 master 前进了 42 个提交,其中其他 kernel PR 把 kernel 版本号从 0.0.137 一路 bump 到 0.0.144,与本 PR 的两个版本行提交撞在同一批文件(kernel/package.json、kernel/package-lock.json、根 package-lock.json)。源码零冲突——正是 PR 描述里预判的那类机械版本行碰撞。
  3. 影响范围与严重程度:仅调度/流程层面——PR 一度不可合并;对代码行为、用户无影响。
  4. 怎么修复的:rebase 两个提交到当前 master;三处冲突全部取 master 侧后继续顺序 bump——commit 1:0.0.144→0.0.145,commit 2:0.0.145→0.0.146(Kernel Boundary 要求每个触碰 kernel/src 的提交各自独立 bump,保持两提交结构不变)。核验:PR 拥有的 7 个文件(wire/protected 源码 + 3 个测试)与旧 head 逐字节一致,全量 diff stat 与原 PR 相同(10 files,+441/−14),无残留冲突标记。(过程透明:本地第一次 rebase 尝试因解析脚本出错产生过一个带冲突标记的坏中间提交,当场 abort 重做,未 push 过任何东西。)
  5. 是否有回归问题:无。本次操作只改了三个版本号,内容零变更。定向验证全绿:kernel 136/136(PR 三个测试文件 + media-payload / message-protection / wire-formats / roundtrip / cross-protocol-identity / wire-google / system-hoist 七个相邻套件)、bili 侧 97/97(含 Image errors accumulating in the conversation | 对话中图片错误堆积 #3398 pin)、typecheck clean、image-billing hermetic lane 5/5。全量套件以新 head 上的远程 CI 为准。
  6. 是否破坏缓存:不涉及。
  7. 是否改了设计方向:否。
  8. 是否引入了新的配置:否。

另提醒一条既有协调事项(非本次引入):#3547 收窄为 host-only 且排在本 PR 之后合入;它落地时 tests/issue3398-opaque-media-reserve.test.ts:87-106 的 document 计费断言需要同步更新(本 PR 单独在时该测试保持绿),目前无人认领该更新,已在 PR 描述中 flag。

判定:冲突解决完毕,等 CI 转绿即可按正常流程进入人工 review/merge。

@ranxianglei

Copy link
Copy Markdown
Owner Author

🤖 Powered by ework · qwen3.8-27b

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

收到冲突转发,核查后无需再次 rebase——当前 PR 在 GitHub 上并不处于 dirty 状态。

八问

  1. 是什么问题:系统再次转发「PR 与 base 分支冲突(merge state dirty)」,要求重新 rebase。
  2. 什么原因导致的:这条转发是陈旧/瞬态快照。上一轮 rebase force-push 之后,GitHub 需要短暂窗口重算 mergeable 状态;镜像很可能在该窗口内(或基于旧快照)采到了 dirty。当前实测:mergeable: true、mergeable_state: blocked(blocked = 可合并、仅等必需 CI checks),base master 仍为 74090accaa——与我上次 rebase 的目标完全一致,master 没有再前进;远端 head 就是上次 push 的 477f3d78d3。
  3. 影响范围与严重程度:无实际影响——代码零变更,未做任何重复 rebase(重复 rebase 只会白跑 CI)。
  4. 怎么修复的:不需要修。按「冲突解完状态会自动转干净,不要重复 rebase」纪律,核实后不动分支。
  5. 是否有回归问题:不涉及(零改动)。
  6. 是否破坏缓存:不涉及。
  7. 是否改了设计方向:否。
  8. 是否引入了新的配置:否。

当前 CI 实况(head 477f3d78d):44 个 check runs——23 success / 13 skipped / 8 进行中或排队 / 0 failure。等剩余 lanes 跑完即全绿,届时可按正常流程进入人工 review/merge。若后续 master 真的再前进产生新冲突,请再转发。

ranxianglei pushed a commit that referenced this pull request Oct 20, 2026
Host-side half of #3410: price document/other unknown top-level blocks in
the billing reserve (probe + cost/count walkers) and warn once per shape
that they ride verbatim but stay out of folding. The kernel-side codec fix
(sidecar passthrough) ships separately in #3961 — merge #3961 first so
priced bytes == forwarded bytes. Pin updated: #3398 document case now
expects opaque-media pricing.
@ranxianglei

Copy link
Copy Markdown
Owner Author

🤖 Powered by ework · qwen3.8-27b

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

Review(独立重审了新 head 477f3d78d 的完整 diff,非沿用旧 head 印象):可合。kernel 层按边界规则留人工合并。

① 原 issue 方向:#3939⑥ 要的是「anthropic 未知顶层 block 透传 + 丢弃告警对齐 openai 线」。本 PR 在 codec 源头(anthropicToCore 的 switch default)修,不是下游打补丁——payload 消失的生产者就是缺 default 的这个 switch,修法打在点子上。告警/计费半拆到 #3547(kernel/host 包边界拆分,属允许的例外)。方向 ✓。

② 回归审查(逐项过既有行为):

  • anthropicToCore 已知六类 block(text/thinking/redacted_thinking/tool_use/tool_result/image):diff 零触碰,default 只对未知类型触发 ✓
  • 往返字节:coreToAnthropic 对 rawAnthropicBlock 消息逐字重发(含 cache_control),label text 永不渲染——与 image/redacted_thinking sidecar 完全同构,parse∘rebuild 不动点保持;新测试用真实 round-trip 断言钉住 ✓
  • protected.ts 两处判定:新检查放在 image/tool_result 检查之后,排除名单 {image, tool_result, redacted_thinking}——所有既有形状的判决逐一对过:redacted_thinking 仍落到 item 级检查得 false(与改前一致),image/tool_result 走原路径不变;唯一新行为 = 未知类型算 media → 排除出折叠(诚实方向:bili 无法归档其 payload,fold 即永久丢失,宁保守)✓
  • 金 pin tests/golden/wire-contract/kernel.json:不在 diff 里 ✓;配置面/提示词/nudge:零触碰 ✓
  • google/openai 两文件的 diff 逐行核对为纯注释(JSDoc 契约块),零代码行变更 ✓

③ 代码审查:default case 的 label 派生([${type}]/[unknown])+ deriveCanonicalMessageId(m.role,"text",label) + clusters.next(base) 保序,完全复用既有 sidecar 模式,无新机制。JSDoc 明确写出「不得在未移动 pin 的情况下重排 emission」——把契约写在使用处,好。

④ 测试有效性:有牙——round-trip 是真实序列化比对(含 cache_control 位置);byte-stability 套件(214 行)用 JSON.stringify(req2.slice(0,req1.length))===JSON.stringify(req1) 断言跨请求前缀字节恒等,非确定性/重排都会被抓;google 同 role 合并被钉为「必需归一化」(仅客户端非法的非交替输入可达)——诚实钉行为而非假装不存在。打桩纪律也守了:unknown-parts pin 在行为变更前已存在,本 PR 内同 PR 移动并写明 provenance。双向门控齐(已知类型仍往返 / 未知类型保留且排除折叠)。

⑤ diff 整洁度:10 文件 +441/−14,全部与本 PR 目的相关;kernel 版本 0.0.145→0.0.146 符合 CI 强制的版本纪律;无跑题文件、无空白噪音。

风险披露(不阻塞):① 合并顺序——本 PR 先于 #3547 合时,document 转发但未计价(#3547 正文已带 pin 备注,少收方向,风险低);若 #3547 先合则 NOTICE 文案会声称 "preserves verbatim" 而 codec 仍在丢(honest-output 违约窗口)——所以顺序必须是 #3961 → #3547。② 新 sidecar 消息让 nudge/token-count/reconcile 多看到一个 ~2 token 的小文本行(payload 本体不计),量级可忽略,且与 image sidecar 现状一致,无新失败类。

八问:

  1. 是什么问题:anthropic 线对未知顶层 block(document/PDF 等)整块静默丢弃,每次 rebuild 丢一次,四条 wire 线里唯一无告警的。
  2. 什么原因:codec switch 缺 default 分支——生产者就在这一处。
  3. 影响范围与严重程度:仅使用 anthropic 线且携带未知顶层 block 的会话;数据永久丢失级(p1 语义),但当前真实流量中该形状罕见(document 主要经 tool_result 嵌套,走的是保留路径)。
  4. 怎么修复的:sidecar 透传——未知 block 挂 rawAnthropicBlock 随核心消息走,反向重建逐字重发;media 判定收编使其排除折叠;归一化形状(openai/google)补 byte-stability 契约 pin。
  5. 回归风险:见上逐项清单——已知六类 block、金 pin、配置面、nudge 全未动;唯一行为变更即目标变更本身,已披露。
  6. 缓存:sidecar 在原序列位重发,前缀字节稳定反而修复了丢块导致的接缝漂移;cache_control 位置随原块保留。
  7. 设计方向:无转向,沿用既有 redacted_thinking/image sidecar 模式;byte-stability 契约是 [Kernel Initiative] Transactional folding boundaries + wire byte fidelity (unified prefix cache fix #3938, kernel side) | [kernel 专项] 折叠边界事务化 + wire 字节保真(前缀缓存统一修复 #3938 内核侧) #3939⑥ 已有方向的固化。
  8. 新配置:无。

CI:477f3d78d 上 11 success / 13 skipped / 6 in_progress,零失败(主 CI shard 还在跑,红了我会跟进)。宿主侧配套 #3547 已按协调收窄重推(4ffb23606,纯宿主、pin 已更新)。

@github-actions

Copy link
Copy Markdown
Contributor

📦 Merged Build Published

This merge to master was published as 0.0.681-master.768a60c (rolling master tag).

npm install -g billion-context@0.0.681-master.768a60c  # 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 Oct 23, 2026
…ng parity (#3410)

The kernel side (PR #3961) rides unknown anthropic top-level blocks on
the sidecar and re-emits them verbatim; the host side it expects:

- src/wire-drop-warn.ts: unknownAnthropicBlocks() - scans parsed
  anthropic bodies for top-level block types outside the known six and
  reports {count, types, firstIndex} (null when clean).
- src/server.ts + src/server/prepare-anthropic.ts: one NOTICE per
  session per type-set (warnedWireDropKeys FIFO, same discipline as
  droppedOpenaiParts) so operators can see document/PDF traffic riding
  the passthrough instead of vanishing silently.
- src/image-tokens.ts: billing parity - unknown blocks meter like
  media: base64 payloads by encoded length, urls at REMOTE_IMAGE_TOKENS
  (capped), bare unknowns at the flat 4096 floor. Known non-media
  blocks (text/thinking/tool_use/tool_result) stay outside the branch -
  the walker's golden anthropic stats are byte-stable.
- tests/issue3410-unknown-anthropic-block.test.ts: report shape, NOTICE
  once-per-type-set cadence, billing matrix (base64/url/bare/mixed),
  e2e passthrough through the real server lane.

Stacked on #3961 (kernel passthrough); Part of #3938.
ranxianglei pushed a commit that referenced this pull request Oct 23, 2026
…ng parity (#3410)

The kernel side (PR #3961) rides unknown anthropic top-level blocks on
the sidecar and re-emits them verbatim; the host side it expects:

- src/wire-drop-warn.ts: unknownAnthropicBlocks() - scans parsed
  anthropic bodies for top-level block types outside the known six and
  reports {count, types, firstIndex} (null when clean).
- src/server.ts + src/server/prepare-anthropic.ts: one NOTICE per
  session per type-set (warnedWireDropKeys FIFO, same discipline as
  droppedOpenaiParts) so operators can see document/PDF traffic riding
  the passthrough instead of vanishing silently.
- src/image-tokens.ts: billing parity - unknown blocks meter like
  media: base64 payloads by encoded length, urls at REMOTE_IMAGE_TOKENS
  (capped), bare unknowns at the flat 4096 floor. Known non-media
  blocks (text/thinking/tool_use/tool_result) stay outside the branch -
  the walker's golden anthropic stats are byte-stable.
- tests/issue3410-unknown-anthropic-block.test.ts: report shape, NOTICE
  once-per-type-set cadence, billing matrix (base64/url/bare/mixed),
  e2e passthrough through the real server lane.

Stacked on #3961 (kernel passthrough); Part of #3938.
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