ADR-081: Implement 5-layer adaptive CSI mesh firmware kernel (#404)

* ADR-081: adaptive CSI mesh firmware kernel + scaffolding Introduces a 5-layer firmware kernel that reframes the existing ESP32 modules as components of a chipset-agnostic architecture and authorizes adaptive control + a compact feature-state stream as the default upstream. Layers: L1 Radio Abstraction Layer — rv_radio_ops_t vtable + ESP32 binding L2 Adaptive Controller — fast/medium/slow loops (200ms/1s/30s) L3 Mesh Sensing Plane — anchor/observer/relay/coordinator (spec) L4 On-device Feature Extr. — rv_feature_state_t (magic 0xC5110006) L5 Rust handoff — feature_state default; debug raw gated Files: docs/adr/ADR-081-adaptive-csi-mesh-firmware-kernel.md (new) firmware/esp32-csi-node/main/rv_radio_ops.h (new) firmware/esp32-csi-node/main/rv_radio_ops_esp32.c (new) firmware/esp32-csi-node/main/rv_feature_state.{h,c} (new) firmware/esp32-csi-node/main/adaptive_controller.{h,c} (new) firmware/esp32-csi-node/main/main.c (wire L1+L2) firmware/esp32-csi-node/main/CMakeLists.txt (add 4 sources) firmware/esp32-csi-node/main/Kconfig.projbuild (controller knobs) CHANGELOG.md (Unreleased) Default policy is conservative: enable_channel_switch and enable_role_change are off, so behavior matches today's firmware unless an operator opts in via menuconfig. The pure adaptive_controller_decide() is exposed for offline unit tests. Reuses (does not rewrite): csi_collector, edge_processing (ADR-039), swarm_bridge (ADR-066), secure_tdm (ADR-032), wasm_runtime (ADR-040). * ADR-081: implement Layers 1/2/4 end-to-end + host tests + QEMU hooks Turns the ADR-081 scaffolding into a working adaptive CSI mesh kernel: Layer 1 radio abstraction has an ESP32 binding and a mock binding; Layer 2 adaptive controller runs on FreeRTOS timers; Layer 4 feature-state packet is emitted at 5 Hz by default, replacing raw ADR-018 CSI as the default upstream. New files: firmware/esp32-csi-node/main/adaptive_controller_decide.c (pure policy) firmware/esp32-csi-node/main/rv_radio_ops_mock.c (QEMU binding) firmware/esp32-csi-node/tests/host/Makefile (host tests) firmware/esp32-csi-node/tests/host/test_adaptive_controller.c firmware/esp32-csi-node/tests/host/test_rv_feature_state.c firmware/esp32-csi-node/tests/host/esp_err.h (shim) firmware/esp32-csi-node/tests/host/.gitignore Modified: adaptive_controller.c — includes pure decide.c; emit_feature_state() wired into fast loop (200 ms = 5 Hz) rv_radio_ops_esp32.c — get_health() fills pkt_yield + send_fail csi_collector.{c,h} — pkt_yield/send_fail accessors (ADR-081 L1) rv_feature_state.h — packed size corrected to 60 bytes (was incorrectly 80 in initial commit) main.c — mock binding registered under mock CSI CMakeLists.txt — rv_radio_ops_mock.c under CSI_MOCK_ENABLED scripts/validate_qemu_output.py — 3 new ADR-081 checks (17/18/19) docs/adr/ADR-081-*.md — status → Accepted (partial); implementation-status matrix; measured benchmarks (decide 3.2 ns, CRC32 614 ns); bandwidth 300 B/s @ 5 Hz (99.7% vs raw); verification section CHANGELOG.md — artifact-level entries Tests (host, gcc -O2 -std=c11): test_adaptive_controller: 18/18 pass, decide() = 3.2 ns/call test_rv_feature_state: 15/15 pass, CRC32(56 B) = 614 ns/pkt, 87 MB/s sizeof(rv_feature_state_t) == 60 asserted IEEE CRC32 known vectors verified Deferred (tracked in ADR-081 roadmap Phase 3/4): Layer 3 mesh-plane message types, role-assignment FSM, Rust-side mirror trait in crates/wifi-densepose-hardware/src/radio_ops.rs. * 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 * Add test_rv_mesh to host-test .gitignore Fixes an untracked-file warning from the repo stop-hook: the compiled binary was built by make but the .gitignore update was missed in 8dfb031. No source changes. * Fix implicit decl of emit_feature_state in adaptive_controller fast_loop_cb calls emit_feature_state() at line 224, but the static definition is at line 256. GCC treats the implicit declaration as non-static, then the real static definition conflicts, and -Werror=all promotes both to hard build errors. Add a forward declaration above the first use. Unblocks ESP32-S3 firmware build and all QEMU matrix jobs. Co-Authored-By: claude-flow <ruv@ruv.net> --------- Co-authored-by: Claude <noreply@anthropic.com>
2026-07-29 18:31:44 +00:00 · 2026-04-20 10:38:23 -04:00
parent b816292ead
commit 5a7f431b0e
27 changed files with 3946 additions and 14 deletions
@@ -0,0 +1,5 @@
+# Compiled host-test binaries
+test_adaptive_controller
+test_rv_feature_state
+test_rv_mesh
+*.o
@@ -0,0 +1,59 @@
+# Host-side unit tests for ADR-081 pure-C logic.
+#
+# These tests exercise adaptive_controller_decide() and the rv_feature_state
+# helpers (CRC32, finalize) using plain gcc/clang, with a minimal esp_err.h
+# shim. No ESP-IDF, no FreeRTOS, no QEMU required.
+#
+# Usage:
+#   cd firmware/esp32-csi-node/tests/host
+#   make
+#   ./test_adaptive_controller
+#   ./test_rv_feature_state
+
+MAIN_DIR := ../../main
+CC      ?= cc
+CFLAGS  ?= -O2 -std=c11 -Wall -Wextra -Wno-unused-parameter \
+           -D_POSIX_C_SOURCE=199309L \
+           -I. -I$(MAIN_DIR)
+LDLIBS  ?= -lrt
+
+# Pure-C sources under test. We compile only the files that have no
+# ESP-IDF dependency in their bodies: rv_feature_state.c is 100% pure.
+# adaptive_controller.c uses FreeRTOS for the timer plumbing, so for the
+# host test we compile only the decide() portion by isolating it in a
+# small unity file (TEST_ADAPT_PURE below).
+FEATURE_STATE_SRCS := $(MAIN_DIR)/rv_feature_state.c
+
+# adaptive_controller.c pulls in FreeRTOS headers that don't exist on
+# host; we include its decide() function by defining TEST_ADAPT_PURE
+# before including the .c. The decide() body itself has no ESP-IDF deps.
+# Simpler: just recompile decide() here via a small shim.
+
+TESTS := test_adaptive_controller test_rv_feature_state test_rv_mesh
+
+all: $(TESTS)
+
+test_adaptive_controller: test_adaptive_controller.c $(MAIN_DIR)/adaptive_controller_decide.c $(MAIN_DIR)/adaptive_controller.h $(MAIN_DIR)/rv_radio_ops.h
+	$(CC) $(CFLAGS) test_adaptive_controller.c $(MAIN_DIR)/adaptive_controller_decide.c -o $@ $(LDLIBS)
+
+test_rv_feature_state: test_rv_feature_state.c $(FEATURE_STATE_SRCS) $(MAIN_DIR)/rv_feature_state.h $(MAIN_DIR)/rv_radio_ops.h
+	$(CC) $(CFLAGS) test_rv_feature_state.c $(FEATURE_STATE_SRCS) -o $@ $(LDLIBS)
+
+# Mesh plane encoder/decoder: compile rv_mesh.c with RV_MESH_HOST_TEST
+# so the firmware-only send helpers (stream_sender, esp_log) are hidden.
+test_rv_mesh: test_rv_mesh.c $(MAIN_DIR)/rv_mesh.c $(MAIN_DIR)/rv_mesh.h $(FEATURE_STATE_SRCS) $(MAIN_DIR)/rv_radio_ops.h
+	$(CC) $(CFLAGS) -DRV_MESH_HOST_TEST=1 \
+	    test_rv_mesh.c $(MAIN_DIR)/rv_mesh.c $(FEATURE_STATE_SRCS) \
+	    -o $@ $(LDLIBS)
+
+check: all
+	./test_adaptive_controller
+	@echo ""
+	./test_rv_feature_state
+	@echo ""
+	./test_rv_mesh
+
+clean:
+	rm -f $(TESTS) *.o
+
+.PHONY: all check clean
@@ -0,0 +1,19 @@
+/* Host test shim for esp_err.h. Allows us to compile the pure-C
+ * portions of the firmware (adaptive_controller_decide, rv_feature_state
+ * CRC + finalize) under plain gcc/clang without the ESP-IDF toolchain. */
+#ifndef HOST_ESP_ERR_SHIM_H
+#define HOST_ESP_ERR_SHIM_H
+
+#include <stdint.h>
+
+typedef int esp_err_t;
+
+#define ESP_OK                   0
+#define ESP_FAIL                -1
+#define ESP_ERR_NO_MEM         0x101
+#define ESP_ERR_INVALID_ARG    0x102
+#define ESP_ERR_INVALID_SIZE   0x104
+#define ESP_ERR_INVALID_VERSION 0x10A
+#define ESP_ERR_INVALID_CRC    0x10B
+
+#endif
@@ -0,0 +1,216 @@
+/*
+ * Host unit test for adaptive_controller_decide().
+ *
+ * The ADR-081 controller decision function is deliberately pure: it takes
+ * (cfg, current_state, observation) and produces a decision. No FreeRTOS,
+ * no ESP-IDF, no side effects. This test exercises every documented branch
+ * of the policy.
+ *
+ * Build + run (from this directory):
+ *   make -f Makefile
+ *   ./test_adaptive_controller
+ */
+
+#include <assert.h>
+#include <stdio.h>
+#include <string.h>
+#include <time.h>
+
+#include "adaptive_controller.h"
+#include "rv_radio_ops.h"
+
+static int g_pass = 0, g_fail = 0;
+
+#define CHECK(cond, msg) do {                                   \
+    if (cond) { g_pass++; }                                     \
+    else { g_fail++; printf("  FAIL: %s (line %d)\n", msg, __LINE__); } \
+} while (0)
+
+static adapt_config_t default_cfg(void) {
+    adapt_config_t c = {
+        .fast_loop_ms = 200,
+        .medium_loop_ms = 1000,
+        .slow_loop_ms = 30000,
+        .aggressive = false,
+        .enable_channel_switch = false,
+        .enable_role_change = false,
+        .motion_threshold = 0.20f,
+        .anomaly_threshold = 0.60f,
+        .min_pkt_yield = 5,
+    };
+    return c;
+}
+
+static adapt_observation_t quiet_obs(void) {
+    adapt_observation_t o = {
+        .pkt_yield_per_sec = 50,
+        .send_fail_count = 0,
+        .rssi_median_dbm = -60,
+        .noise_floor_dbm = -95,
+        .motion_score = 0.01f,
+        .presence_score = 0.0f,
+        .anomaly_score = 0.0f,
+        .node_coherence = 1.0f,
+    };
+    return o;
+}
+
+static void test_degraded_gate_on_pkt_yield_collapse(void) {
+    printf("test: degraded gate on pkt yield collapse\n");
+    adapt_config_t cfg = default_cfg();
+    adapt_observation_t obs = quiet_obs();
+    obs.pkt_yield_per_sec = 2;  /* below min_pkt_yield=5 */
+
+    adapt_decision_t dec;
+    adaptive_controller_decide(&cfg, ADAPT_STATE_SENSE_IDLE, &obs, &dec);
+
+    CHECK(dec.change_state, "should change state");
+    CHECK(dec.new_state == ADAPT_STATE_DEGRADED, "new state == DEGRADED");
+    CHECK(dec.new_profile == RV_PROFILE_PASSIVE_LOW_RATE,
+          "profile pinned to PASSIVE_LOW_RATE in degraded");
+    CHECK(dec.suggested_vital_interval_ms == 2000,
+          "cadence relaxed to 2s in degraded");
+}
+
+static void test_degraded_gate_on_coherence_loss(void) {
+    printf("test: degraded gate on coherence loss\n");
+    adapt_config_t cfg = default_cfg();
+    adapt_observation_t obs = quiet_obs();
+    obs.node_coherence = 0.15f;  /* below 0.20 threshold */
+
+    adapt_decision_t dec;
+    adaptive_controller_decide(&cfg, ADAPT_STATE_SENSE_IDLE, &obs, &dec);
+    CHECK(dec.new_state == ADAPT_STATE_DEGRADED, "coherence loss → DEGRADED");
+}
+
+static void test_anomaly_trumps_motion(void) {
+    printf("test: anomaly trumps motion\n");
+    adapt_config_t cfg = default_cfg();
+    adapt_observation_t obs = quiet_obs();
+    obs.motion_score = 0.9f;  /* high motion */
+    obs.anomaly_score = 0.8f; /* but anomaly is above threshold */
+
+    adapt_decision_t dec;
+    adaptive_controller_decide(&cfg, ADAPT_STATE_SENSE_IDLE, &obs, &dec);
+
+    CHECK(dec.new_state == ADAPT_STATE_ALERT, "anomaly → ALERT");
+    CHECK(dec.new_profile == RV_PROFILE_FAST_MOTION,
+          "alert uses FAST_MOTION profile");
+    CHECK(dec.suggested_vital_interval_ms == 100, "alert cadence 100ms");
+}
+
+static void test_motion_triggers_sense_active(void) {
+    printf("test: motion → SENSE_ACTIVE\n");
+    adapt_config_t cfg = default_cfg();
+    adapt_observation_t obs = quiet_obs();
+    obs.motion_score = 0.50f;
+
+    adapt_decision_t dec;
+    adaptive_controller_decide(&cfg, ADAPT_STATE_SENSE_IDLE, &obs, &dec);
+
+    CHECK(dec.new_state == ADAPT_STATE_SENSE_ACTIVE, "motion → SENSE_ACTIVE");
+    CHECK(dec.new_profile == RV_PROFILE_FAST_MOTION, "profile FAST_MOTION");
+    CHECK(dec.suggested_vital_interval_ms == 200,
+          "non-aggressive cadence 200ms");
+}
+
+static void test_aggressive_cadence(void) {
+    printf("test: aggressive cadence is tighter\n");
+    adapt_config_t cfg = default_cfg();
+    cfg.aggressive = true;
+    adapt_observation_t obs = quiet_obs();
+    obs.motion_score = 0.50f;
+
+    adapt_decision_t dec;
+    adaptive_controller_decide(&cfg, ADAPT_STATE_SENSE_IDLE, &obs, &dec);
+    CHECK(dec.suggested_vital_interval_ms == 100,
+          "aggressive motion cadence 100ms");
+}
+
+static void test_stable_presence_uses_resp_high_sens(void) {
+    printf("test: stable presence → RESP_HIGH_SENS\n");
+    adapt_config_t cfg = default_cfg();
+    adapt_observation_t obs = quiet_obs();
+    obs.presence_score = 0.8f;
+    obs.motion_score = 0.01f;
+
+    adapt_decision_t dec;
+    adaptive_controller_decide(&cfg, ADAPT_STATE_SENSE_IDLE, &obs, &dec);
+    CHECK(dec.new_profile == RV_PROFILE_RESP_HIGH_SENS,
+          "stable presence uses respiration profile");
+    CHECK(dec.suggested_vital_interval_ms == 1000,
+          "respiration cadence 1s");
+}
+
+static void test_empty_room_default_is_passive(void) {
+    printf("test: empty room → PASSIVE_LOW_RATE\n");
+    adapt_config_t cfg = default_cfg();
+    adapt_observation_t obs = quiet_obs();
+
+    adapt_decision_t dec;
+    adaptive_controller_decide(&cfg, ADAPT_STATE_SENSE_IDLE, &obs, &dec);
+    CHECK(dec.new_profile == RV_PROFILE_PASSIVE_LOW_RATE,
+          "empty → passive low rate");
+}
+
+static void test_hysteresis_no_flap(void) {
+    printf("test: no change_state when already in target state\n");
+    adapt_config_t cfg = default_cfg();
+    adapt_observation_t obs = quiet_obs();
+    obs.motion_score = 0.50f;
+
+    adapt_decision_t dec;
+    adaptive_controller_decide(&cfg, ADAPT_STATE_SENSE_ACTIVE, &obs, &dec);
+    CHECK(!dec.change_state,
+          "already in SENSE_ACTIVE — no redundant change_state");
+}
+
+static void test_null_safety(void) {
+    printf("test: NULL args are no-ops (no crash)\n");
+    adapt_decision_t dec = {0};
+    adaptive_controller_decide(NULL, ADAPT_STATE_SENSE_IDLE, NULL, &dec);
+    /* if we got here, no segfault — pass */
+    g_pass++;
+    printf("  OK\n");
+}
+
+static void benchmark_decide(void) {
+    printf("bench: adaptive_controller_decide() throughput\n");
+    adapt_config_t cfg = default_cfg();
+    adapt_observation_t obs = quiet_obs();
+    adapt_decision_t dec;
+
+    const int N = 10000000;
+    struct timespec a, b;
+    clock_gettime(CLOCK_MONOTONIC, &a);
+    for (int i = 0; i < N; i++) {
+        /* Vary input slightly so the compiler can't fold the call. */
+        obs.motion_score = (i & 0xff) / 255.0f;
+        adaptive_controller_decide(&cfg, ADAPT_STATE_SENSE_IDLE, &obs, &dec);
+    }
+    clock_gettime(CLOCK_MONOTONIC, &b);
+    double ns_per_call = ((b.tv_sec - a.tv_sec) * 1e9 +
+                          (b.tv_nsec - a.tv_nsec)) / (double)N;
+    printf("  %d calls, %.1f ns/call\n", N, ns_per_call);
+    /* Sanity: decide() is O(constant) — must be under 10us even on a
+     * slow emulator. Real ESP32 will be ~100-300ns. */
+    CHECK(ns_per_call < 10000.0, "decide() must be under 10us/call");
+}
+
+int main(void) {
+    printf("=== adaptive_controller_decide() host tests ===\n\n");
+
+    test_degraded_gate_on_pkt_yield_collapse();
+    test_degraded_gate_on_coherence_loss();
+    test_anomaly_trumps_motion();
+    test_motion_triggers_sense_active();
+    test_aggressive_cadence();
+    test_stable_presence_uses_resp_high_sens();
+    test_empty_room_default_is_passive();
+    test_hysteresis_no_flap();
+    test_null_safety();
+    benchmark_decide();
+
+    printf("\n=== result: %d pass, %d fail ===\n", g_pass, g_fail);
+    return g_fail > 0 ? 1 : 0;
+}
@@ -0,0 +1,152 @@
+/*
+ * Host unit test for rv_feature_state_* helpers.
+ *
+ * Validates:
+ *   - Packet layout is exactly 80 bytes
+ *   - IEEE CRC32 matches well-known reference vectors
+ *   - finalize() populates magic/seq/ts/crc correctly
+ *   - CRC32 throughput benchmark
+ */
+
+#include <assert.h>
+#include <stdio.h>
+#include <string.h>
+#include <time.h>
+
+#include "rv_feature_state.h"
+#include "rv_radio_ops.h"
+
+static int g_pass = 0, g_fail = 0;
+#define CHECK(cond, msg) do {                                   \
+    if (cond) { g_pass++; }                                     \
+    else { g_fail++; printf("  FAIL: %s (line %d)\n", msg, __LINE__); } \
+} while (0)
+
+static void test_packet_size(void) {
+    printf("test: rv_feature_state_t is 60 bytes on the wire\n");
+    CHECK(sizeof(rv_feature_state_t) == 60, "sizeof == 60");
+}
+
+static void test_crc_known_vectors(void) {
+    printf("test: IEEE CRC32 known vectors\n");
+    /* IEEE CRC32 of "123456789" == 0xCBF43926 (well-known). */
+    uint32_t c1 = rv_feature_state_crc32((const uint8_t *)"123456789", 9);
+    CHECK(c1 == 0xCBF43926u, "CRC32('123456789') == 0xCBF43926");
+
+    /* Empty input → 0x00000000 (before final inversion, 0xFFFFFFFF);
+     * IEEE convention with post-invert → 0x00000000 reversed — but with
+     * our implementation the empty-input CRC is 0x00000000 after post-
+     * invert on ~0xFFFFFFFF = 0x00000000. */
+    uint32_t c2 = rv_feature_state_crc32(NULL, 0);
+    CHECK(c2 == 0x00000000u, "CRC32(empty) == 0");
+
+    /* Single zero byte: IEEE CRC32 of 0x00 = 0xD202EF8D. */
+    uint8_t zero = 0;
+    uint32_t c3 = rv_feature_state_crc32(&zero, 1);
+    CHECK(c3 == 0xD202EF8Du, "CRC32(0x00) == 0xD202EF8D");
+}
+
+static void test_finalize(void) {
+    printf("test: finalize populates required fields\n");
+    rv_feature_state_t pkt;
+    memset(&pkt, 0, sizeof(pkt));
+    pkt.motion_score    = 0.25f;
+    pkt.presence_score  = 0.75f;
+    pkt.respiration_bpm = 14.5f;
+    pkt.quality_flags   = RV_QFLAG_PRESENCE_VALID | RV_QFLAG_RESPIRATION_VALID;
+
+    rv_feature_state_finalize(&pkt, /*node*/ 7, /*seq*/ 42,
+                              /*ts*/ 1234567ULL, RV_PROFILE_RESP_HIGH_SENS);
+
+    CHECK(pkt.magic == RV_FEATURE_STATE_MAGIC, "magic");
+    CHECK(pkt.node_id == 7, "node_id");
+    CHECK(pkt.seq == 42, "seq");
+    CHECK(pkt.ts_us == 1234567ULL, "ts_us");
+    CHECK(pkt.mode == RV_PROFILE_RESP_HIGH_SENS, "mode");
+    CHECK(pkt.reserved == 0, "reserved cleared");
+    CHECK(pkt.crc32 != 0, "crc32 populated (non-trivial input)");
+
+    /* Re-finalize must produce identical CRC (deterministic). */
+    uint32_t crc1 = pkt.crc32;
+    rv_feature_state_finalize(&pkt, 7, 42, 1234567ULL, RV_PROFILE_RESP_HIGH_SENS);
+    CHECK(pkt.crc32 == crc1, "finalize is deterministic");
+
+    /* Changing a payload byte must change the CRC. */
+    pkt.motion_score = 0.26f;
+    rv_feature_state_finalize(&pkt, 7, 42, 1234567ULL, RV_PROFILE_RESP_HIGH_SENS);
+    CHECK(pkt.crc32 != crc1, "CRC changes when payload changes");
+}
+
+static void test_crc_verifiability(void) {
+    printf("test: receiver can verify CRC\n");
+    rv_feature_state_t pkt;
+    memset(&pkt, 0, sizeof(pkt));
+    pkt.motion_score   = 0.33f;
+    pkt.presence_score = 0.66f;
+    rv_feature_state_finalize(&pkt, 1, 100, 555ULL, RV_PROFILE_PASSIVE_LOW_RATE);
+
+    /* Receiver recomputes CRC over all bytes except the trailing crc32. */
+    uint32_t expected = rv_feature_state_crc32(
+        (const uint8_t *)&pkt, sizeof(pkt) - sizeof(uint32_t));
+    CHECK(pkt.crc32 == expected, "receiver-side CRC check matches");
+}
+
+static void benchmark_crc(void) {
+    printf("bench: CRC32 over 60-byte packet (56 B hashed, excl trailing crc32)\n");
+    rv_feature_state_t pkt;
+    memset(&pkt, 0x5A, sizeof(pkt));
+
+    const int N = 5000000;
+    struct timespec a, b;
+    clock_gettime(CLOCK_MONOTONIC, &a);
+    volatile uint32_t sink = 0;
+    for (int i = 0; i < N; i++) {
+        pkt.seq = (uint16_t)i;  /* vary input so compiler can't fold */
+        sink ^= rv_feature_state_crc32(
+            (const uint8_t *)&pkt, sizeof(pkt) - sizeof(uint32_t));
+    }
+    clock_gettime(CLOCK_MONOTONIC, &b);
+    (void)sink;
+    double ns_per_call = ((b.tv_sec - a.tv_sec) * 1e9 +
+                          (b.tv_nsec - a.tv_nsec)) / (double)N;
+    double mb_per_sec = (double)(sizeof(pkt) - sizeof(uint32_t)) / ns_per_call
+                        * 1e9 / (1024.0 * 1024.0);
+    printf("  %d calls, %.1f ns/packet, %.1f MB/s\n",
+           N, ns_per_call, mb_per_sec);
+    /* At 10 Hz feature-state cadence, CRC budget is <100us/packet — we
+     * expect bit-by-bit CRC32 to run ~1 MB/s on host, ~100-300 KB/s on
+     * ESP32-S3 Xtensa LX7. 76-byte CRC takes <1 ms either way. */
+    CHECK(ns_per_call < 50000.0, "CRC32(80B) must be under 50us/packet");
+}
+
+static void benchmark_finalize(void) {
+    printf("bench: full finalize() cost\n");
+    rv_feature_state_t pkt;
+    memset(&pkt, 0x33, sizeof(pkt));
+
+    const int N = 5000000;
+    struct timespec a, b;
+    clock_gettime(CLOCK_MONOTONIC, &a);
+    for (int i = 0; i < N; i++) {
+        rv_feature_state_finalize(&pkt, 1, (uint16_t)i, (uint64_t)i,
+                                  RV_PROFILE_PASSIVE_LOW_RATE);
+    }
+    clock_gettime(CLOCK_MONOTONIC, &b);
+    double ns_per_call = ((b.tv_sec - a.tv_sec) * 1e9 +
+                          (b.tv_nsec - a.tv_nsec)) / (double)N;
+    printf("  %d calls, %.1f ns/call (includes CRC)\n", N, ns_per_call);
+}
+
+int main(void) {
+    printf("=== rv_feature_state_* host tests ===\n\n");
+
+    test_packet_size();
+    test_crc_known_vectors();
+    test_finalize();
+    test_crc_verifiability();
+    benchmark_crc();
+    benchmark_finalize();
+
+    printf("\n=== result: %d pass, %d fail ===\n", g_pass, g_fail);
+    return g_fail > 0 ? 1 : 0;
+}
@@ -0,0 +1,219 @@
+/*
+ * Host unit test for ADR-081 Layer 3 mesh plane encode/decode.
+ *
+ * rv_mesh_encode() and rv_mesh_decode() are the pure halves of the
+ * mesh plane — no ESP-IDF, no sockets — so we exercise them with the
+ * RV_MESH_HOST_TEST flag that disables the send helpers.
+ */
+
+#include <assert.h>
+#include <stdio.h>
+#include <string.h>
+#include <time.h>
+
+#include "rv_mesh.h"
+#include "rv_feature_state.h"
+#include "rv_radio_ops.h"  /* for RV_PROFILE_* enum values */
+
+static int g_pass = 0, g_fail = 0;
+#define CHECK(cond, msg) do {                                   \
+    if (cond) { g_pass++; }                                     \
+    else { g_fail++; printf("  FAIL: %s (line %d)\n", msg, __LINE__); } \
+} while (0)
+
+static void test_header_size(void) {
+    printf("test: rv_mesh_header_t is 16 bytes\n");
+    CHECK(sizeof(rv_mesh_header_t) == 16, "sizeof(header) == 16");
+}
+
+static void test_encode_health_roundtrip(void) {
+    printf("test: HEALTH roundtrip\n");
+    rv_node_status_t st;
+    memset(&st, 0, sizeof(st));
+    st.node_id[0]       = 7;
+    st.local_time_us    = 1234567890ULL;
+    st.role             = RV_ROLE_OBSERVER;
+    st.current_channel  = 6;
+    st.current_bw       = 20;
+    st.noise_floor_dbm  = -93;
+    st.pkt_yield        = 42;
+    st.sync_error_us    = 12;
+
+    uint8_t buf[RV_MESH_MAX_FRAME_BYTES];
+    size_t n = rv_mesh_encode_health(RV_ROLE_OBSERVER, /*epoch*/ 100,
+                                     &st, buf, sizeof(buf));
+    CHECK(n > 0, "encode returns non-zero");
+    CHECK(n == sizeof(rv_mesh_header_t) + sizeof(st) + 4,
+          "encoded size = hdr+payload+crc");
+
+    rv_mesh_header_t hdr;
+    const uint8_t *payload = NULL;
+    uint16_t payload_len = 0;
+    esp_err_t rc = rv_mesh_decode(buf, n, &hdr, &payload, &payload_len);
+    CHECK(rc == ESP_OK, "decode OK");
+    CHECK(hdr.type == RV_MSG_HEALTH, "type == HEALTH");
+    CHECK(hdr.epoch == 100, "epoch survives");
+    CHECK(hdr.payload_len == sizeof(st), "payload_len matches");
+    CHECK(payload != NULL, "payload pointer set");
+    CHECK(memcmp(payload, &st, sizeof(st)) == 0, "payload bytes match");
+}
+
+static void test_encode_anomaly_roundtrip(void) {
+    printf("test: ANOMALY_ALERT roundtrip\n");
+    rv_anomaly_alert_t a;
+    memset(&a, 0, sizeof(a));
+    a.node_id[0]    = 3;
+    a.ts_us         = 999999ULL;
+    a.reason        = RV_ANOMALY_FALL;
+    a.severity      = 200;
+    a.anomaly_score = 0.85f;
+    a.motion_score  = 0.9f;
+
+    uint8_t buf[RV_MESH_MAX_FRAME_BYTES];
+    size_t n = rv_mesh_encode_anomaly_alert(RV_ROLE_OBSERVER, 7, &a,
+                                            buf, sizeof(buf));
+    CHECK(n > 0, "encoded");
+
+    rv_mesh_header_t hdr;
+    const uint8_t *payload = NULL;
+    uint16_t payload_len = 0;
+    esp_err_t rc = rv_mesh_decode(buf, n, &hdr, &payload, &payload_len);
+    CHECK(rc == ESP_OK, "decoded");
+    CHECK(hdr.type == RV_MSG_ANOMALY_ALERT, "type ok");
+    rv_anomaly_alert_t got;
+    memcpy(&got, payload, sizeof(got));
+    CHECK(got.reason == RV_ANOMALY_FALL, "reason survived");
+    CHECK(got.severity == 200, "severity survived");
+}
+
+static void test_encode_feature_delta_wraps_feature_state(void) {
+    printf("test: FEATURE_DELTA wraps rv_feature_state_t\n");
+    rv_feature_state_t fs;
+    memset(&fs, 0, sizeof(fs));
+    fs.motion_score = 0.5f;
+    rv_feature_state_finalize(&fs, /*node*/ 9, /*seq*/ 17,
+                              /*ts*/ 111ULL, RV_PROFILE_FAST_MOTION);
+
+    uint8_t buf[RV_MESH_MAX_FRAME_BYTES];
+    size_t n = rv_mesh_encode_feature_delta(RV_ROLE_OBSERVER, 2, &fs,
+                                            buf, sizeof(buf));
+    CHECK(n == sizeof(rv_mesh_header_t) + sizeof(fs) + 4, "size check");
+
+    rv_mesh_header_t hdr;
+    const uint8_t *payload = NULL;
+    uint16_t len = 0;
+    CHECK(rv_mesh_decode(buf, n, &hdr, &payload, &len) == ESP_OK,
+          "decode OK");
+    rv_feature_state_t got;
+    memcpy(&got, payload, sizeof(got));
+    CHECK(got.magic == RV_FEATURE_STATE_MAGIC, "inner magic preserved");
+    CHECK(got.node_id == 9, "inner node_id preserved");
+    CHECK(got.seq == 17, "inner seq preserved");
+    /* Inner CRC is end-to-end even though the mesh frame has its own
+     * CRC too — two checks for two failure modes. */
+    uint32_t inner_crc = rv_feature_state_crc32(
+        (const uint8_t *)&got, sizeof(got) - sizeof(uint32_t));
+    CHECK(inner_crc == got.crc32, "inner feature_state CRC still valid");
+}
+
+static void test_decode_rejects_bad_magic(void) {
+    printf("test: decode rejects bad magic\n");
+    uint8_t buf[sizeof(rv_mesh_header_t) + 4];
+    memset(buf, 0xFF, sizeof(buf));
+
+    rv_mesh_header_t hdr;
+    const uint8_t *p = NULL;
+    uint16_t plen = 0;
+    esp_err_t rc = rv_mesh_decode(buf, sizeof(buf), &hdr, &p, &plen);
+    CHECK(rc != ESP_OK, "bad magic rejected");
+}
+
+static void test_decode_rejects_truncated(void) {
+    printf("test: decode rejects truncated frame\n");
+    uint8_t buf[sizeof(rv_mesh_header_t) - 1];
+    memset(buf, 0, sizeof(buf));
+    rv_mesh_header_t hdr;
+    const uint8_t *p = NULL;
+    uint16_t plen = 0;
+    esp_err_t rc = rv_mesh_decode(buf, sizeof(buf), &hdr, &p, &plen);
+    CHECK(rc != ESP_OK, "truncated rejected");
+}
+
+static void test_decode_rejects_bad_crc(void) {
+    printf("test: decode rejects CRC mismatch\n");
+    rv_node_status_t st;
+    memset(&st, 0, sizeof(st));
+    st.role = RV_ROLE_OBSERVER;
+    uint8_t buf[RV_MESH_MAX_FRAME_BYTES];
+    size_t n = rv_mesh_encode_health(RV_ROLE_OBSERVER, 1, &st,
+                                     buf, sizeof(buf));
+    CHECK(n > 0, "encoded");
+
+    /* Flip a byte in the payload — CRC must now mismatch. */
+    buf[sizeof(rv_mesh_header_t) + 4] ^= 0x10;
+
+    rv_mesh_header_t hdr;
+    const uint8_t *p = NULL;
+    uint16_t plen = 0;
+    esp_err_t rc = rv_mesh_decode(buf, n, &hdr, &p, &plen);
+    CHECK(rc != ESP_OK, "CRC mismatch rejected");
+}
+
+static void test_encode_rejects_oversize_payload(void) {
+    printf("test: encode rejects oversize payload\n");
+    uint8_t junk[RV_MESH_MAX_PAYLOAD + 1] = {0};
+    uint8_t buf[RV_MESH_MAX_FRAME_BYTES + 8];
+    size_t n = rv_mesh_encode(RV_MSG_HEALTH, RV_ROLE_OBSERVER, RV_AUTH_NONE,
+                              0, junk, sizeof(junk), buf, sizeof(buf));
+    CHECK(n == 0, "oversize payload → 0");
+}
+
+static void test_encode_rejects_small_buf(void) {
+    printf("test: encode rejects too-small buffer\n");
+    rv_node_status_t st = {0};
+    uint8_t buf[16];  /* header fits but not payload */
+    size_t n = rv_mesh_encode_health(RV_ROLE_OBSERVER, 0, &st,
+                                     buf, sizeof(buf));
+    CHECK(n == 0, "small buf → 0");
+}
+
+static void benchmark_encode(void) {
+    printf("bench: encode+decode HEALTH roundtrip\n");
+    rv_node_status_t st;
+    memset(&st, 0x33, sizeof(st));
+    uint8_t buf[RV_MESH_MAX_FRAME_BYTES];
+
+    const int N = 2000000;
+    struct timespec a, b;
+    clock_gettime(CLOCK_MONOTONIC, &a);
+    for (int i = 0; i < N; i++) {
+        st.pkt_yield = (uint16_t)i;
+        size_t n = rv_mesh_encode_health(RV_ROLE_OBSERVER, (uint32_t)i,
+                                         &st, buf, sizeof(buf));
+        rv_mesh_header_t hdr;
+        const uint8_t *p = NULL;
+        uint16_t plen = 0;
+        (void)rv_mesh_decode(buf, n, &hdr, &p, &plen);
+    }
+    clock_gettime(CLOCK_MONOTONIC, &b);
+    double ns = ((b.tv_sec - a.tv_sec) * 1e9 +
+                 (b.tv_nsec - a.tv_nsec)) / (double)N;
+    printf("  %d roundtrips, %.1f ns/call\n", N, ns);
+    CHECK(ns < 20000.0, "encode+decode must be under 20us/roundtrip");
+}
+
+int main(void) {
+    printf("=== rv_mesh encode/decode host tests ===\n\n");
+    test_header_size();
+    test_encode_health_roundtrip();
+    test_encode_anomaly_roundtrip();
+    test_encode_feature_delta_wraps_feature_state();
+    test_decode_rejects_bad_magic();
+    test_decode_rejects_truncated();
+    test_decode_rejects_bad_crc();
+    test_encode_rejects_oversize_payload();
+    test_encode_rejects_small_buf();
+    benchmark_encode();
+    printf("\n=== result: %d pass, %d fail ===\n", g_pass, g_fail);
+    return g_fail > 0 ? 1 : 0;
+}