# 本地工程审查记录（2026-10-01）

> 本文保留发布前的历史审查结果。2026-10-03 的公开仓库、CI 和包发布证据见
> [0.1.0 发布记录](RELEASE_0.1.0.md)。

本记录是本地自查，不代表赛事组验收。依据工作区 `1.txt` 十月章程和 `osc2026-guide` 的本地验收项目检查。命令在 Windows 上的 `E:\Code_Oy\other\MoonBit\MoonErasure` 执行；远端 CI 与发布状态必须在公开仓库建立后另行验证。

## 【1. 总体评价】

核心功能已覆盖系统式 GF(256) 编码、已知分片缺失恢复、CRC 识别损坏、独立帧与清单、跨条带对象、增量处理、范围读取、修复及巡检。项目为 MoonBit 主实现；Apache-2.0 许可、README、六个可运行入口与 CI 工作流已在本地。有效 MoonBit 非空且非纯注释行共 4142 行，其中库实现 2398 行、测试 1545 行、示例 199 行；这不是“库实现超过 4k 行”的声明。历史记录超过 40 条提交，均有可追踪的代码、测试、文档或工程内容。

优先级最高的剩余验收风险是外部状态：当前无 Git remote，`gh auth status` 报全部已配置 GitHub token 失效；因此公开默认分支与最新远端 CI 未验证。`moon publish --dry-run` 的本地打包及解包后检查通过，但连接 mooncakes.io 发布 API 时中断，不能算已发布。十月章程原则上每位参赛者提交一个项目；申请人已有其他项目，应向赛方确认额外项目的申报资格，并人工定稿申报书。

## 【2. 算法与性能分析】

当前实现构造 `(k+m)×k` Vandermonde 矩阵，用前 `k` 行的逆归一化，使前 `k` 个分片保持原数据。编码逐个奇偶行累加 GF(256) 乘积；恢复从完好分片中选 `k` 行求逆，求出缺失的数据行，再重算校验行并核对额外输入。对于长度为 `L` 的单分片，编码时间 `O(mkL)`，生成矩阵 `O(k³+(k+m)k²)`；有数据缺失时恢复求逆 `O(k³)`，字节运算最多 `O(k²L+mkL)`。完整对象的空间含所有帧和输出，为 `O((k+m)×总字节数/k)`；增量编码内部仅保留一个条带，调用方若积累返回帧仍会增加占用。

主要性能瓶颈是重复丢片模式的矩阵求逆、字节级 GF 运算与逐位 CRC-32C。已实现 `RecoverySession`：按选中分片索引缓存最多 64 个逆矩阵，重复模式免去后续 `O(k³)` 求逆；代价是 `O(缓存数×k²)` 额外内存和实例内可变状态，适用于许多条带出现相同节点失效的对象存储；一次性小条带未必受益。具体实现路径为提取内部带矩阵参数的重建函数，预先计算缺失模式，命中复用，未命中求逆并按 FIFO 淘汰；所有分片一致性验证仍由同一路径执行。`recovery_session_test.mbt` 覆盖缓存命中、淘汰及命中后不一致分片被拒绝。

可选的后续优化是将逐位 CRC-32C 改为查表算法：逐字节处理仍是 `O(n)`，但每字节可减少 8 次多项式位迭代；代价是约 1 KiB 常驻表、初始化与跨后端性能验证。现阶段未实测 CRC 占比，因此不应宣称一定值得实施。参考工作负载在 `examples/benchmark`，须在目标机器上以相同构建模式和输入测量，再决定是否引入查表和后端特化。

## 【3. 具体优化步骤】

1. **正确性优先**：保留 `ShardEnvelope` 的规范分片长度、清单一致性和 CRC 校验；任何解析边界改动先加单比特变异或资源上限回归测试，预期阻止非规范输入进入矩阵运算。
2. **按场景选 API**：大对象使用 `ObjectEncoder` / `ObjectDecoder`，把帧及时持久化；预期把库内部待编码数据限制在一条带，避免完整对象 API 的帧积累。
3. **重复模式缓存**：存储故障集中导致相同分片索引反复缺失时使用 `RecoverySession`；预期减少逆矩阵计算，具体收益用同等数据与后端的外部时钟测量。
4. **额外一致性验证**：保留多于 `k` 个完好帧时的校验行交叉核对；预期对未被 CRC 检出的非一致输入报错。恰好 `k` 帧时必须依赖外层完整性，不做未知错误可纠正的承诺。
5. **发布前门禁**：公开仓库建立后复查生态重合，查看默认分支最新 CI 通过，再执行 mooncakes.io 发布与查询；预期把本地合格证据延伸到赛事硬门槛。

## 【4. 推荐修改后的代码】

当前缓存优化已落在 `Codec::reconstruct_with_decoder` 与 `RecoverySession::reconstruct`，无需再重写核心。典型集成方式：

```moonbit
let codec = try! @moonerasure.Codec::new(6, 3)
let session = try! @moonerasure.RecoverySession::new(codec, max_patterns=16)
// 每个条带提供长度为 9 的 Array[Bytes?]，缺失位置填 None。
let restored = try! session.reconstruct(shards)
```

对陌生或受损字节先使用帧解析或 `recover_serialized_object`，而不是直接把不可信原始字节交给 `reconstruct`。缓存实例应归单个工作流所有；并发任务各建实例。

## 【5. 测试建议与当前证据】

- 正常输入：`k=2,m=2` 的手算向量 `01,02 -> 07,04`；四种及以上组合恢复；跨条带不同位置缺失；五类应用示例。
- 边界输入：空对象、1 字节条带、恰好 4096 条带、恰好输出预算与差 1 字节、所有合法字节范围。
- 异常输入：维度越界、重复索引、混入其他 set、截断归档、错误清单、所有帧/清单单比特翻转、CRC 失败、超过奇偶容量的丢片。
- 大规模输入：65,537 字节、`6+3` 且每条带两处缺失；32,777 字节以 137 字节块增量输入并检查缓冲上限。
- 性能场景：`6+3`、每数据分片 8192 字节、20 轮重复丢片；与不用缓存的相同工作负载比较，应报告机器、后端、构建模式、重复次数和中位数。

`moon check --target all --deny-warn`、`moon build --target all --deny-warn`、`moon test --target all --deny-warn` 均通过；75 项测试在 wasm、wasm-gc、js、native 各通过一次。`moon fmt` 与 `moon info` 后 `git diff --exit-code` 为零。工具链：moon 0.1.20260827、moonc 0.10.14、moonrun 0.1.20260920。远端 CI、公开仓库与 mooncakes.io 页面尚无通过证据。