md5

摘要兼容

16 字节 MD5，直接复用 XRT 算法，不重复引入摘要核心或外部 DLL。用于既有格式兼容，不用于密码、认证或防恶意篡改。

公开函数

函数	参数与结果
`version()`	包引擎版本 1.0.0。
`hashHex(data)`	Buffer 或 string，返回 32 个小写 hex 字符。
`hash(data)`	同样的输入，返回 16 字节 Buffer。
`hashFileHex(path, maxInput, onProgress)`	文件摘要。默认 maxInput=268435456、onProgress=null。
`hashFile(...)`	相同参数，返回 16 字节 Buffer。
`hasher(maxInput=268435456)`	返回 Md5Hasher。
`MD5_DIGEST_SIZE`	常量 16。

文本按 UTF-8 字节计算，空输入合法；包含 NUL 的二进制输入使用 Buffer。 maxInput 必须为正，一次性函数不另设业务预算。失败抛异常，不用空结果表示成功。

增量对象

import md5

auto h = md5.hasher()
h.update("a")
h.update("bc")
assert h.digestHex() == "900150983cd24fb0d6963f7d28e17f72"
assert h.inputBytes == uint64(3)
h.reset()

update(Buffer|string) 追加输入；digest 返回 Buffer，digestHex 返回文本，两者都是可重复读取、之后可继续追加的快照。reset 清空输入与失败状态、保留预算。 inputBytes 为 uint64；valid 仅检查句柄非空。错误 update 不部分接收，需 reset 后恢复。独立对象可并发，同一可变对象必须串行；底层 Native 方法不接受任意指针。

文件与进度

string digest = md5.hashFileHex("data.bin",
    onProgress = func(int current, int total, int output) as bool
        return true
    end)

每块最多 64 KiB，EOF 另通知一次，空文件也通知；末尾计数可能重复。参数分别为已读字节、总长度、输出字节。未知总长为零，输出恒为零，uint64 转 int 前检查范围。返回 false 抛 CancelledError，最终通知也可取消；回调抛错保留原类别和消息，允许嵌套独立操作。

参数错误为 ValueError、超限为 RangeError、分配失败为 MemoryError；文件错误保留 XRT 分类。路径通过 XRT UTF-8 文件 API，不修改输入、不交付部分摘要。输入预算不等于 CPU 时限或文件快照。

C API 与所有权

include/xrt_md5.h 提供 xrtMd5Hash、OptionsInit/ErrorInit、 HasherCreate/Update/Digest/Reset/InputBytes/Error/Destroy、File。 File 借用 Reader，从当前游标读取，不关闭、不回退；最终通知成功后才写摘要。 C 进度帧保留 uint64 计数及 FINAL/TOTAL_KNOWN 标志。核心零预算表示不设业务上限，仍检查位计数溢出。

核心可独立使用，不依赖 xlang；已有宿主 XRT 时复用唯一运行库。 include/md5_native.h 声明精确薄绑定 ABI。hex 借用 XRT 临时区，清理/回退后失效；后续调用不覆盖此前文本。二进制 xbuffer* 归调用方所有，C 用 xrtBufferDestroy，语言由 Buffer 接管。

范例与验证范围

教学：examples/extlibs/md5.xl。双语对照：examples/extlibs/md5_basic.xl 与 extlibs/md5/examples/basic.c，固定输出相同。

tools/check_extlib_md5.ps1 检查 149 组独立答案及 8 种地址偏移、填充/分块、百万 a、 15 个生成原型、UTF-8/Buffer、Reader、回调取消/异常、分配故障、四线程独立对象、C/xlang JIT/AOT/GCC。 tools/check_extlib_md5.sh 检查 Linux 独立 C ASan/UBSan/泄漏边界。门禁记录输入哈希，不是跨版本永久认证；未验收 Linux xlang、大端、32 位/ARM、共享可变对象或吞吐性能。