Table of Contents

记录布局与 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 判例——旧论断已推翻)。

反模式

  1. 文件内私定魔数字面量——进 RecordMagic 登记表,撞数让编译期报错兜底。
  2. 按记忆手写 Flags 算术和——查 RecordFlags 位表 + 各头 DefaultFlags(ValidEquals 强校验)。
  3. 手写 CRC64 用 zlib 多项式——Tier 的 CRC64 是 ECMA-182,对不上盘上校验。
  4. 手写偏移/尺寸常量复制布局——引生成 codec 派生,格式漂移静默破坏由生成物拦截。

源码:Layout/(RecordMagic / RecordFlags / Crc32Footer / Crc64Footer)。