兼容性与迁移
Type14 兼容方向、Type13 退役、历史归档和后继版本迁移。
精确版本保证重复解析同一份契约，不保证任意两个实现兼容。平台按结构和方向检查签名，不通过同名、相似字段或版本范围猜测兼容。
输入与输出的方向
实现必须接受调用方允许的全部输入；实现的每一种返回结果和事件载荷必须能被调用方接受。即方法输入逆变、结果和事件协变。
| 变化 | 影响 |
|---|---|
| 实现新增必填参数或收窄输入 | 不兼容 |
| 实现扩大可能返回的值、null 或错误范围 | 可能不兼容，必须按调用方约束证明 |
| 同步/异步改变，缺少所需方法或事件 | 不兼容 |
| 实现额外提供未要求的方法 | 本身不破坏原方法，其他检查仍须通过 |
| 封闭对象增加字段 | 原消费者可能拒绝，不能一概视为兼容 |
Schema 比较返回 Compatible、Incompatible 或 NotProven。后者表示现有算法无法证明包含关系，不授权发布或绑定实现；它不是自动回退到宽松校验。外部引用比较必须提供已授权的精确资源集合。
类型签名不能证明事务、幂等、超时与业务语义相容，见方法行为与重试契约。
统一版本与退役边界
当前唯一开发规范为 baijimu-types 14.0.0 / Type Definition 5.0.0。Module、Workflow、Agent 结构化结果和人工事项统一使用本规范：数据声明采用 JsonSchema 和标准 Schema；RefType 只描述接口。Type13 已从当前开发文档退役，不再提供旧格式作者示例。
旧环境拒绝 Type14 时，应升级相应生产者、消费者与 CLI，再迁移业务资源；不要退回旧数据格式或添加静默转换。文档规范不代替目标环境的部署和迁移验收。
contracts/<contract>/<version>/ 中已发布的历史归档只用于追溯既有不可变产物，不属于当前开发入口。历史字节不能覆盖或伪装成 Type14，也不能据此创建新资源。存量资源须由对应 Owner 创建后继版本；在途执行和存量引用清点、迁移完成后，才移除对应历史读取代码。
迁移到 Type14
旧 DataType / 数据 Map / 数据 RefType 不是 Type14 的输入。迁移时需要理解原合同，再创建新草稿：
- 将数据正文改为标准 Schema，完整 Type 位置使用
JsonSchema包装，子 Schema 不携带平台标签。 - 显式保留原对象开放性；封闭对象加
additionalProperties: false。properties: {}在标准 Schema 中仍默认开放。 - 用类型联合或组合表达 null；区分对象
required、参数required、参数default_value和仅作为注释的 Schemadefault。 - 将数据引用改为
$ref，把命名数据放入dataSchema.$defs、接口放入interfaces；按新作用域校验外部资源与递归。 - 发布后继 Type Definition，更新消费 Module 的精确导入并创建后继 Module / Bundle；确认目标消费者支持后再安装和验证。
历史版本不可原地改写。业务资源的 SemVer 按实际兼容性选择，不能把文档协议版本号复制成所有资源版本号；新库不会自动升级存量资源。
常见错误
| 错误或现象 | 检查与处理 |
|---|---|
| 旧数据标签无法解析 | 确认接收方协议；Type14 使用 JsonSchema，不能只替换标签而保留旧字段 |
type: "unknown" 不合法 | 若实际允许任意 JSON，使用 schema: true；若只允许对象，用 type: "object" |
invalid type: map, expected a sequence | 定位具体路径；methods/events 是数组，interfaces/$defs/properties 是映射 |
properties: {} 接受了额外键 | 标准语义默认开放，封闭空对象需要 additionalProperties:false |
| nullable、one_of 等字段被拒绝 | 数据正文使用标准 Schema 关键字与大小写；不要复制旧类型字段 |
$ref 找不到成员 | 检查精确 URI、资源闭包、JSON Pointer / anchor 与内联 Schema 的独立根作用域 |
| 数据校验通过，模型严格输出失败 | 消费者能力更窄；修改明确的业务合同，不静默补 required、null 或删除约束 |
| 兼容性返回 NotProven | 当前比较器没有证明，不能当作成功 |
先校验 CModel envelope，再按明确协议解析。生产者输出与声明协议不一致时修复生产者；消费者选错协议时修复消费者，不能用宽松解析掩盖责任边界。