#moon-deltasync

#定位与边界

• 不做网络：没有 socket、没有协议握手、没有断点续传，不做 rsync 的 ssh 通道与并发调度。传输层由调用者决定。
• 不做文件系统：库的输入输出统一是内存字节（BytesView / Bytes）；只有 cmd/main 碰文件。不读目录树、不做多文件同步、不做内存映射。
• 不做压缩：可与任意压缩层叠加，本库不感知也不内嵌 deflate/zstd/brotli。
• 不做加密，也不做签名认证：强校验是完整性校验，不是数字签名。它能发现传输或存储造成的损坏，不能阻止有能力的篡改者伪造数据并同步伪造指纹。
• 不追求比成熟 C 实现更快。追求的是确定性、可验证、不做隐藏的第三方依赖、四后端一致。

#三个完整工作流

#环境与快速开始

moon  0.1.20261023 (3778465 2026-10-23)
moonc v0.10.17+d971670cd (2026-10-23)
moonrun 0.1.20261023 (3778465 2026-10-23)

$env:PATH = 'D:\moonbit\_tools\moon-0.10.17\bin;' + $env:PATH

moon check --deny-warn --target all
moon build --target js
moon test  --deny-warn --target js
moon run   examples/version_upgrade --target js
moon run   examples/chunk_dedup     --target js
moon run   examples/corruption_check --target js

moon add niuniu513-ask/moon-deltasync@0.1.1

import {
  "niuniu513-ask/moon-deltasync" @ds,
}

#三个示例的实际输出

old bytes: 120890
new bytes: 120935
| delta 字节 | 8346 |        复制操作数 2，复制字节 114688，字面量字节 8237，节省比例 0.9310
delta bytes on the wire: 8346
rebuilt bytes: 120935 (verified 14 blocks)
identical to the new version: true

{"kind":"chunk","path":"snapshot-1","length":142471,"chunk_count":13,"new_chunks":13,"reused_chunks":0,"stored_bytes":142471,"saved_bytes":0,"root_hex":"e23b35b5…"}
{"kind":"chunk","path":"snapshot-2","length":142471,"chunk_count":13,"new_chunks":1,"reused_chunks":12,"stored_bytes":148786,"saved_bytes":136156,"root_hex":"80b61929…"}
distinct chunks in the store: 14
bytes actually kept: 148786
bytes deduplication avoided: 136156
matches the source: true

intact delta rebuilds 25089 bytes, all checksums agree
damaged delta: rejected: the rebuilt bytes do not match the digest the delta carries
same delta against a different old version: rejected: block 1 does not match the signature

#字节格式

"DSIG"(4) version:u8 block_size:u32 strong_len:u8 total_length:u64 block_count:u32
repeat block_count 次: weak:u32 strong:u8[strong_len]

"DDLT"(4) version:u8 block_size:u32 strong_len:u8 new_length:u64 content_digest:u8[32] op_count:u32
repeat op_count 次:
  tag:u8=0 COPY:      block_index:u32 strong:u8[strong_len]
  tag:u8=1 LITERAL:   length:u32 bytes[length]
  tag:u8=2 COPY_RUN:  start:u32 count:u32 strong:u8[strong_len]

"DCHK"(4) version:u8 min_size:u32 max_size:u32 mask_bits:u8 chunk_count:u32
repeat chunk_count 次: sha256:u8[32] length:varint
root:u8[32]    // = SHA-256(concat(每个块的 32 字节 sha256))

#公开 API

#命令行

moon-deltasync sign    <path>                       # 签名摘要与统计
moon-deltasync delta   <old> <new>   --out <d>      # 计算 delta，可写出 DDLT 原始字节
moon-deltasync apply   <old> <delta> --out <f>      # 应用并逐块校验，可写出重建结果
moon-deltasync chunk   <path>                       # 分块与去重率报告
moon-deltasync verify  <path> <sha256-hex>          # 全流校验

moon run cmd/main --target js -- sign  old.txt --out old.dsig
moon run cmd/main --target js -- delta old.txt new.txt --out patch.ddlt
moon run cmd/main --target js -- apply old.txt patch.ddlt --out rebuilt.txt
moon run cmd/main --target js -- chunk new.txt --out new.dchk

{"kind":"sign","path":"old.txt","total_length":120890,"block_size":8192,"strong_len":16,"block_count":15,"signature_bytes":322,"signature_sha256_hex":"add8904b…","sha256_hex":"d242f2a7…","xxh64_hex":"8d32c2ca93e03df3"}
{"kind":"delta","old":"old.txt","new":"new.txt","new_length":120935,"op_count":3,"copy_ops":2,"copy_blocks":14,"copied_bytes":114688,"literal_bytes":8237,"delta_bytes":8346,"delta_sha256_hex":"7830b34f…","savings_ratio":0.9310}
{"kind":"apply","ok":true,"bytes_written":120935,"blocks_verified":14,"ops_applied":3,"sha256_hex":"970caa0e…"}
{"kind":"chunk","path":"new.txt","length":120935,"chunk_count":4,"unique_chunks":4,"new_chunks":4,"reused_chunks":0,"stored_bytes":120935,"saved_bytes":0,"dedup_ratio":0.0000,"manifest_bytes":190,"root_hex":"ba92558c…"}
{"kind":"verify","ok":true,"sha256_hex":"970caa0e…"}
{"kind":"error","code":"usage","message":"the expected digest is not hexadecimal"}

• signature_bytes 是 DSIG 序列化长度（322 = 22 + 15 × 20）。sha256_hex 是被签名内容的全流 SHA-256，xxh64_hex 是同内容的 XXH64，二者让外部脚本可以独立复核内容；signature_sha256_hex 则是 DSIG 字节本身的哈希，用于比较两份签名是否相同。
• delta 行同时给出 op_count（op 总数）、copy_ops（复制 op 数）、copy_blocks（复制的块数）、copied_bytes（复制字节）。op 数与块数不是一回事：本例 3 个 op 里 2 个是复制，覆盖 14 个块。
• chunk 行的 manifest_bytes 是 DCHK 序列化长度，dedup_ratio 是 4 位小数文本；unique_chunks / stored_bytes / saved_bytes 是存储累计视角（CLI 每次新建 store，所以等于本文件的数）。
• savings_ratio 由整数 ppm 渲染成 4 位小数，不受浮点后端差异影响。

• 四个子命令的 --out 都生效：sign 写 DSIG、chunk 写 DCHK、delta 写 DDLT、apply 写重建结果，写的都是原始字节而不是 JSON。实测 sign --out 得到 322 字节、chunk --out 得到 190 字节，与对应 JSON 里的 signature_bytes / manifest_bytes 一致。
• verify 有两档失败，语义不同：① 参数个数不是 2、摘要不是合法十六进制或不是 32 字节 → {"kind":"error","code":"usage",…} 且退出码 1；② 摘要合法但与文件不符 → {"kind":"verify","ok":false,…} 且退出码 0——这是正常结论（「这份文件不是这个摘要」），不是错误。
• 未知命令与未知参数都返回 usage 错误 + 退出码 1，不会静默丢弃参数（实测 sign f --bogus → unexpected argument: --bogus）。
• 文件不可读、格式损坏分别走 read_failed / format_error，退出码 1。

#不变量

1. 重建一致：任意 old、new，apply_delta(old, compute_delta(new, sign_bytes(old))) 的输出等于 new。
2. 规范化：compute_delta 的输出满足「相邻同类 op 已合并」，重新序列化后逐字节相同。
3. 局部性：new 相对 old 只改 1% 的块时，delta_bytes <= 块数*8 + 改动字节 + 16。
4. 检测损坏（三层）：① 翻转 delta 中任意一个 LITERAL 字节 → 逐 op 校验或整体摘要拒绝；② 把 COPY/COPY_RUN 指向内容不同的旧数据 → BlockMismatch(index)；③ 翻转或截断 DDLT 头部的 content_digest → DigestMismatch。第三层挡住了字面量与长度字段被改坏这类逐块校验看不见的损坏。
5. 分块稳定：数据前缀插入 1 字节后，≥ 90% 的块指纹仍复用（默认参数、≥ 1 MiB 输入）。
6. 去重正确：manifest 重建出的字节与输入相同，root 由块指纹确定性导出。
7. 跨后端一致：相同输入在 wasm / wasm-gc / js / native 上的签名、delta、manifest 逐字节相同。
8. 无 panic：截断、错 magic、错长度、超大 count、错块号等畸形输入全部返回 FormatError 诊断。

#复杂度与上界

#与现有 MoonBit 生态的关系

#验证状态

• delta 字节数与校验器自己的独立 rsync 规划器逐字节相等（10/10 语料，ratio 1.000，最大 96755 B / 2 MiB 语料）——规划质量不是自评出来的。
• 双向互操作 30/30：它用自己生成的 DDLT 喂 CLI apply，重建逐字节相同；CLI 产出的 delta 用它的独立重放器也能重建。
• 跨后端 js vs wasm-gc 7/7 一致；弱校验与 zlib.adler32 逐位一致（含空窗口），滑动更新 20034 次滑窗与直接计算一致。
• 畸形输入 29/29 只报错、不崩溃。§7.5 分块稳定性与 DSIG/DCHK 导出两项阻塞均已解除。

#发布状态与残余不确定

• GitHub：niuniu513-ask/moon-deltasync 是 PUBLIC 仓库，默认分支 main，本机 main 与 origin/main 指向同一提交（仓库仍在活跃提交，SHA 会变）。
• CI：gh run list 显示 main 上最近若干次运行均为 success，最近一次是「docs: make the type declarations and the --out note match the code」，耗时 36s。
• Mooncakes：niuniu513-ask/moon-deltasync@0.1.1 已发布（MIT，is_new: true，创建于 2026-11-09），因此上面的 moon add 可用。

1. CI 只看了最近几次运行：没有逐条回溯全部历史运行结果，也没有核对分支保护、必需检查等仓库设置。
2. 相邻包的实现深度：SOURCES.md 的逐包比对基于索引元数据（名称、描述、keywords、许可证、仓库地址），没有阅读任何相邻包的源码或 README 正文，因此不对其能力细节下定论。
3. 检索快照时效：逐关键词统计基于 2026-10-26 的快照；2026-11-09 的在线注册表为 3,665 个包，中间新增的包（包括 moonlibsync）已在上文单独说明，但未对全部新增包重做逐项比对。

#许可证