# 实测质量与移植范围

记录日期：2026-09-14。下文区分本地初始测量与后续远端验收。[机器可读记录](evidence/local-measurements.json)保存未四舍五入的统计、输入源码哈希及每个后端结果。公开提交均由 CI 重跑验收。

## 环境和执行范围

Windows，Moon `0.1.20260713 (75c7e1f)`，moonc `v0.10.4+2cc641edf`，Node `v24.14.0`，Python 3.8.5。

| 后端 | 严格检查 | 构建 | 单元/示例测试 | 三个示例 | 上游差分 / 外部参考 |
|---|---|---|---|---|---|
| wasm-gc | 通过 | 通过 | 28/28 | 通过 | 通过 / 通过 |
| wasm | 通过 | 通过 | 28/28 | 通过 | 通过 / 通过 |
| js | 通过 | 通过 | 28/28 | 通过 | 通过 / 通过 |
| native | 通过 | 未执行成功 | 未执行成功 | 未执行 | 未执行 |

本机虽然带有工具链内部 tcc 文件，但 Moon native 构建仍报 `no system C compiler found; tried cl, cc, gcc, clang`；未把它说成已通过。CI 在 Ubuntu 上执行四后端矩阵，不跳过 native。CI 使用官方安装入口提供的工具链，版本在日志中记录；不保证与本地快照相同，不称为可逐位复现的编译环境。GitHub Actions 的外部 action 固定到核查过的提交。

## 1. 与移植原库的兼容性

直接运行固定提交的 SunCalc 2.0.1 JavaScript，再与**编译后的 MoonBit 程序**输出比较，而不是对两个 JavaScript 实现做对照。

- 720 组：12 个跨 1900—2150 年的日期 × 4 个时刻 × 15 个观测点，含极区、南半球和日期变更线。
- 每组 32 个字段，共 23,040 次字段比较，其中 4,652 次无事件/null 检查。
- 包括太阳/月亮位置、照明、标准太阳事件、月亮升落、100 m 高度与 -4° 自定义事件。
- 角度容差 1e-6°、距离 1e-6 km、照明/相位 1e-9、事件 2 ms；布尔、状态和无事件值必须完全一致。
- 三个已执行后端均零失败；本机这些样本的各类最大差值恰为 0。**这不代表所有平台逐位一致，更不证明上游模型没有误差。** 三后端重复执行的是同一批 720 组，不合并成 2,160 个独立案例。

## 2. 对照归档天文参考值

使用 SunCalc 固定提交保存的 JPL Horizons / USNO 数据，采集时间 `2026-06-17T17:39:51.096Z`。这是上游归档，不是本次直接向 NASA/USNO 请求的结果，也不是来自与上游无关的全新独立测试集。涵盖 14 个地点、13 个日期（1950、2026、2050 年的样本），共 1,144 条去重编译查询。采用上游比较方法和阈值，额外检查月出/月落的**绝对日期时间**，防止取模一天掩盖错日。

下表为 wasm-gc 实测；wasm、js 得到相同统计。

| 指标 | 有效样本 | 平均绝对误差 | 最大绝对误差 | 验收阈值（均值 / 最大） |
|---|---:|---:|---:|---:|
| 太阳位置角距离 | 728 | 0.082720° | 0.170589° | 0.12° / 0.25° |
| 月亮位置角距离 | 728 | 0.086252° | 0.175767° | 0.12° / 0.25° |
| 月面照明比例 | 52 | 0.00001881 | 0.00004935 | 0.002 / 0.005 |
| 地心月距 | 52 | 21.318 km | 40.894 km | 100 km / 100 km |
| 日出 | 151 | 15.015 秒 | 33.002 秒 | 24 秒 / 48 秒 |
| 日落 | 151 | 14.360 秒 | 32.695 秒 | 24 秒 / 48 秒 |
| 月出/月落绝对时刻 | 299 | 15.372 秒 | 47.869 秒 | 最大 54 秒 |

照明误差是 0..1 比例值；最大值换算为约 0.004935 个百分点。角距离是球面方向间夹角，不是方位角误差。USNO 升落参考时刻按分钟给出，不足以论证亚秒级天文精度。全部门槛及其他事件统计见 JSON；无缺失参考样本。

## 3. 边界、性质与覆盖

28 个测试块包括根包 22 个和三个示例各 2 个。块中循环包含：2,048 个确定性日期/坐标输入、3,012 次年月日历往返、96 组 ±180° 经度等价、180 组常规纬度太阳事件几何残差、64 组 UTC 日内不变性；另测 NaN/Infinity、非法闰日、配置复制/重名/容量、极昼极夜、单边月事件、上游 issue #186、批量分配和时间越界。循环断言不是另行计数的测试块。

仅运行根包 wasm-gc 单元测试的 Moon 覆盖统计为 **407/418 个插桩点**；Cobertura 行口径为 **284/289 个可执行行，98.27%**。系数声明没有可执行行，不纳入分母；不包括示例、差分 oracle 或自动生成查询。没有宣称分支全覆盖，未覆盖点主要在罕见升落求根路径。覆盖率也不是天文正确性的证据。

```sh
python tools/verify.py --defer-native
moon coverage analyze -p Zh666-lab/moonsuncalc -- -f summary
moon coverage report -p Zh666-lab/moonsuncalc -f cobertura -o output/coverage.xml
python tools/record-evidence.py
```

无 C 编译器限制时运行 `python tools/verify.py`，不要继续使用跳过选项。源文件行尾固定 LF，测试源码/数据的 SHA-256 在执行对照前校验；查询文件生成后必须格式稳定、不改变受跟踪 MoonBit 文件。

## 干净检出复核

首次在新目录检出时，完整性校验发现许可证的哈希取自 Windows CRLF 工作副本，而 Git 检出为 LF，造成校验失败。已重新读取固定上游提交的原始 LICENSE（LF）并修正清单；不是关闭校验或修改源码哈希。正式本地交付还需在新检出目录重放验收，不能只依赖已有构建缓存。

## 4. 不能据此承诺的能力

没有实时气压/温度/云层/地形；折射是上游近似，低高度误差尤其值得留意。近极区擦边事件与 ΔT 外推不适合安全关键决策。1900—2150 是接收输入的范围，外部精度样本并不覆盖每一天。没有做吞吐基准，不给出“更快多少倍”；也不将 JPL 数据来源当作本库具备 DE440 级精度的证明。

## 5. GitHub 四后端验收补充

公开仓库 Zh666-lab/moonsuncalc 的运行 [34853569505](https://github.com/Zh666-lab/moonsuncalc/actions/runs/34853569505) 在提交 `e5714cb` 全部通过。Ubuntu 上 wasm-gc、wasm、js、native 均完成严格检查、构建、28/28 测试、三个示例、720 组原库差分及归档天文参考验证；native 不再是未验证项。前文“native 未执行”的表仅指首次 Windows 本地环境。

远端使用 Moon 0.1.20260904、moonc v0.10.12+1634b282e、Node v24.20.0。初轮 CI 发现 July/September 格式器和接口生成的变化，修复后重新执行，没有删除格式或接口检查。Windows 新工具链放在独立研究目录，未替换系统工具链。

native 最大角度差 `5.684341886080802e-14` 度、照明/相位比例差 `2.7755575615628914e-16`，事件差 0 ms，全部低于原设容差；说明不能将本地样本的“差值为0”泛化成所有后端逐位一致。[CI 测量记录](evidence/ci-measurements.json)保留四个后端实际数值。最终发布提交的 CI 链接记录在仓库运行列表和外部交付核验，避免为更新自身 SHA 反复修改版本。