lz4

标准 LZ4 Frame、增量编解码、文件事务和同步进度回调。复用 LZ4F 与 XRT，无需额外压缩 DLL。

验证范围

2026-09-28：Windows 63 步专项通过，包含 23 个实际生成 C 原型、故障注入、四线程 1000 轮和 C/XL JIT/AOT 同输出范例。Windows 和 Linux C 驱动各通过 514 项系统 liblz4 互操作检查；Linux C 通过 ASan/UBSan 与泄漏检测。未验证 Linux xlang、32 位、TSan、长期压力及性能基准，不据此宣称全平台 RC。

快速使用

import lz4

Buffer packed = lz4.compress("hello 世界", acceleration = 4)
assert lz4.decompressText(packed) == "hello 世界"

auto encoder = lz4.compressor()
encoder.update("left")
Buffer wire = encoder.drain()
encoder.update("right")
encoder.finish()
wire.append(encoder.drain())
assert lz4.decompressText(wire) == "leftright"

接口

接口	合同
`version()`	引擎版本文本。
`compress(Buffer\|string, acceleration=1)`	返回 Buffer；acceleration 为 1..65537，不是 HC 等级。
`decompress(Buffer) / decompressText(Buffer)`	返回 Buffer 或文本；二进制，包括 NUL，使用 Buffer。
`compressor / decompressor`	增量对象，update/drain/finish，累计字节只读属性；解压器另有 finished/members。
`compressFile / decompressFile`	source、destination、overwrite=true、限额及可选同步 onProgress；具体参数顺序见 README。

便捷函数默认 maxInput=268435456、maxOutput=536870912，解压另有 maxRatio=1000，要求正数。倍率按每帧已消费前缀计算，不是最终压缩率，也不是 CPU 或工作内存限制。原生类 C 类型构造器的零限额表示不限，优先使用带校验的工厂。

流式与文件

finish 成功后重复调用成功，但不能继续 update；finish 后仍需 drain 最后一段。finished 仅表示完整帧边界，members 不含 skippable 帧。串联帧、关联块、标准块大小和跳过帧均可解压，不支持外部字典 ID。已 drain 的前缀无法撤回，完整验证成功后再发布结果；校验和不是加密认证。

文件接口经同目录临时文件，完整校验、最终进度、flush/close 成功后提交；支持原地转换。取消、回调异常、输入损坏与限额失败不覆盖已有目标，overwrite=false 处理提交竞争。不承诺断电持久性或操作系统拒绝清理时仍能删除临时文件。

onProgress 参数依次为 inputBytes、totalBytes、outputBytes，返回 false 为 CancelledError，最终通知也可以取消；异常保留类型、消息和因果链。同一对象串行使用，可在回调中操作其他独立对象。

错误与边界

ValueError 为参数错误，RangeError 为限额，RuntimeError 为状态，MemoryError 为内存不足，IOError 为压缩数据/文件错误。共享 string 桥的嵌入 NUL 限制没有由本库消除；任意字节输入走 Buffer 路径。包内 VENDOR.md 保留上游许可、哈希及基础 lz4.c/h 精确来源仍待确认的事实。

C 同等能力

xrt_lz4.h 提供 options/error、一次性、增量、Reader/Writer、文件和普通 C 进度回调。输入借用，输出 xbuffer 归调用方释放，reader/writer 不由接口关闭或 flush。C 核心只依赖 XRT；语言 callable 适配另需 xruntime。

范例与复验

发行目录 examples/extlibs/lz4.xl、lz4_basic.xl、lz4_files.xl，C 对照在 extlibs/lz4/examples/basic.c 和 files.c。两组使用相同输入和黄金输出。

tools/check_extlib_lz4.ps1 -Interop 运行完整 Windows 专项及独立互操作；不带 -Interop 不表示已验证互通。tools/check_extlib_lz4.sh 运行 Linux C sanitizer 专项。实际输入哈希、参照库版本和输出由门禁保存。