[P3][maintainability] 为 BrowserMessage 增加 Rust/TypeScript 契约测试或类型生成

[XiNian-dada]

现状

来自 2026-07-05 full audit。浏览器 WebSocket 消息在 Rust 和 TypeScript 两侧手写维护：

• nodelite-proto/src/message.rs:185-229：Rust BrowserMessage / wire message 定义。
• nodelite-server/src/ws/browser.rs:145-169：服务端处理浏览器消息。
• nodelite-server/web/src/api/types.ts:473-499：前端手写对应类型。
• nodelite-server/web/src/ws/client.ts:44-71：前端 WebSocket client 按手写类型分发。

已有 #249 补过运行时校验，#237 覆盖 WireMessage fuzz；但 Rust/TypeScript 之间的浏览器消息契约仍没有自动同步或跨语言 fixture 测试。

影响

后续新增/修改浏览器消息时，Rust 和 TypeScript 可能出现字段名、枚举 tag 或 payload 结构漂移。运行时校验可以降低坏消息影响，但不能提前阻止两侧类型定义分叉；这种问题通常会在 UI 实时功能里表现为沉默失效或难定位的连接异常。

建议

• 选择一种低维护方案固定契约：
  • Rust 侧生成 JSON fixtures，由前端测试消费；或
  • 用 schemars/ts-rs 等生成 TypeScript 类型；或
  • 建立共享 JSON Schema 并在 Rust/TS 两侧测试。
• 把至少一组 server -> browser 和 browser -> server 消息纳入跨语言回归测试。
• 将新增消息类型的契约检查接入 CI。

验收

• Rust 与 TypeScript 的 BrowserMessage 契约有自动化检查。
• 新增 fixture/schema 覆盖至少一个 browser -> server 消息和一个 server -> browser 消息。
• 前端测试能发现字段/tag 漂移。
• CI 会运行相关契约测试或类型生成一致性检查。

来源

• audit-report-NodeLite-2026-07-05.html：type-safety / maintainability 浏览器消息契约发现。
• 本地代码证据：上述 message.rs、browser.rs、types.ts、client.ts。
• 相关但不重复：[P3][stability] 浏览器 WebSocket 消息分发前增加运行时校验 #249、[P2][maintainability] WireMessage 解析缺少 fuzz 测试覆盖 #237。