orbit/docs/sdk/compatibility.md

SDK 与协议兼容矩阵

当前发布线是 HTTP /v1、Worker WebSocket pulse.worker.v1、结果事件 WebSocket orbit.events.v1、Worker/事件帧 protocol_version=1、流程定义 schema_version=1，数据库要求 MySQL 8.4+ 与 Orbit schema v28。协议门禁由 make protocol-check 执行，检查服务端常量、SDK 常量、路由和机器可读 schema 是否一致。

SDK / 客户端	服务端	当前证据	结论
当前仓库 SDK	当前仓库服务端	scripts/test-protocol-compatibility.sh、SDK 单元/竞态测试、HTTP/WSS 集成测试	已验证
上一个正式 SDK 标签	当前服务端	仓库尚未发布正式 SDK 标签	未验证，不得宣称兼容
当前 SDK	上一个正式服务端标签	仓库尚未发布正式服务端标签	未验证，不得宣称兼容
非 Go HTTP 客户端	当前服务端	/v1 接口手册、严格输入和错误码回归	按接口手册逐项验证

兼容规则

同一协议线内只允许保持字段语义、状态值和错误码含义不变的兼容扩展。新增响应字段通常由 HTTP JSON 客户端忽略；新增请求必填字段、修改既有字段类型/单位、修改状态终结语义或改变 WebSocket 帧方向，都不属于兼容扩展。Worker 和事件 SDK 的帧解码会拒绝未知字段或错误版本，避免把协议漂移当作业务结果。

发生不兼容变化时必须新建 HTTP 路径版本、WebSocket 子协议或 schema $id，并保留旧线的服务端/SDK 实现与回归，直到发布说明明确移除日期。不能仅增加一个文档版本字符串来掩盖行为变化。流程业务版本（例如定义的 version）与传输协议版本分开，业务版本固定在实例上，不改变旧实例的执行语义。

发布前组合

候选版本至少执行：

make protocol-check
make sdk-check

然后在干净 checkout 中用候选 SDK module 标签运行健康、任务、Worker、事件订阅、流程定义/实例/恢复和文件转换示例。当前仓库已验证的是同一 checkout 的服务端与 SDK；旧/新跨版本组合、TLS 终止、外部副作用和生产容量仍需在发布候选及接入方环境单独验证。