Java API 与版本兼容
当前尚无稳定版，0.1.0-rc.2 已发布到 Maven Central。自动兼容检查使用该版本的 API 基线，直接从 Central 已发布的 16 个库 JAR 提取，共 733 个可访问类型，覆盖其中已有的公共／受保护声明。来源清单记录逐库坐标、下载地址、上游 SHA-256 校验值、类型数量，以及基线摘要和提取工具；不使用当前候选构建代替已发布字节。
历史 verification/api/baseline-0.1.0-rc.1.json 保留提交 b9c8f77b0872566614984a76bdcd1edaf2f39db9 独立构建的 16 库／670 类型快照；verification/api/baseline-0.1.0-preview.json 保留提交 1665cd7597609e9c7db561cea12b8ca1083e99bb 的开发期快照。新基线必须来自记录提交的独立源码构建或校验过的已发布制品，不能从当前候选源码反推，也不能自动覆盖历史基线。
自动检查
Java 21 的 javap 读取 16 个实际库 JAR，保存公共／受保护类型、成员的 JVM 描述符、泛型及 throws 声明、继承、修饰符和编译期常量，并拒绝公开声明泄漏项目／JDK 以外的第三方类型。默认构建版本为 0.1.0-SNAPSHOT；显式版本通过 -Pexport4jVersion=... 传入。
.\gradlew.bat apiCheck
python scripts/test_api_compatibility.pyLinux／macOS 使用 ./gradlew。apiCheck 同时接入根 check 和三平台 CI；候选快照与差异写入 build/reports/api/。检查拒绝类型／成员消失、声明或常量变化，以及既有类型新增必需的抽象成员；继承等声明变化采取保守拒绝，不能自动推断等价。
新增普通成员会登记为增加项。record 增加 component 本身不直接判为不兼容：旧构造器和访问器仍存在且声明不变时，既有 JVM 调用可以继续使用；新增规范构造器与访问器另列增加项。反射读取 record components、序列化格式、equals／hashCode／toString 语义和新重载可能造成的源码歧义仍须人工评审。接口新增 default 方法也可能与调用方的其他接口冲突，自动签名检查不能证明所有客户端源码可重新编译。
回归夹具实际编译前后两个版本，证明缩小可见性、改变常量／泛型、新增必需抽象方法及公开返回类型泄漏第三方实现会失败，并证明保留旧入口的 record 扩展可通过。这个检查不验证方法体、运行时注解、字节码调用链、布局或阅读器行为；没有把签名相同当作行为相同。
已发布基线的复现
以下命令将 rc.2 制品重新下载到全新的忽略目录，验证各 JAR 与 Central 的 .sha256 一致，再用 Java 21 javap 提取声明。输出写入 build/，可与仓库基线比较；脚本拒绝覆盖已有基线、来源清单或复用下载目录。
python scripts/create_published_api_baseline.py --version 0.1.0-rc.2 --downloads build/verification/api-rc2-recheck/downloads --baseline build/verification/api-rc2-recheck/baseline-0.1.0-rc.2.json --provenance build/verification/api-rc2-recheck/baseline-0.1.0-rc.2.provenance.json来源清单绑定实际下载字节和生成的基线摘要，记录校验过的 Central 制品来源；这里的摘要比对不代替发布签名或真实调用方验收。签名演练的构建输入清单同时包含当前基线、来源清单和提取脚本，避免仍绑定历史基线。
兼容承诺
- 当前
0.x保留明确的不兼容演进空间，每次正式发布须列出差异、迁移和实际验收；不能静默刷新基线隐藏破坏项。 0.1.0-rc.2固定已发布的公共／受保护声明；修复应保持该基线兼容。新增普通入口仍须评审行为及源码歧义；确需破坏声明时重新确定候选版本、迁移和经过审查的基线。- 进入
1.x后，同一主版本保留已公开构造器、方法、访问器与 SPI；破坏性变更进入下一主版本。 - 弃用使用
@Deprecated、Javadoc 替代入口和迁移说明；同一主版本保留弃用入口，不用仅在源码中改名的方式破坏二进制调用。 - 单位、原文 UTF-16、资源关闭、预算、取消、异常／诊断、默认策略和声明的格式损失也属于契约，须用对应跨模块和输出验收验证。
- 确认破坏项后，先确定版本与迁移，再审查新的基线；不提供跳过错误或自动接受全部差异的构建开关。
模块统一版本，由 BOM 对齐。发布与真实远端消费流程见发布规范，平台与阅读器的具体结果见阶段一百零五，候选基线与安全回归见阶段一百零六。