test: add current protocol compatibility gate

docs/sdk/README.md

@@ -4,7 +4,7 @@
 
 module：`git.yuntuo.hk/k2safe/orbit/sdk/go`。SDK 使用独立 go.mod，依赖 Go 标准库与 `github.com/coder/websocket v1.8.15`，不引用服务端模型或数据库实现。
 
-发布候选先执行 [SDK 独立发布门禁](release.md)，确认 `GOWORK=off` 下依赖图、竞态测试、vet 和全包构建均通过；门禁不替代协议兼容矩阵或业务副作用回归。
+发布候选先执行 [SDK 独立发布门禁](release.md) 和[协议兼容矩阵](compatibility.md)，确认 `GOWORK=off` 下依赖图、竞态测试、vet 和全包构建均通过；门禁不替代业务副作用回归。
 
 任务相对延迟使用SubmitTaskRequest.DelayMS，由数据库首次受理时间计算，原键重报不重新计时；[完整延迟示例](../examples/delayed-task.md)包含Worker执行和历史核对。非零DelayMS不能与AvailableAt同用，旧服务须先升级。
 

docs/sdk/compatibility.md

@@ -0,0 +1,27 @@
+# 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`）与传输协议版本分开，业务版本固定在实例上，不改变旧实例的执行语义。
+
+## 发布前组合
+
+候选版本至少执行：
+
+```sh
+make protocol-check
+make sdk-check
+```
+
+然后在干净 checkout 中用候选 SDK module 标签运行健康、任务、Worker、事件订阅、流程定义/实例/恢复和文件转换示例。当前仓库已验证的是同一 checkout 的服务端与 SDK；旧/新跨版本组合、TLS 终止、外部副作用和生产容量仍需在发布候选及接入方环境单独验证。

docs/sdk/release.md

@@ -25,6 +25,8 @@ sh scripts/test-sdk-isolation.sh
 
 `package_count` 随示例增加而变化，不能作为兼容性版本号。门禁只证明源码在当前 Go 工具链下保持独立和可构建，不代表已经发布到远端模块代理，也不替代旧 SDK/新服务端和新 SDK/旧服务端的协议兼容矩阵。
 
+协议版本、WebSocket 子协议、流程 schema 和数据库版本见[兼容矩阵](compatibility.md)。发布候选还必须执行仓库根目录的 `make protocol-check`；它检查当前服务端、SDK 和机器可读 schema 是否仍在同一协议线，不把历史版本组合标记为已验证。
+
 ## 接入方式
 
 SDK 尚未发布正式标签时，开发项目可以使用本地 replace；发布候选必须使用独立 module 的版本标签和干净 checkout 验证。接入方应固定 SDK 版本，升级前先执行自己的接口和业务幂等回归：