V1 RC 契约与发布策略

当前冻结版本

IWish Auth 的 V1 RC 标识为 v1.0.0-rc.1。冻结范围包括：

• OpenAPI 1.0.0-rc.1
• App Session 0.3
• Manifest Schema 2.0
• Account Migration Schema 1.0
• TypeScript SDK 0.3.0
• Python SDK 0.3.0
• CLI 0.4.0

SDK 和 CLI 的包版本不等于平台 RC 版本。业务 App 必须同时记录平台 RC 和所用 SDK/CLI 版本。

兼容性规则

以下改动允许在同一主版本发布：

• 新增可选响应字段。
• 新增可选请求字段。
• 新增 API 路径或 Webhook 事件。
• 修复实现但不改变已声明语义。
• 扩充枚举前已明确要求调用方容忍未知值。

以下改动属于破坏性变更：

• 删除或重命名字段、路径、错误码或事件。
• 把可选字段改为必填。
• 改变字段类型、Session 语义、身份主键或授权边界。
• 缩短兼容窗口，导致已发布 SDK 或现有 App 不能工作。
• 改变 Manifest/迁移 Schema 且旧文档无法通过校验。

破坏性变更必须提升主版本，并同时提供迁移说明、兼容时间窗、双版本测试和回滚方案。不得静默覆盖既有版本化制品。

制品验证

每个 RC 的公开入口为：

/releases/<release>/release.json
/releases/<release>/SHA256SUMS
/releases/<release>/artifacts/*

业务 App 或 AI Agent 应先读取 release.json，再按 SHA256 校验所需 SDK、CLI、Schema 和 OpenAPI。不要仅依赖 /packages/ 的兼容入口判断某次 RC 的完整内容。

数据库兼容

RC 期间的 migration 默认只做向前兼容变更。代码回滚不能恢复数据库结构，因此：

• 先新增，再回填，再切换读取，最后在后续主版本清理。
• 禁止在同一发布中删除仍被上一 Worker 版本使用的列、函数或表。
• 破坏性 DDL 必须有独立审批、可恢复备份和隔离恢复演练。

接入方记录

每个业务 App 的 staging/production 发布证据至少记录：

• IWish Auth RC 版本。
• SDK/CLI 版本与 SHA256。
• OAuth Client 环境和 callback。
• Manifest 版本。
• App 自身 Git commit、数据库 migration 和回滚点。