orbit/docs/reports/phase-7-historical-compatibility.md

P7 历史 SDK / 服务端兼容性演练

验证日期：2026-09-20。该演练选取历史提交 a50d5faac7450ea3a30406d587d9d7746990e2ed（2026-09-17，feat: add audited task review and linked manual retries）作为可追溯 fixture，验证稳定任务 API 的两条方向。仓库目前没有正式 SDK 或服务端 release tag，因此本报告不能替代正式标签矩阵。

执行方式

ORBIT_COMPAT_OLD_COMMIT=a50d5fa ./scripts/test-historical-sdk-compatibility.sh
# 或
make mysql-compatibility

脚本使用 Go 1.27.1 容器构建历史与当前的 orbit、orbit-migrate、orbit-admin，使用一次性 MySQL 8.4 数据库分别初始化两套 schema，再启动真实 HTTP 服务运行 examples/tasks。任务提交、重复幂等、查询、分页和取消都通过真实服务完成；数据库、容器、临时凭据和二进制在退出时清理。

实际结果

{"historical_commit":"a50d5fa","old_server_current_sdk":"passed","current_server_old_sdk":"passed","scope":"stable task API smoke; not a formal release-tag matrix"}

两条方向均得到 duplicate=true、listed=1、final_state=CANCELLED、revision=2。当前 SDK 对历史服务端明确设置 ORBIT_SKIP_SOURCE=1，因为任务来源查询是历史 fixture 之后新增的接口；正常当前版本示例默认仍会校验来源接口。这个开关只用于兼容性 smoke，不属于生产接入配置。

结论与边界

• 稳定任务 API 在该历史提交与当前提交之间完成了双向真实服务演练。
• 结果事件、Worker WebSocket、流程、计划和后续新增接口没有由该历史提交覆盖，不能据此宣称全协议兼容。
• 发布前仍需创建正式不可变 tag，并对每个受支持的旧 tag 执行双向矩阵；不兼容变化应按 HTTP 路径、WS 子协议或 schema $id 升级规则处理。