yovision/contracts/source-config/v1/compatibility.md

v1 兼容、迁移与回退

兼容规则

• v1 发布后只允许在预留的顶层 extensions 对象中增加命名空间化、非秘密的可选扩展。消费者必须忽略自己不认识的扩展命名空间，但仍须拒绝当前 Schema 或语义规则标记为非法的输入；发布扩展时应同步生产者/消费者测试。v1 核心对象保持封闭，不能通过新增核心字段规避新主版本。
• 删除字段、把可选改为必填、收紧已发布取值范围，或改变字段类型、单位、坐标系、Profile 绑定、revision、状态及媒体引用语义，均为破坏性变化，必须发布新主版本目录和新的 schema_version 值。
• 未知主版本必须安全拒绝并保留最后一个已验证配置。不得把未知版本转换成 v1，也不得继续启用来自未知版本的规则。
• v1 的坐标始终是相对于 profile.width × profile.height 图像平面的 0–1 归一化坐标；原点在左上，x 向右、y 向下。该语义不得在 v1 内改变。

revision 与生效

• (config_id, revision) 唯一标识一个不可变快照；同一 config_id 的新发布必须使用严格递增的 revision。
• 消费者仅在 Schema、语义和完整性均通过后，按 effective_at 原子切换整个快照。重复收到同一 revision 应幂等处理；更小 revision 应拒绝为陈旧配置。
• Profile ID、分辨率或编码变化时，生产者必须发布新 revision。已有几何尚未按新 Profile 校准时，必须设置 rule_set.state = recalibration_required；消费者不得启用其中规则。
• 新 revision 校验失败或未到生效时间时，消费者保留上一份已验证且仍有效的 active revision。

支持周期

• 发布新主版本后，Sense 生产者与 Brain 消费者至少并行支持上一主版本一个正式发布周期，且不少于 90 天；具体停止日期必须在新版本协调工单中冻结。
• 并行期内生产者按目标消费者能力选择版本，不得把两个主版本字段混在同一快照。

回退

1. 停止分发有问题的新主版本或新 revision。
2. 重新发布上一主版本的最后一个已验证快照；若仍为同一 config_id，必须使用该主版本下新的、更大 revision，不能覆盖历史 revision。
3. Brain 通过完整 Schema、语义和摘要校验后原子切回；切换前继续使用最后一个有效快照，或在没有有效快照时保持规则停用。
4. 记录失败版本和拒绝原因，但不得记录媒体凭据或完整客户配置。

样例 examples/valid/recalibration-required.json 展示 Profile 变化后的安全停用状态。回退不修改已发布 v1 字段语义，也不要求读取 Sense 数据库。