# API 兼容约定与版本迁移

0.4.x 补丁版本保持根包 `Charles67676767/moonvalve` 的公开类型、函数签名、错误类型和默认行为兼容。已发布版本不可覆盖；新增能力和不兼容调整进入经过评审的后续次版本，不通过补丁悄悄修改路径选择、条件、整数精度或事务语义。

`docs/api-contract.json` 记录当前工具链生成的完整接口 SHA-256 与工具链，并保留 0.4—0.8 的原始接口与哈希（对应 docs/api-VERSION.baseline.txt）。运行 `moon info` 后，`node scripts/check-api.cjs` 检查当前接口基线，并逐项核对旧公开声明仍存在且完全一致。签名检查不能证明全部行为兼容，所以仍需运行核心、CLI、参考实现和注册表消费者检查。仅更新 hash 不能替代迁移说明及次版本评审。

兼容规则包括：

- KV1 对象保持有序且保留重复项，Selector 的 occurrence 从 0 开始。
- `apply` 采用顺序定位，`apply_snapshot` 采用原始快照定位；不会在补丁版本中互换。
- 源文档保留未求值条件与引用，求值和加载由调用方显式执行。
- 二进制数字与 KV3 整数保持原有精度和类型；不静默转为普通 JSON 数字。
- 资源限制和不支持格式继续明确拒绝，不能靠部分成功掩盖失败。

模型中公开数组的直接修改仍由调用方负责；兼容约定不把它们变成不可变容器。0.4.x 是有明确兼容约束的开发系列，不宣称覆盖所有 Valve 格式，也不等同于 1.0 长期支持承诺。

安装与独立验证见 [发布与安装](publishing.md)。

## 0.4 → 0.5

0.5 新增 KV3 原文文档、`KV3Edit`、工程查询和批量字段修改；旧函数、类型及默认参数保持原签名，无须改动现有调用。KV3 分词现在接受紧邻数字的合法行/块注释。整体 `stringify_kv3` 与类型 JSON 导入仍为规范化输出，不自动切换到保留原文编辑。

LSP 新增文件操作和跨文件诊断，客户端可能收到更多相关文档诊断通知。缺失判断需要宿主显式确认；已有只发送文档同步的客户端仍可正常使用，不会因缺少文件缓存被误报。新 CLI 命令与工作台操作为新增入口。0.5.x 补丁保持本系列公开签名，新增公开能力继续进入后续次版本。

## 0.5 → 0.6

新增工程导出、`KV3Query` / `KV3LocatedValue` / `KV3QueryEdit` 与 `KV3SourceRange`；旧函数签名、KV1 查询及已发布编辑操作保持原行为。KV3 查询使用独立入口，不向 KV1 的字符串模型隐式加入数值和标记语义。LSP 现在为 KV3 返回文档符号、折叠、类型悬浮和字面量补全。0.6.x 补丁继续保持本系列公开声明；新增能力进入后续次版本。

## 0.6 → 0.7

公开声明保持兼容。新增 KV3 工程查询、保留注释格式化、ResourceRoot / ResourceReference 及资源引用预览。旧工程查询仅选择 KV1，新入口仅选择 KV3，显式选择错误格式报错。LSP 格式化行为改为保留注释和字面值，可处理带条件/指令的 KV1；需要原来规范化输出时继续使用 stringify / stringify_kv3 或 CLI format / kv3-format。资源导航只有显式映射且宿主确认存在时才返回文件链接。配置方法和完整边界见[工程工作流](project-workflows.md)。

## 0.7 → 0.8

保留此前所有公开声明，新增独立的二进制 KV3、资源容器、VPK、挂载文件系统、依赖图、VMT、本地化/PO 与 DMX 类型。原有文本入口不会自动读取其他格式。Zstandard 引入 Apache-2.0 的 MoonBit 包依赖 bikallem/compress 0.3.4，产品不需要 Python/.NET。ZIP 新入口支持原始二进制文件；原工程快照导出仍先验证快照。版本、数字位保留与未知格式边界见[资源指南](assets.md)。

## 0.8.1

公开接口保持 0.8.0 基线。将 Zstandard 所需的 Apache-2.0 源码与原始测试放在 `internal/vendor`，改用本模块的现代包配置，避免 Mooncakes 文档构建器拒绝依赖的旧 `moon.mod.json`。仅经 MoonBit 格式化器规范语法和格式，无算法改动；完整归属、原始及当前文件哈希随包分发。

## 0.8.2

公开接口继续保持 0.8.0 基线。将上游压缩源码已移除的 `try?` 语法替换为等价的显式 Result 与 try/catch，兼容 Mooncakes 文档构建器的新工具链。压缩算法不变。

## 0.8.3

主工具链、标准库、全部 CI、发布验证与发行包元数据统一为 0.10.18+6c83a7f62，最低支持版本为 0.10.18，满足验收要求的 ≥0.10.16。新版编译器将 Int/UInt 规范为 Int32/UInt32；二者为相同位宽类型的兼容别名，无数值语义或公开功能变更；格式化器同时规范带默认值的参数声明语法，生成接口中的可选性保持不变。保留原始 0.8.0 接口及哈希，旧声明比较仅规范这两个类型名称；当前接口仍执行完整哈希检查。