# 项目申报书：MoonReconcile 集合差异摘要与恢复库

**项目名称与方向：** MoonReconcile，纯 MoonBit 的集合差异摘要与恢复基础库，面向分布式数据交换与概率数据结构。

**项目简介与必要性：** 当两个节点持有大量相同 ID、仅少量 ID 不同时，通过可相减摘要恢复差异，减少全量清单交换。交付可供 MoonBit 应用直接调用的算法库、可选预算控制模块和示例，业务仍负责传输、内容校验与存储；不以完整同步软件作为项目目标。

**现有基础：** 仓库 0.1.0 已有三分带 IBLT、UInt64 集合去重、差异恢复、MRCL 编解码、分区摘要、有序游标构建及基本重试。现有 48 项测试与四目标 CI；现有基准仅覆盖固定小规模输入，不代表真实负载评估。以下新增内容为拟交付工作，尚未全部实现。

**拟实现功能一——明确核心契约：** 整理构建、增删、相减、解码和序列化接口，区分集合去重与底层代数操作；明确宽度、恢复预算、残留单元和失败语义。IBLT 宽度不等于可保证恢复的差异数量；解码失败不输出可应用计划。验收：公开契约、边界测试，以及应用可独立调用的最小示例。

**拟实现功能二——受预算约束的协商：** 在可选模块中增加跨轮次状态与累计传输账本，限制轮数、实际收发帧总字节数及恢复工作量，固定同一会话的 scope、双方 epoch 与 seed；返回成功、继续或带原因的回退结果。验收：首次成功、扩大摘要、预算耗尽、版本变化及重复帧测试；超限前停止，不自行执行全量传输。

**拟实现功能三——恢复率与成本评估：** 增加不同集合规模、差异数量、表宽和固定多种子的数据集，包含容量不足与密集差异；记录恢复率、残留量、轮次、含重试的累计帧字节及耗时，并与原始 UInt64 清单、同域 minisketch 作对照。验收：可复运行脚本、明确工具链与环境、原始结果及适用范围报告，不预设优于成熟库。

**拟实现功能四——独立接入与发布：** 提供与传输通道解耦的双端交换示例，文档说明稳定 ID 映射、快照一致性、内容验证和回退责任；形成 Mooncakes 发布包。验收：四目标 CI 保持通过，独立消费模块可以安装并运行示例；比较用的外部 minisketch 不成为运行时依赖。

**预期场景一：** 边缘缓存冻结双方对象 ID 清单，交换摘要恢复缺少的 ID，应用验证并拉取内容后更新缓存。
**预期场景二：** 备份客户端比较分区摘要，定位变化分区、恢复差异块 ID，由备份程序确认需补传或复核的块。
**预期场景三：** 离线节点重连时固定索引版本，在会话预算内交换差异，无法恢复时由应用改用全量清单，避免无限重试。

**设计方式与边界：** 参考 bitcoin-core/minisketch 将摘要核心与业务同步流程分离的方式；本期保留 IBLT，不移植 BCH/PinSketch，不兼容 minisketch 格式。仅处理 UInt64 ID 集合；不实现数据库、网络认证、内容下载或业务冲突解决。非密码学指纹与 CRC 不提供身份认证或恶意输入安全保证。

**实施与交付：** 第一阶段补齐核心契约与边界测试；第二阶段交付可选预算控制模块及双端示例；第三阶段完成对照评估、接入文档和 Mooncakes 发布。以测试、可运行示例、原始评估结果和可安装包验收，不以代码行数或提交次数替代功能。

**原创与参考：** 非现有库移植，不主张算法原创；IBLT 参考 Goodrich/Mitzenmacher 论文，minisketch（MIT）用于设计参考和评估对照，未复制其源码。项目采用 Apache-2.0，来源见 NOTICE.md；代码与文档使用 AI 辅助，由参赛者理解、核对并维护。历史生态检索仅作选题参考，不作为独占性或审核通过证明。

**公开仓库：** https://github.com/apoloe4/moonreconcile
**设计与验收细则：** https://github.com/apoloe4/moonreconcile/blob/main/docs/DESIGN_V0_2.md