# MoonContract 0.1.1：维护说明与质量证据

测量日期：2026-09-14。基线：`a38d9c8a8a4790179e65be3c4aaac33c675545d3`（0.1.0）。本文件是工程维护记录，不是申报书。

## 对项目的理解

MoonContract 把 JSON/YAML OpenAPI 3.0 文档解析为 AST，经本地引用解析、路径路由编译得到 Contract。请求与响应校验共享 Schema 校验器；Mock 先选响应定义，再生成确定性数据并校验；cases 重放和 CLI 复用这些能力，native server 提供开发环境 HTTP 入口。它不是任意 JSON Schema 引擎，也不是生产网关。

关键不变量：合法的大整数不应因内部 Int32 转换被拒绝；nullable 只能放宽类型、不能绕过 enum；同一状态码的响应选择不应依赖文档排列顺序。原测试覆盖了常规流程，却没有跨 Int32 边界、nullable 与 enum 交互，以及 exact/range/default 全排列，因此 46 个原测试全绿仍不能说明这些行为正确。

## 本轮修复

- `7272615`：Schema integer 改用有限数检查与 floor 判整；拒绝 NaN/Infinity；null 继续检查 enum；未指定类型的 Schema 按实际值类型执行已支持约束。
- `69de30b`：Mock 显式状态按精确码 → 范围码 → default 选择；隐式选出的成功状态也重新按该优先级解析；拒绝 HTTP 范围外的显式状态。
- 新增 7 个永久回归测试块。没有重写历史、拆分占位提交或用代码行数宣称质量。

## 对标方法与量化结果

参考实现是 [python-jsonschema 4.23.0](https://python-jsonschema.readthedocs.io/en/v4.23.0/validate/) 的 Draft202012Validator。只比较双方共有的 Schema 语义，不把 JSON Schema 2020-12 当作 OpenAPI 3.0 全规范。根据 [OpenAPI 3.0.3](https://spec.openapis.org/oas/v3.0.3.html)，对显式 type + nullable 做类型并集转换，其他约束原样保留。90 个案例为本项目自写，不复制参考软件测试集。

| 指标 | 0.1.0 基线 | 0.1.1 修复后 |
| --- | ---: | ---: |
| 固定 Schema 样本与参考判断一致 | 72/90（80%） | 90/90（100%） |
| Mock 24 次显式状态选择正确 | 15/24 | 24/24 |
| Mock 6 次隐式状态选择正确 | 3/6 | 6/6 |
| 永久测试块通过数 | 46/46 | 53/53 |

Schema 样本含 12 组：integer 15、integer-range 7、number 8、nullable-enum 4、nullable-enum-null 4、untyped-enum 9、unicode 10、array 8、object 7、untyped-number 6、untyped-string 6、boolean 6。通过 OpenAPI 解析器进入真实校验器，比较接受/拒绝结果，而非比较错误文案。Mock 测试遍历 200/2XX/default 的 6 种排列，显式请求 200、201、299、404；预期分别为 exact、range、range、fallback。另有 5 个非法状态测试，不混入上述 30 次选择指标。

本地 wasm-gc、wasm、js 均通过 53 个永久测试及独立的 90 个差分样本；native 本地只做严格编译检查，执行交给 Linux CI。CI 对四个目标运行差分测试，上传含平台、版本、HEAD、源码摘要、完整案例和原始输出的 quality-core / quality-native artifacts。参见 [CI](https://github.com/Han-Wentao/mooncontract/actions/workflows/ci.yml) 中对应提交的实际结果；不能用旧构建代替新提交验证。

[机器可读摘要](quality/maintenance-summary.json) 保存基线 SHA、语料 SHA256、源码摘要及失败案例编号。源码摘要受换行符影响，复现时以 Git 提交和语料摘要共同定位。完整报告本地生成，不把临时生成的 90 个测试计为手写功能或永久测试数量。

## 复现

需 MoonBit moonc `v0.10.4+2cc641edf`、Python 3.8+（CI 使用 3.11）及固定参考依赖。以下在仓库根目录、独立 Python 环境运行：

~~~sh
python -m pip install -r tools/quality-requirements.txt
moon fmt --check
moon check --target wasm-gc --deny-warn
moon test --target wasm-gc
python tools/compare_schema.py --target wasm-gc --report .quality-results/current.json
# 将 target 替换成 wasm、js、native 可分别验证；native 执行需 C 工具链。
git worktree add --detach ../mooncontract-baseline a38d9c8
python tools/compare_schema.py --project ../mooncontract-baseline --report .quality-results/baseline.json
~~~

基线命令预期返回非零，报告为 72/90；新版本预期返回零、90/90。工具独占创建临时测试文件并在 finally 中删除，不覆盖已有同名文件。复现 Mock 基线时，将新版本 `src/mock/selection_regression_test.mbt` 复制到独立基线 worktree，再运行 `moon test --target wasm-gc --filter 'mock selection*'`；显式与隐式断言分别显示 15 != 24、3 != 6。不要把这些基线实验改动提交到主分支。

## 边界与下一步

100% 仅表示这 90 个固定样本一致，不是代码覆盖率、完整兼容率、安全审计或性能胜出。本轮没有吞吐/延迟测量，不能据此声称快于其他实现。JSON 数字用 binary64，超过 2^53 的整数不能保证精确；HTTP 参数文本的 integer 路径仍受 Int32 限制。解析器会从 properties/items 推断类型，与完全无类型的 JSON Schema 不等价；未知关键词不代表已支持；3.1、外部引用与组合 Schema 不在当前范围。Mock 在狭窄数值区间的生成策略仍需后续完善，服务器仅用于开发测试。

后续优先扩展参数数值解析和约束生成边界，再扩大互操作样本；每次先记录可复现失败，再修复并回归，不以增加行数或提交次数作为交付目标。