Schema Registry 消费者兼容发布：Reader/Writer 解析、Lag 水位与升级顺序

团队给订单事件增加 currency 并设置默认值，Schema Registry 的 BACKWARD 检查通过，于是 producer 立即上线。实时消费者已经升级，停机两周的结算任务仍用旧 reader；另一个消费者把 enum 未知值映射成第一项，数据没有报错却被按错误币种汇总。兼容检查只回答特定 reader/writer schema 能否解析，不知道每个消费者的业务分支和积压水位。

Avro 反序列化同时使用 writer schema 和 reader schema，并定义字段匹配、默认值、类型提升、union 与 enum 解析规则。Confluent Schema Registry 区分 backward、forward、full 及 transitive 模式；非 transitive 检查通常只比较指定历史边界。平台必须把这些规则连接到真实部署顺序。事件驱动架构解释松耦合，REST API 版本控制处理请求响应接口；事件 schema 还要面对长期保存的数据和离线 reader。

发布的是 schema 与消费范围的闭合合同

eventSchemaRelease.v1 绑定 subject、格式、规范 schema digest、registry ID、compatibility mode、是否 transitive、writer/reader canonical form、logical type policy、默认值语义、字段分类、producer audience、consumer inventory snapshot、topic/partition watermark、保留期和上一 release。field name 相同但单位、时区或 null 含义变化属于语义破坏，不能靠 parser compatible 放行。

schema: eventSchemaRelease.v1
subject: order-events-value
release: 18
format: avro-1.12
compatibility: BACKWARD_TRANSITIVE
schemaDigest: sha256:8c1...
consumerInventory: consumers@watermark-771
producerEpoch: 42

inventory 从鉴权、消费组、批处理调度和数据目录汇总，每个 consumer 记录 owner、reader digest、支持字段/enum、最后部署、当前 offset、最大休眠和业务断言。未知 consumer 或无 owner 的保留数据使发布状态为 COVERAGE_UNKNOWN。只扫描当前在线 group 会漏掉月末任务、灾备 reader 和回放工具。训练数据 Schema 演进关注训练集字段，本合同约束连续事件读写。

用兼容方向决定升级顺序

状态为 DRAFT -> REGISTRY_CHECKED -> CONSUMER_TESTED -> WATERMARK_READY -> APPROVED -> ACTIVE -> RETIRED。BACKWARD 表示新 reader 可读旧 writer 数据，通常先升级 consumers，再切 producer；FORWARD 允许旧 reader 读取新 writer，通常先切 producer；FULL 才允许更灵活顺序。实际顺序仍由 release 明示，并在保存的历史 writer schema 上运行 reader conformance，不能只信模式名称。

每个 consumer 在密封 fixture 中读取所有受支持历史 writer generation、新候选和未知 enum/null/默认值案例，输出业务投影 digest。通过后签发 readiness receipt，绑定 reader artifact、schema digest 和已追平 offset。producer 的唯一接受点是 gateway CAS 提升 producer epoch；前提是强制 consumer receipts 覆盖率 100%，休眠 consumer 已隔离/退役，且当前 registry mode 与批准摘要一致。

消息携带 writer schema ID 和 producer epoch。消费者遇到未知 ID、错误 subject 或低于安全 floor 的 reader 时进入 dead letter，不可用“最新 schema”猜。Schema cache 也按 registry generation 失效；缓存 Revalidation的 fence 可阻止撤销后旧 schema 回填。API Mock 与 Fixture 漂移提醒测试样例也必须从真实合同派生，而不是手工维护漂亮 JSON。

让解析成功但语义错误暴露

故障测试删除无默认字段、改变 decimal scale、移动 logical timestamp 单位、给 enum 增加旧 reader 不认识的 symbol、错配 subject ID、registry 回滚配置、consumer readiness 后又回退 artifact、积压跨越 producer cutover、compact topic 缺历史样本，以及新旧 producer 同时写。断言 parser error、业务投影差异和 coverage unknown 都能阻断接受，不能把 decode 成功算完成。

门禁可要求：registry compatibility 与独立解析 oracle 一致率 100%；强制 consumer inventory owner/readiness 覆盖率 100%；全部保留 writer generation 的 fixture 业务摘要差异为 0 或在批准清单；未知 schema 静默 fallback 为 0；producer epoch 切换后旧 writer 接受为 0；dead-letter 不超过预注册阈值且每项有 owner。TRANSITIVE 模式也不能替代真实消费者测试。

上线先让 gateway shadow 校验候选但仍发送旧 schema，再升级一组内部 consumer 并双读比较，最后按 topic producer 稳定分桶。异常时停止新 epoch，把 writer alias 切回上一 schema；新字段事件若已经持久化，必须确认旧 reader 能读或保留新 reader 路径，不能只回滚 producer 后宣布恢复。历史 schema、fixture 和 readiness receipt 保持不可变，Agent API 契约门可复用同样的消费者优先思路，但事件保留期让兼容窗口通常更长。