ADR-081: Layer 3 mesh plane + Rust mirror trait — all 5 layers landed

Fully implements the remaining deferred pieces of the adaptive CSI mesh
firmware kernel. All 5 layers (Radio Abstraction, Adaptive Controller,
Mesh Sensing Plane, On-device Feature Extraction, Rust handoff) are
now implemented and host-tested end-to-end.

Layer 3 — Mesh Sensing Plane (firmware/esp32-csi-node/main/rv_mesh.{h,c}):
  * 4 node roles: Unassigned / Anchor / Observer / FusionRelay / Coordinator
  * 7 message types: TIME_SYNC, ROLE_ASSIGN, CHANNEL_PLAN,
    CALIBRATION_START, FEATURE_DELTA, HEALTH, ANOMALY_ALERT
  * 3 auth classes: None / HMAC-SHA256-session / Ed25519-batch
  * Payload types: rv_node_status_t (28 B), rv_anomaly_alert_t (28 B),
    rv_time_sync_t (16 B), rv_role_assign_t (16 B),
    rv_channel_plan_t (24 B), rv_calibration_start_t (20 B)
  * 16-byte envelope + payload + IEEE CRC32 trailer
  * Pure rv_mesh_encode()/rv_mesh_decode() plus typed convenience encoders
  * rv_mesh_send_health() + rv_mesh_send_anomaly() helpers

Controller wiring (adaptive_controller.c):
  * Slow loop (30 s default) now emits HEALTH
  * apply_decision() emits ANOMALY_ALERT on transitions to ALERT /
    DEGRADED
  * Role + mesh epoch tracked in module state; epoch bumps on role
    change

Layer 5 — Rust mirror (crates/wifi-densepose-hardware/src/radio_ops.rs):
  * RadioOps trait mirrors rv_radio_ops_t vtable
  * MockRadio backend for offline tests
  * MeshHeader / NodeStatus / AnomalyAlert types mirror rv_mesh.h
  * Byte-identical IEEE CRC32 (poly 0xEDB88320) verified against
    firmware test vectors (0xCBF43926 for "123456789")
  * decode_mesh / decode_node_status / decode_anomaly_alert / encode_health
  * 8 unit tests, including mesh_constants_match_firmware which asserts
    MESH_MAGIC/VERSION/HEADER_SIZE/MAX_PAYLOAD match rv_mesh.h
    byte-for-byte
  * Exported from lib.rs
  * signal/ruvector/train/mat crates untouched — satisfies ADR-081
    portability acceptance test

Tests (all passing):
  test_adaptive_controller:   18/18   (C, decide() 3.2 ns/call)
  test_rv_feature_state:      15/15   (C, CRC32 87 MB/s)
  test_rv_mesh:               27/27   (C, roundtrip 1.0 µs)
  radio_ops::tests (Rust):     8/8
  --- total:                 68/68 assertions green ---

Docs:
  * ADR-081 status flipped to Accepted
  * Implementation-status matrix updated; L3 + Rust mirror both
    marked Implemented
  * Benchmarks table extended with rv_mesh encode+decode roundtrip
  * Verification section updated with cargo test invocation
  * CHANGELOG: two new entries for L3 mesh plane + Rust mirror

Remaining follow-ups (Phase 3.5 polish, not blocking):
  * Mesh RX path (UDP listener + dispatch) on the firmware
  * Ed25519 signing for CHANNEL_PLAN / CALIBRATION_START
  * Hardware validation on COM7
This commit is contained in:
Claude
2026-04-19 03:57:18 +00:00
parent d53e29506e
commit 8dfb031cb3
12 changed files with 1633 additions and 39 deletions
+32
View File
@@ -64,6 +64,38 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
checks for adaptive controller boot line, mock radio ops
registration, and slow-loop heartbeat, so QEMU runs regression-gate
Layer 1/2 presence.
- **Firmware: ADR-081 Layer 3 mesh sensing plane** — New
`firmware/esp32-csi-node/main/rv_mesh.{h,c}` defines 4 node roles
(Anchor / Observer / Fusion relay / Coordinator), 7 on-wire message
types (TIME_SYNC, ROLE_ASSIGN, CHANNEL_PLAN, CALIBRATION_START,
FEATURE_DELTA, HEALTH, ANOMALY_ALERT), 3 authorization classes
(None / HMAC-SHA256-session / Ed25519-batch), `rv_node_status_t`
(28 B), `rv_anomaly_alert_t` (28 B), `rv_time_sync_t`,
`rv_role_assign_t`, `rv_channel_plan_t`, `rv_calibration_start_t`.
Pure-C encoder/decoder (`rv_mesh_encode()` / `rv_mesh_decode()`) with
16-byte envelope + payload + IEEE CRC32 trailer; convenience encoders
for each message type. Controller now emits `HEALTH` every slow-loop
tick (30 s default) and `ANOMALY_ALERT` on state transitions to ALERT
or DEGRADED. Host tests: `test_rv_mesh` exercises 27 assertions
covering roundtrip, bad magic, truncation, CRC flipping, oversize
payload rejection, and encode+decode throughput (1.0 μs/roundtrip
on host).
- **Rust: ADR-081 Layer 1/3 mirror module** — New
`crates/wifi-densepose-hardware/src/radio_ops.rs` mirrors the
firmware-side `rv_radio_ops_t` vtable as the Rust `RadioOps` trait
(init, set_channel, set_mode, set_csi_enabled, set_capture_profile,
get_health) and provides `MockRadio` for offline testing.
Also mirrors the `rv_mesh.h` types (`MeshHeader`, `NodeStatus`,
`AnomalyAlert`, `MeshRole`, `MeshMsgType`, `AuthClass`) and ships
byte-identical `crc32_ieee()`, `decode_mesh()`, `decode_node_status()`,
`decode_anomaly_alert()`, and `encode_health()`. Exported from
`lib.rs`. 8 unit tests pass; `crc32_matches_firmware_vectors`
verifies parity with the firmware-side test vectors
(`0xCBF43926` for `"123456789"`, `0xD202EF8D` for single-byte zero),
and `mesh_constants_match_firmware` asserts `MESH_MAGIC`,
`MESH_VERSION`, `MESH_HEADER_SIZE`, and `MESH_MAX_PAYLOAD` match
`rv_mesh.h` byte-for-byte. Satisfies ADR-081's portability
acceptance test: signal/ruvector/train/mat crates are untouched.
- **Firmware: adaptive controller** — New
`firmware/esp32-csi-node/main/adaptive_controller.{c,h}` implements
the three-loop closed-loop control specified by ADR-081: fast