第 19 章：验证器规范
验证器用于判断 VFP 是否符合本规范。验证结果应至少区分 Fatal、Error、Warning 与 Info：Fatal 表示无法继续解析；Error 表示资产不合规；Warning 表示可忽略的缓存或前向兼容问题；Info 用于统计和诊断。
19.1 必须验证的层级
| 层级 | 必须检查 |
|---|---|
| 容器 | Header、Footer、版本、文件长度、对齐、保留字段 |
| Directory | DIR0 结构、Entry 长度、Offset、范围、交叠、CRC32 |
| 权威数据 | META、PAL0、CHIX、VOX0 的存在性、唯一性、字段与跨区段关系 |
| 内容 | Palette 引用、Chunk 尺寸、体素容量、非空统计、RLE 展开 |
| 完整性 | 各 Payload CRC32、Directory CRC32、Source Hash |
| 缓存 | Source Hash、Chunk 引用和内部范围；THMB 还验证 PNG signature、IHDR、尺寸和 RGBA8 格式；失败可降级 |
19.2 验证顺序
验证器必须按依赖顺序执行：
- 获取真实文件长度；
- 验证 Header 和 Footer；
- 定位、读取并验证 DIR0；
- 验证所有 Directory Entry 范围和 CRC32；
- 解析 META、PAL0、CHIX；
- 解析并验证全部 VOX0；
- 重新计算统计和 Source Hash；
- 验证可选区段，记录可降级错误；
- 输出结构化结果。
不能在未验证 Directory 前信任任一 Offset。不能在未验证 PAL0 和 CHIX 前完整验证 VOX0。
19.3 最低错误代码
实现应至少输出以下稳定错误代码：
| Code | 等级 | 含义 |
|---|---|---|
VFP_HEADER_MAGIC | Fatal | Header Magic 无效 |
VFP_FOOTER_INVALID | Fatal | Footer 无效或无法定位 Directory |
VFP_DIRECTORY_RANGE | Fatal | Directory 或 Payload 范围越界/交叠 |
VFP_CRC_MISMATCH | Error | Directory 或 Payload CRC32 不匹配 |
VFP_REQUIRED_SECTION | Error | 缺少或重复权威区段 |
VFP_CHUNK_MAPPING | Error | CHIX 与 VOX0 映射不一致 |
VFP_PALETTE_INDEX | Error | VOX0 引用未定义 Palette Index |
VFP_VOXEL_ENCODING | Error | RAW8/RLE8 数据不合法 |
VFP_SOURCE_HASH | Error | META Source Hash 不匹配 |
VFP_CACHE_STALE | Warning | 缓存 Hash 不匹配或不可用 |
VFP_UNKNOWN_OPTIONAL | Warning | 未知可选 Tag/Flag/Codec 被忽略 |
19.4 验证结果
验证器应报告文件版本、资产 UUID、网格尺寸、Chunk 数、非空体素数、Palette 数、有效缓存数、错误列表和警告列表。检测到 Error 或 Fatal 时，结果必须标记为 valid = false；只有 Warning 时可标记为 valid = true, degraded = true。
本章总结
验证器不是只检查能否打开文件，而是检查文件能否被无歧义、安全且可重建地解释。权威数据错误必须失败，缓存错误可以降级。