记录布局与 CRC 契约(Layout/)
RecordMagic(魔数登记表)
全部跨格式/跨产品的魔数唯一真源——[ConstantRegistry] 判重(KTSG040 重复值编译期报错)。
- 新建格式魔数先查表再登记(重复即编译红);消费方一律引
RecordMagic.Xxx常量, 禁文件内私定字面量。现行族(抽样):BRHD(BlittableRing)/ VRHD(VarKeyRing)/ LMHD·RMHD (Log/Ring meta)/ PIHD·PIFT(索引帧)/ TC_SEGTU(段元组)/ WLHD(TierWAL opaque)/ TKV1(Kv 版本 opaque)/ TBB1·THB1·TZB1·TSE2(备份流)/ TTS1·TTS2(envelope)。 - 判例:Set 备份流与 SetEnvelope 曾撞数 TSE1——修复后 Set 备份 = TSE2(撞数由登记表编译期拦截)。
RecordFlags(旗标位表)
跨格式共享的 flags 位语义(FLAG_CRC32C 0x03 / FLAG_CRC_IN_FOOTER 0x04 / FLAG_PAYLOAD_2B 0x08 / FLAG_META_STANDALONE 0x40 + bits8-11 codecId + 状态位 bits12+)——位定义唯一真源;
各格式头的 DefaultFlags = 位算术组合(如 LogMeta/RingMeta = 0x4F,盘上 ValidEquals
强校验)。外部解析器以位表组合口径为准,勿抄历史文档的算术和。
CRC Footer(Crc32Footer / Crc64Footer)
- CRC64 = ECMA-182(多项式
0x42F0E1EBA9EA3693、init 0、无异或输出)——不是 zlib/ISO 常见约定; - CRC32C = 标准 Castagnoli(init 0xFFFFFFFF、final XOR 0xFFFFFFFF)。
- Footer 布局随格式(12B/28B 等)——见 binary-format-spec 分册。
[BinaryLayout] 消费契约
Contracts 的记录结构体标注 [BinaryLayout] → KernLab.Loom.Layout 编译期生成 Codec
(StructSize/Size_*/Offset_*/Read__*/Write__*):
- 尺寸常量从生成物派生(
XxxCodec.StructSize)——禁 const 复制布局值(第六次纠偏判例); - 零手写字节序——单字段取值/写入也是生成器的活(
Features = All的 Read/Write 族, 第七次纠偏判例);struct 自身方法同样零手写; - CRC 字段位置/覆盖范围进布局声明走
Offset_*(第五次纠偏判例); - 生成属性不可进 const 表达式 → 引生成
StructSize常量(ClusterConfig 判例——旧论断已推翻)。
反模式
- 文件内私定魔数字面量——进
RecordMagic登记表,撞数让编译期报错兜底。 - 按记忆手写 Flags 算术和——查
RecordFlags位表 + 各头DefaultFlags(ValidEquals 强校验)。 - 手写 CRC64 用 zlib 多项式——Tier 的 CRC64 是 ECMA-182,对不上盘上校验。
- 手写偏移/尺寸常量复制布局——引生成 codec 派生,格式漂移静默破坏由生成物拦截。
源码:Layout/(RecordMagic / RecordFlags / Crc32Footer / Crc64Footer)。