# 项目申报书

**项目名称**：moondelta-core — Delta Lake 表格式内核的 MoonBit 实现\
**参赛者**：张国迅（GitHub：xiguaAp6y3）\
**联系方式**：已在官方渠道提交，这里不展示 \
**GitHub 仓库链接**：https://github.com/xiguaAp6y3/moondelta-core \
**项目方向**：MoonBit 数据基础设施，面向 lakehouse / ETL / 数据管道的 Delta 表读写\
**是否为移植项目**：否 —— 按 Delta Lake 协议规范原创实现

## 1. 项目简介

MoonBit 数据生态已具备 Parquet 编解码、Arrow IPC 与 DataFrame 等基础构件，但此前 `mooncakes.io` 上尚无任何事务表格式（Table Format）库，无法将离散的 Parquet 文件组织为具备原子提交、多版本快照、时间旅行和统计剪枝能力的表。

`moondelta-core` 按 **Delta Transaction Log Protocol（reader v1 / writer v2）** 规范实现了这一核心层：打开磁盘上的 Delta 表目录，回放 `_delta_log`（支持从 Parquet Checkpoint 恢复），给出指定版本的文件清单，按分区与文件级 `min/max` 统计剪枝，读写含复杂嵌套 Schema（`struct` / 标准 3-level `list` / `map`）的数据文件并原子提交新版本。目前（v0.3.1，约 5,200 行手写 MoonBit 代码）已与 `delta-rs 1.6.6`、DuckDB 完成扁平表与嵌套表的双向目录级互操作对拍，并发布至 `mooncakes.io`。

## 2. 项目方向与通用性说明

* **业务无关**：面向 Lakehouse / ETL / 数据管道，凡需要“带版本与事务日志的表”场景（ETL 入湖、外部表校验迁移、CI 数据契约审计）均可直接复用。
* **生态与格式一致**：在 `reader v1 / writer v2` 闭集内，产出与消费的目录结构同 `delta-rs`、DuckDB 双向逐值对齐（证据见仓库 `artifacts/acceptance/`）。
* **零外部重运行时绑定**：纯 MoonBit 实现（仅依赖官方 `moonbitlang/x@0.5.5`），不依赖 JVM 或 Rust 运行时；当前支持 Native 本地文件系统，架构天然适配后续 Wasm/JS 及对象存储扩展。
* **边界显式（Fail-fast）**：闭集之外的输入（`reader >= 2` 特性、`decimal`/`uuid`、ZSTD/GZIP 等未支持压缩、多部分 Checkpoint）一律返回结构化错误（错误类型 + 原因 + 退出码），绝不静默降级或产出脏数据。

## 3. 预期使用场景

1. **MoonBit 轻量级 ETL 入湖与外部引擎消费**：在无 JVM/Spark 环境中，通过 `create_table` + `append_rows` 将业务数据（含嵌套列）原子写出为标准 Delta 目录，下游直接由 DuckDB 或 `delta-rs` 零转换读取分析。
2. **外部表离线校验与截断日志恢复**：读取外部引擎（Databricks / Spark / `delta-rs`）产出的 Delta 表（含早期 JSON 日志已被清理、必须从 `_last_checkpoint` 恢复基底并叠加增量 JSON commit 的表），调用 `snapshot_at(v)` 校验指定版本的文件清单、行数与字段值。
3. **CI 数据契约与提交审计**：在数据流水线 CI 阶段挂载只读路径，按版本回放日志并结合分区与文件级 `min/max` 剪枝，快速输出“本次提交增删了 N 个数据文件、影响 M 行、落在特定分区”的审计报告，并拦截非法 Schema 变更。

## 4. 核心功能

* **事务日志解析与 Checkpoint 恢复**：完整解析 20 位定长 JSON 日志中的 `protocol` / `metaData` / `add` / `remove` / `commitInfo` / `txn`（显式忽略 `cdc`/`domainMetadata`，拒绝未知 action）；支持单文件经典 Parquet Checkpoint 解析与状态叠加，兼容 Spark 与 `delta-rs` 两种可空性形态。
* **协议强制与门控**：严格校验 `minReaderVersion == 1` 与 `minWriterVersion <= 2`；显式拒绝 `readerFeatures`（Column Mapping、v2 Checkpoint）与 `add.deletionVector`。
* **多版本快照与扫描剪枝**：支持 `snapshot_at(v)` 时间旅行与 `history()`；支持分区列等值过滤与标量列文件级 `min/max` 统计剪枝（统计 JSON 损坏显式报错，嵌套字段跳过剪枝保证正确性）。
* **基础与嵌套 Schema 读写**：基于 Dremel shredding 槽位流（`def/rep level`）实现 11 种基础类型（`boolean`/`byte`/`short`/`int`/`long`/`float`/`double`/`string`/`binary`/`date`/`timestamp`）及嵌套类型（`struct` / 3-level `list` / `map`）的装配读取与镜像拆分写出；支持 `UNCOMPRESSED`/`SNAPPY`、`add.path` URL 解码与分区值自动回填。
* **原子提交与 CLI 工具**：`create_table` 与 `append_rows` 强制校验列名/类型/`NOT NULL`，采用 `put-if-absent` 防止覆盖；提供 `delta inspect | history | scan | read | create | version` 命令行工具与 37 个具名单元测试。

## 5. 原创说明與第三方构件参考

* **原创属性**：本项目为**原创项目**，严格对照 Delta Lake 官方协议规范（`github.com/delta-io/delta`，Apache-2.0）从零编写状态机与读写逻辑，未复制 `delta-rs` 或 Spark 代码。对拍测试数据引自 `delta-rs` 与 `apache/parquet-testing`（Apache-2.0，SHA-256 记录于 `fixtures/README.md`）。
* **底层 Parquet 构件参考与扩展**：底层 Parquet 物理文件编解码基于 MoonBit 社区库 `mizchi/parquet@0.2.2`（`https://github.com/mizchi/parquet`，许可证：**Apache-2.0**）进行 vendored 扩展（记录于 `NOTICE.md` 与 `THIRD_PARTY_NOTICES.md`）。原库仅支持扁平标量读写；本项目在 `src/vendor/parquet` 中原创新增了 **Dremel shredded 槽位流（叶级值 + `def/rep level`）读写入口**、扩展了 `BOOLEAN`/`DOUBLE` 写入，并修复了原库在 `REPEATED` 层级上的 `def level` 递增规则，在此之上独立实现了 `src/shred.mbt`、`src/writenested.mbt` 与 `src/checkpoint.mbt`。

## 6. 仓库状态与交付验证

* **GitHub 仓库**：含完整演进 commits、CI 流水线、37/37 具名单元测试及 `artifacts/acceptance/` 跨引擎 0 FAIL 对拍证据）。
* **生态发布**：`0.3.1` 已正式发布至 `mooncakes.io`（`xiguaAp6y3/moondelta-core`），并通过空工程拉取、编译与运行全链路验证。