#MoonXZ

发布说明。

• 0.4.2 及更早版本有解码缺陷：解析 LZMA2 未压缩长度字段时存在进位错误， 128 KiB / 256 KiB / 1 MiB 等常见体积的合法 Python / xz-utils 输出会解码 失败；同一批版本的长度校验还存在整数溢出。请勿用它们解压外部产生的 XZ 文件
• 0.4.3 修复上述缺陷；0.4.4 只同步了 moonc 0.10.15 的格式与发布源码
• 0.4.1 及更早版本还会在新工具链上因 implicit_impl_as_method 构建失败
• 0.4.5 修复外部 XZ 流的逐字节流式解码误报，并加入一致性验证模块
• 0.4.6 适配 moonc 0.10.17 的公开接口格式，行为与 0.4.5 相同

构建要求 moonc 0.10.14 或更高；当前源码已在 moonc v0.10.17+d971670cd 上 完整验证（check --deny-warn、四个后端的 test --deny-warn、fmt --check、 bundle --all、CLI 示例、一致性语料、基准与互操作脚本）。详见 CHANGELOG.md 和 docs/compatibility.md。

#功能状态

#安装与使用

moon add lin2077-zeming/moonxz

import {
  "lin2077-zeming/moonxz/lib" @moonxz,
}

fn example() -> Unit raise {
  let input = b"MoonXZ quick start\n"
  let encoded = @moonxz.compress(input)
  let decoded = @moonxz.decompress(encoded)
  println(decoded == input)
}

#最小可复现示例

moon run cmd/main -- demo

input_bytes=7400 xz_bytes=156 percent=2
roundtrip=true
xz_hex=fd377a585a000004e6d6b44602...

let encoded = @moonxz.compress_with_check(input, @moonxz.CheckKind::Sha256)

let options = @moonxz.CompressionOptions::new(
  level=9,
  dict_size=8 * 1024 * 1024,
  filter=@moonxz.FilterMode::X86,
)
let encoded = @moonxz.compress_with_options(input, options)

let writer = @moonxz.XzWriter::new()
let first = writer.write(b"first block")
let second = writer.write(b"second block")
let tail = writer.finish()

let reader = @moonxz.XzReader::new(first + second + tail)
let block = reader.read_block()

let decoded = @moonxz.decompress_with_limit(encoded, 16 * 1024 * 1024)

// 解压由 xz --format=lzma 或 Python lzma.compress(data, format=lzma.FORMAT_ALONE) 生成的文件
let decoded = @moonxz.decompress_lzma1(legacy)

// 写出 .lzma
let encoded = @moonxz.compress_lzma1(input)

// 读取头部信息，便于诊断
let (lc, lp, pb) = @moonxz.lzma1_properties(legacy)
let declared = @moonxz.lzma1_declared_size(legacy)

#BCJ filter 支持范围

#当前版本边界与补齐计划

• ARM、SPARC：在特定字上地址运算溢出，编码后再解码无法还原原文，liblzma 也会拒绝 MoonXZ 写出的流（Corrupt input data）
• ARM64：早先实现存在同类溢出；现在可由官方 xz 5.8.3 与 lzma-mbt 提供 可执行对照，因此补齐路径已经明确
• ARM-Thumb、PowerPC、IA64：无法归纳出与 liblzma 一致的字节变换规则

#一致性与差分验证

moon run tools/conformance/cmd/main -- run tools/conformance/corpus/manifest.json _build/conformance-report.json

#CLI

moon run cmd/main -- demo
moon run cmd/main -- compress <hex> [none|crc32|crc64|sha256]
moon run cmd/main -- decompress <hex>
moon run cmd/main -- roundtrip <hex>
moon run cmd/main -- lzma-decompress <hex>
moon run cmd/main -- lzma-roundtrip <hex>
moon run cmd/main -- compress-file <input> <output> [check] [none|x86|delta]
moon run cmd/main -- decompress-file <input> <output>
moon run cmd/main -- lzma-compress-file <input> <output>
moon run cmd/main -- lzma-decompress-file <input> <output>

#性能

moon test --release --target native

• 压缩速度强烈依赖数据的可压缩性。 重复数据约 68 MiB/s，而随机数据只有 约 3.2 MiB/s。随机数据每次匹配搜索都要走完整条哈希链才会放弃，因此慢得多。 解压速度则稳定在 35–54 MiB/s。
• 半重复与随机数据的输出与 liblzma 基本持平；重复数据仍有约 5 倍差距， 原因是 LZMA2 压缩块的未压缩上限当前保守地停在 64 KiB，限制了可用匹配距离。 提高该上限可以把它降到约 1.3 倍，但会让编码器写出的块超出本库解码器目前能 正确处理的形状，因此暂未启用；实测数据与入手点记录在 docs/DESIGN.md。

#流式解码与内存占用

let decoder = @moonxz.XzStreamDecoder::new()
// 每次拿到一段压缩数据就喂进去，然后尽量取出已解出的块
decoder.supply(chunk)
loop decoder.next() {
  Some(block) => handle(block)
  None => break          // 需要更多输入，除非已经调用 finish_input
}
// 输入结束时调用，之后 next 返回 None 即为流被截断
decoder.finish_input()

#验证

moon check --deny-warn
moon test --deny-warn
moon fmt --check
moon test --target all --deny-warn

• CRC32 和 SHA-256 已知向量
• 空输入和普通输入 roundtrip
• None / CRC32 / CRC64 / SHA-256 四种 block check
• 多 LZMA2 chunk、压缩级别和字典大小组合，含 65536 字节 chunk 边界两侧
• liblzma 生成的 128 KiB / 256 KiB / 1 MiB 单块 fixture（控制字节 0xE1 / 0xE3 / 0xEF），覆盖 18 位未压缩长度字段的进位路径
• 重复数据和不可压缩数据的自动回退
• delta 和 x86 BCJ filter 的标准向量（liblzma 生成）
• 未实现 BCJ filter 明确返回 Unsupported
• .lzma 两种头形式的解码、编码绕回与损坏头部拒绝，含空输入的编码
• 超长声明长度字段必须被拒绝且不得 panic
• 逐字节截断：任何前缀都不得解出原始数据
• 单字节全量变异：任何变异都不得 panic，也不得静默产出与原文不同的数据
• 伪随机垃圾输入：与变异测试互补，覆盖完全没有合法结构的输入
• 声明膨胀：头部声明超大输出时必须在输出限制处失败
• 流式 Writer/Reader 的多 block 读写
• 流式 XzStreamDecoder 逐字节喂入与一次性解码逐字节一致，含拼接流与 padding； 另覆盖外部 XZ 流省略 Block 压缩大小时的逐字节输入、截断检测与输出上限
• 文件 CLI 压缩、解压和内容一致性
• Python lzma 生成的压缩 XZ 测试向量
• 输出大小限制错误

#验收级自查

python scripts/self_audit.py .

#项目结构

moon.mod                 模块元数据
moon.work                workspace：根库 + 一致性工具
lib/moon.pkg             库包配置
lib/moonxz.mbt           公共 API
lib/xz.mbt               XZ 容器解析和写入
lib/lzma1.mbt            .lzma 旧格式头部、解码和编码
lib/lzma2.mbt            LZMA2 chunk 解析
lib/lzma_decoder.mbt     LZMA 概率模型和状态机
lib/range_decoder.mbt    LZMA range decoder
lib/range_encoder.mbt    LZMA range encoder
lib/lzma_encoder.mbt     LZMA 编码状态机
lib/lzma2_encoder.mbt    LZMA2 压缩块编码和回退
lib/match_finder.mbt     Hash chain match finder
lib/filters.mbt          Delta 与 x86 BCJ filter
lib/streaming.mbt        流式 Reader / Writer 与有界窗口解码器
lib/check.mbt            CRC32 / CRC64 / SHA-256
lib/util.mbt             字节游标、VLI 和序列化辅助
cmd/main/                可运行 CLI
tools/conformance/       独立的一致性 / 差分验证模块
docs/compatibility.md     规范版本、支持矩阵和证据索引
docs/DESIGN.md           实现设计说明

#互操作示例

$xz = (moon run -q cmd/main -- compress 6869 sha256).Trim()
python -c "import lzma,sys; print(lzma.decompress(bytes.fromhex(sys.argv[1])))" $xz

b'hi'

#开源与来源说明