# MoonBSDiff 仓库规划与实施状态

来源：2026 年 11 月 4 日编制的《MoonBSDiff 二进制差分与补丁库开发与验收规划书》，读取当前版本并保留全文；仓库外原文件未修改。

来源文件 SHA-256：`6e8b1419eee65adc5a15a4cc3d94de5a024e5753a8fbbd8fefce8c25631390a9`。

以下记录截至本次 Commit 16 发布准备；原规划中的预计时间、CI、CLI 和发布描述仍是计划。仓库地址为 [BigSaltyMan/moonBSDiff](https://github.com/BigSaltyMan/moonBSDiff)，使用原规划指定的 `github-bigsalty` SSH 别名。GitHub 仓库名大小写不改变归属，模块名继续使用 `BigSaltyMan/moonbsdiff`。

## 截至 Commit 10 的真实记录

| 步骤 | 实际提交 | 内容 |
| --- | --- | --- |
| Commit 1 | `6ce69b768a438bc9822e53bc56a5574390410400` | 建立 MoonBSDiff 工程与错误限制模型 |
| Commit 2 | `ab74651238b7d663dfc922b9598c6e9fe08e9a9c` | 实现 BSDIFF40 整数与文件头解析 |
| Commit 3 | `6d1e109ca27a4d08b465e67653e6b8affef5dc77` | 建立固定 BSDiff 参考与离线测试数据 |
| Commit 4 | `8ccd4367e8aa740ca8b58fd82391756d80569998` | 实现受限 bzip2 数据块适配 |
| Commit 5 | `dfcc2a63591eeef2b76d262ff6bc223b76d81a85` | 支持 BSDIFF40 补丁应用 |
| Commit 6 | `b574890782faf5b207d89edede8c939afe429b7f` | 完善补丁应用边界与资源检查 |
| Commit 7 | `f906ee5d29cce496365b9c9c9c3590cdb3c4bb49` | 实现二进制后缀数组索引 |
| Commit 8 | `41f3a9fb227b35e3b4cf0c00991afabe833c478c` | 实现后缀匹配与差分段选择 |
| Commit 9 | `fa7d05eafde413f14b925c7288691a28a7e3236f` | 支持 BSDIFF40 二进制补丁生成 |
| Commit 10 | `d20524e42375d58058c2089a6643f780f44bb030` | 建立 BSDiff 双向互操作与随机回归 |

历史证据保留在格式、来源、压缩、应用、索引、匹配、生成和兼容性文档中，不表示本轮重跑了所有历史矩阵。Commit 10 的 31 个独立输入和随机种子不变。

## Commit 11 本次完成内容

- 排序初始化与轮次累计计费；扫描、查询、原始块编码、压缩适配复制及最终拼装共享生成工作预算。
- 索引前检查已知最小原始块量，每次段增长前检查控制数量与原始块量；控制数组精确分配。
- 复用 moonzip 0.3.5 原有 Writer，以有界喂入及共享输出额度替代一次性全流累积。未修改编码引擎或内部复制源码。
- 新增 `Limits::for_diff()`，通过 16 个 4 KiB/64 KiB 规模样本测量，记录真实计数、过程时间和输入/补丁哈希。可靠峰值内存未测。
- native 新增资源测试 6 项、既有生成 20 项、相关索引/匹配 12 项通过；JS/Wasm-GC 紧凑资源契约各 5 项通过。
- 最终双向矩阵 native 31+31、JS 19+19、Wasm-GC 19+19，138 次恢复逐字节一致，必需案例无失败或漏跑。
- [资源说明](generation-resources.md)、[测量记录](../testdata/generation/resource-measurements.json)、[兼容性记录](compatibility.md)给出范围；公开接口仅新增默认配置入口。

本地提交后才执行 GitHub 创建/上传与最终 SHA 的首次 CI，实际远程结果在完成报告中给出，不提前声明通过。该上传不包含 Mooncakes 发布、tag 或 GitHub Release。

## Commit 12 本次实施记录（2026-11-12）

基线：`109c817ad2460b14a99a3558ec981a712c81c11b`，master，起点工作区干净。
此前 Commit 11 实现为 `5181a29c29b4047310324216793ab5a1da84ec5e`，随后仅追加注册表初始化 CI 修复，已上传 BigSaltyMan/moonBSDiff。

- 提供 native diff、patch、help、version；版本从 moon.mod 生成，退出码 0/2/1，直接调用公开 diff/apply。
- native 包隔离平台文件操作，无新增 IO 模块依赖，不改变核心算法、压缩依赖或根公开接口。
- CLI 仅调整应用补丁上限至 128 KiB，66,279 字节补丁在两平台实际往返。
- 文件大小预检及运行中累计限制；实际身份检查；Windows 独占临时文件和句柄无替换重命名；Linux 匿名临时文件及无替换 linkat。
- Windows 31 项文件测试中 29 通过、2 项缺少符号链接权限跳过，9 项私有真实文件 IO 契约通过；Linux 31 项及9项全部通过。
- CI 保留库检查，增加 Windows/Linux CLI 任务。上传后核验最终 SHA 和真实 CI；不提前把本地结果写成远程成功。
- [CLI 使用与保证范围](cli.md)和[精简证据](../testdata/cli/native-results.json)记录实际行为。Linux 输出要求 O_TMPFILE 文件系统及 /proc，未实现危险回退；未承诺断电持久性。

原规划全文与仓库外原文件保持不变。以下为 Commit 12 当时的记录，Commit 13—16 当时继续待实施；未发布 Mooncakes、tag 或 Release。

## Commit 13 实施范围

基线 `34f42433d8477af359bd278a1f700175fd9051b9`。复用现有测试、CLI和31输入清单，补 JS/Wasm-GC check/build、独立真实参考任务、非零测试与源码对应门禁。本地只验证新增检查逻辑和配置，不重跑旧矩阵。最终同一 SHA 的目标、CLI、参考执行交由正式 CI 并在完成报告核对，不预填成功。这是 Commit 13 当时的待实施范围；当前状态见下表。

## Commit 14 实施范围

基线 `925087200396bde2d22c06b641fbf164e5c6fcf8`。新增公开 API 纯内存示例及自有两版 Wasm-GC 模块，使用固定工具链 release/strip 编译。清单预期来自独立编译，演示调用正式CLI并比较完整字节与固定哈希。仅验证新示例，不在本地重跑旧矩阵、CLI全集、资源或压缩大样本。CI复用Linux CLI构建，仅增加一次示例运行。干净源码复现与最终SHA的实际CI在完成报告给出，不预填成功。这是 Commit 14 当时的待实施范围；当前状态见下表。

## Commit 15 实施记录

基线 `1feee0c04f857fa95ebda0d04646d7952a624d3e`。固定五类输入：相同、稀疏修改、周期、固定随机（各4096字节）及既有3962字节 Wasm 更新。每实现每案例预热1次、测量3次生成/应用，逐字节恢复检查。Linux/WSL native release，计时包含进程与 IO，核心 API 时间及可靠峰值内存未测。复用已核验 C 工具，没有重建 oracle 或本地重跑历史矩阵。结果、原始样本、哈希及限制见 [基准](benchmarks.md)。

0.1.0 保持 Unreleased，冻结现有功能：不新增格式、目录同步、网络、GUI、调优参数或扩大平台/资源保证。剩余为兼容性缺陷、必要修复、包审计、最终验证、Mooncakes 发布、独立消费及发布记录。Commit 16 待实施；本步骤不发布、不创建 tag。

## Commit 16 发布准备

基线 `0e67949d73493f0edade3fc6c50833b76dca02b4`，冻结功能范围不变。`scripts/release_audit.py` 从指定 Git SHA 导出干净源码，再执行格式、接口及官方打包并逐成员核验；候选消费从 ZIP 独立解包，注册表消费则使用全新 SDK 缓存和无 workspace 的外部目录。最终源码须取得对应 CI（库、CLI、示例、真实参考及候选消费）成功后才发布。发布后以独立文档提交记录源码 SHA、实际公开包身份、CI 和安装结果；此准备记录不预填发布成功，不创建 tag 或 GitHub Release。见 [验收说明](acceptance.md)。

## 后续状态

| 步骤 | 状态 |
| --- | --- |
| Commit 12 Native 命令行与文件交付 | 已实现并完成本地 Windows/Linux 文件验证；最终远程 CI 在完成报告核对 |
| Commit 13 跨目标检查与兼容性报告 | 已整理目标检查、独立参考任务及门禁；最终 SHA 的远程结果在完成报告核对 |
| Commit 14 最小示例与 Wasm 更新演示 | 已提供源码、固定清单及可执行驱动；干净导出与最终 CI 结果在完成报告核对 |
| Commit 15 基准、文档与范围冻结 | 已完成五类固定小输入测量、文档核对、Unreleased CHANGELOG 和范围冻结；最终 SHA CI 在完成报告核对 |
| Commit 16 源码包审计与发布验收 | 已建立干净源码包审计及外部消费入口；发布与注册表消费结果将在独立发布记录提交中据实记录 |

---

以下保留来源规划全文、原编制日期、范围及后续验收要求。原文的计划状态与将来时以以上真实记录区分。

# MoonBSDiff 二进制差分与补丁库开发与验收规划书

编制日期：2026 年 11 月 4 日。目标版本：`0.1.0`。状态：立项与实施计划。

**GitHub 上传归属（固定约定）：MoonBSDiff 的代码、测试、文档与 CI 配置统一提交并推送到 `BigSaltyMan/moonbsdiff`，使用 `BigSaltyMan` 账户对应的 SSH 密钥与别名 `github-bigsalty`。**

MoonBSDiff 拟以 MoonBit 实现兼容 BSDIFF40 格式的二进制差分生成与补丁应用，参考 BSDiff 的成熟算法和文件格式。首版围绕两个可复用库入口、一个 native 命令行工具、上游双向互操作和可复现示例完成交付，服务 WebAssembly 模块、可执行文件及资源文件的增量分发。

本规划安排 **16 个首版必需开发与交付步骤**，按实际功能变化组织提交，预计投入两到三周。每步列出修改位置、实现内容、验证要求和完成条件；遇到缺陷可以增加修复提交，不通过空提交或机械拆分满足数量。提交数不代替功能完成度。

本文以 MoonClip 规划书的章节结构和逐提交方式编写，但不沿用其历史赛程、奖励、版本记录及几何功能。下面的代码路径均相对于未来独立的 MoonBSDiff 仓库；本文创建不代表仓库、核心算法或发布工作已经完成。

## 一 项目定位与参赛边界

### 项目名称与用途

- 项目名称：MoonBSDiff。
- 拟用模块名：`BigSaltyMan/moonbsdiff`，创建时核对账号命名空间和名称可用性。
- 项目方向：基础工具库、二进制数据处理、开发者工具。
- 项目性质：参考移植项目，明确 BSDiff 的原作者、版本、许可证和实际移植范围。
- 实现主体：MoonBit。运行库自行实现格式处理、索引、匹配、差分和补丁应用；bzip2 使用现有 MoonBit 依赖。
- 目标用户：需要生成文件增量包、恢复新版本二进制内容或在 MoonBit 工具中嵌入差分能力的开发者。

项目产物是可以实际应用的标准二进制补丁。给定正确的旧文件与对应补丁，应能按字节恢复目标新文件。文件内容按字节处理，不依赖扩展名，也不需要理解 Wasm、PE、ELF 或资源文件内部结构。

### 与现有项目的关系

MoonBSDiff 与 MoonClip、moonsize 分别解决文件差分、二维几何和 Wasm 体积分析问题。可以使用自行编译的两版 Wasm 模块作为演示，但核心库不依赖这些旧项目，也不把已有代码和成果重新计作新增工作。

前期 Mooncakes 检索中，`bsdiff`、`bspatch` 未找到直接对应模块；`librsync` 也未找到直接对应模块。检索同时发现已有 VCDIFF 编解码项目。BSDIFF40 与 VCDIFF 是不同格式，应比较实际接口、格式和用途，不将“名称未命中”写成整个生态没有二进制增量工具的结论。

在 `docs/related-work.md` 中补充正式立项时的检索日期、关键词、链接和实际 API 比较。MoonBSDiff 的独立贡献是标准 BSDIFF40 生成与应用、MoonBit 可复用接口、错误与资源限制，以及独立互操作证据。

### 主办方要求与计划边界

本规划以本次提供的九项验收要求为依据：MoonBit 主体实现、moonc 不低于 0.10.16、公开 GitHub 仓库、核心功能完整、可复现 README、check/build/test CI、可运行示例、核心测试、Mooncakes 实际发布及 OSI 认可许可证。

赛事月份、报名截止、奖励和其他申报细节以当期主办方通知为准，本文不从 MoonClip 历史文档继承这些内容，也不以代码行数或提交数保证通过审核。

### 已完成的前置验证

2026 年 11 月 4 日，已在独立临时目录完成以下验证：

| 项目 | 实际结果 | 证据边界 |
| --- | --- | --- |
| 工具链 | `moonc v0.10.19+bee578715`，2026-11-02 构建 | 满足版本下限；正式项目仍需锁定并复验 |
| 压缩依赖 | `moonbitstack/moonzip@0.3.5` 的 bzip2 包可安装 | 未修改依赖源码 |
| 类型检查 | native、JS、Wasm、Wasm-GC 四目标通过 | 不是四目标的完整运行验证 |
| 压缩互操作 | native、JS、Wasm-GC 分别执行六组输入，完成 Python bz2 与 MoonBit 双向核验 | 探针压缩级别为 1；正式格式验证还需覆盖上游常用的级别 9 |
| 输入类别 | 空、UTF-8 文本、全部字节值、重复数据、固定随机数据、跨块数据 | 最大一组原始数据 110080 字节，不代表大型文件性能 |
| 上游归档 | 已取得 BSDiff 4.3 原始归档并计算 SHA-256 | 尚未在本轮编译和运行其参考程序 |

压缩探针使用程序断言和 Python 独立解码核验，不是 MoonBSDiff 的正式测试套件。补丁格式、应用算法、生成算法、CLI、项目级 CI 和 Mooncakes 发布均尚未完成。实施时把必要探针输入、脚本和结果整理到独立仓库中，不依赖本机临时目录长期存在。

## 二 首版范围与停止条件

### 必须完成的能力

| 能力 | 首版要求 | 完成证据 |
| --- | --- | --- |
| 补丁格式 | BSDIFF40 文件头、整数编码、控制块、差分块和新增块 | 人工字节向量、边界测试及独立解析核对 |
| 补丁应用 | 根据旧数据和补丁恢复新数据 | 上游补丁可由 MoonBSDiff 应用，结果逐字节一致 |
| 差分生成 | 依据旧、新数据寻找匹配并生成有效补丁 | MoonBSDiff 补丁可由上游 bspatch 应用 |
| 匹配算法 | 后缀数组、匹配查找、前后向段选择及重叠处理 | 小规模独立预期、重复数据及回归用例 |
| 压缩封装 | 三个数据块分别使用 bzip2 | 空块、非空块、级别与跨块数据经过外部核验 |
| 错误处理 | 格式、截断、长度、偏移、溢出、解压和资源超限错误 | 可识别错误，不以空结果或进程退出伪装成功 |
| 资源限制 | 输入、补丁、恢复输出、解压和主要生成工作量限制 | 在分配和扩张前检查，正常与超限路径均测试 |
| 公开 API | `diff` 与 `apply`，必要的配置、限制和错误类型 | 独立消费者可以只依赖已发布包调用 |
| CLI | `diff`、`patch`、帮助和版本信息 | Windows/Linux native 的文件级完整流程 |
| 运行环境 | 库在 native、JS、Wasm-GC 上检查、构建和测试 | 各目标分别记录结果；普通 Wasm 暂只保留已完成的探针检查结论 |
| 示例与分发 | 库示例、Wasm 文件更新示例、README、CI 和 Mooncakes 包 | 干净检出与注册表安装均可复现 |

### 首版范围边界

首版采用完整字节缓冲区接口，处理单个旧文件、新文件与补丁。后缀数组、差分缓冲区和输出会占用与输入规模相关的内存，不宣称常量内存或完整流式处理。

目录同步、SSH/HTTP 传输、自动更新服务、GUI、安装器、包签名、BSDIFF43 等其他格式、内存映射和并行差分留到后续版本。本期没有额外的条件扩展提交，避免扩展挤占兼容性与交付时间。

### 停止条件

必需矩阵通过后停止增加功能，剩余时间用于真实差异、错误边界、文档、发布与独立消费验证。

若生成器不能正确利用旧数据、只能把完整新文件塞进新增块，不能按“二进制差分生成已完成”验收。全量新增可以是空旧文件或完全不匹配输入的合法结果，但不能成为所有输入的固定实现。

若核心功能仍有未解释差异，应继续修复或重新确认交付时间，不通过删除困难案例、放宽字节比较或把必需算法移入“可选”维持完成声明。

## 三 上游来源与移植路线

### 固定参考版本

初始算法与格式基线采用 **BSDiff 4.3**，原作者 Colin Percival。固定对象是源码分发归档，不凭空填写 Git 提交号。

- 项目主页：<https://www.daemonology.net/bsdiff/>
- 官方原始归档地址：<https://www.daemonology.net/bsdiff/bsdiff-4.3.tar.gz>
- 本次实际取得的原始源码镜像：<https://deb.debian.org/debian/pool/main/b/bsdiff/bsdiff_4.3.orig.tar.gz>
- 实际归档大小：5740 字节。
- 实际计算的 SHA-256：

```text
18821588b2dc5bf159aa37d3bcb7b885d85ffd1e19f23a0c57a58723fea85f48
```

本次官方归档下载返回 HTTP 403，随后从 Debian 原始源码镜像取得归档；实算哈希与 Homebrew 分发配方记录相同。未来参考脚本必须重新核验归档，不能把本文中的事实当成脚本已执行的证明。[Homebrew 配方](https://github.com/Homebrew/homebrew-core/blob/HEAD/Formula/b/bsdiff.rb)

主要阅读和移植对象是归档中的 `bsdiff.c`、`bspatch.c` 及格式说明。BSDiff 4.3 的后缀排序路线是算法阅读基线；不混入使用不同封装的第三方实现后继续称为同一参考。

### MoonBit 实现方式

- 格式编码、长度与偏移检查集中到独立模块，生成与应用共用这些规则。
- 索引使用整数数组和原始字节视图，不为每个后缀复制完整字节串。
- 后缀排序先对照原版 qsufsort 的结构与不变量实现；如改用倍增加基数排序，记录替换原因并用独立小数据预期验证。
- 匹配扫描、前后向匹配、重叠调整和控制三元组形成可独立测试的私有函数。
- bzip2 通过窄适配层调用已发布 MoonBit 包，压缩细节不扩展成第二个自研项目。
- 库不进行文件 IO，不调用 C 程序、Python 或远程服务。参考程序和 Python 仅参与测试及数据生成。
- 参考程序需要的头文件或构建适配单独保存补丁与哈希；算法修改不能混在“平台适配”中。

### 正确性参照与错误输入

旧版 C 实现用于合法输入上的算法和格式互操作。其错误检查不能作为本项目处理恶意或损坏输入的全部标准，也不要求 MoonBSDiff 复制其整数溢出、未检查长度等历史行为。

损坏补丁使用人工构造的明确预期、MoonBit 安全契约和独立解析器验证。参考子进程异常退出、超时或缺少结果均报告为问题，不转成成功或静默跳过。

### 许可证与依赖

建议项目采用 **BSD-2-Clause**，保留 Colin Percival 的版权与许可声明。在 `docs/upstream.md` 记录原文件、归档哈希、MoonBit 对应文件、算法改动和参考工具构建方法。

`moonbitstack/moonzip@0.3.5` 是复用的压缩依赖，按其锁定版本的许可要求记录来源；其他直接或传递依赖也应实际核对。生成测试数据、参考源码、演示源码和第三方补丁分别注明来源。包命名、README 和许可证不能使使用者误认为全部压缩代码由本项目原创。

## 四 数值、格式与行为契约

### 文件头与整数编码

1. 文件头固定为 32 字节，开头八字节为 ASCII `BSDIFF40`。
2. 后续三个八字节字段依次表示压缩后的控制块长度、压缩后的差分块长度和恢复文件大小；新增块占补丁剩余部分。
3. 格式整数采用小端的符号与数值分离编码，最高字节最高位表示负号，不是普通二进制补码。
4. 编解码覆盖零、负零输入、正负值及最大可表示幅值。编码不能直接对 Int64 最小值取负数；它不在该格式的可编码范围内。
5. 文件长度和偏移先用受检查的 Int64 计算；转换为数组索引前再确认非负、在缓冲区内且不超过目标平台和资源上限。
6. 压缩块长度和新文件大小必须非负；`32 + 控制长度 + 差分长度` 等运算逐项防溢出并检查实际补丁边界。

文件头声称可以表示很大长度，不等于本库能在内存中处理完整范围。实际支持规模由数组上限和资源限制共同决定。

### 控制指令与恢复语义

控制块由三元组 `(x, y, z)` 组成，每个分量使用上述整数编码：

- 取差分块的 x 字节，与旧文件对应字节相加，结果按模 256 写入新数据。
- 取新增块的 y 字节直接写入新数据。
- 旧数据游标在已经前进 x 字节后，再按有符号 z 调整位置。

x、y 必须非负，z 可以为负。每次推进检查新文件剩余空间、差分和新增块剩余数据及整数范围。旧文件范围外的字节贡献按参考语义视为零，不能因为旧游标暂时为负或超出末尾就无条件拒绝合法补丁。

允许只调整旧游标而不增加输出的合法控制指令；通过控制数据上限、指令次数和工作量限制终止异常输入，不能粗暴把所有零输出指令判错。

空旧文件、空新文件和两者均空分别处理。成功恢复空文件是合法结果，不是“没有执行”或错误占位。

### 压缩块与封装边界

三个块分别是一条完整的 bzip2 流，空块也采用合法空流。生成器首版固定使用级别 9，避免提前增加调优参数；依赖探针的级别 1 成功不能替代级别 9 的正式验证。

适配层需要确认解压上限、完整结束和校验和检查的实际行为。首版采用明确的单流封装：拒绝不完整流、校验失败、拼接流和段内尾随杂字节，且不允许解压绕过预算。控制块按 24 字节对齐，成功应用后不保留未使用控制指令、差分或新增数据。

这是有意采用的严格封装策略。部分宽松参考程序可能忽略尾随或冗余数据，不能据此要求本库接受全部这类输入；`docs/compatibility.md` 要明确这项差别。Commit 4 必须确认依赖能提供所需的流结束及消费边界信息，不能只凭解压返回成功推断完整消费。

若现有依赖无法支持这项检查，先记录具体缺口并评估小范围适配或替换依赖；不自行悄悄降低检查，也不借机重写整个 bzip2 引擎。

### 确定性、完整性与兼容性

- 同一旧数据、新数据、选项和固定依赖版本应产生稳定结果，数据中不引入时间戳。
- 与上游互操作比较恢复后的完整字节，不要求补丁字节、控制段划分或补丁大小完全相同。
- BSDIFF40 本身不含旧文件和新文件的密码学哈希。CRC 校验压缩数据，不等于验证调用者选对了旧文件。
- 首版不承诺识别所有旧文件不匹配；实际应用方应在外层验证旧文件与恢复结果的预期哈希。示例必须展示结果校验。
- 输入字节不被修改，调用失败不返回部分成功结果。API 不隐式退出进程。

### 资源限制与错误

限制至少覆盖旧数据、新数据、补丁、解压总量、控制数据/指令数量，以及主要匹配和排序工作。上限在分配、扩张、解压和循环处理前生效，不能在数据已全部展开后才检查。

默认限制的具体数值在 Commit 6 与 Commit 11 根据实际资源测量固化，并写入文档及边界测试。无界处理不能通过零或负值隐式开启；测试可以传入较低上限验证恰好够用和差一单位。

MoonBit 可控循环的工作计数不等于 bzip2 内部的完整 CPU 预算；首版不声称具备严格墙钟超时、实时性或整个进程的峰值内存保证。

错误至少区分无效配置、格式不支持、截断数据、非法字段、整数溢出、解压失败、输出越界和资源超限。保留阶段、块类型和可定位偏移，不把损坏输入转换成空补丁或空新文件。

### 拟定公开接口

以下是接口设计草案，不是已经编译通过的 MoonBit 声明；最终以工具链检查和生成的 `.mbti` 为准。

```text
BsdiffError / ErrorStage / Limits

diff(old_bytes, new_bytes, limits)
    -> Result[Bytes, BsdiffError]

apply(old_bytes, patch_bytes, limits)
    -> Result[Bytes, BsdiffError]
```

首版公开入口围绕 diff 与 apply。后缀数组、压缩适配、控制指令和格式拼装先保持私有，不为了展示内部结构扩大长期维护的 API。

### CLI 行为

拟提供以下接口；这些是目标用法，不是已经可执行的命令：

```text
moonbsdiff diff OLD_FILE NEW_FILE PATCH_FILE
moonbsdiff patch OLD_FILE PATCH_FILE OUTPUT_FILE
moonbsdiff --help
moonbsdiff --version
```

- 文件按二进制读取；读取前检查可得的大小，读取中仍执行上限检查，避免文件变化绕过限制。
- 默认拒绝覆盖已有输出文件，拒绝输出与输入指向同一文件；本版不增加强制覆盖开关。
- 成功前在目标目录使用独占创建的临时文件；完整写入、关闭后以不覆盖已有目标的方式交付结果。失败清理本次临时输出，不删除已有文件。
- 成功退出码为 0，参数错误为 2，运行失败为 1；错误写入标准错误。
- 帮助说明本工具子命令的参数顺序，不能把它与上游 bspatch 的 `OLD NEW PATCH` 顺序混淆。
- Windows 与 Linux 的路径、非 ASCII 文件名、目标已存在和读写错误分别测试，不以路径字符串不相同代替必要的同文件检查。

## 五 仓库结构与工程约定

### Git 版本管理与上传账户

| 配置项 | 本项目约定 |
| --- | --- |
| 项目 | MoonBSDiff（moonbsdiff） |
| GitHub 所有者 | `BigSaltyMan` |
| 公开仓库 | `https://github.com/BigSaltyMan/moonbsdiff` |
| origin SSH 地址 | `git@github-bigsalty:BigSaltyMan/moonbsdiff.git` |
| SSH 主机别名 | `github-bigsalty` |
| 新提交署名 | 仓库级 `user.name` 使用 `BigSaltyMan`，`user.email` 使用该账户已验证的邮箱或完整 noreply 邮箱 |

执行本规划的开发者或代理应沿用上述归属。每个开发步骤的实质修改提交到本项目仓库，并在对应检查通过后推送到上述 GitHub 仓库。首次上传前核对 origin 的实际推送地址与仓库级署名，运行 `ssh -T git@github-bigsalty` 确认认证提示为 `Hi BigSaltyMan!`。

MoonLibSync 使用另一账户 `YKDshaxing`；两个项目分别保留自己的 Git 仓库、origin 和提交身份，不通过反复修改全局 Git 用户信息切换。本段是执行要求，不表示本文编辑时已经创建远程仓库、提交或推送代码。

### 源码目录与工程约定

```text
moonbsdiff/
  moon.mod
  moon.pkg
  errors.mbt
  limits.mbt
  intcodec.mbt
  format.mbt
  compression.mbt
  apply.mbt
  suffix_array.mbt
  matching.mbt
  diff.mbt
  *_test.mbt
  *_wbtest.mbt
  cmd/main/
  cmd/example/
  cmd/conformance/
  examples/basic/
  testdata/dependency-probe/
  testdata/upstream/
  testdata/regressions/
  tools/oracle/upstream.lock.json
  tools/oracle/
  scripts/
  docs/
  .github/workflows/ci.yml
  README.md
  LICENSE
```

文件可按实际需要拆分，不为对应目录表创建空实现。根库保持计算逻辑，CLI、IO、参考程序与测试工具分别维护。命令行包声明 native 支持范围，避免库的 JS/Wasm-GC 检查被 native 文件 IO 拖入。

使用实际验证的 `moonc 0.10.19` 作为初始开发与 CI 基线，记录完整版本；主办方允许的最低版本不等于本项目已经验证的最低兼容版本。

沿用 MoonBit 的 `///|` 分块、黑盒/白盒测试和稳定结果断言。每笔实现后更新 `.mbti` 与格式，审查公开接口差异，再运行适用检查。早期组件可以保持私有，不公开永远返回空结果的占位函数。

提交只包含对应步骤的文件与必要修复，保留无关工作。发布包不包含临时归档、参考二进制、个人环境配置、测试缓存或未获分发许可的数据。

## 六 16 个开发与交付步骤

下面是依赖顺序，不强制每天一笔。每步完成后再进入依赖它的后续步骤；兼容性与错误处理不能推迟到发布当天。

### Commit 1 工程初始化与限制错误模型

**修改位置：** `moon.mod`、`moon.pkg`、`errors.mbt`、`limits.mbt`、基础测试、`LICENSE`、README、CI。

- 建立独立模块、目标范围、许可证和来源说明，锁定压缩依赖与工具链。
- 定义错误阶段与限制配置，提供实际的配置验证，覆盖非法值和边界值。
- 将前期压缩探针的输入、生成方法与结果整理入库，明确它与核心功能测试的区别。
- CI 从本笔开始运行格式、native 检查、构建和非零实际测试；未实现功能使用计划语气。

**完成条件：** 项目能检查、构建和执行真实基础测试，依赖与规则可追溯。

**提交信息：** `建立 MoonBSDiff 工程与错误限制模型`

### Commit 2 BSDIFF40 整数编码与封装解析

**修改位置：** `intcodec.mbt`、`format.mbt`、编码与解析测试、`docs/format.md`。

- 实现符号幅值八字节编码、文件头解析、块切分和受检查的长度运算。
- 覆盖负零、最大幅值、Int64 最小值拒绝、短头部、错误魔数及长度越界。
- 格式预期由手工字节向量与独立 Python 小工具给出，不能只做自编码再自解码。
- 写清单流封装、数据消费、空输出和不支持格式的规则。

**完成条件：** 编码与边界能独立验证，解析不分配由未经检查长度决定的大数组。

**提交信息：** `实现 BSDIFF40 整数与文件头解析`

### Commit 3 固定上游参考与离线数据

**修改位置：** `tools/oracle/`、锁文件、`scripts/generate_reference.py`、`testdata/upstream/`、`docs/upstream.md`。

- 下载并核验固定 4.3 归档，记录源文件哈希、编译器、libbz2、命令和必要平台适配。
- 编译真实 bsdiff/bspatch；只把它们用于测试，普通库调用和普通单元测试不依赖 C 工具。
- 建立有版本的 manifest，记录旧、新、补丁、预期结果、来源及 SHA-256。
- 生成空文件、相同文件、局部插删改、重复数据和完整字节范围等首批合法数据。
- 让比较器故意遇到缺失案例、改坏输出和改坏哈希，确认会失败。

**完成条件：** 能实际生成并复核独立参考数据，版本和结果均有来源；只有锁文件不算完成。

**提交信息：** `建立固定 BSDiff 参考与离线测试数据`

### Commit 4 带边界的 bzip2 适配

**修改位置：** `compression.mbt`、相关测试、依赖探针和格式文档。

- 封装控制、差分和新增块的压缩解压，首版生成固定级别 9。
- 核验消费边界、完整结束、CRC、单流策略和解压限制，必要适配保留依赖来源。
- 覆盖空流、级别 1/9、接近块边界、跨块、截断、校验损坏、连接流及尾随数据。
- 用 Python bz2 等独立实现交叉验证，测试解压上限恰好够用与差一字节。
- 对已知缺口给出实际失败和处理结论，不能只复用“六组探针通过”的旧结论。

**完成条件：** 格式层能调用真实且边界可解释的压缩适配，错误和限制不会丢失。

**提交信息：** `实现受限 bzip2 数据块适配`

### Commit 5 核心补丁应用

**修改位置：** `apply.mbt`、格式与压缩适配、公开黑盒测试、`.mbti`。

- 实现控制三元组执行、差分字节模 256 相加、新增数据复制和旧游标调整。
- 提供真实 apply 入口，处理空输入、空结果及旧数据范围外的零贡献。
- 每次读写和偏移推进都执行长度、范围和溢出检查。
- 对上游首批补丁恢复完整新数据；预期直接来自原始新文件。

**完成条件：** 首批参考补丁能正确应用，错误返回 Err，输入不变且没有部分结果。

**提交信息：** `支持 BSDIFF40 补丁应用`

### Commit 6 补丁应用边界与阶段验收

**修改位置：** `apply.mbt`、`limits.mbt`、`testdata/regressions/`、应用测试与文档。

- 补齐负位移、零输出控制、整数极值、全部数据消费和严格封装回归。
- 用独立构造器生成旧数据范围外、控制不足、输出不足/过量等有明确预期的案例。
- 完成控制数据、总解压量、输出大小与指令限制，测量并固化应用端默认值。
- native、JS、Wasm-GC 分别验证；记录上游生成到 MoonBSDiff 应用这一方向的实际结果。

**完成条件：** 应用功能在声明边界内可独立使用，阶段报告没有未解释差异。

**提交信息：** `完善补丁应用边界与资源检查`

### Commit 7 后缀数组构建

**修改位置：** `suffix_array.mbt`、白盒测试、上游映射说明。

- 按已经选定的 qsufsort 或有记录的替代路线实现索引构建，明确空后缀和哨兵规则。
- 不复制所有完整后缀，也不以仅适用于文本的零终止字符串规则处理二进制数据。
- 检查排序数组、秩与临时缓冲区的规模和中间算术。
- 对小输入使用独立朴素排序核验完整数组，覆盖全相同、周期、0x00、0xff 和固定随机输入。

**完成条件：** 后缀顺序、完整性和边界独立正确，内存增长方式可说明。

**提交信息：** `实现二进制后缀数组索引`

### Commit 8 匹配扫描与段选择

**修改位置：** `matching.mbt`、`diff.mbt` 私有逻辑、算法测试。

- 实现索引查找、最长匹配、偏移评分、前向与后向匹配及重叠调整。
- 保持参考算法可解释的结构，记录核心不变量和 MoonBit 适配。
- 用人工可判断的插入、删除、移动、重复块和高重复数据验证扫描过程。
- 覆盖相同最长匹配、末尾匹配和空旧数据，不以特判固定演示数据代替匹配。

**完成条件：** 能形成正确控制段和匹配区间，过程不跳过或重复消费新数据。

**提交信息：** `实现后缀匹配与差分段选择`

### Commit 9 标准补丁生成

**修改位置：** `diff.mbt`、格式编码、压缩适配、公开黑盒测试和 `.mbti`。

- 生成控制三元组、字节差分数据和新增数据，按固定格式压缩与拼装。
- 接通 diff 入口，完成空旧、新数据和完全不同数据的合法生成。
- 用独立解析检查块长度、目标长度、整数编码和三个完整压缩流。
- 同时保留自往返和外部应用验证；不要求输出与参考补丁逐字节相同。

**完成条件：** MoonBSDiff 生成的补丁能由真实上游 bspatch 恢复原始新文件。

**提交信息：** `支持 BSDIFF40 二进制补丁生成`

### Commit 10 双向互操作与随机回归

**修改位置：** `cmd/conformance/`、参考脚本、manifest、回归用例、`docs/compatibility.md`。

- 两个方向均实际执行：上游生成到 MoonBSDiff 应用，MoonBSDiff 生成到上游应用。
- 覆盖空、相同、稀疏修改、段移动、随机和不可压缩数据；固定随机种子。
- 比较完整输出与原始新文件，必要时用哈希保存证据，不只比较长度或自计算摘要。
- 缺失、额外、重复结果、异常退出、超时和跳过均有严格处理；失败输入可保存和缩减。
- 报告独立案例数、各方向、各目标和跳过原因，不把多次执行相加当作新增案例。

**完成条件：** 首版既定双向矩阵通过，未解释差异为零，比较器能识别故意损坏结果。

**提交信息：** `建立 BSDiff 双向互操作与随机回归`

### Commit 11 生成资源保护与错误后复用

**修改位置：** `limits.mbt`、索引/匹配/生成入口、白盒与黑盒测试、数值文档。

- 预检旧、新输入与补丁限制，对索引、生成缓冲区和主要循环使用一次调用的累计记录。
- 阶段切换不能重新获得完整工作额度；计数和乘法防溢出，错误时不修改调用者数据。
- 测量并固化生成端默认限制，明确缓冲区复制、压缩依赖和工作计数的能力边界。
- 验证恰好够用、差一单位、失败后正常调用、重复调用与结果隔离。
- 不以临时提高默认额度掩盖算法无进展或超常资源增长。

**完成条件：** diff/apply 的失败路径、默认限制和输入规模约定一致且可复现。

**提交信息：** `完善差分资源限制与调用隔离`

### Commit 12 Native 命令行与文件交付

**修改位置：** `cmd/main/`、必要 IO 适配、CLI 测试、README。

- 完成 diff、patch、帮助和版本，沿用同一核心 API，不在 CLI 里实现第二套算法。
- 锁定实际使用的 MoonBit IO 依赖，先确认 Windows/Linux 和当前工具链支持。
- 按约定处理二进制读写、读入限制、已有输出、同文件、临时文件与失败清理。
- 覆盖路径含空格、中文文件名、参数错误、不可读输入、目标已存在和完整往返。
- 对照上游参数顺序写清调用示例，固定退出码和标准错误行为。

**完成条件：** 两个平台可通过文件命令完成生成与恢复，失败不会破坏已有输入和输出。

**提交信息：** `提供二进制差分与补丁命令行`

### Commit 13 跨目标检查与兼容性报告

**修改位置：** CI、`scripts/check_acceptance.py`、`scripts/check_reference.py`、兼容性文档。

- 在 Linux CI 执行库的 native、JS、Wasm-GC 检查、构建和测试，Windows 验证 native。
- 普通库测试使用离线固定数据；独立参考任务下载锁定归档并实际执行双向核验。
- 日志中区分库测试、CLI、参考互操作和外部消费者；筛选后零测试视为验证失败。
- 参考任务的输入、输出和执行 SHA 可追溯；修改参考输入、比较器或生成器时复核相关固定预期。
- 更新接口文件和格式检查，确认平台专用包没有污染核心库。

**完成条件：** 同一提交的检查结果和报告对应实际代码，完整矩阵不会因漏跑而假绿。

**提交信息：** `完善跨目标持续集成与兼容性报告`

### Commit 14 最小示例与 Wasm 更新演示

**修改位置：** `examples/basic/`、`cmd/example/`、示例生成脚本、README。

- 提供不需要文件系统的最小库例子，构造旧、新字节、生成补丁并验证恢复数据。
- 用仓库自有源码和固定编译参数生成两版小型 Wasm 模块，执行 CLI 差分与恢复。
- 输出文件大小及预期哈希核验结果，记录生成方式，避免仅上传无法追溯的二进制。
- 演示调用正式库，失败时退出非零；固定案例的预期不能在运行中用被测逻辑重新生成。

**完成条件：** 新使用者可以按 README 从干净检出复现两种示例，并判断结果是否正确。

**提交信息：** `提供库调用与 Wasm 增量更新示例`

### Commit 15 基准、文档与范围冻结

**修改位置：** `docs/benchmarks.md`、`docs/format.md`、`docs/compatibility.md`、`docs/upstream.md`、README、CHANGELOG。

- 测量相同、稀疏修改、重复、随机和实际 Wasm 数据的生成/应用时间及补丁大小。
- 记录工具链、CPU、平台、构建模式、输入哈希和测量方法；无法测峰值内存时明确未测。
- 与参考工具比较时使用相同输入和可说明配置，不用单个友好案例宣称全面优势。
- 定稿格式、严格封装、负位移、旧文件校验限制、资源策略和平台支持。
- 冻结首版范围，后续只处理兼容性缺陷、测试和交付问题。

**完成条件：** 文档与真实行为一致，测量可复现，所有支持声明都有对应证据。

**提交信息：** `完善使用文档与差分基准记录`

### Commit 16 源码包审计与发布验收

**修改位置：** 模块元信息、CHANGELOG、发布审计脚本、`docs/acceptance.md` 和必要交付文档。

- 从干净源码检出检查标准测试、参考互操作、CLI、示例及文档，不把历史提交的成功当作最终结果。
- 执行包审计，检查清单、许可证、依赖、公开接口和无关文件；记录最终源码 SHA 与实际包哈希。
- 用候选包在仓库外做安装与调用检查；此时只能称候选包验证，不能称注册表消费。
- 固定最终源码后取得对应 SHA 的成功 CI，实际发布 Mooncakes，再从独立目录安装已发布版本调用 diff/apply。
- 发布后状态记录写入独立文档提交，说明其与发布源码 SHA 的关系；不在发布源码里预填尚未发生的上传和消费结果。

**完成条件：** 源码、CI、实际发布版本与独立消费记录能够对应，九项验收要求有真实证据。

**提交信息：** `准备 MoonBSDiff 首版发布与验收材料`

本步骤包括源码提交和其后的发布操作。发布不是增加提交数量的手段；本规划的编写不代表当前已经执行 moon publish、标签或 GitHub Release。

## 七 测试与比较方法

### 输入输出比较

成功路径以恢复结果与原始新文件逐字节相等为准。大文件报告可附 SHA-256，但生成报告的工具不能只使用被测库自己计算的预期。

补丁内容不与上游做全字节强制一致比较；不同匹配或压缩输出可以合法互操作。生成器是否真正差分，还要用有明显可复用内容的固定样例检查控制和差分结构，避免全量新增实现通过自往返。

### 必须覆盖的矩阵

| 维度 | 案例 |
| --- | --- |
| 空输入 | 旧空、新空、同时为空、空目标补丁 |
| 编辑 | 相同、替换、插入、删除、前后追加、截短、块移动 |
| 字节 | 0x00、0xff、全部字节值、UTF-8、周期和长重复串 |
| 匹配 | 相同最长匹配、末尾匹配、交叠、负 seek、旧区间外零贡献 |
| 压缩 | 空流、级别 1/9、块边界、跨块、CRC 错误、截断、单流边界 |
| 格式 | 短头、错误魔数、符号幅值边界、负长度、溢出、错位控制 |
| 消费 | 数据不足、额外控制、额外差分/新增数据、零输出指令 |
| 资源 | 各限制、恰好够用/差一单位、累计工作、失败重试 |
| API | 输入不变、结果隔离、重复调用、结构化错误 |
| CLI | 路径、中文文件名、同文件、已有输出、读写失败、退出码 |
| 互操作 | 上游生成/本库应用，本库生成/上游应用，各目标分别记录 |
| 分发 | 干净源码、候选包、Mooncakes 注册表版本的独立调用 |

### 性质测试与独立预期

自往返 `apply(old, diff(old, new)) == new` 是必要检查，但不足以证明格式兼容。格式编码、后缀数组和负偏移等关键规则都应有来自其他实现或人工可推导的预期。

随机测试固定种子、保存完整输入，真实失败案例进入回归目录。异常案例不能统一接受任意错误；需要检查是否落到预期错误类别、是否保留相关阶段以及是否影响后续调用。

测试数量由覆盖矩阵决定，不先承诺虚构的总数，不把同一输入在三目标重复执行计作三份独立参考数据。

## 八 检查命令与持续集成

以下是未来仓库的实施要求，不代表已经执行。每个步骤只运行与变化相适应的检查，发布前再跑完整矩阵。工具链与脚本版本固定在仓库中。

日常维护：

```text
moon info
moon fmt
moon fmt --check
git diff --check
git diff --exit-code -- "*.mbti"
```

`moon info` 后先审阅预期接口变更；CI 的接口检查在仓库已包含正确生成文件时执行，不能为了检查通过把所有接口差异直接接受。

核心功能完成后的跨目标检查：

```text
moon check --target native --deny-warn
moon build --target native
moon test --target native --deny-warn

moon check --target js --deny-warn
moon build --target js
moon test --target js --deny-warn

moon check --target wasm-gc --deny-warn
moon build --target wasm-gc
moon test --target wasm-gc --deny-warn
```

native CLI 包需正确声明目标范围；如果工具链要求按包选择构建，脚本显式选择支持的包，不能把正常的 native 专用范围当成核心库跨目标失败，也不能靠全局跳过隐藏核心失败。

对照和验收脚本完成后，拟提供：

```text
python scripts/check_reference.py --manifest testdata/manifest.json --strict
moon run cmd/example --target native
python scripts/check_acceptance.py
```

脚本应实际执行并核对结果，拒绝缺失日志、零测试、未执行案例和过期报告。没有加入脚本的检查不能在 README 中声称由 CI 覆盖。

本次仅编写规划文件，不运行未来项目的代码测试；已有依赖探针和源码归档核验单独记录。

## 九 排期与范围检查

以实际开工日起计算约 10—15 个有效开发日，不虚构当前赛事截止日期。最后三天保留给差异收敛、包与文档，不启动新的算法模块。

| 时间 | 工作 | 阶段判断 |
| --- | --- | --- |
| 第 1—2 天 | Commit 1—4，工程、格式、固定参考和压缩适配 | 有独立格式预期，参考数据能生成，压缩边界可以验证 |
| 第 3—4 天 | Commit 5—6，补丁应用与资源边界 | 上游补丁可在三个运行目标恢复正确结果 |
| 第 5—8 天 | Commit 7—10，索引、匹配、生成与双向对照 | 两个互操作方向通过，生成器真实利用旧数据 |
| 第 9—11 天 | Commit 11—14，生成保护、CLI、CI 和示例 | 核心范围冻结，两个平台 CLI 与示例可运行 |
| 第 12 天 | Commit 15，基准和文档定稿 | 支持声明与实测结果对应，剩余问题已列明 |
| 第 13—15 天 | Commit 16，最终验证、包审计、发布及消费 | 只修复和交付，保留实际安装/发布问题的缓冲 |

第 4 天仍不能可靠应用固定上游补丁时，先解决格式和解压边界，不并行堆叠生成器。第 8 天双向互操作仍有未解释差异时，重新评估排期，暂不投入外围展示。最终三天不追加协议、目录、网络或 GUI。

这是一份估计排期，不能通过减少核心正确性要求来凑齐日期。两周可提前完成的条件是核心、测试和分发证据均已经齐备，而不是只完成演示。

## 十 风险与处理方式

| 风险 | 处理方式 |
| --- | --- |
| 源码下载不可用或被替换 | 锁定原始归档哈希，使用可核验镜像，下载失败与哈希不符都停止参考生成 |
| 原版 C 的错误检查不足 | 合法输入用作兼容参考，损坏输入按独立安全契约验证 |
| 符号幅值当作补码读取 | 独立编码向量、负零和幅值边界测试 |
| 负位移或旧区间外读取处理错误 | 锁定参考语义，构造人工补丁，验证零贡献及安全偏移 |
| 自往返隐藏两边相同错误 | 双向实际互操作，独立格式解析和原始目标字节比较 |
| 后缀排序对重复数据退化 | 完整后缀数组预期、重复串案例、工作计数与规模基线 |
| 生成器变成完整新文件压缩 | 检查可复用样例的控制结构、差分与大小，不以单纯可恢复判定完成 |
| bzip2 包忽略尾随数据或未落实限制 | Commit 4 单独验证消费和结束能力，缺口有记录后修复，不凭 API 名称推断 |
| 缓冲区和解压占用超预期 | 分配前限制、解压总量和实际资源记录，明确完整缓冲区模型 |
| CLI 写失败破坏现有文件 | 独占临时文件、不覆盖交付、同文件检查、失败清理测试 |
| 用户误以为补丁会验证旧文件身份 | 文档明确 BSDIFF40 无内置文件哈希，示例展示外部完整性校验 |
| 测试或发布证据与最终源码不一致 | 记录源码 SHA、CI SHA、包哈希和注册表版本，发布后文档分开记账 |

## 十一 申报摘要与验收材料

### 一页申报摘要草案

> MoonBSDiff 拟参考 BSDiff 4.3，以 MoonBit 实现兼容 BSDIFF40 格式的二进制差分与补丁应用库。首版提供根据旧、新数据生成标准补丁，以及结合旧数据和补丁恢复目标数据的能力，并提供 native 命令行工具、最小库调用和 Wasm 模块更新示例。核心覆盖后缀数组索引、匹配扫描、控制指令、差分字节、格式封装及明确的错误和资源限制，bzip2 复用现有 MoonBit 依赖。通过固定版本上游的双向互操作、异常回归和 native/JS/Wasm-GC 测试验证，最终发布到 Mooncakes。项目采用 BSD-2-Clause，保留上游及依赖来源，明确完整缓冲区处理方式与 BSDIFF40 不内置文件哈希的边界。

实际申报时填写真实仓库链接、人员信息和已经确认的范围。此摘要使用计划语气；完成后按实际事实改写，不预填实现、CI、发布和消费结果，也不额外要求主办方没有要求的验收表格。

### 最终交付清单

1. 公开独立 GitHub 仓库，默认分支包含成果，保留可追踪的实质提交。
2. 实际验证的 MoonBit 工具链，编译器不低于主办方要求。
3. diff/apply 的真实库接口、native CLI、格式与错误契约。
4. README、API 文档、支持范围、资源限制和旧文件完整性说明。
5. 固定上游归档及哈希、移植映射、参考构建信息和所有第三方来源。
6. 核心、边界、随机和双向互操作结果；案例数、目标数及跳过分别记录。
7. 覆盖检查、构建、测试、示例的成功 CI，结果对应最终源码提交。
8. 最小库调用与可由自有源码重建的 Wasm 更新演示。
9. 实际发布的 Mooncakes 版本及仓库外注册表消费者调用记录。
10. 根许可证、依赖许可说明、真实基准和包审计材料。

### 九项验收要求对应

| 主办方要求 | 本项目交付 |
| --- | --- |
| MoonBit 主体，moonc 不低于 0.10.16 | MoonBit 核心，初始固定验证基线 0.10.19 |
| GitHub 公开、记录清晰 | 独立仓库与按实质功能组织的开发历史 |
| 结构清楚、核心完整 | 格式/应用/生成/IO 分层，diff 与 apply 完整 |
| README 可复现 | 安装、API、CLI、示例、范围及错误说明 |
| CI 覆盖检查、构建、测试 | 分目标和分平台执行，拒绝漏跑与零测试 |
| 至少一个可运行示例 | 最小库调用与 Wasm 文件更新示例 |
| 核心路径完整测试 | 功能矩阵、异常、随机与独立双向互操作 |
| 发布到 Mooncakes | 实际发布和独立目录安装调用证据 |
| OSI 认可许可，符合上游要求 | BSD-2-Clause，保留上游及依赖许可和来源 |

## 十二 首版完成判断

MoonBSDiff `0.1.0` 的完成标志是：外部 MoonBit 项目能够安装已发布版本，调用 diff 生成真实 BSDIFF40 补丁，调用 apply 恢复预期新数据；与固定上游的两个互操作方向均有独立证据，声明范围内的失败有明确错误和资源边界，CLI、示例、README、许可证、包与最终源码 CI 一致。

16 个步骤是实施顺序，不是自动完成清单。只有依赖探针通过、只能应用补丁、只有自往返、仅候选包可安装或仅文档齐全，都不能单独称为首版已经完成。后续版本依据实际使用需要安排，不为验收追加无关平台和展示功能。