# 架构与取舍

> 这份文档是验收材料的一部分（可解释性 25%）：不只写"是什么"，还写**为什么不是另一种做法**。

## 1. 包结构与依赖方向

```
core      Rng / Bytes 工具 / Target / Oracle / Config / Stats / Finding
  ↑
mutate    Dictionary + 变异算子（havoc / 结构化 / 字典 / splice / boundary）
corpus    去重语料库 + 锦标赛选择（偏好短输入）
cov       Buckets（无量纲反馈）+ EdgeSet（覆盖率产物解析）
shrink    ddmin
  ↑
targets   内置用例：json.lite / csv.lite / varint 差分对
  ↑
engine    Session：跑循环、判 oracle、收语料、记 finding
  ↑
report    text / jsonl / html / 回归测试生成
  ↑
api       对外入口（embedder 用）
  ↑
cli       只有参数解析
```

依赖是单向的，没有环：`core` 不知道 `engine` 存在，`report` 不知道 `targets` 存在，`engine` 不知道 `report` 存在（`api` 把三者拼起来）。这条纪律的直接收益是：`report` 可以用一个手工构造的 `Finding` 测试，不需要跑一次 fuzz。

## 2. 一次执行的完整路径

```
corpus.pick()                          ← 锦标赛选择，偏好短输入
  → mutator.mutate(base, pool)         ← 1~4 轮变异
  → target.run(candidate)              ← 只返回 String，不抛错
  → oracle.check(candidate, output)    ← "" 表示通过
      ├─ "" → cov.signature(output) → buckets.observe → 新桶则入语料
      └─ 非空 → ddmin 最小化 → 按"形状"去重 → Finding
```

三个刻意的选择：

1. **target 不允许抛错**。`(Bytes) -> String`，失败也必须变成字符串。这样"拒绝输入"和"崩了"在类型层面就是两件事——前者是数据，后者是进程死亡。
2. **oracle 返回字符串而不是枚举**。`""` = 通过，非空 = 原因。少一层类型，报告里直接可读，且不阻碍未来加新 oracle。
3. **finding 按形状去重**。`v:4294967186` 和 `v:12348032000` 是同一个 32 位截断 bug，报告里出现十六次不如出现一次。去重键是"把连续数字折叠成 `#` 后的哈希"。

## 3. 四个关键决策

### D1：反馈信号分两层：插桩优先，形状兜底

覆盖率是 fuzzer 的引擎，而 MoonBit 自带的覆盖率产物用不了：`moon build --enable-coverage` 出来的二进制跑完**不落盘**（`moon test --enable-coverage` 才会写 `moonbit_coverage_*.txt`，那是测试驱动的行为）。我实测过：instrumented native 二进制跑一次，仓库里没有任何 `moonbit_coverage*` 文件。所以"读编译器产物"这条路对一个 fuzz 循环是断的。

于是分两层：

1. **插桩**（`@cov.hit(id)`）：target 在分支处调用，引擎拿"本次执行命中集合的指纹"做新颖性判断。指纹用**逐 id 哈希的 XOR**，所以顺序无关——同一批分支不同顺序算同一条路径，这是刻意的，否则语料会被顺序噪声撑爆。任何后端都能用，零依赖。
2. **形状回退**：没插桩的 target 什么都不报，引擎回退到"输出形状"（`v:123` 与 `v:456` 同形状）。

引擎不配置开关、也不需要知道 target 属于哪类，判据只有一句 `@cov.observed() > 0`。这让"先跑起来再决定要不要插桩"成为可能：同一个 `moonx fuzz run`，插桩过的 target 得到路径级反馈，没插桩的照样能跑。

`cov/EdgeSet`（解析 `moonbit_coverage_*.txt`）保留在代码里并带测试，但它服务的是 `moon test` 场景，不参与 fuzz 循环——文档里不把它算作已接线的能力。

效果对比（20,000 次执行，同一台机器）：`csv`（插桩 10 个状态位）语料 94 条 / 92 个独立签名；`json`（未插桩）语料 237 条 / 231 个签名。差别不是"更多"，而是"更对"——94 条语料里存的是不同的扫描路径，不是一个摘要字符串的变体。没插桩时 `csv` 只有 51 个签名，而且全是摘要形状。

### D2：批次 worker + 每行 flush，于是不需要二分

`--isolate` 把执行挪进子进程：父进程保留语料与调度，子进程执行一个批次（默认 512 个输入），**每跑完一条就往结果文件写一行并 flush**。

关键不在"隔离"，而在"每行 flush"：崩溃时结果文件里有几行，被打死的就是批次里的第几个输入。**二分是更慢地求同一个数字**，所以设计里原本写的"崩溃后二分定位"没有实现——不是省事，是因为有了逐行落盘它就没有存在价值。

两个后端事实决定了实现形状：

1. **wasm-gc / js 没有 spawn**。所以 `--isolate` 只在 native 生效；其他后端 `@proc.supported()` 为 false，直接退回进程内执行，而不是假装隔离。
2. **Windows 上 spawn 有两个坑**，都不是"写错了"，而是环境本身的形状：
   - `system()` 把命令行交给 `cmd.exe`，用 ANSI 代码页解码。项目路径里有中文（`文档`、`项目`、任何中文用户名）时，子进程启动直接失败，退出码 1。绕法：给 `system()` 传**相对当前目录**的路径（`_build/native/.../cli.exe` 全是 ASCII），子进程继承 cwd 照样找得到。彻底修法要 `_wsystem`，但它只存在于 Windows，而这里没法按 OS 做编译期分支。
   - 命令行以引号开头、后面又跟着别的引号时，`cmd.exe` 的 `/C` 引号剥离规则会把参数切错。所以文件参数一律"含空格才加引号"（`@proc.arg`），生成的临时文件名里没有空格。

代价写在明处：隔离模式约 2500 exec/s，进程内约 200000 exec/s，差 80 倍——每次批次一个进程，启动成本就是这么多。所以默认不开，`--isolate` 是"要抓崩溃时才付的钱"。

### D2b：最小化按"轮"批量，而不是按"候选"

隔离模式下做 ddmin 有一个尖锐的矛盾：最小化要问几百次"这个更短的输入还坏吗"，而每次提问都要付一次进程启动。

试图把单次提问变便宜是死路（进程启动是常数），所以改成**改变提问的单位**：ddmin 的每一轮生成一整组候选（删第 i 块，i = 1..n），一次 worker 调用判完所有候选，父进程只取第一个"仍然坏"的。一轮 = 一次 spawn，于是 20 轮 = 20 次进程启动，而不是两百次。

三个实现细节，都是踩出来的：

1. **空候选不能进批次**。hex 行格式承载不了零长度输入；少一行读回来的结果和"崩在第 k 条"长得一模一样。第一版就是这么把每轮 probe 变成 32 次无效 spawn 的。
2. **崩溃要能续跑**。候选里有一条打崩了 worker，后面的候选还没跑；父进程从 k+1 重新提交，直到整轮分类完，并用 spawn 次数上限兜底。
3. **比较的是"状态"不是"坏不坏"**。状态分 0/1/2（接受 / 违例 / 崩溃），最小化只认与原始 finding 同类的状态——否则一条 mismatch 会被缩到某个毫不相干的 crash 上，看起来更小，实际是另一个 bug。

代价是可见的：3000 次执行，开 shrink 30.4s / 关 1.1s，finding 5 字节 vs 956 字节。默认开，`--no-shrink` 关。

### D2c：并行不共享内存，只共享文件

`--jobs N` 的一轮是：父进程从语料里抽 N 个批次 → 写 N 个启动脚本 → **一次 shell 调用把 N 个脚本全部 start** → 轮询 N 个 done 文件 → 全部到齐后统一 absorb。

三个决定：

1. **不共享内存**。语料和调度留在父进程，候选以 hex 文件出去、结果以行文件回来。代价是每轮的文件 IO，收益是不需要任何锁，也不需要和子进程约定内存布局——这在 MoonBit 里尤其重要，因为跨进程传递 `Bytes`/`String` 不是它能表达的事情。
2. **一进程启动一次，不是一 job 一次**。每起一个 `cmd.exe` 约 57ms；四个 job 就是 228ms，占掉一个 512 批次的大半。把 `start /b ... & start /b ...` 拼成一条命令，只付一次。这也是为什么 `--batch-size` 必须跟着 `--jobs` 调大：固定成本不变，批越大占比越低。
3. **用 done 文件而不是等待进程**。`start /b` 不给你句柄，`system()` 又是阻塞的。启动脚本因此无条件写 done 文件（内容是该 job 的退出码）——包括 worker 崩溃的情况，因为 `echo %ERRORLEVEL% > f` 在脚本里是独立一行。父进程只认"done 文件有没有出现"，崩溃与否由结果行数与退出码判断。

一个 Windows 特有的坑：`echo 0> file` 会被 cmd.exe 解析成"把 handle 0 重定向到 file"，什么都不写。必须写成 `echo 0 > file`（`>` 前留空格）。第一版没有空格，于是每个 job 都被判定为"永不完成"，`--jobs` 直接卡死 120 秒。

### D2e：语料落盘用编号，不用目录遍历

持久化语料只需要两个操作：把一个输入写成一个文件、把所有输入读回来。第二个操作在 MoonBit 里没有对应的 API——stdlib 没有 `readdir`，我也不想为它加一套 Win32/POSIX 的目录遍历绑定。

于是换个问法：**不需要"列出目录"，只需要"知道下一个文件叫什么"**。

```
<dir>/corpus-0001.hex   一个输入，小写 hex，一行
<dir>/corpus-0002.hex
...
```

加载就是从 1 开始按编号打开，遇到第一个读不到的就停；保存就是按编号重写。代价是每次加载多一次失败的 `fopen`，收益是整个功能不需要任何新 FFI，而且在三个后端上行为一致（相对路径由 `proc` 处理）。

两个副作用是有意的：

- **遇缺口截断**：`corpus-0007.hex` 没了就只加载 1–6。这让文件布局可以手工修复（删掉尾巴、保留前缀），而不是必须跑一次压缩。
- **不收缩**：一次只保留 40 条语料的运行不会删掉上次的 90 个文件，下次加载仍然看到 90 条。语料是单调长的，这符合直觉——fuzzer 不该忘记走过的路。

这也是为什么 `--corpus-max` 存在：编号方案下"语料上限"就是"文件数上限"，必须能封顶。



### D3：差分 oracle 用"两个实现"，不用"两个后端"

跨后端差分（wasm-gc vs native）是 MoonBit 独有的机会，但一次进程只能是一个后端。v0.1 的做法是把差分下沉为**同后端内的双实现对比**（`varint.fast` vs `varint.ref`），这已经能抓到最有价值的一类 bug：**不崩、不报错、结果是错的**。

跨后端差异则通过另一条路径获得，而且它已经被验证：

```bash
moon run cli --target wasm-gc -- run --target varint --seed 1 --json > a.jsonl
moon run cli --target js      -- run --target varint --seed 1 --json > b.jsonl
```

同 seed 下两个后端产出**完全相同**的 52 条语料与 3 条 finding（见 `findings.md`），说明确定性成立，`diff` 才有意义。

### D4：不修改官方 `moon`，不新增任何依赖

零依赖（只用标准库 + `core/encoding/utf8`），意味着：

- `moon add moonsting` 不会把依赖树拖长；
- 不用等官方接受 PR 才能用；
- 但也不能提供 `moon fuzz` 子命令——分发靠 `moonx` 或直接 `moon run cli`。

## 4. 与现有 fuzzer 的取舍

| 来源 | 借鉴 | 放弃 | 为什么 |
|---|---|---|---|
| libFuzzer | 语料即"有趣输入"集合、执行数驱动、`minimize` 概念 | 编译器插桩回调、`LLVMFuzzerTestOneInput` ABI | 需要改编译器 |
| AFL/AFL++ | havoc 变异算子表、字典、splice | fork server、共享内存位图、`@@` 文件占位 | 无进程 API；位图需要插桩 |
| atheris（Python） | "同进程、按函数签名驱动"的易用性 | 字节码级插桩 | 同上 |
| Hypothesis | 结构化变异优先于纯字节变异 | 完整的 shrink 策略树 | ddmin + 单字节扫描已够用 |
| quickcheck（MoonBit 自带） | `Arbitrary` 派生思路 | 只做随机、不留语料 | 这正是缺口所在 |

## 5. 已知限制（v0.1）

1. **没有进程隔离**：panic 会终止整轮 fuzz；崩溃用例的捕获依赖下一步的 worker 方案。
2. **默认反馈是形状而非边**：对"输出只有 ok/err 两种"的 target，反馈接近饱和（json 用例 10 万次执行只积累 254 个桶）。
3. **无文件系统持久化**：语料活在内存里，跑完即弃；`--corpus-dir` 需要 native/js 的文件 API。
4. **三个后端都已验证**：wasm-gc / js / native 同 seed 产出逐字节相同；native 目前只有 debug 与 release 两种构建，没有专属分支。
5. **单线程**：`--jobs` 尚未实现，执行数上限内是单核跑满。
