# API 与版本兼容政策

本政策约束今后的正式版本。0.5.0 核心接口作为首个冻结基线；历史版本的变更仍以各版本更新日志为准。

## 版本规则

- 补丁版本用于兼容的缺陷修复、文档和验证改进。
- 次版本可增加接口、独立包及可选功能，保持已有公开调用方式和正常结果语义。
- 破坏性变更必须升级主版本并提供迁移说明；处于 0.x 期间也不以“小版本”为由静默破坏已有 API，必要时进入 1.0 或提供并行的新接口。
- 已发布源码和产物不覆盖。发布前完成文档、版本和安装示例检查。

## 承诺范围

核心及正式发布的可选包的公开函数签名、可构造类型、字段、枚举和错误类别均在范围内。公开结构体增加必填字段、公开枚举增加使穷尽匹配失效的变体，都按破坏性变化处理。

Node bridge 的公开导出、已声明的 CLI 参数、退出码、JSON 既有字段含义和配置 version:1 也属于兼容范围。JSON 对象键顺序、系统错误文字和性能数值不作稳定承诺；消费者应容忍新增 JSON 字段。

字段缺失、IP 未命中和查询错误的区分不能静默改变。安全修复可能收紧对损坏或恶意输入的接受范围，必须解释原因、增加回归样本并在更新日志说明；不能借此改变正常受支持输入的类型或语义。

内部函数、开发辅助脚本、测试报告结构及未发布接口不属于已发布 API。0.6.0 为新增网段、检查接口和 geo 包增加冻结基线，同时保留来自 0.5.0 注册表归档的旧基线。0.6.0 候选接口随源码冻结，最终注册表归档中的声明须与这些基线一致；发布凭据记录此项核对。

## 弃用与自动检查

正常弃用至少保留两个后续次版本且不少于 90 天，并给出替代用法；移除仍需升级主版本。安全事件确需例外时，公开说明受影响输入与迁移方式。

`node scripts/api-compat.mjs` 重新生成接口信息，核对受控文件是否过时，并比较来自 0.5.0 注册表归档的公开声明。删除函数、修改签名、修改既有结构体/枚举、改变既有包导入会使 CI 失败；新增独立声明允许通过。基线来源及 SHA-256 存在 `scripts/api-baseline/manifest.json`，不能为了让检查通过直接改写旧基线。

这是保守的声明检查，不是完整语义证明。CLI 回归、独立参考对照和旧消费者编译继续负责行为兼容验证；仅有声明检查通过不能证明全部行为兼容。

0.7.0 新增 Native diff 命令，核心、bridge 和 geo 声明保持 0.6.0 基线不变；安装验证脚本修复不改变库接口。

0.9.0 候选新增独立 analytics 包及冻结声明基线。新 analyze 报告的五类统计互斥；原有日志分析示例仍保留其输出语义，消费者应主动迁移，不能仅替换入口就假设两种计数口径相同。