RuView BFLD 线缆帧格式与隐私分级线缆协议深度解析：86 字节定长头、分区载荷与确定性序列化

本指南以 ADR-119 为核心主体，系统拆解 RuView 中 BFLD（Beamforming Feedback Layer for Detection，基于 802.11 压缩波束成形反馈信息的 WiFi 感知层）在物理链路上传输的 BfldFrame 格式：字段级字节布局、隐私分级门控、CRC 校验与错误语义，并结合 wifi-densepose-bfld crate 的 frame.rs、payload.rs 与全套接受性测试逐一印证。读完你不仅能手工解析/构造一帧 BFLD 数据，还能理解「确定性序列化 + 字节级隐私分类」这套可审计、可 witness 校验的线缆协议设计取舍，并可直接把 BfldFrameHeader 与 BfldPayload 的 API 用于自己的 MQTT / ESP-NOW 传输实现。

---

1. 设计背景：为什么 BFLD 需要一份专属线缆格式

BFLD 是 ADR-118 定义的伞形决策下的数据管线：源节点（捕获 802.11 压缩波束成形反馈信息 BFI 的设备）通过线缆下发 BfldFrame，被 RuView 聚合器、Home Assistant 桥（ADR-122）以及 witness 证据包消费。ADR-119 为这条链路提出了五条刚性约束：

#	目标	含义
1	确定性（Deterministic）	相同输入 ⇒ 逐位相同输出，witness 哈希才能跨验证存活（沿用 ADR-028 的证明模式）
2	自描述（Self-describing）	帧头带 magic + version，未来 BFLD 版本演进不会静默污染聚合器状态
3	字节级隐私分级（Privacy-classified at byte level）	接收方在解析 payload 之前就必须知道数据类别，可以丢弃自己无权处理的数据
4	紧凑（Compact）	BFLD 节点最高以 10 Hz 发射，帧体必须小到能塞进不分片的 MQTT 与 ESP-NOW 传输
5	字节序稳定（Endianness-stable）	捕获侧横跨 x86_64（ruvultra）、aarch64（cognitum-v0、Pi 5 集群）与 Xtensa（ESP32-S3），三者必须产出逐字节一致的流

格式的最接近先例是 ADR-095 中定义的 rvCSI CsiFrame。BFLD 沿用了同一套 little-endian 约定，以及同一套「先校验、后 FFI 暴露」的姿势。

---

2. BfldFrame 帧头：86 字节定长、packed、little-endian

2.1 帧头结构定义

ADR-119 §2.1 给出的参考定义如下（Rust）：

#[repr(C, packed)]
pub struct BfldFrameHeader {
    pub magic: u32,              // 0xBF1D_0001
    pub version: u16,            // 1
    pub flags: u16,              // bit0=has_csi_delta, bit1=privacy_mode, bit2-15 reserved
    pub timestamp_ns: u64,       // monotonic capture clock

    pub ap_hash: [u8; 16],       // BLAKE3-keyed(site_salt, ap_mac)[0..16]
    pub sta_hash: [u8; 16],      // BLAKE3-keyed(site_salt ‖ day_epoch, sta_mac)[0..16]
    pub session_id: [u8; 16],    // ephemeral, rotated on capture-session boundary

    pub channel: u16,            // 802.11 channel number
    pub bandwidth_mhz: u16,      // 20 | 40 | 80 | 160
    pub rssi_dbm: i16,
    pub noise_floor_dbm: i16,

    pub n_subcarriers: u16,
    pub n_tx: u8,
    pub n_rx: u8,
    pub quantization: u8,        // 0=f32, 1=i16, 2=i8, 3=packed (4-bit nibbles)
    pub privacy_class: u8,       // 0=raw, 1=derived, 2=anonymous, 3=restricted (default 2)

    pub payload_len: u32,
    pub payload_crc32: u32,      // CRC-32/ISO-HDLC over payload bytes only
}

一个重要的勘误：早期草案把帧头写成「40 字节」，那是一次计数错误，在 P1 脚手架阶段被实现捕获并修正。实际 packed 布局为 86 字节，由 frame.rs 中 static_assertions::const_assert_eq!(core::mem::size_of::<BfldFrameHeader>(), BFLD_HEADER_SIZE) 在编译期强制锁定（见下文 AC1）。

2.2 逐字节偏移推导

从 frame.rs 的 from_le_bytes 解析逻辑，可以精确还原每个字段的字节偏移：

字段	类型	起始偏移	长度	语义
magic	u32 LE	0	4	0xBF1D_0001，见 §5
version	u16 LE	4	2	布局主版本，当前 1
flags	u16 LE	6	2	bit0=has_csi_delta、bit1=privacy_mode，其余保留
timestamp_ns	u64 LE	8	8	单调时钟纳秒时间戳
ap_hash	[u8;16]	16	16	BLAKE3-keyed(site_salt, ap_mac) 前 16 字节
sta_hash	[u8;16]	32	16	BLAKE3-keyed(site_salt‖day_epoch, sta_mac) 前 16 字节，按日轮换
session_id	[u8;16]	48	16	临时会话标识，捕获会话边界轮换
channel	u16 LE	64	2	802.11 信道号
bandwidth_mhz	u16 LE	66	2	20 / 40 / 80 / 160
rssi_dbm	i16 LE	68	2	接收信号强度（dBm）
noise_floor_dbm	i16 LE	70	2	噪声底（dBm）
n_subcarriers	u16 LE	72	2	OFDM 子载波数
n_tx	u8	74	1	发射天线数
n_rx	u8	75	1	接收天线数
quantization	u8	76	1	0=f32，1=i16，2=i8，3=packed（4-bit nibble）
privacy_class	u8	77	1	0=raw，1=derived，2=anonymous，3=restricted
payload_len	u32 LE	78	4	payload 字节长度
payload_crc32	u32 LE	82	4	仅覆盖 payload 的 CRC-32/ISO-HDLC

需要强调两点实现细节：

• 哈希字段设计：ap_hash / sta_hash 均不是明文 MAC，而是 keyed BLAKE3 的前 16 字节截断。ap_hash 以站点级盐 site_salt 作为 key；sta_hash 以 site_salt ‖ day_epoch 作为 key，从而做到「跨站点、跨天不可关联」（配合 ADR-120 的哈希轮换策略）。
• flags 位图的实现演进：frame.rs 中实际注册了三个位：HAS_CSI_DELTA = 1<<0、PRIVACY_MODE = 1<<1、SELF_ONLY = 1<<3（后者面向 ADR-123 §2.5 的 ESP32-S3 自供模式，不携带 identity_risk_score）。未知名位必须原样往返（round-trip），KNOWN_FLAGS_MASK / RESERVED_FLAGS_MASK 为此提供了前向兼容检查工具——这正是 ADR-119「保留位锁定未来扩展顺序」消极后果的落地形态。

2.3 无 unsafe 的序列化与反序列化

由于 #[repr(C, packed)] 会带来非对齐访问问题，crate 刻意禁止 unsafe，并改用显式的 to_le_bytes() / from_le_bytes() 手工编码，编码后的字节流即规范线缆形态。构造帧时使用 BfldFrameHeader::empty()（自动填好 magic 与 version），其余字段由调用方填充：

let mut h = BfldFrameHeader::empty();
h.flags = flags::HAS_CSI_DELTA;
h.timestamp_ns = 1_700_000_000_000_000_000;
h.channel = 36;
h.bandwidth_mhz = 80;
h.n_subcarriers = 234;
h.n_tx = 2;
h.n_rx = 2;
h.quantization = 1;
h.privacy_class = 2; // anonymous

上述写法与 frame_roundtrip.rs 中的测试样本完全一致：to_bytes() 后整帧长度严格等于 BFLD_HEADER_SIZE + payload.len()（86 + 载荷字节数）。

---

3. Payload：定序分区 + 长度前缀 + 统一 CRC 域

3.1 六段固定顺序

Payload 是一串「长度前缀 + 字节体」的类型化分区序列，分区顺序固定：

payload = compressed_angle_matrix
        ‖ amplitude_proxy
        ‖ phase_proxy
        ‖ snr_vector
        ‖ optional_csi_delta            (present iff flags.bit0 set)
        ‖ optional_vendor_extension     (length 0 allowed)

每个分区编码为 [u32 len_le][bytes...]。要点：

• 前四段（压缩波束角度矩阵、幅度代理、相位代理、SNR 向量）与 vendor 扩展段恒在场（vendor 允许长度为 0）；
• CSI 增量段（csi_delta）仅当帧头 flags 的 bit0（HAS_CSI_DELTA）置位时出现，置位 0 时整段省略；
• CRC32 覆盖所有分区字节、包含长度前缀，但不覆盖帧头。

源码 payload.rs 的 wire_len 展示了精确的线上长度公式：

n = 4字节前缀 × 5（4 个必选段 + vendor）
  + compressed_angle_matrix.len()
  + amplitude_proxy.len()
  + phase_proxy.len()
  + snr_vector.len()
  + vendor_extension.len()
  (+ 4字节前缀 + csi_delta.len()，仅当 HAS_CSI_DELTA 置位)

测试 payload_sections.rs 印证：BfldPayload::default() 空载荷编码后恰好是 5 × 4 = 20 个全零字节（5 个零长前缀分区），并能无损往返；声明了 1000 字节但缓冲区只有 14 字节的分区会触发 MalformedSection。

3.2 分段 CRC 的正确语义

分段 CRC 存在一个容易搞错的细节：CRC 作用域是「分区前缀 + 分区体」串接后的整段 payload 字节。在 frame.rs 中，BfldFrame::from_payload(header, payload) 先把类型化的 BfldPayload 走 to_bytes() 压成字节，再交给 BfldFrame::new——后者自动同步 payload_len 与 payload_crc32，因此 CRC 天然覆盖了带前缀的规范线缆字节。BfldFrame::to_bytes() 每次序列化都会重算 CRC，即使调用方手动污染过 header.payload_crc32，输出依然内部自洽。

---

4. 隐私分级门控：序列化即执行，越界即报错

4.1 四个隐私类（字节值即语义）

lib.rs 用 #[repr(u8)] 枚举定义了四个级别，数字序即「身份信息含量」序：

值	类	语义
0	Raw	本地研究数据，含原始 BFI 矩阵，永不联网（结构性不变量 I1）
1	Derived	需操作者确认的局域网研究模式：角度下采样到 8-bit、top-k 子载波，身份字段可用（Soul Signature 部署所需）
2	Anonymous（生产默认）	仅聚合感知，不含任何身份派生字段
3	Restricted	养老/受监管场景：类 2 基础上进一步抑制 identity_risk_score 与哈希

4.2 序列化前的分区门控规则

序列化器在写入任何 payload 字节之前强制执行下列规则：

privacy_class	compressed_angle_matrix	身份派生字段	说明
0 (raw)	完整	完整	仅限本地，绝不序列化到网络 sink
1 (derived)	下采样至 8-bit、top-k 子载波	完整	操作者确认的研究模式
2 (anonymous, 默认)	缺失（零长分区）	缺失	生产默认
3 (restricted)	缺失	缺失 + 仅诊断	等价类 2，并在总线上抑制 identity_risk_score

4.3 Sink 标记 trait：把「类 0 不许上线」编译进类型系统

ADR-119 只要求结构上禁止类 0 走网络 sink；实现把这条规则做成了sink 类型标记 trait（sink.rs）：

Sink trait	MIN_CLASS	可接受类
LocalSink	Raw	0, 1, 2, 3
NetworkSink	Derived	1, 2, 3
MatterSink（也是 NetworkSink）	Anonymous	2, 3

每个输出目的地（内存缓冲、MQTT topic、Matter cluster）实现且只实现其中一个 trait，并通过常量 Sink::MIN_CLASS 声明其愿意接受的最低类。运行时闸门是一次简单的 >= 比较——因为类号越大身份信息越少，接受 MIN_CLASS 的 sink 天然接受所有更高编号类：

pub fn check_class<S: Sink>(class: PrivacyClass) -> Result<(), BfldError> {
    if class.as_u8() >= S::MIN_CLASS.as_u8() {
        Ok(())
    } else {
        Err(BfldError::PrivacyViolation { reason: S::KIND })
    }
}

于是「类 0 帧通过 NetworkSink::publish()」在调用点就返回 Err(BfldError::PrivacyViolation)——对应接受性标准 AC3。Matter 边界只放行类 2/3，与 ADR-122 §2.4 的 cog-ha-matter 过滤一致（PrivacyClass::allows_matter() 只对 Anonymous | Restricted 返回 true）。

4.4 PrivacyGate：单向降级（demote），永不提升

帧在生命周期内只会「信息量递减」。privacy_gate.rs 提供唯一合法的转换入口 PrivacyGate::demote(frame, target)：

1. 断言目标类号 ≥ 当前类号——从 Derived(1) 降到 Anonymous(2) 合法；反向 Attempt 提升会得到 BfldError::InvalidDemote；
2. 按目标类清零不允许出现的分区体（使用 black_box 守卫的循环抵御死存储消除，随后 clear()）：
   • 目标 ≥ Anonymous：清零 compressed_angle_matrix 与 csi_delta；
   • 目标 ≥ Restricted：再清零 amplitude_proxy 与 phase_proxy；
   • snr_vector 与 vendor_extension 始终保留；
3. 重同步 header.privacy_class 与 payload_crc32，返回新帧。

设计上不存在 promote——分区一旦清零，原始字节不可恢复。测试 privacy_gate_demote.rs 逐条验证了「同类的降级是恒等操作」「Derived→Anonymous 剥离角度矩阵」「Derived→Restricted 连幅度/相位一起剥离」等行为。

---

5. 确定性序列化：三大约束与测试证据

ADR-119 §2.4 给出确定性序列化的三条保证：

1. 字段顺序固定：由 #[repr(C, packed)] 保证；
2. 浮点量化规范：quantization 字节 1/2/3 使用规定的 round-half-to-even + 文档化的饱和策略；f32（值 0）在线上被禁止（仅本地）；
3. CRC32 最后计算：所有分区字节落位之后才计算，避免 header 重写。

实现层面还叠加了一条重要事实：编码全程不使用 unsafe（crate 内禁止），全部通过 to_le_bytes / from_le_bytes 助手完成——编码后的字节即规范线缆形态，天然规避了 #[repr(C, packed)] 的结构体 padding 在不同编译器/目标间的差异。

测试证据（仓库内可复现）：

• frame_roundtrip.rs 的 frame_serialization_is_deterministic：同一帧两次 to_bytes() 逐字节相等；
• pipeline_determinism.rs：验证两条配置+盐+输入流完全相同的管线产出逐字节一致的 event JSON——这是跨 BFLD 版本做 replay 回归测试的前提（对应 ADR 中「200 帧 BFI fixture 多次序列化后 BLAKE3 位级一致」witness 测试的管线级版本）；
• 平台稳定性：帧头结构体在 x86_64 / aarch64 / xtensa-esp32s3 上的 packed 尺寸一致，由编译期 const_assert_eq! + 运行期测试 frame_header_size.rs 双重把关。

由于序列化是 #[no_std] 兼容的（见 §6），同一套头编码逻辑未来可以直接跑在 ESP32-S3 上（当 ADR-123 P2 加入 ESP-NOW 传输时），跨架构字节一致性正是 witness 哈希能存活验证的前提。

---

6. Magic 值选择：让 hexdump 自己开口说话

0xBF1D_0001 的取值逻辑：小端 hexdump 中 bf1d 读起来接近 "BFLD"，方便 wireshark / xxd 调试时肉眼识别；末尾的 0001 是主版本号——不兼容的布局变更才 bump magic 主版本，次版本演进则只动 version 字段。对应常量 BFLD_MAGIC 与 BFLD_VERSION 都定义在 frame.rs，并被测试 frame_header_size.rs 的 magic_reads_as_bfld_in_hex、version_is_one 锁定。

无 magic（或变宽 magic）被否决的原因是：在共享传输上，接收方必须能区分 BFLD 帧与 rvCSI CsiFrame 及其它 RuView 载荷（见 §7 Alt 3）。

---

7. 校验、错误语义与安全边界

接收路径的防御是分层的。BfldFrame::from_bytes 执行完整校验链，任一环节失败即返回对应 BfldError（lib.rs），且不会暴露部分解析的 payload 状态：

错误	触发条件	对应 AC
InvalidMagic(u32)	前 4 字节不是 0xBF1D_0001	—
UnsupportedVersion(u16)	version 非当前支持的 1	—
TruncatedFrame {got, need}	缓冲区 < 86 字节，或 < 86 + 声明 payload_len	—
Crc {expected, actual}	重算 CRC 与帧头 payload_crc32 不符	AC4
MalformedSection {offset, reason}	分区长度前缀越界 / 分区体越出缓冲 / vendor 段后残留字节	AC6
PrivacyViolation {reason}	类 0 帧尝试发布到 NetworkSink / 更严格 sink	AC3
InvalidPrivacyClass(u8)	类字节不在 0..=3	—
InvalidDemote {from, to}	尝试把帧「升级」回更高信息含量	—

几个容易踩坑的边界，全部有测试背书：

• CRC 失配：翻转 payload 中任一字节，from_bytes 返回 Err(BfldError::Crc)，测试 frame_roundtrip.rs 显式断言 expected != actual；
• 空 payload 合法：CRC 算法（CRC-32/ISO-HDLC：poly 0xEDB88320、init 0xFFFFFFFF、xorout 0xFFFFFFFF、reflected，与以太网/zlib 相同）对空缓冲的校验值为 0x00000000，空载荷可无损往返；
• flag 与分区的对齐：csi_delta 段与 flags.bit0 必须一致。payload_sections.rs 证明：用带 CSI delta 的载荷按「无 CSI delta」解析时，多余字节会触发 vendor 段后的 trailing-bytes 守卫；而 frame_payload_integration.rs 验证 BfldFrame::from_payload 会根据 csi_delta.is_some() 自动置位/清位 HAS_CSI_DELTA，保证编码器侧不会产生错位帧。

---

8. 采用后果（Consequences）盘点

积极后果

• MTU 友好：86 字节定长帧头 + 紧凑分区载荷，即便 4×4 MIMO、256 子载波的高密度配置也能舒适地装入 1500 字节 MTU 内不分片传输（注：ADR 正文「40-byte header」属于计数错误的遗留表述，实际 86 字节）；
• #[no_std] 兼容：序列化路径不依赖堆与标准库，同一套代码未来可直接运行在 ESP32-S3 上（ADR-123 P2 的 ESP-NOW 传输）。当前完整的 BfldFrame（含 Vec<u8> payload）与类型化 BfldPayload 仍 gated 在 std feature 下，零拷贝的 BfldFrameRef 变体规划随 ESP32-S3 self-only 适配一起落地；
• Witness 集成直接：archive/v1 中既有的 expected-hash 校验文件格式可以平移到 bfld_verify.py，消费同一套 SHA-256 期望哈希文件格式（ADR-028 证明模式）。

消极后果

• #[repr(C, packed)] 要求消费方使用 read_unaligned（实现上通过先拷贝局部变量再编码来规避非对齐借用告警，代码注释亦注明 #[derive(BfldFrameAccess)] proc-macro 是后续的缓解路径）；
• 保留 flag 位（bit2–15）锁定了未来扩展顺序，任何新位赋值都是一次版本 bump（实现中 bit3 已被 SELF_ONLY 占用，见 frame.rs flags 模块）。

中性后果

• vendor 扩展分区允许下游 RuView cog（如 cog-pose-estimation）在不改帧头的情况下附加元数据，代价是 CRC 作用域扩张；vendor 分区明确处于 witness 哈希之外。

---

9. 备选方案回顾：为什么不用 Protobuf / CBOR

备选	结论	否决理由
Protobuf / FlatBuffers	否决	schema 演进开销；witness 哈希跨 protoc 版本不稳定；对大量小尺寸固定形状字段约有 ~3× 线缆膨胀
CBOR	否决	确定性 CBOR（RFC 8949 §4.2）可行，但解析面大，no_std 的 ESP32 路径上 tag 处理是陷阱
变宽 magic / 无 magic	否决	共享传输上接收方必须区分 BFLD 帧与 rvCSI CsiFrame 及其它 RuView 载荷
CRC32 挪进帧头	否决	CRC 必须在 payload 之后计算，否则其值会迫使帧头重写；置于尾部避免缓冲回传（buffer-pass-back）

---

10. 接受性标准与仓库内的测试映射

ADR-119 处于 Proposed 状态，勾选框尚未勾选；下表逐条映射到本仓库源码/测试中可验证的实现证据：

AC	验收内容	仓库内验证点
AC1	BfldFrameHeader 在 x86_64 / aarch64 / xtensa-esp32s3 上 packed 尺寸恰为 86 字节（草案 40 字节系计数错误）	frame.rs 的 const_assert_eq!（编译期）+ frame_header_size.rs（CI 运行期，附带可读报错）
AC2	固定 fixture 的 1,000 次序列化产出位级一致的 BLAKE3	frame_roundtrip.rs 确定性测试 + pipeline_determinism.rs 跨管线确定性
AC3	类 0 帧经 NetworkSink::publish() 返回 Err(PrivacyViolation)	sink.rs 的 check_class 与 sink trait 层次
AC4	payload CRC 失配令 parse() 返回 Err(Crc)，且不暴露部分 payload	frame.rs from_bytes + frame_roundtrip.rs CRC 翻转测试
AC5	序列化/解析往返完整保留所有帧头字段	frame_roundtrip.rs frame_roundtrip_preserves_header_and_payload
AC6	flags.bit0=0 时出现意外 CSI-delta 分区被拒绝	payload.rs trailing-bytes 守卫 + payload_sections.rs
AC7	序列化吞吐 ≥ 50k 帧/秒（2025 年代 M1/M2 / Pi 5 单核）	基准目标（bench 基线见仓库 benchmark_baseline.json 同族度量约定）

---

11. 扩展视角：Python 绑定与生态对接

线缆格式的上游是帧的生产/消费，下游则有 Python 生态接入。仓库 python/tests/test_bfld.py（ADR-117 P3.5）锁定了 BfldKind / BfldFrame / BfldReport 的 Python 面——例如 HE 模式的子载波数断言（HE20=242、HE40=484、HE80=996、HE160=1992），与 python/src/bindings/bfld.rs 的 Rust 绑定相对应。这在未来把真实 Rust 摄入 crate 无缝切入 Python 面时保持非破坏性。

若你想动手验证整条隐私门控管线，可直接运行 crate 自带的端到端示例：

# 在 v2 Rust 工作区内执行（crate 位于 v2/crates/wifi-densepose-bfld）
cargo run -p wifi-densepose-bfld --example bfld_minimal

该示例（examples/bfld_minimal.rs）演示了操作者视角的完整流程：构造带 SignatureHasher 的 BfldPipeline、喂入一份 SensingInputs + IdentityEmbedding、输出一行 privacy_class = "anonymous" 的 JSON event。

---

12. 参考资料与深入阅读路径

• 上游决策：ADR-118 BFLD 总决策（§2 umbrella decision）、ADR-119 本协议
• 隐私细化：ADR-120 隐私类与哈希轮换（类语义、SELF_ONLY 门控、PrivacyGate）、ADR-122 BFLD-HA-Matter 暴露（Matter 边界仅收类 2/3）、ADR-123 捕获路径（nexmon/ESP32）
• 先例与证明：ADR-095 rvCSI CsiFrame、ADR-028 witness/确定性证明
• 核心实现：v2/crates/wifi-densepose-bfld（frame.rs、payload.rs、sink.rs、privacy_gate.rs、lib.rs）
• 测试套件：v2/crates/wifi-densepose-bfld/tests/ 下的 frame_header_size.rs、frame_roundtrip.rs、payload_sections.rs、frame_payload_integration.rs、privacy_gate_demote.rs、pipeline_determinism.rs
• 依赖与标准：CRC-32/ISO-HDLC（crc crate，与以太网同多项式）、BLAKE3 keyed 模式（blake3 crate）、IEEE 802.11-2020 §19.3.12（Compressed Beamforming Report，角度矩阵的行业来源）

综上，BFLD 线缆协议的核心是可验证的最小设计：repr(C, packed) 固定字段顺序、显式 LE 编码消除平台差异、分区定序 + 尾部 CRC 让校验在暴露任何状态前完成、sink 标记 trait 把隐私边界推进到类型系统、而 CRC 与 magic 又把「错误帧」挡在解析之外。对于任何需要在资源受限的感知节点与聚合端之间传输既紧凑又可审计传感数据的设计者而言，这份 ADR 连同其实现都是一个可以直接借鉴的完整样本。