# MoonRRA 项目申报书

**项目名称：** MoonRRA——MoonBit 固定容量多分辨率时序归档库。

**项目简介与方向：** 面向监控与设备采样的可嵌入基础库，以 MoonBit 实现时间桶聚合、循环覆盖与状态恢复。通过近期细粒度记录、长期聚合记录，在固定配置下限制历史数据占用，供应用直接集成。

**通用性与生态价值：** 提供创建、更新、区间查询、覆盖信息、快照导出及恢复接口，支持 Native、JS、Wasm 和 Wasm-GC。与现有窗口统计、PromQL 查询及无损时序压缩库相比，本项目侧重固定容量、多级保留周期和有损聚合，可作为不同采集应用的历史存储核心。

**预期使用场景：**
1. 服务监控：按分钟输入内存指标，同时保留分钟记录与小时均值，查询不同时间尺度的历史，过期记录自动覆盖。
2. 设备采样：输入温度及缺测状态，按已知数据阈值形成汇总；保存快照后重新加载，继续未完成的聚合，缺测不被误记为零。
3. 网络流量：将接口累计字节数转换为速率，显式处理计数器重置或回绕，查询近期速率和较长期峰值。

**已有基础：** 已完成对齐采样、平均/最小/最大/最后已知值四种聚合、缺测阈值、环形覆盖、查询覆盖元数据和版本化二进制快照。0.1.0 已发布 Mooncakes；提供三个运行示例、14 组测试及四目标检查/构建/测试 CI，并完成独立消费者安装验证。

**拟完善功能与交付目标：**
1. 文件存储适配：增加 Native 快照保存、重新打开和继续写入接口，提供可运行的文件往返示例及文件读写错误测试。
2. 成熟实现对照：针对支持的对齐采样子集建立 RRDtool 对照用例，覆盖四种聚合与缺测，记录浮点容差和语义差异。
3. 工程完善：补充长期运行的吞吐与空间基准、损坏快照和时间边界测试、中文接口文档；发布后续版本并验证消费者安装与运行。

**技术路线与功能边界：** 每条指标独立建库，各归档配置聚合倍数、槽位容量和最少已知点数；以环形槽位覆盖过期桶，快照保存未完成聚合状态。核心采用纯 MoonBit，文件 I/O 与归档逻辑分离。首期要求严格递增且对齐的时间戳，明确未知值与历史覆盖范围；不包含分布式服务、任意标签索引、RRDtool 全功能或 .rrd 格式兼容，不承诺事务和断电一致性。

**原创、参考与许可证：** 独立 MoonBit 实现，参考 [RRDtool 文档](https://oss.oetiker.ch/rrdtool/doc/rrdcreate.en.html) 的循环归档概念，未移植其源码。采用 Apache-2.0 许可证；后续引入第三方代码或测试材料时记录来源、许可证与使用范围。

**公开仓库：** https://github.com/apoloe4/moonrra

**已发布模块：** https://mooncakes.io/docs/apoloe4/moonrra@0.1.0
