# MoonBSDiff 仓库规划与实施状态

## 0.4.0 发布收尾（2026-11-16）

已正式发布：源码与 tag `e39e66f1270c0f4e37cb14fcfc5739edc46d1798`，Mooncakes 0.4.0 与两平台 CLI 同源，源 CI 43877720043 六任务通过。公开包/附件重下载一致，Windows 注册表三目标消费通过；Linux 本地注册表索引连接重置，仍未完成，不能用 Linux 候选或 CLI 验证替代。发布后文档记录独立于冻结源码，详见发布说明及 testdata/release/0.4.0.json。历史身份保留，功能扩展停止。

功能扩展冻结于 `4e9dbe84b4fd67d8e876788767ae1eb1e1236187`。Commit 17—27 的已实现范围统一整理为 0.4.0，未独立发布的 0.3.0 内容并入；库与两平台 CLI 必须对应同一发布源码。此后仅进行版本、候选包审计、仓库外消费、发行归档和发布身份核对，不重跑本地旧全集。历史记录及其 Unreleased 描述按原实施日期保留；正式状态以[0.4.0 发布说明](release-0.4.0.md)、注册表及正式 Release 为准。既有 0.1.0、0.2.0 身份不变；不新增功能。

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

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

以下历史记录截至 Commit 16 发布后验收；新增的 [0.1.0 之后的功能规划](#010-之后的功能规划2026-11-12-补充)列出后续待实施能力。原规划中的预计时间、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 16 发布后记录（2026-11-12）

发布源码固定为 `156f461d7d9bba589b5f78020945a6d4e714b578`，[对应 CI](https://github.com/BigSaltyMan/moonBSDiff/actions/runs/43178018685) 四项任务成功，含 142 native 测试、既定双向 138 次恢复、两平台 CLI、示例和三目标候选消费。正式上传返回 200 OK，公开包 326294 字节、179 文件，SHA-256 为 `d16972902120bc971a118f927cd15612cd0aaf79cc0b48bf8561c9604a8fab63`。Windows 仓库外全新 SDK 缓存实际安装 0.1.0，并在 native、JS、Wasm-GC 调用 diff/apply；所有包成员及恢复字节核对一致。Linux 本地索引获取连接重置未记为注册表消费成功；CI 的 Linux 源码/CLI/候选证据与其分开。

这是发布后的独立文档记录，不属于已上传源码，不改变发布身份。未创建 tag 或 GitHub Release，未扩大冻结范围；详情和完整哈希见 [发布记录](release-0.1.0.md)。

## 后续状态

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

## 0.1.0 之后的功能规划（2026-11-12 补充）

本节是基于已发布 0.1.0 的后续产品规划；Commit 17—22 已实现于 GitHub CLI 0.2.0 发行流程，Commit 23—25 已提供 0.3.0 Unreleased 显式规模策略、索引复用及压缩选项，Commit 26 已提供 0.4.0 Unreleased 文件式应用，Commit 27 已完成文件式应用进度与取消，其他阶段未实现；Mooncakes 0.2.0 未发布，GitHub 正式发行身份以 v0.2.0 Release 与对应成功 CI 为准。它不改写下方首版原规划，不改变 0.1.0 的源码、包哈希、兼容性声明或历史验收结果。版本号是建议的目标分组，不是发布日期或已发布承诺；每组达到完成条件后再确定实际版本。

规划补充时最明显的使用障碍是：CLI 生成默认仅支持 64 KiB 输入且没有限额参数（Commit 17 已提供显式覆盖，默认值和规模保证不变）；补丁缺少便于查看的信息和绑定旧文件身份的产品流程；Linux 输出依赖 O_TMPFILE 与 /proc；使用 CLI 仍需自行配置编译环境。先解决这些问题，再扩展规模和高级 API。判断来自当前 [CLI](cli.md)、[生成资源](generation-resources.md)、[公开接口](../pkg.generated.mbti)和[发布记录](release-0.1.0.md)，不是新的功能验证。

### 实施规则与版本顺序

- 继续生成标准 BSDIFF40，保留已有 diff/apply 和显式 Limits 用法。新增能力优先使用可选参数、独立接口或外层清单，不把自定义头部塞进 BSDIFF40。
- 0.1.0 已冻结；新功能放入后续版本，不覆盖 Mooncakes 0.1.0，不移动既有发布身份。新公开 API 的最终名称以实现时的接口审查为准，下面的名称只是设计目标。
- 本地只测试新增或实际改动的功能；复用已通过的旧案例和最终 SHA 的 CI，不为规划、文案或无关功能重跑历史矩阵。现有 CI 门禁保留；改动确实影响旧行为时才补直接相关回归。
- 编号延续 Commit 17 起，方便逐步生成执行 prompt；按实质变化提交，可以合并紧密相关步骤或增加必要修复，不按提交数量验收。
- 原补充只包含规划；后续按步骤记录实际实施状态。未实施条目、变更依赖、构建发布资产及发布新版本，仍须对应执行任务授权。

| 优先级 | 建议目标 | 功能 | 为什么先做 |
| --- | --- | --- | --- |
| P0 | 0.2.0 | CLI 限额参数、inspect/JSON、哈希清单、verify/校验恢复 | 让现有库更容易用于真实文件，及时识别选错旧文件和损坏补丁 |
| P0 | 0.2.0 | Linux 文件交付兼容路径、Windows/Linux CLI 下载包 | 减少文件系统和本地编译环境的使用门槛 |
| P1 | 0.3.0 | 分级扩大生成规模、旧文件索引复用、压缩级别选择 | 处理更实际的文件和多版本分发，并提供可测量的成本选择 |
| P2 | 0.4.0 评估 | 文件式增量应用、进度与取消 | 在格式和工作区约束明确后改善大文件内存占用及长任务体验 |

Commit 17—22 已实施于 GitHub CLI 发行；Commit 23—25 已实施于后续源码能力，Commit 26 已实施于 0.4.0 Unreleased，Commit 27 已实施文件式应用范围，其他阶段未实施。每一步只做自己的功能和必要文档，不提前堆叠整条路线。

### Commit 17 CLI 限额参数与有效配置显示（P0）

**修改位置：** cmd/main/、参数解析与文件读取适配、CLI 文档。

- 为 diff/patch 提供显式大小和工作额度参数，至少覆盖旧文件、新文件或恢复输出、补丁、展开数据、控制指令及生成工作；选项名和各子命令适用范围实现前统一设计。
- 支持无歧义的字节单位，明确 B、KiB、MiB 的含义；拒绝负数、零、溢出、未知单位、重复冲突选项及不适用参数。不能用 0 或负数开启无界模式。
- 提供查看有效配置的方式，显示实际采用的上限和生成/应用策略，方便用户解释超限错误。
- 默认行为沿用 0.1.0；用户提升文件上限时，其他独立配额仍然生效，不暗中同步放大，也不把输入尺寸以内解释为一定成功。
- 文件读取上限和核心 Limits 使用同一份解析配置，防止 CLI 先读入超大文件后才由核心拒绝。

**只验证新增行为：** 默认命令保持兼容；一个显式配置的成功案例；非法参数拒绝；一次真实文件超过配置上限的拒绝。复用旧文件交付测试，不重跑 CLI 全集。

**完成条件：** 用户可以明确控制资源范围并看到有效配置；CLI 与核心限制一致，错误可定位。

**Commit 17 实施记录：** 基线 `2fe843a3fcc6002741e6fb3fcfba66190e763f4e`。新增八项 CLI 限额覆盖和无文件参数的 `--show-limits`，严格正十进制及 B/KiB/MiB 检查；先解析并验证，再将同一配置传给受限读取与 diff/apply。patch 拒绝排序/匹配参数。Windows/Linux 新增集合各 5 项、38 次 CLI 调用通过，无跳过；未在本地重跑旧 CLI/IO、库、互操作或资源矩阵。保留 C 文件交付、库默认工厂、根 .mbti 和依赖。本节原有 Commit 17—27 规划随实现提交入库。CI 复用现有两平台 CLI 构建，只追加限额集合；最终 SHA 的实际远程结果在完成报告核对，不预填成功。后续版本目标 0.2.0，未发布、不移动 0.1.0 身份，不实施 Commit 18。

### Commit 18 补丁 inspect 与结构化 JSON 输出（P0）

**修改位置：** 格式信息的只读内部入口、cmd/main/、CLI 文档。

- 提供 inspect PATCH 和可选 JSON 输出，展示格式、实际补丁大小、声明恢复大小、三个压缩区间的位置及长度。
- 首版 inspect 默认只解析文件头和区间，明确标为 header-only。它不证明 CRC、控制合法性、旧文件身份或能够成功恢复。
- 后续如加入深度统计，复用受限解压和控制检查，给出差分/新增字节量、指令数量与完整消费状态；未执行的统计输出 null 或明确状态，不能填 0 冒充已检查。
- JSON 有 schema_version 和稳定字段语义，机器结果与诊断分离；不把未定位的偏移伪装为 0。
- 不要求用户安装 Python，也不把内部调试结构直接全部公开为稳定 API。

**只验证新增行为：** 一个合法头部、一个非法头部、空目标补丁和 JSON 字段/校验层级。已有整数与封装测试直接复用。

**完成条件：** 用户和脚本可以查看补丁结构，且不会把浅层检查误认为完整验证。

**Commit 18 实施记录：** 基线 `deed05893b43bab73469e61c3fd163ac7f6c238e`。新增只读 `inspect PATCH`，仅支持 `--json` 与 `--max-patch-bytes`，沿用前置选项、`--` 和严格大小解析。默认补丁读取上限 128 KiB。结构检查复用一个内部 parse_envelope，原 apply 包装保留输出策略；根接口最小增加 inspect_header 和只读 PatchInfo，未复制完整解析器。文本/JSON 明示 header-only 与未执行项，JSON 字节字段均为精确十进制字符串。Windows/Linux 新增集合各 5 项、30 次 CLI 调用通过；Windows native 另跑 7 项原格式回归和 1 项新增公开 API 测试，合计 8 项通过。原固定补丁未重新生成；没有本地重跑旧 CLI 全集、库矩阵、互操作、解压大样本或测量。未解压、未恢复、未验证 CRC/控制/身份。CI 复用两平台 CLI 构建，仅追加 inspect 集合。实际输出、schema、API 原因与边界见 [inspect](inspect.md)。最终 SHA 的远程结果在完成报告核对，不预填成功。0.2.0 Unreleased，不发布、不创建 tag、不进入 Commit 19。

### Commit 19 外部 SHA-256 清单生成（P0）

**修改位置：** 独立清单模块、cmd/main/、清单格式文档及示例。

- 为生成流程增加可选旁置清单，记录 schema_version、BSDIFF40 格式、旧文件/新文件/补丁的字节数及 SHA-256，以及生成工具版本。
- 补丁本体保持标准 BSDIFF40，清单不与其拼接，不影响上游 bspatch 使用原始补丁。
- 散列必须针对实际交给 diff 的输入和实际生成的补丁，不能先 hash 一个路径、再重新读取可能已变化的文件来生成补丁。
- 清单中的路径仅用于显示，不自动驱动读取、写入或目录遍历。解析也受大小、字段和整数限制。
- 清单和补丁分别遵守不覆盖交付规则。双文件交付不是跨文件事务；失败时准确报告已交付内容，清单未完成不得声称更新包已完整生成。
- SHA-256 用于内容一致性，不证明发布者身份；若攻击者能同时替换清单和补丁，普通哈希清单不能提供真实性保证。可信预期应来自可信发布渠道，签名方案后续另行评估。

**只验证新增行为：** 固定内容的独立哈希预期、清单字段和错误哈希、文件变化使用同一输入数据的约定、两个输出之一交付失败的准确报告。

**完成条件：** 用户能够取得与实际旧、新、补丁内容绑定的外部清单，不改变 BSDIFF40 兼容性。

**Commit 19 实施记录：** 基线 `d61cd52b506416513920bb2dd6ad758bf5589172`。新增仅用于 diff 的可选 --manifest PATH；使用同一份受限读取的 old/new Bytes 和返回的 patch Bytes 生成 schema 1，十进制字符串大小、完整小写 SHA-256、实际构建版本，不记录路径/时间戳。复用现有传递依赖 mooncrypt 0.4.7 的 SHA-256，补为固定直接依赖并核验 Apache-2.0；未复制算法或增加 IO 依赖。两输出先预检，新增只读父目录身份/文件名别名比较；原交付函数未改写，先补丁后清单，非跨文件事务，部分失败保留补丁且明确报清单未完成。Windows/Linux 新增集合各 5 项通过（22/19 次 CLI 调用，无跳过），两个 native 主机各通过 1 项新增哈希单元；旧 IO runner 显式选中原 io_wbtest 文件，避免把新哈希测试计入原 9 项 IO 契约。本地未重跑旧 CLI/IO、库矩阵、互操作或测量。根 .mbti 与默认工厂不变；真实清单与信任边界见 [manifest](manifest.md)。CI 复用既有构建，只追加清单集合；最终 SHA CI 在完成报告核对。不发布、不创建 tag，不实施 Commit 20。

### Commit 20 verify 与校验后交付（P0）

**依赖：** Commit 19。**修改位置：** cmd/main/、清单校验流程、文件交付适配。

- 提供 verify OLD PATCH --manifest MANIFEST 一类验证入口：检查清单结构、旧文件和补丁身份，受限应用后核对预期新文件大小及 SHA-256。
- patch 增加可选清单验证：旧文件或补丁不匹配时尽早拒绝；恢复内容满足预期后才交付最终输出，校验失败不留下伪成功文件。
- 验证与执行使用相同输入字节或受控句柄/快照，避免 hash 后重读导致检查与实际应用脱节。
- verify 不创建最终输出文件，但第一版可继续采用现有内存 apply；不能把它宣传成无需恢复数据或流式验证。
- 未带清单的原始 patch 用法保留，并继续说明其不能可靠识别旧文件选错。

**只验证新增行为：** 正确清单；错误旧文件；被修改的补丁；错误恢复预期；失败不交付。复用现有文件写入和 apply 检查。

**完成条件：** 可选校验流程确实约束实际输入和最终交付，用户能明确区分格式合法、内容一致及来源可信。

**Commit 20 实施记录：** 基线 `bdeaccd561e55a007283b08d2bd522791df851a8`。新增 verify --manifest OLD PATCH 与可选 patch --manifest，复用同一核验流程和 mooncrypt 0.4.7 SHA-256。清单固定 16 KiB 受限读取、JSON 深度 8，标准解析器在解析时拒绝所有重复键（含转义等价），未知字段也拒绝；严格字段类型、非负 Int64 十进制字符串大小和完整小写哈希。先验证声明额度，再读同一 old/patch Bytes、核对身份和头部、真正 apply、核对恢复大小/哈希。verify 无最终输出；带清单 patch 全部通过才调用原不覆盖交付，额外预检输出与清单身份。复用并固化 Commit 19 的原始微型样例，未重新生成补丁。Windows/Linux 新集合各 5 项、44 次调用通过，无跳过；未在本地重跑旧 CLI/IO、库、互操作或测量。根 .mbti、默认工厂、依赖和 native IO 均不变；原 Commit 19 的 patch 参数不适用断言调整为缺值断言。CI 复用构建仅追加新集合，最终 SHA 的实际结果在完成报告核对。0.2.0 Unreleased，不发布、不创建 tag、不进入 Commit 21。

### Commit 21 Linux 文件交付兼容路径（P0，能力验证通过后实现）

**修改位置：** native IO 适配、CLI 平台说明。

- 保留当前匿名临时文件路径，评估在没有 O_TMPFILE 或 /proc 时的安全替代；目标是扩大实际可用文件系统，而非直接放宽失败处理。
- 候选路线包括同目录私有临时目录/独占文件、目录句柄锚定和真正不覆盖的交付原语。逐项确认目标文件系统、权限、清理和竞态语义。
- 禁止以 exists 检查加普通可能覆盖的 rename 作为替代；不按未经约束的用户路径删除临时文件；不能回退为直接截断最终输出。
- 若无法在明确威胁模型下保持原有保证，就继续明确失败，不添加危险回退。只在实际通过的文件系统声明支持。
- macOS、网络文件系统与断电持久性不因该功能自动获得支持或保证。

**只验证新增行为：** 强制走兼容路径的正常交付、目标竞态和临时对象替换/清理；选择一个实际不支持当前匿名路径的环境验证。旧平台主路径不重复整套测试。

**完成条件：** 至少一个新增场景真实可用，并保持不覆盖和安全清理约定；否则记录阻塞与保留旧行为。

**Commit 21 实施记录：** 基线 `1dc691b2f8ea4db05f225f88396d8fdf3665dc43`。保留匿名 O_TMPFILE+/proc 主路径，只有写入前明确能力缺失才选择受限兼容路径；权限、磁盘或写入/关闭错误不换路重试。兼容路径限本地 ext 权限语义（实际验证 ext4），可信所有者/受保护父目录内独占 0700 私有目录与 0600 文件，持有描述符，写入关闭确认后 linkat 不覆盖交付。依靠权限/命名空间不变式保障清理，不把单次 inode 比较声称为无竞态；异常身份保留并报告，交付后错误不删最终文件回滚。同 UID 恶意控制/root 与所有恶意父目录不在该路径保证内。新增 Linux-only 私有测试 2 组、18 场景通过；WSL2 ext4 私有挂载命名空间内普通 UID1000、能力0、真实 /proc/self/fd 缺失时，无产品钩子的带清单生成/校验后 patch/verify 3 调用字节一致且无临时残留，宿主挂载未变。Windows 路径、根接口、默认值及依赖不变，未本地重跑旧集合。CI 复用原 Linux 构建，增真实隔离验证；最终 SHA 结果在完成报告核对。见 [设计与证据](linux-delivery.md)。0.2.0 Unreleased，不发布、不创建 tag、不进入 Commit 22。

### Commit 22 可下载的 Windows/Linux CLI（P0）

**修改位置：** 发布构建配置、资产清单、安装与使用说明。

- 为实际构建和验证的 Windows AMD64、Linux x86_64 提供 CLI 归档、SHA-256、对应源码 SHA、工具链及必要许可证，不把源码包或测试二进制冒充用户发行资产。
- Linux 明确构建环境、libc/系统接口基线及文件系统条件；未经验证不标为通用 Linux、静态无依赖或可在所有发行版运行。
- 不让用户为了运行预编译 CLI 再安装 MoonBit、Python 或 C 编译器；若仍有系统运行库前提，准确列出。
- 安装说明只涉及解包和用户选择的位置，不默认提权，不自动修改全局 PATH。Mooncakes 库发布和 CLI 二进制发布分开核对身份。
- 不回写或覆盖 0.1.0 的发布包；针对包含这些功能的后续版本形成源码、构建与资产对应关系。

**只验证新增行为：** 每个平台从发行归档解包后运行 help/version 及一个小型文件往返，检查资产哈希和真实运行依赖，不重跑全部 CLI 文件用例。

**完成条件：** 用户能从正式后续 Release 下载、核对并使用对应平台 CLI，资产与已验证源码一致。

**Commit 22 实施记录：** 基线 `f1c93b37bb098b1326137e0059feec19ddd929e0`。模块与生成 CLI 元信息统一为 0.2.0；新增干净 SHA 的 Windows AMD64/Linux x86_64 native release 归档、实际 DLL/ELF/glibc 依赖检查、解包后 help/version 与一次带清单恢复校验。CI 复用原两平台环境，仅增加发行路径，汇总任务严格绑定同一源码与归档/可执行文件哈希，生成 SHA256SUMS 和 build-info.json；普通 push 不发布。版本相关候选源码包审计改读实际 module version，公开 0.1.0 注册表消费流程和历史证据不变。本地只验证新增脚本与版本/格式，不重跑旧矩阵。正式 tag、资产和最终成功 CI 在完成报告核对，不在源码中预填自身 SHA；此记录本身不是上传成功凭据。Mooncakes 0.2.0 未发布，根接口、算法、默认配置及依赖不变。见 [CLI 安装与构建](cli-install.md)。不进入 Commit 23。

### Commit 23 分级扩大生成文件规模（P1）

**修改位置：** 索引/匹配资源策略、Limits 配置、规模说明。

- 在显式限额可用后，以 256 KiB、1 MiB 为候选阶段评估更实际的生成规模；4 MiB 及以上仅在前一阶段有足够资源证据后评估，不提前承诺支持。
- 优先用真实计数定位排序、扫描、编码和复制开销，必要时优化对应热点；不能只增大 max_sort_work/max_match_work 后宣传性能提升。
- 给出时间、实际取得的内存数据和缓冲区上界推导，区分进程时间、核心时间、采样 RSS 与可靠峰值。
- 先提供有说明的显式策略；是否调整默认 64 KiB 范围取决于测量，不强迫所有调用者承担更大的默认资源消耗。
- 不同大小、重复度或编辑类型可能触及不同额度，不把成功处理一个样本写成该尺寸所有输入都保证成功。

**只验证新增行为：** 每个新增规模选少量代表输入，验证完整恢复与边界；只对修改的算法补相关回归，不复制全部旧矩阵。

**完成条件：** 新规模有明确配置、资源证据与实际恢复记录，旧默认和限制语义保持可解释。

**Commit 23 实施记录：** 基线 `59f9cada166db39c4d14fbd905c3ba80fa7d72ed`。先完成 256 KiB 再评估 1 MiB，各 3 组确定的稀疏/周期/独立 LCG32 随机输入；首次有界候选额度均通过，六组实际生成/恢复逐字节一致、输入不变。保留 64 KiB 默认，交付完整显式 Limits 与配套应用额度；没有修改算法、预算、格式、压缩级别、文件交付、公开接口或依赖。native release 记录原始计数、分项推导、块/补丁大小、核心生成/应用与完整调用时间，GNU time 调用最大 RSS 与未测 API 峰值明确区分。低排序额度完整错误断言和失败后新 public 调用通过；两级随机案例各用正式 CLI 一次生成/恢复，显式补丁读取上限、完整字节与独立哈希核对通过。机器策略、六组测量与两组 CLI 证据见 testdata/generation/scale-*.json 和 scales.json。测量在字节相同的生产源码快照中仅添加 wbtest 时钟/哈希引用，不改根配置；固定清单可离线检查，重放拒绝覆盖用户输出。新增 CI 仅一个 Linux native 任务顺序执行这些新规模，不设绝对时间门槛；最终 SHA 的 CI 在完成报告核对。JS/Wasm-GC/Windows 大规模、4 MiB+、旧矩阵和历史测量未重跑。新内容为 0.3.0 Unreleased，不改写 v0.2.0 发行身份、不发布 Mooncakes、不创建 tag、不进入 Commit 24。见 [规模与策略](generation-scales.md)。

### Commit 24 可复用旧文件索引（P1）

**修改位置：** 索引封装、生成入口、必要公开 API。

- 为同一旧版本生成多个目标版本补丁提供受控索引对象，例如 DiffIndex::build 与基于该对象的生成入口；最终名称以 API 评审为准。
- 对象绑定确切的旧数据及索引，复制或持有不可被调用者修改的内容，避免旧字节变化后继续错误复用。
- 构建阶段单独检查输入、排序和保留内存额度；每次生成拥有独立匹配/编码预算。复用意味着不重复排序，不意味着可以绕过构建成本或取消其他限制。
- 说明索引生命周期和保留内存；不承诺尚未验证的并发安全，不提供无界全局缓存。
- 保留现有 diff 便捷入口，单次调用继续自行管理临时状态。

**只验证新增行为：** 同一旧数据生成两个目标、与单次 diff 的恢复结果一致、调用者输入修改隔离、失败后对象复用和配额独立。

**完成条件：** 多目标场景实际减少重复索引构建，行为与普通 diff 一致且保留资源边界。

**Commit 24 实施记录：** 基线 `1995c5934ec7c08b714e68fbf68d4cf7dae49406`。新增字段私有的 DiffIndex，build 验证配置/旧大小后复用现有后缀构建，排序在整个构建中累计；对象仅保留安全 API 下不可变 Bytes 与最终 SA。每次 diff 重新验证旧/新/输出/补丁/原始大小等额度并新建匹配生成预算，不重新排序或保存剩余额度。普通 diff 保留签名、预排序检查和原有预算语义；抽取共用预检及匹配/编码/封装函数，没有改变排序、匹配、格式或压缩算法。native/JS/Wasm-GC 各 5 项新增黑盒紧凑测试通过，覆盖多目标恢复、普通 diff 对照、确定性、安全 Array 别名、精确额度/差一单位失败/恢复、各次大小限制、空旧与空目标；一项 native 普通累计预算关联回归通过。可运行的 JS 示例构建一次索引恢复两个目标。根 .mbti 仅新增 DiffIndex 和两个方法，无公开数组、预算或调试计数器。历史大规模记录改按其原始 Git 提交核验，CI 普通 push 不重测大规模，显式 workflow_dispatch 才重放；此变更不将旧测量冒充当前代码证据。默认工厂、依赖、CLI 产品路径及发布身份不变，未本地重跑旧矩阵、CLI、互操作、资源测量；没有计时加速倍数或并发安全声明。完整接口、内存持有和目标证据见 [索引说明](diff-index.md)。0.3.0 Unreleased，不发布、不创建 tag、不进入 Commit 25；最终源码和 CI 身份在完成报告核对。

### Commit 25 压缩级别与生成选项（P1）

**修改位置：** 生成选项、压缩封装、CLI 与 API 文档。

- 提供清晰的生成选项，首先只增加 bzip2 level 1..9，默认继续为 9；非法值直接拒绝，不静默钳制。
- 保留原 diff 的默认行为，以新增选项入口实现兼容扩展，不把 Limits 混成算法偏好配置。
- 对级别对应的块工作区、输出排放和资源计费重新给出依据；不能只改参数后继续引用 level 9 的全部测量结论。
- 用相同小型输入展示生成时间与补丁大小的实际取舍，不承诺低级别一定更快或高级别一定更小。
- 不同时加入多种压缩算法或改变 BSDIFF40 三条 bzip2 流的格式。

**只验证新增行为：** 级别边界和非法值、默认 9 保持兼容、代表性非默认级别的外部应用及资源检查。

**完成条件：** 用户可以明确选择压缩级别，生成仍可被标准 bspatch 应用，默认调用不变。

**Commit 25 实施记录：** 基线 `87ed02b98a81d23317c38486852a90792b9f435b`。新增独立 DiffOptions(compression_level 1..9，默认9)、普通与索引 diff_with_options；原签名转到同一实现，构建索引无压缩选项。非法级别在排序/扫描/编码前返回结构化 Configuration/compression_level 错误，不依赖 Writer 钳制。三个流统一有效级别，保留共享预算与输出限制。CLI 仅 diff 接受 --compression-level，严格正十进制、重复/缺值/不适用拒绝；--show-limits 单列生成选项，与 manifest/限额/-- 正常组合，schema1无新字段。固定Writer/引擎哈希复核不变；按100000*k块阈值与单次RLE增量小于最小阈值证明每次至多一块，沿用level9保守排放上界，不混用其他级别测量。native/JS/Wasm-GC各3项紧凑API通过；Windows/Linux各3项新增CLI、各20次调用通过，原默认补丁与固定Commit19二进制逐字节相同。一项旧native累计预算关联检查通过。native单目标模板独立导出1..9小案例，Python核对三流级别、CRC、EOF及全部消费；100010字节周期新数据level1实际解码块数control/diff/extra=1/0/2，补丁1038字节，不扫描魔数计数。缓存且核验的真实bspatch恢复level6小样及level1跨块样，未本地重建oracle。level1/6/9定稿单样本生成61.617/22.663/22.713微秒、补丁均169字节，明确冷启动顺序与噪声，不宣称优劣；内存峰值未测。CI复用既有目标任务，仅Linux参考任务执行新增跨块和两例外部校验；新内容为0.3.0 Unreleased，默认工厂/依赖/schema/发行身份不变，不重跑历史矩阵、测量或大型压缩探针，不发布、不创建tag、不进入Commit26。见 [选项与证据](generation-options.md)，最终源码与CI在完成报告核对。

### Commit 26 文件式增量应用（P2，先设计再实施）

**修改位置：** 独立 native 文件应用层、增量解压接口、输出交付。

- 保留内存 apply，为大文件评估另一个文件接口：旧文件按受控位置读取，新文件逐段写入临时输出，最终校验后交付。
- 三个压缩区间分别维护读取位置和真实流结束状态，支持负 seek 与旧范围外零贡献；保持每块/整流 CRC、严格单流及完整消费策略。
- 必须先具备真实可暂停的受限解码，不能每次重复解压完整前缀，也不能把已全部解压进内存的输出分片写盘后称为流式。
- 累计解压、指令、读写量和输出额度跨全部分段生效；块工作区与固定复制仍需说明。输出末尾验证成功前不交付最终文件。
- 此步骤只评估流式应用，不承诺流式生成、常量进程内存或严格超时。若依赖能力不足，先记录缺口和最小适配方案，不顺势重写整个压缩引擎。

**只验证新增行为：** 分段边界、负 seek、流尾 CRC、累计预算和写入中断；以一个内存 apply 已验证的输入作为结果对照。

**完成条件：** 能证明内存保留主要受块/分段策略约束，而非恢复文件总大小，并保持既有格式与交付保证。

**Commit 26 实施记录：** 基线 `7393ead3c96a3d7ad50b276ffeb317d968c9f89b`。先验证固定工具链的 native 回调和受限暂停解码，再增加显式 patch --stream。按区间独立读取压缩输入、旧数据绝对位置和临时输出均最多4096字节；共享原有块变换，最终RLE以pending run续读，不保留整流展开或恢复总数组。三流共享累计展开预算，控制数量、目标/输入上限和游标溢出检查保留；全部CRC、结束、完整消费和输入关闭完成后，复用Windows/Linux既有交付函数的关闭与不覆盖发布。拒绝stream+manifest，不扩大并发输入快照或进程峰值保证。Windows/Linux各5组新增文件检查（完整通过各41次调用；最后增加短控制断言与限额诊断收紧后，各仅定向2组通过，最终全集42次由CI验证），16/128KiB独立恢复与内存apply一致；长RLE、三流CRC/截断/尾随、极值、额度和拒绝交付验证通过。新增私有交付组Windows1项/Linux2项，覆盖短写/中断/关闭/发布/竞态/清理/后续调用与Linux强制兼容。共享拉取探针native/JS/Wasm-GC各1项，直接关联压缩紧凑各4项；纯前缀与原格式native共8项。根接口仅增加纯inspect_header_prefix以复用封装检查；适配补丁/哈希/许可来源同步，依赖与默认工厂不变。保留0.3.0记录，未本地重跑旧CLI/IO全集、库矩阵、互操作、历史大样本或测量。内存数据为可审查逻辑缓冲边界，RSS和峰值未测；不发布、不创建tag、不进入Commit27。实际源码与最终CI在完成报告核对，见[文件式应用](file-apply.md)。

### Commit 27 进度报告与协作取消（P2）

**依赖：** 先固定可计量的阶段和调用状态；如结合 Commit 26，可优先对文件式应用提供。

- 在索引、匹配、压缩和写入等明确边界报告进度，记录阶段与已处理量；不能用不存在的总工作量伪造精确百分比。
- CLI 进度写 stderr，可选 JSON 事件；stdout 的机器结果不被破坏。默认保持安静，不按每字节调用回调。
- 取消属于结构化失败，不返回部分补丁或交付部分新文件。预算、临时对象和索引复用状态按实际所有权清理。
- JS 主线程同步调用不会仅凭增加回调自动获得异步可取消能力；需要分步执行或 Worker 等独立设计后才能声明相应支持。
- 取消只在协作检查点生效，不宣传能打断任意 bzip2 内部计算或提供严格墙钟截止。

**只验证新增行为：** 一个正常阶段序列、一个可定位的中途取消、输出未交付及后续调用正常。

**完成条件：** 用户能观察实际进度并在支持的检查点取消，状态和输出约定明确。

**Commit 27 实施记录（仅文件式应用）：** 基线 `352750ee4718dd93cea4f56c8f70fd3e5d52c8bd`。仅为 patch --stream 增加 --progress text|json，默认成功安静，全部进度及运行诊断写stderr，JSON逐行schema1、字节十进制字符串。报告已完整写入临时对象的字节，64KiB阈值及阶段变化节流；最终验证、关闭、提交准入与不覆盖交付结束后才报告完成。独立操作状态及代际标记的native通知，Linux SIGINT、Windows Ctrl+C/Ctrl+Break处理器只通知，正常路径在控制/拉取/旧读取/写入/最终检查/提交前确认取消，返回130；不以EOF冒充取消。原子或屏蔽信号的最终准入区分交付前后，不回滚最终路径，记录真实publication与清理诊断。Windows/Linux各4组新增正常协议检查通过；私有检查覆盖写入中取消、关闭警告、竞争目标前取消、准入后成功/交付失败及同进程重用，Linux额外核对屏蔽期间pending SIGINT。真实中断分别向受控子进程发SIGINT和独立控制台组CTRL_BREAK_EVENT，通过4096字节处取消、未交付本次文件、临时清理及后续同进程恢复。根接口、默认值、依赖、复制解码源码不变；未重跑本地旧CLI/IO全集、矩阵、互操作、测量。生成器/JS异步/立即中断/墙钟截止未实现；保留0.3.0、0.4.0 Unreleased和既有发行身份。详见[协议与证据](file-apply.md#progress-and-cooperative-cancellation-commit-27)，最终源码与远程CI由完成报告核对，不发布、不创建tag、不扩展后续功能。

### 暂不列为必需功能

目录同步、自动更新服务、HTTP/SSH 传输、GUI、安装器、其他补丁格式、并行生成、签名体系和跨文件事务暂不进入本轮必需清单。它们需要独立用户场景、格式/身份设计及依赖评估，不能因补充规划而自动启动。macOS、浏览器 Worker 和更多架构也只在有实际构建与运行证据后增加支持声明。

0.1.0 的 tag/GitHub Release 和 Linux 注册表消费网络重试属于既有交付收尾，不冒充新增产品功能。按当前仓库发布记录，tag/Release 尚未创建，Linux 本地注册表消费未完成；未来实际完成后再独立更新证据。

### 后续版本的验证与发布规则

只为新功能增加定向验证；不机械承诺测试数量，不把三个目标重复执行计作三个独立案例。文档变更只检查内容、链接及差异，不编译或运行旧套件。涉及文件交付、格式或压缩的真实改动，仅补直接相关的旧行为回归。

新版本发布时复用同一最终 SHA 的现有 CI；按实际变化核对包内容和一次精确版本消费，不重测全部历史性能。新增平台资产只做新增平台的必要运行验证。后续每步继续使用 BigSaltyMan 仓库级身份与 github-bigsalty，按对应任务完成实质提交、正常推送和源码/CI 身份核对，不覆盖历史版本、包或 tag。

### 规划依据与查阅入口

- 当前产品事实：[CLI](cli.md)、[生成资源](generation-resources.md)、[0.1.0 发布](release-0.1.0.md)。
- [BSDiff 作者说明](https://www.daemonology.net/bsdiff/)指出参考生成算法依赖后缀排序且有显著内存成本；后续规模目标须另行测量，不能把参考实现的成本公式直接当作本项目实测。
- [Linux rename(2)](https://man7.org/linux/man-pages/man2/rename.2.html)区分普通替换语义与 RENAME_NOREPLACE，并说明后者需要文件系统支持；[link(2)](https://man7.org/linux/man-pages/man2/link.2.html)说明不覆盖链接与相关描述符接口。这里只支持兼容路径的设计评估，不代表本项目已经实现或验证。

---

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

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