跳到主要内容

第 16 章：Source Hash

Source Hash 是当前权威资产内容的 SHA-256 摘要。它用于判断缓存、预览或外部索引是否仍对应当前 META、PAL0、CHIX 和 VOX0。它不是文件整体 Hash，不覆盖 Header、Footer、Directory 排列、填充、UUID 或缓存。

16.1 规范化输入​

哈希输入按以下顺序拼接：

UTF-8 bytes: "VFP-SOURCE-1.3\0"
META 128 bytes, but sourceHash field [64,96) replaced with 32 zero bytes
PAL0 decoded RAW8 payload bytes
CHIX decoded RAW8 payload bytes
for each CHIX Entry in ascending chunkId:
    VOX0 canonical bytes = 32-byte VOX0 Header + decoded RAW8 palette-index array

这里的 “decoded RAW8 palette-index array” 指无论 VOX0 内部使用 RAW8 还是 RLE8，都展开为长度等于 voxelCapacity 的 Palette Index 数组。VOX0 Header 的 voxelCodec 字段在规范化输入中必须改写为 0，voxelDataLength 改写为 voxelCapacity，其余字段保持不变。这样不同压缩选择不会改变同一资产的 Source Hash。

META、PAL0、CHIX 均要求 RAW8；若未来允许它们使用压缩，输入仍必须是解码后的规范 Payload 字节。

16.2 计算与存储​

写入器必须在所有权威区段最终确定后计算 SHA-256，将 32 字节结果写入 META 的 sourceHash。随后再写入所有缓存和预览，使它们记录或引用该值。

任何以下变化均必须导致 Source Hash 重新计算：网格尺寸、Chunk 切分、Palette 映射、任一 Palette 属性、任一 VOX0 Palette Index、Chunk ID 或 Chunk 坐标变化。仅改变 VBUF、MSH0、PRVW、THMB、Directory 排列、文件 UUID、生成器 UUID 或 Footer 时不得改变它。

16.3 校验与使用​

验证器必须按 16.1 重新构造输入并比较完整 32 字节结果。缓存只能在其记录的 Hash 与 META 的 Hash 完全一致时使用。使用前缀 Hash 的轻量区段至少必须比对规范规定的前缀长度；若存在完整 Hash，应优先比较完整值。

Source Hash 校验失败表示权威数据自身不一致或文件被错误修改，必须使资产无效；缓存 Hash 不匹配仅表示缓存过期，应被丢弃。

本章总结​

Source Hash 为“同一资产的权威内容”提供与物理文件布局无关的稳定身份，是 VFP 缓存可安全复用的基础。