版本契约

不同版本字段保护不同边界，不能互相替代。

契约	当前值	保护内容
DIY Pack schema	1	manifest/cards/effects 的可移植 JSON 形状
Engine API	"1"	DIY Pack 可依赖的公共加载能力
Snapshot schema	1	快照信封形状
Rules contract	"rules-v2"	对局规则语义
Runtime protocol	1	决策、动作与会话推进契约
Trace schema	1	动作回放形状
Fingerprint schema	1	稳定指纹输入编码约定

兼容原则

• 版本完全匹配才恢复快照或回放；
• 卡池指纹必须同时匹配；
• DIY Pack v1 的依赖版本必须精确匹配；
• 未知字段、未知枚举和未知效果响亮失败；
• 当前不提供隐式 schema 迁移；
• 新增带 Serde 默认值的内部字段仍需测试旧形状读取与新形状往返。

何时升级

以下变化通常要求升级对应契约：

• 可序列化公共字段的删除、改名或语义变化；
• Action、Observation 或 Pending 协议不兼容改变；
• 快照恢复后会得到不同规则语义；
• Pack 可用字段或命名空间/依赖解释发生不兼容变化；
• 指纹规范改变，导致相同逻辑内容产生不同指纹。

仅新增内部测试、文档或不影响已序列化形状的实现重构，不应机械抬升全部版本。

升级流程

1. 在规则文档登记语义变化；
2. 明确受影响的最小契约；
3. 更新常量、schema 与示例；
4. 添加旧版响亮拒绝或显式迁移测试；
5. 重新生成覆盖率、卡池与文档确定性产物；
6. 在发布说明中列出调用方需要采取的动作。