blake3

哈希校验

普通哈希、原生 keyed hash、密钥派生与可扩展长度摘要。内嵌 portable C 后端，复用宿主 XRT/xruntime，无需额外 BLAKE3 DLL。

一次性与文件 API

outLen 单位是字节，默认 32。hex 结果为小写，字符数量是摘要字节数的两倍。文本使用 UTF-8 字节，任意二进制使用 Buffer。

函数	参数与返回
`version()`	返回固定后端版本 1.5.0。
`hashHex(data, outLen=32)`	data 为 Buffer 或 string，返回 string。
`hashBytes(data, outLen=32)`	相同输入，返回独立拥有型 Buffer。
`hashMacHex(data, key, outLen=32)`	两个 Buffer 或两个 string；密钥必须恰好 32 字节。
`hashKdfHex(keyMaterial, context, outLen=32)`	材料为 Buffer 或 string，上下文为 string，返回 string。
`hashFileHex(path, maxInput, outLen, onProgress)`	普通模式文件哈希，默认 maxInput=268435456、outLen=32、onProgress=null。

BLAKE3_OUT_LEN 和 BLAKE3_KEY_LEN 均为 32。密钥按字节计数，空密钥及 31/33 字节密钥都报错，不填充或截断。 keyed hash 是原生模式，不是 HMAC；密钥派生不代替 Argon2 等口令慢哈希。

outLen 必须为正；同一输入的短摘要是长摘要的前缀，可以输出超过 32 字节。分配型薄绑定统一使用当前 XRT 默认 512 MiB 输出预算，hex 的临时空间约为三倍摘要长度，此预算不代表峰值内存或 CPU 限制。没有一次性 keyed/KDF Bytes 函数，原始字节输出使用增量对象。

增量对象

工厂	类型与模式
`hasher(maxInput=268435456)`	Blake3Hasher，普通模式。
`keyedHasher(Buffer key, maxInput=268435456)`	Blake3KeyedHasher，复制密钥到独立状态。
`deriveHasher(string context, maxInput=268435456)`	Blake3Hasher，保留派生后的模式与密钥。

成员	合同
`update(Buffer\|string)`	追加数据，空输入有效。
`digestHex(outLen=32)` / `digestBytes(outLen=32)`	读取快照，不结束状态；可重复使用不同输出长度。
`inputBytes` / `valid`	成功累计输入字节数；valid 仅表示句柄非空。
`clone()`	独立状态，复制模式、密钥、限额、计数和失败状态。
`reset() as bool`	清除输入与失败状态，保留模式和限额，成功返回 true。

import blake3

auto hash = blake3.hasher()
hash.update("ab")
auto branch = hash.clone()
hash.update("c")
branch.update("d")
assert hash.digestHex() == blake3.hashHex("abc")
assert branch.digestHex() == blake3.hashHex("abd")
println(hash.digestHex(16))

失败的 update 不增加计数，并使对象进入失败状态；必须 reset 后继续。克隆失败对象也保留失败状态，两者各自 reset。非法摘要参数不会毒化原有数据。同一可变 hasher 须串行访问，不同对象可独立运行。析构清零自己的状态，不承诺擦除调用方副本、寄存器、交换页或已导出的摘要。

推荐使用工厂。*Native 成员和 point 接管构造用于原生互操作，不能传入任意指针或重复接管一个句柄。类型化对象本身管理原生资源寿命。

进度与错误

可选回调类型为 (func(int, int, int) as bool)?，依次接收 inputBytes、 totalBytes、outputBytes；未知总长为 0，outputBytes 恒为 0。每块读取后同步通知，EOF 再通知一次，空文件也有结束通知。语言回调不带 FINAL 标志，末次计数可能与前次相同。

string digest = blake3.hashFileHex("data.bin",
    onProgress = func(int inputBytes, int totalBytes, int outputBytes) as bool
        return true
    end)

回调返回 false 抛 CancelledError；用户异常保留类别和消息。可嵌套另一独立文件哈希。取消或失败不返回部分摘要、不修改源文件，也不回退已消费的 reader 游标。文件路径使用 XRT UTF-8 API，不提供针对并发写入的文件快照。

非法参数或密钥长度为 ValueError；超过输入/输出预算为 RangeError。
分配失败为 MemoryError，打开失败沿用 XRT FileError，无诊断的读取失败为 IOError。
Reader 已有的错误及回调异常保持原类别和消息，不统一覆盖为通用 I/O 错误。
xlang 工厂和文件 maxInput 必须为正，默认 256 MiB。

C API 与范例

核心头 include/xrt_blake3.h 提供 OptionsInit、ErrorInit、 Hash/HashKeyed/HashKdf、HasherCreate/CreateKeyed/CreateDeriveKey、 HasherUpdate/Digest/Reset/Clone/InputBytes/Error/Destroy 和 File，统一前缀为 xrtBlake3。

核心一次性函数写入调用方缓冲，不强加分配型包装的默认限额。Hasher/File 的 NULL 配置使用 XRT 默认限额；显式配置的零输入/输出预算表示关闭对应业务限制，但仍检查计数溢出。薄绑定的 maxInput=0 则表示默认值，不等于核心 C 配置的无限制。

File 借用 reader 从当前游标读到 EOF，保留 C 进度帧的 TOTAL_KNOWN/FINAL 标志。薄绑定头为 include/blake3_native.h；hex 返回值借用 XRT 临时区，清理或回退后失效，长期保留须复制。原始摘要是拥有型 xbuffer，由 C 调用方销毁。

教学：examples/extlibs/blake3.xl。双语对照： examples/extlibs/blake3_basic.xl 与 extlibs/blake3/examples/basic.c，共同黄金输出为 examples/extlibs/blake3_basic.expected.txt。

验证范围与来源

2026-09-27 Windows 门禁覆盖 35 条上游向量的三模式六长度、23 个实际生成原型、 C/xlang JIT/AOT/GCC、Reader 与回调、Unicode、分配故障、独立四线程和双语黄金输出。 Linux 独立 C 使用 ASan/UBSan 和泄漏检查。输入内容及文件集合在门禁前后比对。

入口：tools/check_extlib_blake3.ps1 和 tools/check_extlib_blake3.sh。不代表 Linux xlang、32 位/ARM、共享可变对象并发、SIMD 吞吐或密码学审计认证。来源锁定为上游 1.5.0，commit 5aa53f07f7188a569cadfc5daf1522972d9a9630；文件哈希、本地零初始化补丁和 CC0/Apache-2.0 许可证见包内 VENDOR.md 与 third_party。