# 验收材料 · moonsting

> 面向 2026 MoonBit 黑客松的验收清单：能力矩阵、实测数据、一键复现、已知限制。
> 所有数字都可以用本文里的命令在本机重跑；写死的数字都注明了执行参数。

## 1. 项目是什么

给 MoonBit 补上模糊测试这一层：**喂坏字节，拿回一个最小反例、一份报告和一条能粘进仓库的回归测试**。零第三方依赖，同一份代码编译到 `wasm-gc` / `js` / `native` 三个后端。

```
moonsting run  --target varint --seed 1 --max-execs 50000
moonsting run  --target boom   --isolate          # 崩溃隔离
moonsting run  --target csv    --corpus-dir .corpus --cov-report
moonsting replay   --target varint --hex 92ffffff0f
moonsting minimize --target varint --hex 92ffffff0f00010203
```

## 2. 能力矩阵

| 能力 | 状态 | 用哪条命令验证 |
|---|---|---|
| 变异引擎：havoc / 结构化 / 字典 / splice / 边界 | ✅ | `moon run cli -- run --target json --max-execs 20000` |
| 结构化变异（按输入形状分派：JSON / base64 / %XX / CSV / 二进制） | ✅ | 见 `§4 度量` |
| 语料库：去重、锦标赛选择、trim | ✅ | 任何一次 run 的 `corpus` 行 |
| 四种 oracle：smoke / metamorphic / 往返 / 双实现差分 | ✅ | `moonsting list` 的 oracle 列 |
| ddmin 最小化（in-process） | ✅ | `moonsting minimize ...` |
| finding 按"形状"去重 | ✅ | `varint` 的 3 条 finding 而不是几十条 |
| 报告：text / jsonl / 自包含 html / 回归测试生成 | ✅ | `--json` `--html` `--emit-test` |
| 语料持久化（编号文件，无需 readdir） | ✅ | `--corpus-dir` 跑两次 |
| 进程隔离 + 崩溃输入定位（native） | ✅ | `--isolate --target boom` |
| 隔离模式下的批量最小化 | ✅ | `--isolate --target varint`（`--no-shrink` 可关） |
| 并行 worker（`--jobs N`） | ✅ | `--isolate --jobs 8 --batch-size 4096` |
| 手写插桩覆盖反馈 + 形状回退 | ✅ | `--cov-report` |
| 插桩报告（命中 id 段 / 空洞），两种执行模式都支持 | ✅ | `--cov-report` |
| CI 钩子（有 finding 非零退出） | ✅ | `--fail-on-finding` |
| 编译器覆盖率产物接线 | ❌ | 普通二进制不落盘，见 `docs/架构.md` D1 |
| 结构化变异器覆盖 protobuf/TLV 字段级 | ❌ | 现在只有长度 ±1 |

## 3. 实测数据（本机：Windows 11 / Ryzen，2026-11-18）

### 3.1 十二个 target（各 20,000 次执行，seed 1，wasm-gc）

| target | oracle | findings | 独立签名 | 备注 |
|---|---|---|---|---|
| `varint` | diff | **3** | 17 | 32 位截断，真 bug |
| `decimal` | roundtrip | **1** | 27 | 溢出导致自我拒绝 |
| `json` | metamorphic | 0 | 231 | 空白不变性成立 |
| `csv` | smoke | 0 | 92 | 无崩溃 |
| `utf8` | diff | 0 | 165 | 两个独立实现零分歧（50k 输入） |
| `protobuf` | roundtrip | 0 | 155 | 非最小 varint 等全部拒绝 |
| `rle` | roundtrip | 0 | 30 | 宽度纪律单独校验 |
| `urlenc` | roundtrip | 0 | 20 | 严格拒绝非规范编码 |
| `tlv` | roundtrip | 0 | 10 | 长度算术一致 |
| `base64` | roundtrip | 0 | 4 | 可达路径本来就少 |
| `csvstrict` | roundtrip | 0 | 51 | 严格拒绝多余引号、CR、空尾行 |
| `arff` | comment-invariant | 0 | 41 | 注释不改变摘要 |

### 3.2 吞吐

| 配置 | 吞吐 |
|---|---|
| 进程内，wasm-gc | 201,207 exec/s |
| 进程内，native release | 191,938 exec/s |
| 进程内，js (node) | 61,919 exec/s |
| 隔离，单 worker | 2,626 exec/s |
| 隔离 + `--jobs 8 --batch-size 4096` | **8,336 exec/s** |

### 3.3 确定性

同 seed、同执行数，三个后端的 JSONL **逐字节相同**（含 finding 的 exec 序号），语料规模一致：

```bash
moon run cli --target wasm-gc -- run --target varint --seed 1 --max-execs 50000 --json > a.jsonl
moon run cli --target native  -- run --target varint --seed 1 --max-execs 50000 --json > c.jsonl
diff a.jsonl c.jsonl   # 无输出
```

### 3.4 插桩覆盖

```bash
moon run cli --target native -- run --target protobuf --max-execs 4000 --cov-report
# coverage : 15 ids hit (920-931, 933-934, 941)
# gaps     : 935-940 (...)
```

隔离模式下同参数输出**完全相同**（worker 把命中 id 段带回父进程）。

## 4. 两个"度量"结论（可解释性素材）

1. **结构化变异要证明的是"变异体仍然合法"，不是"语料更多"**：用后者衡量会得出"没效果"的错误结论（语料条数受插桩粒度限制）。
2. **JSON 变异的合法率 46% → 99%**：转折点不是调参，而是把操作单位从"token"换成"成员"（复制整对 `k:v`、删除连 key 一起）。中途还发现自己的检查器太软（只数括号配平），把 `{"a":}` 当成合法，报出了虚高的 66%。

## 4.1 配套文档

| 文档 | 对应验收维度 |
|---|---|
| [开发历程.md](开发历程.md) | 可解释性 25%：决策过程、AI 使用、开源借鉴取舍 |
| [case-varint.md](case-varint.md) | 工程质量 25%：一个真 bug 的完整闭环 |
| [架构.md](架构.md) | 可解释性 25%：模块边界与每个"不做"的理由 |

## 5. 一键复现

```bash
# 全部测试（三个后端）
moon test --target native     # 110
moon test --target wasm-gc    # 91
moon test --target js         # 91

# 五件事的巡回演示（约 30 秒）
script/demo.ps1          # Windows
script/demo.sh           # Linux / macOS / Git Bash
```

## 6. 已知限制（不掩饰）

1. **没有自动插桩**：写 target 的人要自己在分支上放 `@cov.hit(id)`；没放就静默回退到形状反馈。
2. **语料目录遇缺口截断**：`corpus-0007.hex` 缺失时只加载 1–6；写入不收缩。
3. **隔离模式崩溃用例不做 shrink**：缩它要对每个候选起进程；非崩溃用例可以。
4. **并行是亚线性的**：`--jobs` 必须配 `--batch-size`，组合表见 README。
5. **`--cov-report` 的空洞是近似的**：id 人工分配，"从未命中"可能是没人走到的分支，也可能是从没分配的号段。
6. **结构化变异不覆盖 protobuf/TLV 的字段级改写**：目前只有长度 ±1。

## 7. 代码规模

| 项 | 数量 |
|---|---|
| 包 | 11 个（core / mutate / corpus / cov / shrink / targets / engine / report / api / cli / proc） |
| 实现 | 6,598 行 / 48 文件 |
| 测试 | 1,145 行 / 20 文件 |
| 测试用例 | 110（native） / 91（wasm-gc、js，去掉 native 专属） |
| 提交 | 29 |
| 依赖 | 0（仅标准库） |
