blake3

哈希校验

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

2026-10-30：修复Reader/回调的C错误快照丢失原后端码，仅补两处赋值，不改变算法、正常路径或ABI。96组验证原错误身份、分类/域/码/消息/偏移、摘要不变、Reader借用、首因后的禁止分配及立即恢复；两平台同一回归旧36红→0。回调中断的模块分类仍为CANCELLED，具体用户异常从原线程错误读取。

Windows默认60项58通过；Linux原生ASan/UBSan、向量/分配/关闭/线程、双语黄金输出及两平台各8份普通独立程序通过，23条实际生成原型和错改返回值负例过。M3私有接管仍被接受，M2全局对象仍在EXE打印后退出1，均保留为发布阻断，不签收整包。Windows首个GCC选择和失败保留已压实，真实入口raw37/outer1、Linux37/127验证过；主线、XRT及vendor未修改。

一次性与文件 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，上下文为完整 UTF-8 字节序列（含 NUL 也不会截断），返回 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 等口令慢哈希。

deriveHasher 与一次性 KDF 使用相同的带长度上下文语义； C API 也显式接收上下文字节长度，普通 C 字符串调用者传入 strlen(context)。

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。

原生 *Native 成员仅供类内部包装使用；导入方通过上述成员读写数据，不直接传入裸指针和字节长度。

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 须串行访问，不同对象可独立运行。析构清零自己的状态，不承诺擦除调用方副本、寄存器、交换页或已导出的摘要。

推荐使用工厂。公开 keyed 构造只接收自带长度的 bytes，原生层要求密钥恰好 32 字节；C 指针/长度入口由 C 调用方负责配对。 *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，含 NUL 的路径会报 ValueError；不提供针对并发写入的文件快照。

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

C API 与范例

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

核心一次性函数写入调用方缓冲，不强加分配型包装的默认限额。Hasher/File 的 NULL 配置使用默认限额；流对象用 xrtBlake3OptionsInit，文件显式限额用 xrtBlake3LimitsInit。显式配置须匹配长度/版本，除输入/输出预算外的限额、标志和保留字段为零，错误配置在读取前拒绝。零输入/输出预算表示关闭对应业务限制，但仍检查计数溢出。薄绑定的 maxInput=0 则表示默认值，不等于核心 C 配置的无限制。

File 借用 reader 从当前游标读到 EOF，保留 C 进度帧的 TOTAL_KNOWN/FINAL 标志。 C 调用方须检查 Reader 的关闭结果；XLang 文件哈希自行关闭文件，关闭失败不返回摘要。薄绑定头为 include/blake3_native.h；不带_owned的hex接口借用XRT临时区，清理或回退后失效；带_owned的char*由调用方xrtFree，XLang公开文本路径直接接管。原始摘要是拥有型xbuffer，由C调用方销毁。错误快照的iBackendCode保留Reader或回调原XRT码，读取诊断后再由调用方关闭Reader。

教学：examples/extlibs/blake3.xl。双语对照： examples/extlibs/blake3_basic.xl 与 extlibs/blake3/examples/basic.c，共同黄金输出为 examples/extlibs/blake3_basic.expected.txt。从仓库根目录可直接运行 release/xl.exe run release/extlibs/blake3/examples/basic.c，无需额外源文件参数。

验证范围与来源

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

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

2026-10-18：文件哈希的 Reader 关闭失败红绿负例、Windows 严格 C/JIT 与 Linux ASan/UBSan/XLang 双语联合门禁通过。当前完整 AOT 构建缺主线 xl6NativeHandleTraceLeaf，不签收发布级。

2026-10-20：C 单文件范例直接运行及生成可执行文件均通过官方向量对照；Windows 门禁可加 -SkipAot 独立复验 C/JIT，Linux ASan/UBSan 和 XLang 双语门禁通过。完整 XLang AOT 与私有接管构造器访问边界仍待主线修复。

2026-10-21：完整教学范例的文件哈希改用独占临时目录并在 finally 清理；完整 XLang JIT 范例通过。Windows 门禁隔离本次工作目录，Linux 使用 mktemp；Windows -SkipAot 与 Linux C ASan/UBSan、XLang、双语对照通过。默认 Windows AOT 仍缺 xl6NativeHandleTraceLeaf，包外私有句柄构造器仍被 xl check 错误放行，不签收发布级。