feat(camera): direct V4L2 capture via v4l crate — eliminates ffmpeg orphans

Replaces ffmpeg subprocess with direct V4L2 mmap capture using the `v4l` Rust crate. Supports MJPG (decoded via jpeg-decoder) and YUYV formats. Key changes: - Primary backend: v4l::io::mmap::Stream (no subprocess, no orphans) - Fallback: ffmpeg with 10-second timeout + kill on hang - MJPG → RGB via jpeg-decoder, YUYV → RGB inline conversion - Device released cleanly on drop (no zombie processes) Fixes the recurring stale ffmpeg issue (killed ~8 times in 61 hours of continuous monitoring). The ffmpeg subprocess would hang on V4L2 device access and become an orphan consuming 99%+ CPU. Co-Authored-By: claude-flow <ruv@ruv.net>
Update README + user-guide for PR #405 review-fix additions
2026-06-17 11:33:19 +00:00 · 2026-04-22 23:41:12 -04:00 · 2026-04-20 12:48:45 -04:00 · 2026-04-20 12:40:34 -04:00 · 2026-04-20 12:29:48 -04:00 · 2026-04-20 12:29:31 -04:00
72 changed files with 8976 additions and 56 deletions
@@ -12,31 +12,50 @@ on:

 jobs:
  build:
-    name: Build ESP32-S3 Firmware
+    name: Build ESP32-S3 Firmware (${{ matrix.variant }})
    runs-on: ubuntu-latest
    container:
      image: espressif/idf:v5.4
+    strategy:
+      fail-fast: false
+      matrix:
+        include:
+          - variant: 8mb
+            sdkconfig: sdkconfig.defaults
+            partition_table_name: partitions_display.csv
+            size_limit_kb: 1100
+            artifact_app: esp32-csi-node.bin
+            artifact_pt: partition-table.bin
+          - variant: 4mb
+            sdkconfig: sdkconfig.defaults.4mb
+            partition_table_name: partitions_4mb.csv
+            size_limit_kb: 1100
+            artifact_app: esp32-csi-node-4mb.bin
+            artifact_pt: partition-table-4mb.bin

    steps:
      - uses: actions/checkout@v4

-      - name: Build firmware
+      - name: Build firmware (${{ matrix.variant }})
        working-directory: firmware/esp32-csi-node
        run: |
          . $IDF_PATH/export.sh
+          if [ "${{ matrix.variant }}" != "8mb" ]; then
+            cp "${{ matrix.sdkconfig }}" sdkconfig.defaults
+          fi
          idf.py set-target esp32s3
          idf.py build

-      - name: Verify binary size (< 1100 KB gate)
+      - name: Verify binary size (< ${{ matrix.size_limit_kb }} KB gate)
        working-directory: firmware/esp32-csi-node
        run: |
          BIN=build/esp32-csi-node.bin
          SIZE=$(stat -c%s "$BIN")
-          MAX=$((1100 * 1024))
+          MAX=$((${{ matrix.size_limit_kb }} * 1024))
          echo "Binary size: $SIZE bytes ($(( SIZE / 1024 )) KB)"
-          echo "Size limit:  $MAX bytes (1100 KB — includes WASM runtime + HTTP client for Seed swarm bridge)"
+          echo "Size limit:  $MAX bytes (${{ matrix.size_limit_kb }} KB)"
          if [ "$SIZE" -gt "$MAX" ]; then
-            echo "::error::Firmware binary exceeds 1100 KB size gate ($SIZE > $MAX)"
+            echo "::error::Firmware binary exceeds ${{ matrix.size_limit_kb }} KB size gate ($SIZE > $MAX)"
            exit 1
          fi
          echo "Binary size OK: $SIZE <= $MAX"
@@ -47,14 +66,11 @@ jobs:
          ERRORS=0
          BIN=build/esp32-csi-node.bin

-          # Check binary exists and is non-empty.
          if [ ! -s "$BIN" ]; then
            echo "::error::Binary not found or empty"
            exit 1
          fi

-          # Check partition table magic (0xAA50 at offset 0).
-          # Use od instead of xxd (xxd not available in espressif/idf container).
          PT=build/partition_table/partition-table.bin
          if [ -f "$PT" ]; then
            MAGIC=$(od -A n -t x1 -N 2 "$PT" | tr -d ' ')
@@ -64,14 +80,12 @@ jobs:
            fi
          fi

-          # Check bootloader exists.
          BL=build/bootloader/bootloader.bin
          if [ ! -s "$BL" ]; then
            echo "::warning::Bootloader binary missing or empty"
            ERRORS=$((ERRORS + 1))
          fi

-          # Verify non-zero data in binary (not all 0xFF padding).
          NONZERO=$(od -A n -t x1 -N 1024 "$BIN" | tr -d ' f\n' | wc -c)
          if [ "$NONZERO" -lt 100 ]; then
            echo "::error::Binary appears to be mostly padding (non-zero chars: $NONZERO)"
@@ -84,19 +98,27 @@ jobs:
            echo "Flash image integrity verified"
          fi

+      - name: Stage release binaries with variant-specific names
+        working-directory: firmware/esp32-csi-node
+        run: |
+          mkdir -p release-staging
+          cp build/esp32-csi-node.bin                      release-staging/${{ matrix.artifact_app }}
+          cp build/partition_table/partition-table.bin     release-staging/${{ matrix.artifact_pt }}
+          if [ "${{ matrix.variant }}" = "8mb" ]; then
+            cp build/bootloader/bootloader.bin             release-staging/bootloader.bin
+            cp build/ota_data_initial.bin                  release-staging/ota_data_initial.bin
+          fi
+          ls -la release-staging/
+
      - name: Check QEMU ESP32-S3 support status
        run: |
          echo "::notice::ESP32-S3 QEMU support is experimental in ESP-IDF v5.4. "
          echo "Full smoke testing requires QEMU 8.2+ with xtensa-esp32s3 target."
          echo "See: https://github.com/espressif/qemu/wiki"

-      - name: Upload firmware artifact
+      - name: Upload firmware artifact (${{ matrix.variant }})
        uses: actions/upload-artifact@v4
        with:
-          name: esp32-csi-node-firmware
-          path: |
-            firmware/esp32-csi-node/build/esp32-csi-node.bin
-            firmware/esp32-csi-node/build/bootloader/bootloader.bin
-            firmware/esp32-csi-node/build/partition_table/partition-table.bin
-            firmware/esp32-csi-node/build/ota_data_initial.bin
+          name: esp32-csi-node-firmware-${{ matrix.variant }}
+          path: firmware/esp32-csi-node/release-staging/
          retention-days: 90
@@ -250,3 +250,5 @@ v1/src/sensing/mac_wifi
 # Local build scripts
 firmware/esp32-csi-node/build_firmware.batdata/
 models/
+demo_pointcloud.ply
+demo_splats.json
@@ -7,6 +7,120 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0

 ## [Unreleased]

+## [v0.6.2-esp32] — 2026-04-20
+
+Firmware release cutting ADR-081 and the Timer Svc stack fix discovered during
+on-hardware validation. Cut from `main` at commit pointing to this entry.
+Tested on ESP32-S3 (QFN56 rev v0.2, MAC `3c:0f:02:e9:b5:f8`), 30 s continuous
+run: no crashes, 149 `rv_feature_state_t` emissions (~5 Hz), medium/slow ticks
+firing cleanly, HEALTH mesh packets sent.
+
+### Fixed
+- **Firmware: Timer Svc stack overflow on ADR-081 fast loop** — `emit_feature_state()` runs inside the FreeRTOS Timer Svc task via the fast-loop callback; it calls `stream_sender` network I/O which pushes past the ESP-IDF 2 KiB default timer stack and panics ~1 s after boot. Bumped `CONFIG_FREERTOS_TIMER_TASK_STACK_DEPTH` to 8 KiB in `sdkconfig.defaults`, `sdkconfig.defaults.template`, and `sdkconfig.defaults.4mb`. Follow-up (tracked separately): move heavy work out of the timer daemon into a dedicated worker task.
+- **Firmware: `adaptive_controller.c` implicit declaration** (#404) — `fast_loop_cb` called `emit_feature_state()` before its static definition, triggering `-Werror=implicit-function-declaration`. Added a forward declaration above the first use.
+
+### Changed
+- **CI: firmware build matrix (8MB + 4MB)** — `firmware-ci.yml` now matrix-builds both the default 8MB (`sdkconfig.defaults`) and 4MB SuperMini (`sdkconfig.defaults.4mb`) variants, uploading distinct artifacts and producing variant-named release binaries (`esp32-csi-node.bin` / `esp32-csi-node-4mb.bin`, `partition-table.bin` / `partition-table-4mb.bin`).
+
+### Added
+- **ADR-081: Adaptive CSI Mesh Firmware Kernel** — New 5-layer architecture
+  (Radio Abstraction Layer / Adaptive Controller / Mesh Sensing Plane /
+  On-device Feature Extraction / Rust handoff) that reframes the existing
+  ESP32 firmware modules as components of a chipset-agnostic kernel. ADR
+  in `docs/adr/ADR-081-adaptive-csi-mesh-firmware-kernel.md`. Goal: swap
+  one radio family for another without changing the Rust signal /
+  ruvector / train / mat crates.
+- **Firmware: radio abstraction vtable (`rv_radio_ops_t`)** — New
+  `firmware/esp32-csi-node/main/rv_radio_ops.{h}` defines the
+  chipset-agnostic ops (init, set_channel, set_mode, set_csi_enabled,
+  set_capture_profile, get_health), profile enum
+  (`RV_PROFILE_PASSIVE_LOW_RATE` / `ACTIVE_PROBE` / `RESP_HIGH_SENS` /
+  `FAST_MOTION` / `CALIBRATION`), and health snapshot struct.
+  `rv_radio_ops_esp32.c` provides the ESP32 binding wrapping
+  `csi_collector` + `esp_wifi_*`. A second binding (mock or alternate
+  chipset) is the portability acceptance test for ADR-081.
+- **Firmware: `rv_feature_state_t` packet (magic `0xC5110006`)** — New
+  60-byte compact per-node sensing state (packed, verified by
+  `_Static_assert`) in `firmware/esp32-csi-node/main/rv_feature_state.h`:
+  motion, presence, respiration BPM/conf, heartbeat BPM/conf, anomaly
+  score, env-shift score, node coherence, quality flags, IEEE CRC32.
+  Replaces raw ADR-018 CSI as the default upstream stream (~99.7%
+  bandwidth reduction: 300 B/s at 5 Hz vs. ~100 KB/s raw).
+- **Firmware: mock radio ops binding for QEMU** — New
+  `firmware/esp32-csi-node/main/rv_radio_ops_mock.c`, compiled only when
+  `CONFIG_CSI_MOCK_ENABLED`. Satisfies ADR-081's portability acceptance
+  test: a second `rv_radio_ops_t` binding compiles and runs against the
+  same controller + mesh-plane code as the ESP32 binding.
+- **Firmware: feature-state emitter wired into controller fast loop** —
+  `adaptive_controller.c` now emits one 60-byte `rv_feature_state_t` per
+  fast tick (default 200 ms → 5 Hz), pulling from the latest edge vitals
+  and controller observation. This is the first end-to-end Layer 4/5
+  path for ADR-081.
+- **Firmware: `csi_collector_get_pkt_yield_per_sec()` /
+  `_get_send_fail_count()` accessors** — Expose the CSI callback rate
+  and UDP send-failure counter so the ESP32 radio ops binding can
+  populate `rv_radio_health_t.pkt_yield_per_sec` and `.send_fail_count`,
+  closing the adaptive controller's observation loop.
+- **Firmware: host-side unit test suite for ADR-081 pure logic** — New
+  `firmware/esp32-csi-node/tests/host/` (Makefile + 2 test files + shim
+  `esp_err.h`). Exercises `adaptive_controller_decide()` (9 test cases:
+  degraded gate on pkt-yield collapse + coherence loss, anomaly > motion,
+  motion → SENSE_ACTIVE, aggressive cadence, stable presence →
+  RESP_HIGH_SENS, empty-room default, hysteresis, NULL safety) and
+  `rv_feature_state_*` helpers (size assertion, IEEE CRC32 known
+  vectors, determinism, receiver-side verification). 33/33 assertions
+  pass. Benchmarks: decide() 3.2 ns/call, CRC32(56 B) 614 ns/pkt
+  (87 MB/s), full finalize() 616 ns/call. Pure function
+  `adaptive_controller_decide()` extracted to
+  `adaptive_controller_decide.c` so the firmware build and the host
+  tests share a single source-of-truth implementation.
+- **Scripts: `validate_qemu_output.py` ADR-081 checks** — Validator
+  (invoked by ADR-061 `scripts/qemu-esp32s3-test.sh` in CI) gains three
+  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
+  (~200 ms) for cadence and active probing, medium (~1 s) for channel
+  selection and role transitions, slow (~30 s) for baseline
+  recalibration. Pure `adaptive_controller_decide()` policy function is
+  exposed in the header for offline unit testing. Default policy is
+  conservative (`enable_channel_switch` and `enable_role_change` off);
+  Kconfig surface added under "Adaptive Controller (ADR-081)".
+
 ### Fixed
 - **`provision.py` esptool v5 compat** (#391) — Stale `write_flash` (underscore) syntax in the dry-run manual-flash hint now uses `write-flash` (hyphenated) for esptool >= 5.x. The primary flash command was already correct.
 - **`provision.py` silent NVS wipe** (#391) — The script replaces the entire `csi_cfg` NVS namespace on every run, so partial invocations were silently erasing WiFi credentials and causing `Retrying WiFi connection (10/10)` in the field. Now refuses to run without `--ssid`, `--password`, and `--target-ip` unless `--force-partial` is passed. `--force-partial` prints a warning listing which keys will be wiped.
@@ -96,6 +96,47 @@ node scripts/mincut-person-counter.js --port 5006  # Correct person counting
 >
 ---

+### Real-Time Dense Point Cloud (NEW)
+
+RuView now generates **real-time 3D point clouds** by fusing camera depth + WiFi CSI + mmWave radar. All sensors stream simultaneously into a unified spatial model.
+
+| Sensor | Data | Integration |
+|--------|------|-------------|
+| **Camera** | MiDaS monocular depth (GPU) | 640×480 → 19,200+ depth points per frame |
+| **ESP32 CSI** | ADR-018 binary frames (UDP) | RF tomography → 8×8×4 occupancy grid |
+| **WiFlow Pose** | 17 COCO keypoints from CSI | Skeleton overlay on point cloud |
+| **Vital Signs** | Breathing rate from CSI phase | Stored in ruOS brain every 60s |
+| **Motion** | CSI amplitude variance | Adaptive capture rate (skip depth when still) |
+
+**Quick start:**
+```bash
+cd rust-port/wifi-densepose-rs
+cargo build --release -p wifi-densepose-pointcloud
+./target/release/ruview-pointcloud serve --bind 127.0.0.1:9880
+# Open http://localhost:9880 for live 3D viewer
+```
+
+**CLI commands:**
+```bash
+ruview-pointcloud demo                            # synthetic demo
+ruview-pointcloud serve --bind 127.0.0.1:9880     # live server + Three.js viewer
+ruview-pointcloud capture --output room.ply       # capture to PLY
+ruview-pointcloud train                           # depth calibration + DPO pairs
+ruview-pointcloud cameras                         # list available cameras
+ruview-pointcloud csi-test --count 100            # send test CSI frames
+ruview-pointcloud fingerprint office --seconds 5  # record named CSI room fingerprint
+```
+
+The HTTP/viewer server defaults to **loopback (`127.0.0.1`)** — exposing live camera/CSI/vitals on `0.0.0.0` is an explicit opt-in. Brain URL defaults to `http://127.0.0.1:9876` and is overridable via `RUVIEW_BRAIN_URL` env var or the `--brain` flag on `serve`/`train`.
+
+The pose overlay currently uses an **amplitude-energy heuristic** (`heuristic_pose_from_amplitude`) rather than trained WiFlow inference — real ONNX/Candle inference is tracked as a follow-up.
+
+**Performance:** 22ms pipeline, 905 req/s API, 40K voxel room model from 20 frames.
+
+**Brain integration:** Spatial observations (motion, vitals, skeleton, occupancy) sync to the ruOS brain every 60 seconds for agent reasoning.
+
+See [PR #405](https://github.com/ruvnet/RuView/pull/405) for full details.
+
 ### What's New in v0.7.0

 <details>
@@ -904,6 +945,8 @@ cargo add wifi-densepose-ruvector   # RuVector v2.0.4 integration layer (ADR-017
 | [`wifi-densepose-api`](https://crates.io/crates/wifi-densepose-api) | REST + WebSocket API layer | -- | [![crates.io](https://img.shields.io/crates/v/wifi-densepose-api.svg)](https://crates.io/crates/wifi-densepose-api) |
 | [`wifi-densepose-config`](https://crates.io/crates/wifi-densepose-config) | Configuration management | -- | [![crates.io](https://img.shields.io/crates/v/wifi-densepose-config.svg)](https://crates.io/crates/wifi-densepose-config) |
 | [`wifi-densepose-db`](https://crates.io/crates/wifi-densepose-db) | Database persistence (PostgreSQL, SQLite, Redis) | -- | [![crates.io](https://img.shields.io/crates/v/wifi-densepose-db.svg)](https://crates.io/crates/wifi-densepose-db) |
+| `wifi-densepose-pointcloud` | Real-time dense point cloud from camera + WiFi CSI fusion (Three.js viewer, brain bridge). Workspace-only for now. | -- | — |
+| `wifi-densepose-geo` | Geospatial context (Sentinel-2 tiles, SRTM elevation, OSM, weather, night-mode). Workspace-only for now. | -- | — |

 All crates integrate with [RuVector v2.0.4](https://github.com/ruvnet/ruvector) — see [AI Backbone](#ai-backbone-ruvector) below.

@@ -50,7 +50,15 @@ ENV RUST_LOG=info
 # Override at runtime:  docker run -e CSI_SOURCE=esp32 ...
 ENV CSI_SOURCE=auto

-ENTRYPOINT ["/bin/sh", "-c"]
-# Shell-form CMD allows $CSI_SOURCE to be substituted at container start.
-# The ENV default above (CSI_SOURCE=auto) applies when the variable is unset.
-CMD ["/app/sensing-server --source ${CSI_SOURCE} --tick-ms 100 --ui-path /app/ui --http-port 3000 --ws-port 3001"]
+# MODELS_DIR controls where the server scans for .rvf model files.
+# Mount a host directory here to make models visible to the API:
+#   docker run -v /path/to/models:/app/models -e MODELS_DIR=/app/models ...
+ENV MODELS_DIR=data/models
+
+COPY docker/docker-entrypoint.sh /app/docker-entrypoint.sh
+
+# Exec-form ENTRYPOINT so Docker appends user arguments correctly.
+# Pass flags directly:  docker run <image> --source esp32 --tick-ms 500
+# Or use env vars:      docker run -e CSI_SOURCE=esp32 <image>
+ENTRYPOINT ["/app/docker-entrypoint.sh"]
+CMD []
@@ -18,8 +18,13 @@ services:
      #          wifi           — use host Wi-Fi RSSI/scan data (Windows netsh)
      #          simulated      — generate synthetic CSI data (no hardware required)
      - CSI_SOURCE=${CSI_SOURCE:-auto}
-    # command is passed as arguments to ENTRYPOINT (/bin/sh -c), so $CSI_SOURCE is expanded by the shell.
-    command: ["/app/sensing-server --source ${CSI_SOURCE:-auto} --tick-ms 100 --ui-path /app/ui --http-port 3000 --ws-port 3001"]
+      # MODELS_DIR controls where the server scans for .rvf model files.
+      # Mount a host directory and set this to make models visible:
+      #   volumes: ["/path/to/models:/app/models"]
+      #   MODELS_DIR=/app/models
+      - MODELS_DIR=${MODELS_DIR:-data/models}
+    # No explicit command needed — docker-entrypoint.sh uses CSI_SOURCE.
+    # Override with: command: ["--source", "esp32", "--tick-ms", "500"]

  python-sensing:
    build:
@@ -0,0 +1,32 @@
+#!/bin/sh
+# Docker entrypoint for WiFi-DensePose sensing server.
+#
+# Supports two usage patterns:
+#
+# 1. No arguments — use defaults from environment:
+#      docker run -e CSI_SOURCE=esp32 ruvnet/wifi-densepose:latest
+#
+# 2. Pass CLI flags directly:
+#      docker run ruvnet/wifi-densepose:latest --source esp32 --tick-ms 500
+#      docker run ruvnet/wifi-densepose:latest --model /app/models/my.rvf
+#
+# Environment variables:
+#   CSI_SOURCE   — data source: auto (default), esp32, wifi, simulated
+#   MODELS_DIR   — directory to scan for .rvf model files (default: data/models)
+set -e
+
+# If the first argument looks like a flag (starts with -), prepend the
+# server binary so users can just pass flags:
+#   docker run <image> --source esp32 --tick-ms 500
+if [ "${1#-}" != "$1" ] || [ -z "$1" ]; then
+    set -- /app/sensing-server \
+        --source "${CSI_SOURCE:-auto}" \
+        --tick-ms 100 \
+        --ui-path /app/ui \
+        --http-port 3000 \
+        --ws-port 3001 \
+        --bind-addr 0.0.0.0 \
+        "$@"
+fi
+
+exec "$@"
@@ -0,0 +1,65 @@
+# ADR-044: Geospatial Satellite Integration
+
+## Status
+Accepted
+
+## Context
+RuView generates real-time 3D point clouds from camera + WiFi CSI, but these exist in a local coordinate frame with no geographic reference. Integrating free satellite imagery, terrain elevation, and map data provides environmental context that enables the ruOS brain to reason about the physical world beyond the room.
+
+## Decision
+
+### Data Sources (all free, no API keys)
+| Source | Data | Resolution | Update | Format |
+|--------|------|-----------|--------|--------|
+| EOX Sentinel-2 Cloudless | Satellite tiles | 10m | Static mosaic | XYZ/JPEG |
+| SRTM GL1 (NASA) | Elevation/DEM | 30m (1-arcsec) | Static | Binary HGT |
+| Overpass API (OSM) | Buildings, roads | Vector | Real-time | JSON |
+| ip-api.com | IP geolocation | ~1km | Per-request | JSON |
+| Sentinel-2 STAC | Temporal satellite | 10m | Every 5 days | COG/STAC |
+| Open Meteo | Weather | Point | Hourly | JSON |
+
+### Architecture
+Pure Rust implementation in `wifi-densepose-geo` crate. No GDAL/PROJ/GEOS — coordinate transforms implemented directly (~250 LOC). Tile caching on disk at `~/.local/share/ruview/geo-cache/`.
+
+### Coordinate System
+- WGS84 for geographic coordinates
+- ENU (East-North-Up) as the bridge between local sensor frame and world
+- Local sensor frame: camera origin, +Z forward, +Y up
+
+### Temporal Awareness
+Nightly scheduled fetch of Sentinel-2 latest imagery + OSM diffs + weather.
+Changes detected via image comparison and stored as brain memories for
+contrastive learning.
+
+### Brain Integration
+Geospatial context stored as brain memories:
+- `spatial-geo`: location, elevation, nearby landmarks
+- `spatial-change`: detected changes in satellite/OSM data
+- `spatial-weather`: current conditions + forecast
+- `spatial-season`: vegetation index, snow cover, seasonal patterns
+- `spatial-local`: hyperlocal web context from Common Crawl WET
+
+### Extended Data Sources (via ruvector WET/Common Crawl)
+| Source | Data | Use |
+|--------|------|-----|
+| Common Crawl WET | Web text near location | Local business info, reviews, events |
+| Wikidata | Structured knowledge | Building names, POI descriptions |
+| NASA FIRMS | Active fire (3-hour) | Safety alerts |
+| USGS Earthquakes | Seismic events | Safety context |
+| OpenAQ | Air quality (PM2.5) | Environmental health |
+| Overture Maps | Building footprints (Meta/MS) | Higher quality than OSM |
+
+The ruvector brain server has existing `web_ingest` + Common Crawl support.
+WET files filtered by geographic URL patterns provide hyperlocal context.
+
+## Consequences
+### Positive
+- Agent gains environmental awareness beyond the room
+- Temporal data enables seasonal calibration of CSI sensing
+- Change detection finds construction, vegetation, weather effects
+- All data sources are genuinely free with no API keys
+
+### Negative
+- Initial data fetch requires internet (~2MB tiles + ~25MB DEM)
+- Cached data becomes stale (mitigated by nightly refresh)
+- IP geolocation has ~1km accuracy (mitigated by manual override)
@@ -1,4 +1,4 @@
-# ADR-044: Provisioning Tool Enhancements
+# ADR-050: Provisioning Tool Enhancements

 **Status**: Proposed
 **Date**: 2026-03-03
@@ -0,0 +1,503 @@
+# ADR-081: Adaptive CSI Mesh Firmware Kernel
+
+| Field       | Value                                                                 |
+|-------------|-----------------------------------------------------------------------|
+| **Status**  | Accepted — Layers 1/2/3/4/5 implemented and host-tested; mesh RX path and Ed25519 signing tracked as Phase 3.5 polish |
+| **Date**    | 2026-04-19                                                            |
+| **Authors** | ruv                                                                   |
+| **Depends** | ADR-018, ADR-028, ADR-029, ADR-031, ADR-032, ADR-039, ADR-066, ADR-073 |
+
+## Context
+
+RuView's firmware grew bottom-up. ADR-018 defined a binary CSI frame, ADR-029
+added channel hopping and TDM, ADR-039 added a tiered edge-intelligence
+pipeline, ADR-040 added programmable WASM modules, ADR-060 added per-node
+channel and MAC overrides, ADR-066 added a swarm bridge to a coordinator, and
+ADR-073 added multifrequency mesh scanning. Each one was a sound local
+decision. Together they produced a firmware that works on ESP32-S3 but is
+**implicitly coupled** to that chipset through `csi_collector.c` calling
+`esp_wifi_*` directly and through hard-coded assumptions about the WiFi driver
+callback shape.
+
+This is a problem for three reasons:
+
+1. **Portability.** Espressif exposes CSI through an official driver API. On
+   locked Broadcom and Cypress chips, projects like Nexmon achieve the same
+   thing by patching the firmware blob — but only for specific chip and
+   firmware build combinations. Future RuView nodes will likely span both
+   models plus eventually a custom silicon path. Today, none of the modules
+   above can be reused unchanged on any non-ESP32 chip.
+
+2. **Adaptivity.** The current firmware reacts to configuration, not to
+   conditions. Channel hop intervals, edge tier, vitals cadence, top-K
+   subcarriers, fall threshold, and power duty are all read from NVS at boot
+   and never revisited. There is no closed-loop control: if a channel becomes
+   congested, if motion spikes, if inter-node coherence drops, or if the
+   environment is stable enough to coast at lower cadence, nothing changes
+   onboard. The adaptive classifier in `wifi-densepose-sensing-server` does
+   adapt — but only on the host side, after the data has already traversed the
+   network at fixed rate.
+
+3. **Mesh as an afterthought.** ADR-029 wired in a `TdmCoordinator` and ADR-066
+   added a swarm bridge to a Cognitum Seed, but there is no first-class node
+   role enumeration (anchor / observer / fusion-relay / coordinator), no
+   role-assignment protocol, no `FEATURE_DELTA` message type, no
+   coordinator-driven channel plan, and no automatic role re-election when a
+   node drops. Multi-node deployments today are stitched together by manual
+   per-node NVS provisioning.
+
+The hard truth is that the firmware hack — getting raw CSI off a radio — is
+not the moat. The moat is **adaptive control, multi-node fusion, compact
+state encoding, persistent memory, and contrastive reasoning on top of the
+radio layer**. The current architecture does not name those layers, so they
+get reinvented inline by every new ADR.
+
+## Decision
+
+Adopt a **5-layer adaptive RF sensing kernel** as the canonical RuView
+firmware architecture, and refactor the existing modules to fit underneath
+it. The five layers, top to bottom:
+
+```
+┌─────────────────────────────────────────────────────────────────────────┐
+│ Layer 5 — Rust handoff                                                  │
+│   Two streams only: feature_state (default) and debug_csi_frame (gated) │
+└─────────────────────────────────────────────────────────────────────────┘
+┌─────────────────────────────────────────────────────────────────────────┐
+│ Layer 4 — On-device feature extraction                                  │
+│   100 ms motion, 1 s respiration, 5 s baseline windows                  │
+│   Emits compact rv_feature_state_t (magic 0xC5110006)                   │
+└─────────────────────────────────────────────────────────────────────────┘
+┌─────────────────────────────────────────────────────────────────────────┐
+│ Layer 3 — Mesh sensing plane                                            │
+│   Roles: Anchor / Observer / Fusion relay / Coordinator                 │
+│   Messages: TIME_SYNC, ROLE_ASSIGN, CHANNEL_PLAN, CALIBRATION_START,    │
+│             FEATURE_DELTA, HEALTH, ANOMALY_ALERT                        │
+└─────────────────────────────────────────────────────────────────────────┘
+┌─────────────────────────────────────────────────────────────────────────┐
+│ Layer 2 — Adaptive controller                                           │
+│   Fast loop  ~200 ms — packet rate, active probing                      │
+│   Medium loop ~1 s  — channel selection, role changes                   │
+│   Slow loop ~30 s  — baseline recalibration                             │
+└─────────────────────────────────────────────────────────────────────────┘
+┌─────────────────────────────────────────────────────────────────────────┐
+│ Layer 1 — Radio Abstraction Layer (rv_radio_ops_t vtable)               │
+│   ESP32 binding, future Nexmon binding, future custom silicon binding   │
+└─────────────────────────────────────────────────────────────────────────┘
+```
+
+### Layer 1 — Radio Abstraction Layer
+
+A single function-pointer vtable, `rv_radio_ops_t`, defined in
+`firmware/esp32-csi-node/main/rv_radio_ops.h`:
+
+```c
+typedef struct {
+    int (*init)(void);
+    int (*set_channel)(uint8_t ch, uint8_t bw);
+    int (*set_mode)(uint8_t mode);            /* RV_RADIO_MODE_* */
+    int (*set_csi_enabled)(bool en);
+    int (*set_capture_profile)(uint8_t profile_id);
+    int (*get_health)(rv_radio_health_t *out);
+} rv_radio_ops_t;
+```
+
+Capture profiles, named not numbered:
+
+| Profile                        | Intent                                                |
+|--------------------------------|-------------------------------------------------------|
+| `RV_PROFILE_PASSIVE_LOW_RATE`  | Default idle: minimum cadence, presence only          |
+| `RV_PROFILE_ACTIVE_PROBE`      | Inject NDP frames at high rate                        |
+| `RV_PROFILE_RESP_HIGH_SENS`    | Quietest channel, longest window, vitals-only         |
+| `RV_PROFILE_FAST_MOTION`       | Short window, high cadence                            |
+| `RV_PROFILE_CALIBRATION`       | Synchronized burst across nodes                       |
+
+Two bindings ship in this ADR:
+
+- **ESP32 binding** (`rv_radio_ops_esp32.c`) wraps `csi_collector.c`,
+  `esp_wifi_set_channel()`, `esp_wifi_set_csi()`, and
+  `csi_inject_ndp_frame()`.
+- **Mock binding** (`rv_radio_ops_mock.c`) wraps `mock_csi.c` so QEMU
+  scenarios can exercise the controller and mesh plane without a radio.
+
+A third binding (Nexmon-patched Broadcom) is reserved but not implemented
+here.
+
+### Layer 2 — Adaptive controller
+
+`firmware/esp32-csi-node/main/adaptive_controller.{c,h}`. A single FreeRTOS
+task with three cooperating timers:
+
+| Loop   | Period  | Inputs                                                                 | Outputs                                              |
+|--------|---------|------------------------------------------------------------------------|------------------------------------------------------|
+| Fast   | ~200 ms | packet yield, retry/drop rate, motion score                            | cadence (vital_interval_ms), active vs passive probe |
+| Medium | ~1 s    | CSI variance, RSSI median, channel occupancy, inter-node agreement     | channel selection (via radio ops), role transitions  |
+| Slow   | ~30 s   | drift profile (Stable/Linear/StepChange), respiration confidence       | baseline recalibration, switch to delta-only mode    |
+
+The controller publishes its decisions through the radio ops vtable
+(`set_capture_profile`, `set_channel`) and through the mesh plane
+(`CHANNEL_PLAN`, `ROLE_ASSIGN`). Default policy is conservative and matches
+today's behavior; aggressive adaptation is opt-in via Kconfig.
+
+### Layer 3 — Mesh sensing plane
+
+Extends `swarm_bridge.c` with explicit node roles (Anchor / Observer /
+Fusion relay / Coordinator) and a 7-message type protocol:
+
+| Message              | Cadence            | Sender(s)        | Purpose                                       |
+|----------------------|--------------------|------------------|-----------------------------------------------|
+| `TIME_SYNC`          | 100 ms             | Anchor           | Reuse ADR-032 `SyncBeacon` (28 bytes, HMAC)   |
+| `ROLE_ASSIGN`        | event-driven       | Coordinator      | Node ID → role mapping                         |
+| `CHANNEL_PLAN`       | event-driven       | Coordinator      | Per-node channel + dwell schedule              |
+| `CALIBRATION_START`  | event-driven       | Coordinator      | Synchronized calibration burst                 |
+| `FEATURE_DELTA`      | 1–10 Hz            | Observer / Relay | Compact feature delta (see Layer 4)            |
+| `HEALTH`             | 1 Hz               | All              | `rv_node_status_t` (see below)                 |
+| `ANOMALY_ALERT`      | event-driven       | Observer         | Phase-physics violation, multi-link mismatch   |
+
+Node status payload:
+
+```c
+typedef struct __attribute__((packed)) {
+    uint8_t  node_id[8];
+    uint64_t local_time_us;
+    uint8_t  role;
+    uint8_t  current_channel;
+    uint8_t  current_bw;
+    int8_t   noise_floor_dbm;
+    uint16_t pkt_yield;
+    uint16_t sync_error_us;
+    uint16_t health_flags;
+} rv_node_status_t;
+```
+
+Time-sync target is an engineering goal, not a guaranteed constant — it
+depends on the clock quality of the chosen radio family. The first
+acceptance test (Phase 2) measures it on real hardware.
+
+### Layer 4 — On-device feature extraction
+
+Defined in `firmware/esp32-csi-node/main/rv_feature_state.h`. Single
+on-the-wire packet, **60 bytes packed** (verified by `_Static_assert` and
+host unit test), magic `0xC5110006` (next free after ADR-039's
+`0xC5110002`, ADR-069's `0xC5110003`, ADR-063's `0xC5110004`, and ADR-039's
+compressed `0xC5110005`):
+
+```c
+#define RV_FEATURE_STATE_MAGIC  0xC5110006u
+
+typedef struct __attribute__((packed)) {
+    uint32_t magic;             /* RV_FEATURE_STATE_MAGIC */
+    uint8_t  node_id;
+    uint8_t  mode;              /* RV_PROFILE_* identifier */
+    uint16_t seq;               /* monotonic per-node sequence */
+    uint64_t ts_us;             /* node-local microseconds */
+    float    motion_score;
+    float    presence_score;
+    float    respiration_bpm;
+    float    respiration_conf;
+    float    heartbeat_bpm;
+    float    heartbeat_conf;
+    float    anomaly_score;
+    float    env_shift_score;
+    float    node_coherence;
+    uint16_t quality_flags;
+    uint16_t reserved;
+    uint32_t crc32;             /* IEEE polynomial over bytes [0..end-4] */
+} rv_feature_state_t;
+
+_Static_assert(sizeof(rv_feature_state_t) == 60,
+               "rv_feature_state_t must be 60 bytes on the wire");
+```
+
+Three windows feed it: 100 ms (motion), 1 s (respiration), 5 s (baseline /
+env shift). Each `rv_feature_state_t` represents the most recent state of
+all three; mode field tells the receiver which window dominates this
+update.
+
+`rv_feature_state_t` does not replace ADR-039's `edge_vitals_pkt_t`
+(0xC5110002) or ADR-063's `edge_fused_vitals_pkt_t` (0xC5110004). Those
+remain the wire format for vitals-specific consumers. `rv_feature_state_t`
+is the **default upstream payload** for the sensing pipeline; vitals
+packets are now an alternate emission mode for backward compatibility.
+
+### Layer 5 — Rust handoff
+
+The Rust side sees only two streams from a node:
+
+1. **`feature_state` stream** — `rv_feature_state_t`, default-on, 1–10 Hz.
+2. **`debug_csi_frame` stream** — ADR-018 raw frames (magic 0xC5110001),
+   default-off, opt-in via NVS or `CHANNEL_PLAN`. Used for calibration,
+   debugging, training-set capture.
+
+The Rust handoff is mirrored as a trait in
+`crates/wifi-densepose-hardware/src/radio_ops.rs` so test harnesses (and
+eventually the Rust-side controller for centralized coordinator nodes) can
+swap radio backends without touching `wifi-densepose-signal`,
+`wifi-densepose-ruvector`, `wifi-densepose-train`, or
+`wifi-densepose-mat`. Rust-side mirror trait is **out of scope for the
+firmware-only PR** that ships this ADR; tracked as Phase 4 follow-up.
+
+## State Machine
+
+```
+BOOT → SELF_TEST → RADIO_INIT → TIME_SYNC → CALIBRATION → SENSE_IDLE
+                                                            ↓ ↑
+                                                         SENSE_ACTIVE
+                                                            ↓
+                                                          ALERT
+                                                            ↓
+                                                        DEGRADED
+```
+
+Transitions:
+
+- **CALIBRATION** on boot, on role change, on sustained inter-node
+  disagreement.
+- **SENSE_ACTIVE** when motion or anomaly score crosses threshold.
+- **DEGRADED** when packet yield, sync quality, or memory pressure drops
+  below threshold; falls back to ADR-039 Tier-0 raw passthrough as the
+  last-resort survivable mode.
+
+## Data budgets
+
+| Stream                  | Default rate                | Notes                                        |
+|-------------------------|-----------------------------|----------------------------------------------|
+| Raw capture (internal)  | 50–200 pps per observer     | Stays on-device unless debug stream enabled  |
+| `rv_feature_state_t`    | 1–10 Hz per node            | Default upstream                             |
+| `ANOMALY_ALERT`         | event-driven                | Burst-bounded                                |
+| Debug ADR-018 raw CSI   | 0 (off by default)          | Burst-only via `CHANNEL_PLAN` debug flag     |
+
+ADR-039 measured raw CSI at ~5 KB/frame and ~100 KB/s per node. The default
+upstream with ADR-081's 60-byte `rv_feature_state_t` at 5 Hz is **300 B/s
+per node — a 99.7% reduction**. A 50-node deployment at 5 Hz fits in
+15 KB/s total, easily carried by a single-AP backhaul.
+
+## Channel planning policy
+
+Codified rules — these are constraints on the controller, not just defaults:
+
+- Keep one anchor on a stable channel; observers distributed across the
+  least-congested channels.
+- Rotate **one** observer at a time. Never change all nodes simultaneously.
+- Pin `RV_PROFILE_RESP_HIGH_SENS` to the quietest stable channel for the
+  duration of a respiration window.
+- Use a short active burst on a quiet channel for calibration, then return
+  to passive capture.
+
+This generalizes the per-deployment policy in ADR-073 ("node 1: ch 1/6/11,
+node 2: ch 3/5/9") into a controller-driven plan that the coordinator can
+publish via `CHANNEL_PLAN`. IEEE 802.11bf is the standards direction this
+points toward.
+
+## Security & integrity
+
+- Every `FEATURE_DELTA` carries node id, monotonic seq, ts_us, and CRC32
+  (IEEE polynomial), per the struct above.
+- Every control message (`ROLE_ASSIGN`, `CHANNEL_PLAN`, `CALIBRATION_START`)
+  carries sender role, epoch, replay window index, and authorization class,
+  reusing the HMAC-SHA256 + 16-frame replay window from ADR-032
+  (`secure_tdm.rs`).
+- Optional Ed25519 signature at session/batch granularity for signed
+  `CHANNEL_PLAN` and `CALIBRATION_START` messages, reusing the
+  ADR-040/RVF Ed25519 path already shipping in firmware.
+
+## Reuse map (do not rewrite)
+
+| Concern                     | Existing component                                                                                       |
+|-----------------------------|----------------------------------------------------------------------------------------------------------|
+| ADR-018 binary frame        | `firmware/esp32-csi-node/main/csi_collector.c` (magic `0xC5110001`)                                      |
+| ESP32 CSI driver glue       | `firmware/esp32-csi-node/main/csi_collector.c:225-303`                                                   |
+| Channel hopping             | `csi_collector_set_hop_table()` and `csi_collector_start_hop_timer()`                                    |
+| NDP injection               | `csi_inject_ndp_frame()` (placeholder, sufficient for L1 binding)                                        |
+| TDM scheduling              | `crates/wifi-densepose-hardware/src/esp32/tdm.rs`                                                        |
+| Secure beacons              | `crates/wifi-densepose-hardware/src/esp32/secure_tdm.rs` (HMAC + replay)                                 |
+| Edge intelligence (Tier 1/2)| `firmware/esp32-csi-node/main/edge_processing.c` (magic `0xC5110002`/`0xC5110005`)                       |
+| Fused vitals                | ADR-063 `edge_fused_vitals_pkt_t` (magic `0xC5110004`)                                                   |
+| Swarm bridge                | `firmware/esp32-csi-node/main/swarm_bridge.c`                                                            |
+| WASM Tier 3 modules         | `firmware/esp32-csi-node/main/wasm_runtime.c` (ADR-040)                                                  |
+| Multistatic fusion          | `crates/wifi-densepose-ruvector/src/viewpoint/fusion.rs`                                                 |
+| Adaptive classifier         | `crates/wifi-densepose-sensing-server/src/adaptive_classifier.rs:61-75`                                  |
+| Feature primitives (Rust)   | `crates/wifi-densepose-signal/src/{motion.rs,features.rs,ruvsense/coherence.rs}`                         |
+
+## Implementation status (2026-04-19)
+
+This ADR ships **with** the initial implementation, not ahead of it.
+Artifacts delivered alongside the ADR:
+
+| Component                               | File                                                                    | State       |
+|-----------------------------------------|-------------------------------------------------------------------------|-------------|
+| L1 vtable + profile/mode/health enums   | `firmware/esp32-csi-node/main/rv_radio_ops.h`                           | Implemented |
+| L1 ESP32 binding                        | `firmware/esp32-csi-node/main/rv_radio_ops_esp32.c`                     | Implemented |
+| L1 Mock (QEMU) binding                  | `firmware/esp32-csi-node/main/rv_radio_ops_mock.c`                      | Implemented |
+| L2 Controller FreeRTOS plumbing         | `firmware/esp32-csi-node/main/adaptive_controller.c`                    | Implemented |
+| L2 Pure decision policy (testable)      | `firmware/esp32-csi-node/main/adaptive_controller_decide.c`             | Implemented |
+| L3 Mesh-plane types + encoder/decoder   | `firmware/esp32-csi-node/main/rv_mesh.{h,c}`                            | Implemented |
+| L3 HEALTH emit (slow loop, 30 s)        | `adaptive_controller.c:slow_loop_cb()`                                  | Implemented |
+| L3 ANOMALY_ALERT on state transition    | `adaptive_controller.c:apply_decision()`                                | Implemented |
+| L3 Role tracking + epoch monotonicity   | `adaptive_controller.c` (`s_role`, `s_mesh_epoch`)                      | Implemented |
+| L4 Feature state packet + helpers       | `firmware/esp32-csi-node/main/rv_feature_state.{h,c}`                   | Implemented |
+| L4 Emitter from fast loop (5 Hz)        | `adaptive_controller.c:emit_feature_state()`                            | Implemented |
+| L1 Packet yield + send-fail accessors   | `csi_collector.c:csi_collector_get_pkt_yield_per_sec()` + send fail    | Implemented |
+| L5 Rust mirror trait + mesh decoder     | `crates/wifi-densepose-hardware/src/radio_ops.rs`                       | Implemented |
+| Host C unit tests (60 assertions)       | `firmware/esp32-csi-node/tests/host/`                                   | **60/60 ✓** |
+| Rust unit tests (8 assertions)          | `crates/wifi-densepose-hardware` (`radio_ops::tests`)                   | **8/8 ✓**   |
+| QEMU validator hooks (3 new checks)     | `scripts/validate_qemu_output.py` (check 17/18/19)                      | Passing     |
+| L3 mesh RX path (receive + dispatch)    | —                                                                       | Phase 3.5   |
+| Ed25519 signing for CHANNEL_PLAN etc.   | —                                                                       | Phase 3.5   |
+| Hardware validation on COM7             | —                                                                       | Pending     |
+
+## Measured performance
+
+Host-side benchmarks (`firmware/esp32-csi-node/tests/host/`), x86-64,
+gcc `-O2`, 2026-04-19. Numbers are illustrative of algorithmic cost on
+a modern CPU; on-target ESP32-S3 Xtensa LX7 at 240 MHz is ~5–10×
+slower for bit-by-bit CRC and broadly comparable for the decide
+function after inlining.
+
+| Operation                                   | Cost per call       | Notes                               |
+|---------------------------------------------|---------------------|-------------------------------------|
+| `adaptive_controller_decide()`              | **3.2 ns** (host)   | O(1) policy, 9 branches evaluated   |
+| `rv_feature_state_crc32()` (56 B hashed)    | **612 ns** (host)   | 87 MB/s — bit-by-bit IEEE CRC32     |
+| `rv_feature_state_finalize()` (full)        | **592 ns** (host)   | CRC-dominated                       |
+| `rv_mesh_encode_health()` + `_decode()`     | **1010 ns** (host)  | Full roundtrip, hdr+payload+CRC     |
+
+Projected on-target cost at 5 Hz cadence:
+
+| Budget                                     | Value               |
+|--------------------------------------------|---------------------|
+| Controller fast-loop tick work (ESP32-S3)  | < 10 μs (est.)      |
+| CRC32 per feature packet (ESP32-S3)        | ~3–6 μs (est.)      |
+| Feature-state emit cost @ 5 Hz             | ~30 μs/sec (0.003%) |
+| UDP send cost (existing stream_sender)     | — unchanged —       |
+
+**Bandwidth:**
+
+| Mode                                        | Rate        |
+|---------------------------------------------|-------------|
+| Raw ADR-018 CSI (pre-ADR-081)               | ~100 KB/s   |
+| ADR-039 compressed CSI (Tier 1)             | ~50–70 KB/s |
+| ADR-039 vitals packet (32 B @ 1 Hz)         | 32 B/s      |
+| **ADR-081 feature state (60 B @ 5 Hz)**     | **300 B/s** |
+
+**Memory:**
+
+| Component                                   | Static RAM          |
+|---------------------------------------------|---------------------|
+| Controller state (s_cfg + s_last_obs + …)   | ~80 bytes           |
+| Feature-state emit packet (stack, per tick) | 60 bytes            |
+| CRC lookup table                            | 0 (bit-by-bit)      |
+| Three FreeRTOS software timers              | ~3 × 56 B overhead  |
+
+**Tests:**
+
+| Suite                                       | Assertions | Result     |
+|---------------------------------------------|-----------:|------------|
+| `test_adaptive_controller` (host C)         |         18 | **PASS**   |
+| `test_rv_feature_state` (host C)            |         15 | **PASS**   |
+| `test_rv_mesh` (host C)                     |         27 | **PASS**   |
+| `radio_ops::tests` (Rust)                   |          8 | **PASS**   |
+| **Total**                                   |     **68** | **68/68**  |
+| QEMU validator (`ADR-061` pipeline)         |  +3 checks | hooked     |
+
+Cross-language parity: the Rust `crc32_ieee()` is verified against the
+same known vectors used by the C test (`0xCBF43926` for `"123456789"`,
+`0xD202EF8D` for a single zero byte), and the `mesh_constants_match_firmware`
+test asserts `MESH_MAGIC`, `MESH_VERSION`, `MESH_HEADER_SIZE`, and
+`MESH_MAX_PAYLOAD` match the C header byte-for-byte. Any drift between
+the two implementations fails CI.
+
+## New components this ADR authorizes
+
+| New file                                                                                  | Purpose                                                |
+|-------------------------------------------------------------------------------------------|--------------------------------------------------------|
+| `firmware/esp32-csi-node/main/rv_radio_ops.h`                                             | `rv_radio_ops_t` vtable + profile/mode/health enums    |
+| `firmware/esp32-csi-node/main/rv_radio_ops_esp32.c`                                       | ESP32 binding wrapping `csi_collector` + `esp_wifi_*`  |
+| `firmware/esp32-csi-node/main/rv_feature_state.h`                                         | `rv_feature_state_t` packet + `RV_FEATURE_STATE_MAGIC` |
+| `firmware/esp32-csi-node/main/adaptive_controller.h`                                      | Controller API + observation/decision structs           |
+| `firmware/esp32-csi-node/main/adaptive_controller.c`                                      | 200 ms / 1 s / 30 s loops, FreeRTOS task               |
+| `crates/wifi-densepose-hardware/src/radio_ops.rs` *(Phase 4 follow-up)*                  | Rust mirror trait for backend swapping                 |
+
+## Roadmap
+
+| Phase | Scope                                      | Status                                           |
+|-------|--------------------------------------------|--------------------------------------------------|
+| 1     | Single supported-CSI node + features → Rust | Largely done via ADR-018, ADR-039                |
+| 2     | 3-node Seed v2 mesh + time-sync + plan     | Partially done (ADR-029, ADR-066, ADR-073)       |
+| 3     | Adaptive controller, delta reporting, DEGRADED | **This ADR** authorizes the firmware skeleton |
+| 4     | Cross-chipset bindings (Nexmon, custom)    | Reserved; gated by Phase 3 stability             |
+
+## Acceptance criteria
+
+1. **Portability gate.** A second `rv_radio_ops_t` binding (mock or
+   alternate chipset) compiles and runs the controller + mesh plane code
+   unchanged. The signal/ruvector/train/mat crates compile against a Rust
+   mirror trait without modification.
+2. **Mesh resilience benchmark.** A 3-node prototype maintains stable
+   `presence_score` and `motion_score` when one observer changes channel
+   or drops out for 5 seconds.
+3. **Default upstream is compact.** Raw ADR-018 CSI is off by default; the
+   default upstream is `rv_feature_state_t` at 1–10 Hz.
+4. **Integrity.** Every `FEATURE_DELTA` carries node id, seq, ts_us, CRC32.
+   Every control message carries epoch + replay-window + authorization
+   class, verified against ADR-032's existing HMAC machinery.
+
+## Consequences
+
+### Positive
+
+- The firmware hack is no longer the moat. The 5 layers are explicit and
+  separately testable.
+- Default upstream bandwidth drops ~99% vs. raw ADR-018, making 50+ node
+  deployments practical.
+- A documented vtable + Kconfig surface gates new features ("which layer
+  does this belong in?") instead of letting them accrete inline.
+- Adaptive control of cadence, channel, and role becomes a first-class
+  firmware concern — the user-facing knob ("be smarter when busy, save
+  power when idle") finally has a home.
+
+### Negative
+
+- An abstraction tax on the single-chipset case: `rv_radio_ops_t` is a
+  vtable for a family currently of size 1.
+- Adds ~5–8 KB SRAM for controller state and the new feature-state ring.
+- Requires re-routing existing `swarm_bridge` traffic through the mesh
+  plane message types over time (incremental, not breaking).
+
+### Neutral
+
+- This ADR introduces no new dependencies, no new networking stacks, and
+  no new hardware requirements.
+- ADR-039, ADR-063, ADR-066, ADR-069, ADR-073 are **not superseded**; they
+  are reframed as components of Layer 3 / Layer 4.
+
+## Verification
+
+```bash
+# Host-side C unit tests (no ESP-IDF, no QEMU required)
+cd firmware/esp32-csi-node/tests/host
+make check
+# → test_adaptive_controller: 18/18 pass, decide() = 3.2 ns/call
+# → test_rv_feature_state:    15/15 pass, CRC32(56 B) = 612 ns/pkt
+# → test_rv_mesh:             27/27 pass, HEALTH roundtrip = 1.0 µs
+
+# Rust-side radio_ops trait + mesh decoder tests
+cd rust-port/wifi-densepose-rs
+cargo test -p wifi-densepose-hardware --no-default-features --lib radio_ops
+# → 8 passed; verifies MockRadio, CRC32 parity with firmware vectors,
+#   HEALTH encode/decode roundtrip, bad-magic/short/CRC rejection,
+#   and that MESH_MAGIC/VERSION/HEADER_SIZE match rv_mesh.h
+
+# QEMU end-to-end (requires ESP-IDF + qemu-system-xtensa, see ADR-061)
+bash scripts/qemu-esp32s3-test.sh
+# → Validator now runs 19 checks; new ADR-081 checks 17/18/19 verify
+#   adaptive_ctrl boot line, rv_radio_mock binding registration, and
+#   slow-loop heartbeat.
+
+# Full workspace
+cargo test --workspace --no-default-features
+```
+
+## Related
+
+ADR-018, ADR-028, ADR-029, ADR-030, ADR-031, ADR-032, ADR-039, ADR-040,
+ADR-060, ADR-061, ADR-063, ADR-066, ADR-069, ADR-073, ADR-078.
@@ -536,6 +536,110 @@ Both UIs update in real-time via WebSocket and auto-detect the sensing server on

 ---

+## Dense Point Cloud (Camera + WiFi CSI Fusion)
+
+RuView can generate real-time 3D point clouds by fusing camera depth estimation with WiFi CSI spatial sensing. This creates a spatial model of the environment that updates in real-time.
+
+### Setup
+
+```bash
+# Build the pointcloud binary
+cd rust-port/wifi-densepose-rs
+cargo build --release -p wifi-densepose-pointcloud
+
+# Start the server (auto-detects camera + CSI). Loopback-only by default.
+./target/release/ruview-pointcloud serve --bind 127.0.0.1:9880
+```
+
+Open `http://localhost:9880` for the interactive Three.js 3D viewer.
+
+> **Security note.** The server exposes live camera, skeleton, vitals, and occupancy over HTTP. The `--bind` flag defaults to `127.0.0.1:9880` (loopback-only). Exposing on `0.0.0.0` or a LAN IP is opt-in — the server logs a warning when it does, but there is no auth/TLS layer. Put a reverse proxy in front if you need remote access.
+
+> **Brain URL.** Observations are POSTed to `http://127.0.0.1:9876` by default. Override via the `RUVIEW_BRAIN_URL` environment variable or the `--brain <url>` flag on `serve` / `train`.
+
+### Sensors
+
+| Sensor | Auto-detected | Data |
+|--------|--------------|------|
+| Camera (`/dev/video0`) | Yes (Linux UVC) | RGB frames → MiDaS depth → 3D points |
+| ESP32 CSI (UDP:3333) | Yes (if provisioned) | ADR-018 binary → occupancy + pose + vitals |
+| MiDaS depth server (port 9885) | Optional | GPU-accelerated neural depth estimation |
+
+### Commands
+
+| Command | Description |
+|---------|-------------|
+| `ruview-pointcloud serve --bind 127.0.0.1:9880` | Start HTTP server + Three.js viewer (loopback-only by default) |
+| `ruview-pointcloud demo` | Generate synthetic point cloud (no hardware needed) |
+| `ruview-pointcloud capture --output room.ply` | Capture single frame to PLY file |
+| `ruview-pointcloud cameras` | List available cameras |
+| `ruview-pointcloud train --data-dir ./data [--brain URL]` | Depth calibration + occupancy training (writes under canonicalized `data-dir`; refuses `..` traversal) |
+| `ruview-pointcloud csi-test --count 100` | Send test CSI frames (no ESP32 needed) |
+| `ruview-pointcloud fingerprint <name> [--seconds 5]` | Record a named CSI room fingerprint for later matching |
+
+### Pipeline Components
+
+1. **ADR-018 Parser** — Decodes ESP32 CSI binary frames from UDP (magic `0xC5110001` raw CSI and `0xC5110006` feature state), extracts I/Q subcarrier amplitudes and phases. Lives in `parser.rs`; unit-tested against hand-rolled test vectors.
+2. **Pose (stub)** — 17 COCO keypoint *layout* generated by `heuristic_pose_from_amplitude` from CSI amplitude energy. This is **not** the trained WiFlow model — it is a placeholder so the viewer has a skeleton to render. Wiring to real Candle/ONNX inference from the `wifi-densepose-nn` crate is a planned follow-up.
+3. **Vital Signs** — Breathing rate from CSI phase analysis (peak counting on stable subcarrier)
+4. **Motion Detection** — CSI amplitude variance over 20 frames, triggers adaptive capture
+5. **RF Tomography** — Backprojection from per-node RSSI to 8×8×4 occupancy grid
+6. **Camera Depth** — MiDaS monocular depth (GPU) with luminance+edge fallback
+7. **Sensor Fusion** — Voxel-grid merging of camera depth + CSI occupancy
+8. **Brain Bridge** — Stores spatial observations in the ruOS brain every 60 seconds
+
+### API Endpoints
+
+| Endpoint | Method | Returns |
+|----------|--------|---------|
+| `/health` | GET | `{"status": "ok"}` |
+| `/api/status` | GET | Camera, CSI, pipeline state, vitals, motion |
+| `/api/cloud` | GET | Point cloud (up to 1000 points) + pipeline data |
+| `/api/splats` | GET | Gaussian splats for Three.js rendering |
+| `/` | GET | Interactive Three.js 3D viewer |
+
+### Training
+
+The training pipeline calibrates depth estimation and occupancy detection:
+
+```bash
+ruview-pointcloud train --data-dir ~/.local/share/ruview/training --brain http://127.0.0.1:9876
+```
+
+This captures frames, runs depth calibration (grid search over scale/offset/gamma), trains occupancy thresholds, exports DPO preference pairs, and submits results to the ruOS brain.
+
+### Output Formats
+
+- **PLY** — Standard 3D point cloud (ASCII, with RGB color)
+- **Gaussian Splats** — JSON format for Three.js rendering
+- **Brain Memories** — Spatial observations stored as `spatial-observation`, `spatial-motion`, `spatial-vitals`
+
+### Deep Room Scan
+
+Capture a high-quality 3D model of the room:
+
+```bash
+# Stop the live server first (frees the camera)
+# Then capture 20 frames and process with MiDaS
+ruview-pointcloud capture --frames 20 --output room_model.ply
+```
+
+Result: 40,000+ voxels at 5cm resolution, 12,000+ Gaussian splats.
+
+### ESP32 Provisioning for CSI
+
+To send CSI data to the pointcloud server:
+
+```bash
+python3 firmware/esp32-csi-node/provision.py \
+    --port /dev/ttyACM0 \
+    --ssid "YourWiFi" --password "YourPassword" \
+    --target-ip 192.168.1.123 --target-port 3333 \
+    --node-id 1
+```
+
+---
+
 ## Vital Sign Detection

 The system extracts breathing rate and heart rate from CSI signal fluctuations using FFT peak detection.
@@ -4,13 +4,18 @@ set(SRCS
    "wasm_runtime.c" "wasm_upload.c" "rvf_parser.c"
    "mmwave_sensor.c"
    "swarm_bridge.c"
+    # ADR-081 — adaptive CSI mesh firmware kernel
+    "rv_radio_ops_esp32.c"
+    "rv_feature_state.c"
+    "rv_mesh.c"
+    "adaptive_controller.c"
 )

 set(REQUIRES "")

-# ADR-061: Mock CSI generator for QEMU testing
+# ADR-061: Mock CSI generator for QEMU testing + ADR-081 mock radio binding
 if(CONFIG_CSI_MOCK_ENABLED)
-    list(APPEND SRCS "mock_csi.c")
+    list(APPEND SRCS "mock_csi.c" "rv_radio_ops_mock.c")
 endif()

 # ADR-045: AMOLED display support (compile-time optional)
@@ -87,6 +87,89 @@ menu "Edge Intelligence (ADR-039)"

 endmenu

+menu "Adaptive Controller (ADR-081)"
+
+    config ADAPTIVE_FAST_LOOP_MS
+        int "Fast loop period (ms)"
+        default 200
+        range 50 2000
+        help
+            Period of the fast control loop. The fast loop reads radio
+            health and edge-derived motion/presence/anomaly scores and
+            updates the active capture profile. Default 200 ms matches
+            the ADR-081 spec.
+
+    config ADAPTIVE_MEDIUM_LOOP_MS
+        int "Medium loop period (ms)"
+        default 1000
+        range 200 30000
+        help
+            Period of the medium control loop. The medium loop is where
+            channel selection and role transitions happen (when
+            enable_channel_switch / enable_role_change are on).
+
+    config ADAPTIVE_SLOW_LOOP_MS
+        int "Slow loop period (ms)"
+        default 30000
+        range 1000 300000
+        help
+            Period of the slow control loop. The slow loop publishes
+            HEALTH messages and may request CALIBRATION_START on
+            sustained drift.
+
+    config ADAPTIVE_AGGRESSIVE
+        bool "Aggressive adaptation"
+        default n
+        help
+            When enabled, the controller reacts to motion / anomaly
+            sooner and uses a tighter cadence in SENSE_ACTIVE. Default
+            off matches today's conservative behavior.
+
+    config ADAPTIVE_ENABLE_CHANNEL_SWITCH
+        bool "Allow controller to change WiFi channel"
+        default n
+        help
+            When disabled, the controller never calls set_channel() —
+            channel hopping (ADR-029) and channel override (ADR-060)
+            remain in charge. Enable only after Phase 3 follow-up
+            work has wired the channel-plan mesh message.
+
+    config ADAPTIVE_ENABLE_ROLE_CHANGE
+        bool "Allow controller to change mesh role"
+        default n
+        help
+            When disabled, the controller never advertises a different
+            role to the swarm bridge. Enable after the mesh-plane
+            ROLE_ASSIGN protocol is in place.
+
+    config ADAPTIVE_MOTION_THRESH_PERMIL
+        int "Motion threshold (per-mille)"
+        default 200
+        range 1 1000
+        help
+            Motion score above which the controller transitions to
+            SENSE_ACTIVE and selects RV_PROFILE_FAST_MOTION. Expressed
+            in per-mille (200 = 0.20).
+
+    config ADAPTIVE_ANOMALY_THRESH_PERMIL
+        int "Anomaly threshold (per-mille)"
+        default 600
+        range 1 1000
+        help
+            Anomaly score above which the controller transitions to
+            ALERT. Per-mille (600 = 0.60).
+
+    config ADAPTIVE_MIN_PKT_YIELD
+        int "Minimum packet yield before DEGRADED (pps)"
+        default 5
+        range 0 100
+        help
+            CSI callback rate (per second) below which the controller
+            falls back to DEGRADED mode and pins the radio to
+            RV_PROFILE_PASSIVE_LOW_RATE. 0 disables the degraded gate.
+
+endmenu
+
 menu "AMOLED Display (ADR-045)"

    config DISPLAY_ENABLE
@@ -0,0 +1,414 @@
+/**
+ * @file adaptive_controller.c
+ * @brief ADR-081 Layer 2 — Adaptive sensing controller implementation.
+ *
+ * The decide() function is pure and unit-testable; the FreeRTOS plumbing
+ * around it (timers, observation snapshot) is the only ESP-IDF surface.
+ *
+ * Default policy is conservative: it will not change channels unless
+ * enable_channel_switch is true, and it will not change roles unless
+ * enable_role_change is true. With both off the controller still tracks
+ * state and feeds the mesh plane's HEALTH messages, so it is safe to
+ * enable in production before the mesh plane is fully in place.
+ */
+
+#include "adaptive_controller.h"
+#include "rv_radio_ops.h"
+#include "rv_feature_state.h"
+#include "rv_mesh.h"
+#include "edge_processing.h"
+#include "stream_sender.h"
+#include "csi_collector.h"
+
+#include <string.h>
+#include "freertos/FreeRTOS.h"
+#include "freertos/task.h"
+#include "freertos/timers.h"
+#include "esp_log.h"
+#include "esp_timer.h"
+#include "sdkconfig.h"
+
+static const char *TAG = "adaptive_ctrl";
+
+/* ---- Module state ---- */
+
+static bool                s_inited = false;
+static adapt_config_t      s_cfg;
+static adapt_state_t       s_state = ADAPT_STATE_BOOT;
+static adapt_observation_t s_last_obs;
+static bool                s_obs_valid = false;
+static portMUX_TYPE        s_obs_lock = portMUX_INITIALIZER_UNLOCKED;
+
+static TimerHandle_t s_fast_timer   = NULL;
+static TimerHandle_t s_medium_timer = NULL;
+static TimerHandle_t s_slow_timer   = NULL;
+
+/* Forward decl: defined below, called from fast_loop_cb. */
+static void emit_feature_state(void);
+
+/* ---- Defaults ---- */
+
+#ifndef CONFIG_ADAPTIVE_FAST_LOOP_MS
+#define CONFIG_ADAPTIVE_FAST_LOOP_MS    200
+#endif
+#ifndef CONFIG_ADAPTIVE_MEDIUM_LOOP_MS
+#define CONFIG_ADAPTIVE_MEDIUM_LOOP_MS  1000
+#endif
+#ifndef CONFIG_ADAPTIVE_SLOW_LOOP_MS
+#define CONFIG_ADAPTIVE_SLOW_LOOP_MS    30000
+#endif
+#ifndef CONFIG_ADAPTIVE_MIN_PKT_YIELD
+#define CONFIG_ADAPTIVE_MIN_PKT_YIELD   5
+#endif
+/* Defaults expressed as integer permille so Kconfig can carry them. */
+#ifndef CONFIG_ADAPTIVE_MOTION_THRESH_PERMIL
+#define CONFIG_ADAPTIVE_MOTION_THRESH_PERMIL   200  /* 0.20 */
+#endif
+#ifndef CONFIG_ADAPTIVE_ANOMALY_THRESH_PERMIL
+#define CONFIG_ADAPTIVE_ANOMALY_THRESH_PERMIL  600  /* 0.60 */
+#endif
+
+static void apply_defaults(adapt_config_t *cfg)
+{
+    cfg->fast_loop_ms          = CONFIG_ADAPTIVE_FAST_LOOP_MS;
+    cfg->medium_loop_ms        = CONFIG_ADAPTIVE_MEDIUM_LOOP_MS;
+    cfg->slow_loop_ms          = CONFIG_ADAPTIVE_SLOW_LOOP_MS;
+#ifdef CONFIG_ADAPTIVE_AGGRESSIVE
+    cfg->aggressive            = true;
+#else
+    cfg->aggressive            = false;
+#endif
+#ifdef CONFIG_ADAPTIVE_ENABLE_CHANNEL_SWITCH
+    cfg->enable_channel_switch = true;
+#else
+    cfg->enable_channel_switch = false;
+#endif
+#ifdef CONFIG_ADAPTIVE_ENABLE_ROLE_CHANGE
+    cfg->enable_role_change    = true;
+#else
+    cfg->enable_role_change    = false;
+#endif
+    cfg->motion_threshold  = (float)CONFIG_ADAPTIVE_MOTION_THRESH_PERMIL  / 1000.0f;
+    cfg->anomaly_threshold = (float)CONFIG_ADAPTIVE_ANOMALY_THRESH_PERMIL / 1000.0f;
+    cfg->min_pkt_yield     = CONFIG_ADAPTIVE_MIN_PKT_YIELD;
+}
+
+/* Pure decision policy lives in its own file so it can link under
+ * host unit tests without FreeRTOS. It is part of this translation
+ * unit via #include to preserve a single object at build time. */
+#include "adaptive_controller_decide.c"
+
+/* ---- Observation collection ---- */
+
+static void collect_observation(adapt_observation_t *out)
+{
+    memset(out, 0, sizeof(*out));
+
+    /* Radio health from the active binding. */
+    const rv_radio_ops_t *ops = rv_radio_ops_get();
+    if (ops != NULL && ops->get_health != NULL) {
+        rv_radio_health_t h;
+        if (ops->get_health(&h) == ESP_OK) {
+            out->pkt_yield_per_sec = h.pkt_yield_per_sec;
+            out->send_fail_count   = h.send_fail_count;
+            out->rssi_median_dbm   = h.rssi_median_dbm;
+            out->noise_floor_dbm   = h.noise_floor_dbm;
+        }
+    }
+
+    /* Edge-derived state. The ADR-039 vitals packet exposes presence_score
+     * and motion_energy directly; we treat motion_energy as a proxy for
+     * motion_score by clamping to [0,1]. anomaly_score and node_coherence
+     * are not yet emitted by edge_processing — placeholder until Layer 4
+     * extraction lands. */
+    edge_vitals_pkt_t vitals;
+    if (edge_get_vitals(&vitals)) {
+        out->presence_score = vitals.presence_score;
+        float m = vitals.motion_energy;
+        if (m < 0.0f) m = 0.0f;
+        if (m > 1.0f) m = 1.0f;
+        out->motion_score   = m;
+    }
+    out->anomaly_score  = 0.0f;
+    out->node_coherence = 1.0f;
+}
+
+/* ---- Decision application ---- */
+
+/* ADR-081 L3: epoch monotonically advances per mesh session. Seeded at
+ * init; every major state transition or role change bumps it so
+ * receivers can order events. */
+static uint32_t s_mesh_epoch = 1;
+
+/* ADR-081 L3: current node role. Updated by ROLE_ASSIGN receipt (future
+ * mesh-plane RX path) or forced by tests. Default Observer. */
+static uint8_t s_role = RV_ROLE_OBSERVER;
+
+/* 8-byte node id. Upper 7 bytes are zero by default; byte 0 is the
+ * legacy CSI node id for compatibility with the ADR-018 header. */
+static void node_id_bytes(uint8_t out[8])
+{
+    memset(out, 0, 8);
+    out[0] = csi_collector_get_node_id();
+}
+
+static void apply_decision(const adapt_decision_t *dec)
+{
+    const rv_radio_ops_t *ops = rv_radio_ops_get();
+    adapt_state_t prev = s_state;
+
+    if (dec->change_state) {
+        ESP_LOGI(TAG, "state %u → %u",
+                 (unsigned)s_state, (unsigned)dec->new_state);
+        s_state = (adapt_state_t)dec->new_state;
+
+        /* ADR-081 L3: on transition to ALERT, emit ANOMALY_ALERT on the
+         * mesh plane. On any role-relevant transition, bump the epoch. */
+        if (s_state == ADAPT_STATE_ALERT && prev != ADAPT_STATE_ALERT) {
+            uint8_t nid[8];
+            node_id_bytes(nid);
+            adapt_observation_t obs;
+            float motion = 0.0f, anomaly = 0.0f;
+            portENTER_CRITICAL(&s_obs_lock);
+            if (s_obs_valid) { obs = s_last_obs; motion = obs.motion_score;
+                               anomaly = obs.anomaly_score; }
+            portEXIT_CRITICAL(&s_obs_lock);
+            uint8_t severity = (uint8_t)(anomaly * 255.0f);
+            rv_mesh_send_anomaly(s_role, s_mesh_epoch, nid,
+                                 RV_ANOMALY_COHERENCE_LOSS, severity,
+                                 anomaly, motion);
+        }
+        if (s_state == ADAPT_STATE_DEGRADED && prev != ADAPT_STATE_DEGRADED) {
+            uint8_t nid[8];
+            node_id_bytes(nid);
+            rv_mesh_send_anomaly(s_role, s_mesh_epoch, nid,
+                                 RV_ANOMALY_PKT_YIELD_COLLAPSE,
+                                 200, 1.0f, 0.0f);
+        }
+        s_mesh_epoch++;
+    }
+
+    if (dec->change_profile && ops != NULL && ops->set_capture_profile != NULL) {
+        ops->set_capture_profile(dec->new_profile);
+    }
+
+    if (dec->change_channel && s_cfg.enable_channel_switch &&
+        ops != NULL && ops->set_channel != NULL) {
+        ops->set_channel(dec->new_channel, 20);
+    }
+
+    /* suggested_vital_interval_ms: the controller publishes a hint; the
+     * edge pipeline picks it up via edge_processing on its next emit. We
+     * don't yet have edge_set_vital_interval(); recorded for Phase 3. */
+    (void)dec->request_calibration;
+}
+
+/* ---- Loop callbacks ---- */
+
+static void fast_loop_cb(TimerHandle_t t)
+{
+    (void)t;
+    adapt_observation_t obs;
+    collect_observation(&obs);
+
+    portENTER_CRITICAL(&s_obs_lock);
+    s_last_obs  = obs;
+    s_obs_valid = true;
+    portEXIT_CRITICAL(&s_obs_lock);
+
+    adapt_decision_t dec;
+    adaptive_controller_decide(&s_cfg, s_state, &obs, &dec);
+    apply_decision(&dec);
+
+    /* ADR-081 Layer 4/5: emit compact feature state on every fast tick
+     * (default 200 ms → 5 Hz, within the 1–10 Hz spec). Replaces raw
+     * ADR-018 CSI as the default upstream; raw remains available as a
+     * debug stream gated by the channel plan. */
+    emit_feature_state();
+}
+
+static void medium_loop_cb(TimerHandle_t t)
+{
+    (void)t;
+    /* Phase 3 stub: when enable_channel_switch is on, choose a channel
+     * based on RSSI/noise/yield. Today, log the snapshot so operators can
+     * see the controller is running. */
+    adapt_observation_t obs;
+    portENTER_CRITICAL(&s_obs_lock);
+    obs = s_last_obs;
+    portEXIT_CRITICAL(&s_obs_lock);
+
+    if (s_obs_valid) {
+        ESP_LOGI(TAG, "medium tick: state=%u yield=%upps motion=%.2f presence=%.2f rssi=%d",
+                 (unsigned)s_state,
+                 (unsigned)obs.pkt_yield_per_sec,
+                 (double)obs.motion_score,
+                 (double)obs.presence_score,
+                 (int)obs.rssi_median_dbm);
+    }
+}
+
+/* ADR-081 Layer 4: emit one rv_feature_state_t packet onto the wire.
+ *
+ * Pulls from the latest observation + latest vitals + the active capture
+ * profile. Send is best-effort — stream_sender will report its own
+ * failures; we don't re-queue. At 5 Hz default cadence this is 300 B/s
+ * per node, vs. ~100 KB/s for raw ADR-018 CSI. */
+static uint16_t s_feature_state_seq = 0;
+
+static void emit_feature_state(void)
+{
+    rv_feature_state_t pkt;
+    memset(&pkt, 0, sizeof(pkt));
+
+    adapt_observation_t obs;
+    bool have_obs = false;
+    portENTER_CRITICAL(&s_obs_lock);
+    if (s_obs_valid) {
+        obs = s_last_obs;
+        have_obs = true;
+    }
+    portEXIT_CRITICAL(&s_obs_lock);
+
+    if (have_obs) {
+        pkt.motion_score    = obs.motion_score;
+        pkt.presence_score  = obs.presence_score;
+        pkt.anomaly_score   = obs.anomaly_score;
+        pkt.node_coherence  = obs.node_coherence;
+    }
+
+    /* Fill vitals from edge_processing's latest packet. */
+    edge_vitals_pkt_t v;
+    if (edge_get_vitals(&v)) {
+        pkt.respiration_bpm  = (float)v.breathing_rate / 100.0f;
+        pkt.heartbeat_bpm    = (float)v.heartrate / 10000.0f;
+        /* Confidence proxies: presence score for resp, 1.0 if heart BPM
+         * is within physiological range. */
+        pkt.respiration_conf = (v.breathing_rate > 0) ? v.presence_score : 0.0f;
+        pkt.heartbeat_conf   = (v.heartrate > 400000u && v.heartrate < 1800000u)
+                                 ? 0.8f : 0.0f;
+        if (pkt.respiration_bpm > 0.0f) pkt.quality_flags |= RV_QFLAG_RESPIRATION_VALID;
+        if (pkt.heartbeat_bpm   > 0.0f) pkt.quality_flags |= RV_QFLAG_HEARTBEAT_VALID;
+        if (pkt.presence_score >= 0.5f) pkt.quality_flags |= RV_QFLAG_PRESENCE_VALID;
+        if (v.flags & 0x02)             pkt.quality_flags |= RV_QFLAG_ANOMALY_TRIGGERED;  /* fall bit */
+    }
+
+    if (s_state == ADAPT_STATE_DEGRADED)   pkt.quality_flags |= RV_QFLAG_DEGRADED_MODE;
+    if (s_state == ADAPT_STATE_CALIBRATION) pkt.quality_flags |= RV_QFLAG_CALIBRATING;
+
+    /* Active profile, for receiver-side weighting. */
+    const rv_radio_ops_t *ops = rv_radio_ops_get();
+    uint8_t profile = RV_PROFILE_PASSIVE_LOW_RATE;
+    if (ops != NULL && ops->get_health != NULL) {
+        rv_radio_health_t h;
+        if (ops->get_health(&h) == ESP_OK) profile = h.current_profile;
+    }
+
+    rv_feature_state_finalize(&pkt,
+                              csi_collector_get_node_id(),
+                              s_feature_state_seq++,
+                              (uint64_t)esp_timer_get_time(),
+                              profile);
+
+    int sent = stream_sender_send((const uint8_t *)&pkt, sizeof(pkt));
+    if (sent < 0) {
+        ESP_LOGW(TAG, "feature_state emit failed");
+    }
+}
+
+static void slow_loop_cb(TimerHandle_t t)
+{
+    (void)t;
+    /* ADR-081 L3: publish a HEALTH mesh message every slow tick
+     * (default 30 s). The coordinator uses these to track liveness and
+     * detect sync-error drift. */
+    uint8_t nid[8];
+    node_id_bytes(nid);
+    rv_mesh_send_health(s_role, s_mesh_epoch, nid);
+
+    ESP_LOGI(TAG, "slow tick (state=%u, feature_state_seq=%u, role=%u, epoch=%u) HEALTH sent",
+             (unsigned)s_state, (unsigned)s_feature_state_seq,
+             (unsigned)s_role, (unsigned)s_mesh_epoch);
+}
+
+/* ---- Public API ---- */
+
+esp_err_t adaptive_controller_init(const adapt_config_t *cfg)
+{
+    if (s_inited) {
+        return ESP_OK;
+    }
+
+    if (cfg != NULL) {
+        s_cfg = *cfg;
+    } else {
+        apply_defaults(&s_cfg);
+    }
+
+    /* Sanity clamps. */
+    if (s_cfg.fast_loop_ms   < 50)   s_cfg.fast_loop_ms   = 50;
+    if (s_cfg.medium_loop_ms < 200)  s_cfg.medium_loop_ms = 200;
+    if (s_cfg.slow_loop_ms   < 1000) s_cfg.slow_loop_ms   = 1000;
+
+    s_state = ADAPT_STATE_RADIO_INIT;
+
+    s_fast_timer = xTimerCreate("adapt_fast",
+                                pdMS_TO_TICKS(s_cfg.fast_loop_ms),
+                                pdTRUE, NULL, fast_loop_cb);
+    s_medium_timer = xTimerCreate("adapt_med",
+                                  pdMS_TO_TICKS(s_cfg.medium_loop_ms),
+                                  pdTRUE, NULL, medium_loop_cb);
+    s_slow_timer = xTimerCreate("adapt_slow",
+                                pdMS_TO_TICKS(s_cfg.slow_loop_ms),
+                                pdTRUE, NULL, slow_loop_cb);
+
+    if (s_fast_timer == NULL || s_medium_timer == NULL || s_slow_timer == NULL) {
+        ESP_LOGE(TAG, "timer create failed");
+        return ESP_ERR_NO_MEM;
+    }
+
+    if (xTimerStart(s_fast_timer,   0) != pdPASS ||
+        xTimerStart(s_medium_timer, 0) != pdPASS ||
+        xTimerStart(s_slow_timer,   0) != pdPASS) {
+        ESP_LOGE(TAG, "timer start failed");
+        return ESP_FAIL;
+    }
+
+    s_state  = ADAPT_STATE_SENSE_IDLE;
+    s_inited = true;
+
+    ESP_LOGI(TAG,
+             "adaptive controller online: fast=%ums med=%ums slow=%ums "
+             "(channel_switch=%d role_change=%d aggressive=%d)",
+             (unsigned)s_cfg.fast_loop_ms,
+             (unsigned)s_cfg.medium_loop_ms,
+             (unsigned)s_cfg.slow_loop_ms,
+             (int)s_cfg.enable_channel_switch,
+             (int)s_cfg.enable_role_change,
+             (int)s_cfg.aggressive);
+    return ESP_OK;
+}
+
+adapt_state_t adaptive_controller_state(void)
+{
+    return s_state;
+}
+
+bool adaptive_controller_observation(adapt_observation_t *out)
+{
+    if (out == NULL) return false;
+    bool ok = false;
+    portENTER_CRITICAL(&s_obs_lock);
+    if (s_obs_valid) {
+        *out = s_last_obs;
+        ok = true;
+    }
+    portEXIT_CRITICAL(&s_obs_lock);
+    return ok;
+}
+
+void adaptive_controller_force_state(adapt_state_t st)
+{
+    ESP_LOGI(TAG, "force state %u → %u", (unsigned)s_state, (unsigned)st);
+    s_state = st;
+}
@@ -0,0 +1,125 @@
+/**
+ * @file adaptive_controller.h
+ * @brief ADR-081 Layer 2 — Adaptive sensing controller.
+ *
+ * Closed-loop firmware control over cadence, capture profile, channel, and
+ * mesh role. Three cooperating loops:
+ *
+ *   Fast   (~200 ms): packet rate, active probing
+ *   Medium (~1 s)   : channel selection, role transitions
+ *   Slow   (~30 s)  : baseline recalibration
+ *
+ * Outputs are routed through:
+ *   - rv_radio_ops_t (Layer 1) for set_channel / set_capture_profile
+ *   - swarm_bridge / mesh plane (Layer 3) for CHANNEL_PLAN, ROLE_ASSIGN
+ *   - edge_processing (Layer 4) for cadence and threshold updates
+ *
+ * Default policy is conservative — matches today's behavior. Aggressive
+ * adaptation is opt-in via Kconfig (ADAPTIVE_CONTROLLER_AGGRESSIVE).
+ */
+
+#ifndef ADAPTIVE_CONTROLLER_H
+#define ADAPTIVE_CONTROLLER_H
+
+#include <stdint.h>
+#include <stdbool.h>
+#include "esp_err.h"
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+/** Controller-level state machine (ADR-081 firmware FSM). */
+typedef enum {
+    ADAPT_STATE_BOOT          = 0,
+    ADAPT_STATE_SELF_TEST     = 1,
+    ADAPT_STATE_RADIO_INIT    = 2,
+    ADAPT_STATE_TIME_SYNC     = 3,
+    ADAPT_STATE_CALIBRATION   = 4,
+    ADAPT_STATE_SENSE_IDLE    = 5,
+    ADAPT_STATE_SENSE_ACTIVE  = 6,
+    ADAPT_STATE_ALERT         = 7,
+    ADAPT_STATE_DEGRADED      = 8,
+} adapt_state_t;
+
+/** Observation window aggregated each fast tick. */
+typedef struct {
+    uint16_t pkt_yield_per_sec;   /**< From rv_radio_health.pkt_yield_per_sec. */
+    uint16_t send_fail_count;     /**< UDP/socket send failures. */
+    int8_t   rssi_median_dbm;
+    int8_t   noise_floor_dbm;
+    float    motion_score;        /**< Pulled from edge_processing. */
+    float    presence_score;
+    float    anomaly_score;
+    float    node_coherence;      /**< Inter-link coherence; 1.0 if single node. */
+} adapt_observation_t;
+
+/** Decisions emitted by a controller tick. */
+typedef struct {
+    bool     change_profile;
+    uint8_t  new_profile;         /**< rv_capture_profile_t. */
+    bool     change_channel;
+    uint8_t  new_channel;
+    bool     change_state;
+    uint8_t  new_state;           /**< adapt_state_t. */
+    bool     request_calibration; /**< Coordinator should issue CALIBRATION_START. */
+    uint16_t suggested_vital_interval_ms;
+} adapt_decision_t;
+
+/** Controller config (loaded from NVS / Kconfig). */
+typedef struct {
+    uint16_t fast_loop_ms;        /**< Default 200 ms. */
+    uint16_t medium_loop_ms;      /**< Default 1000 ms. */
+    uint16_t slow_loop_ms;        /**< Default 30000 ms. */
+    bool     aggressive;          /**< true = react sooner / more often. */
+    bool     enable_channel_switch; /**< false = controller may never hop. */
+    bool     enable_role_change;
+    float    motion_threshold;    /**< 0..1, enter SENSE_ACTIVE above this. */
+    float    anomaly_threshold;   /**< 0..1, enter ALERT above this. */
+    uint16_t min_pkt_yield;       /**< pps below this → DEGRADED. */
+} adapt_config_t;
+
+/**
+ * Initialize the adaptive controller.
+ *
+ * Spawns one FreeRTOS task that runs the three loops via FreeRTOS timers.
+ * Idempotent — second call is a no-op.
+ *
+ * @param cfg  Config (NULL = use Kconfig defaults).
+ * @return ESP_OK on success.
+ */
+esp_err_t adaptive_controller_init(const adapt_config_t *cfg);
+
+/** Get the current state. */
+adapt_state_t adaptive_controller_state(void);
+
+/**
+ * Snapshot the latest observation (most recent fast-loop sample).
+ * Useful for telemetry and the `HEALTH` mesh message.
+ *
+ * @param out  Output buffer.
+ * @return true if a valid observation has been recorded.
+ */
+bool adaptive_controller_observation(adapt_observation_t *out);
+
+/**
+ * Force a state transition (e.g. from a remote ROLE_ASSIGN message).
+ * Logged at INFO; controller may immediately transition again on next tick.
+ */
+void adaptive_controller_force_state(adapt_state_t st);
+
+/**
+ * Pure-function policy: given an observation + current state + config,
+ * compute the decision. Exposed in the header so it can be unit-tested
+ * offline (no FreeRTOS / ESP-IDF dependency in the body).
+ */
+void adaptive_controller_decide(const adapt_config_t *cfg,
+                                adapt_state_t current,
+                                const adapt_observation_t *obs,
+                                adapt_decision_t *out);
+
+#ifdef __cplusplus
+}
+#endif
+
+#endif /* ADAPTIVE_CONTROLLER_H */
@@ -0,0 +1,83 @@
+/**
+ * @file adaptive_controller_decide.c
+ * @brief ADR-081 Layer 2 — pure decision policy.
+ *
+ * Extracted so host unit tests can link this without ESP-IDF / FreeRTOS.
+ * adaptive_controller.c includes this file; the host Makefile links it
+ * directly against the test harness.
+ */
+
+#include <string.h>
+#include "adaptive_controller.h"
+#include "rv_radio_ops.h"
+
+void adaptive_controller_decide(const adapt_config_t *cfg,
+                                adapt_state_t current,
+                                const adapt_observation_t *obs,
+                                adapt_decision_t *out)
+{
+    if (cfg == NULL || obs == NULL || out == NULL) {
+        return;
+    }
+    memset(out, 0, sizeof(*out));
+    out->new_state   = (uint8_t)current;
+    out->new_profile = RV_PROFILE_PASSIVE_LOW_RATE;
+
+    /* Degraded gate: pkt yield collapse or severe coherence loss → DEGRADED. */
+    if (obs->pkt_yield_per_sec < cfg->min_pkt_yield ||
+        obs->node_coherence    < 0.20f) {
+        if (current != ADAPT_STATE_DEGRADED) {
+            out->change_state = true;
+            out->new_state    = ADAPT_STATE_DEGRADED;
+        }
+        out->change_profile = (current != ADAPT_STATE_DEGRADED);
+        out->new_profile    = RV_PROFILE_PASSIVE_LOW_RATE;
+        out->suggested_vital_interval_ms = 2000;
+        return;
+    }
+
+    /* Anomaly trumps motion. */
+    if (obs->anomaly_score >= cfg->anomaly_threshold) {
+        if (current != ADAPT_STATE_ALERT) {
+            out->change_state = true;
+            out->new_state    = ADAPT_STATE_ALERT;
+        }
+        out->change_profile = true;
+        out->new_profile    = RV_PROFILE_FAST_MOTION;
+        out->suggested_vital_interval_ms = 100;
+        return;
+    }
+
+    /* Motion → SENSE_ACTIVE with FAST_MOTION profile. */
+    if (obs->motion_score >= cfg->motion_threshold) {
+        if (current != ADAPT_STATE_SENSE_ACTIVE) {
+            out->change_state = true;
+            out->new_state    = ADAPT_STATE_SENSE_ACTIVE;
+        }
+        out->change_profile = true;
+        out->new_profile    = RV_PROFILE_FAST_MOTION;
+        out->suggested_vital_interval_ms = cfg->aggressive ? 100 : 200;
+        return;
+    }
+
+    /* Stable presence + quiet → high-sensitivity respiration. */
+    if (obs->presence_score >= 0.5f && obs->motion_score < 0.05f) {
+        if (current != ADAPT_STATE_SENSE_IDLE) {
+            out->change_state = true;
+            out->new_state    = ADAPT_STATE_SENSE_IDLE;
+        }
+        out->change_profile = true;
+        out->new_profile    = RV_PROFILE_RESP_HIGH_SENS;
+        out->suggested_vital_interval_ms = 1000;
+        return;
+    }
+
+    /* Default: passive low rate. */
+    if (current != ADAPT_STATE_SENSE_IDLE) {
+        out->change_state = true;
+        out->new_state    = ADAPT_STATE_SENSE_IDLE;
+    }
+    out->change_profile = (current != ADAPT_STATE_SENSE_IDLE);
+    out->new_profile    = RV_PROFILE_PASSIVE_LOW_RATE;
+    out->suggested_vital_interval_ms = cfg->aggressive ? 500 : 1000;
+}
@@ -308,6 +308,43 @@ uint8_t csi_collector_get_node_id(void)
    return s_node_id;
 }

+/* ---- ADR-081: packet yield accessor for the radio abstraction layer ---- */
+
+uint16_t csi_collector_get_pkt_yield_per_sec(void)
+{
+    /* Simple sliding window: record the callback count at ~1 s ago, return
+     * the delta. Called from adaptive_controller's fast loop (200 ms), so
+     * we update the snapshot every ~5 calls. */
+    static int64_t  s_yield_window_start_us = 0;
+    static uint32_t s_yield_window_start_cb = 0;
+    static uint16_t s_last_yield            = 0;
+
+    int64_t now = esp_timer_get_time();
+    if (s_yield_window_start_us == 0) {
+        s_yield_window_start_us = now;
+        s_yield_window_start_cb = s_cb_count;
+        return 0;
+    }
+    int64_t elapsed = now - s_yield_window_start_us;
+    if (elapsed < 1000000LL) {
+        return s_last_yield;
+    }
+    uint32_t delta = s_cb_count - s_yield_window_start_cb;
+    /* Scale back to per-second if the window ran long (shouldn't, but be safe). */
+    uint64_t per_sec = ((uint64_t)delta * 1000000ULL) / (uint64_t)elapsed;
+    if (per_sec > 0xFFFFu) per_sec = 0xFFFFu;
+    s_last_yield            = (uint16_t)per_sec;
+    s_yield_window_start_us = now;
+    s_yield_window_start_cb = s_cb_count;
+    return s_last_yield;
+}
+
+uint16_t csi_collector_get_send_fail_count(void)
+{
+    uint32_t f = s_send_fail;
+    return (f > 0xFFFFu) ? 0xFFFFu : (uint16_t)f;
+}
+
 /* ---- ADR-029: Channel hopping ---- */

 void csi_collector_set_hop_table(const uint8_t *channels, uint8_t hop_count, uint32_t dwell_ms)
@@ -94,4 +94,23 @@ void csi_collector_start_hop_timer(void);
 */
 esp_err_t csi_inject_ndp_frame(void);

+/**
+ * Get the recent CSI callback rate (per second).
+ *
+ * Computed as a sliding 1-second window over the internal s_cb_count
+ * counter. Used by the ADR-081 radio abstraction layer to fill the
+ * pkt_yield_per_sec field of rv_radio_health_t.
+ *
+ * @return Callbacks observed in the trailing ~1 second.
+ */
+uint16_t csi_collector_get_pkt_yield_per_sec(void);
+
+/**
+ * Get the cumulative UDP send-failure counter since boot.
+ *
+ * @return Number of stream_sender_send() failures recorded by the
+ *         CSI callback path.
+ */
+uint16_t csi_collector_get_send_fail_count(void);
+
 #endif /* CSI_COLLECTOR_H */
@@ -30,6 +30,8 @@
 #include "display_task.h"
 #include "mmwave_sensor.h"
 #include "swarm_bridge.h"
+#include "rv_radio_ops.h"          /* ADR-081 Layer 1 — Radio Abstraction Layer. */
+#include "adaptive_controller.h"   /* ADR-081 Layer 2 — Adaptive controller. */
 #ifdef CONFIG_CSI_MOCK_ENABLED
 #include "mock_csi.h"
 #endif
@@ -278,6 +280,31 @@ void app_main(void)
    ESP_LOGI(TAG, "Mock CSI mode: skipping swarm bridge");
 #endif

+    /* ADR-081 Layer 1: register the active radio ops binding.
+     * - Real hardware: ESP32 binding wrapping csi_collector + esp_wifi.
+     * - QEMU / offline: mock binding wrapping mock_csi.c.
+     * Either way, the layers above (adaptive controller, mesh plane,
+     * feature extraction) address the radio through the same vtable —
+     * this is the portability acceptance test in ADR-081. */
+#ifdef CONFIG_CSI_MOCK_ENABLED
+    rv_radio_ops_mock_register();
+#else
+    rv_radio_ops_esp32_register();
+#endif
+    const rv_radio_ops_t *radio_ops = rv_radio_ops_get();
+    if (radio_ops != NULL && radio_ops->init != NULL) {
+        radio_ops->init();
+    }
+
+    /* ADR-081 Layer 2: start the adaptive controller. NULL config → use
+     * Kconfig defaults. Default policy is conservative: no channel
+     * switching, no role change. Operators opt in via menuconfig. */
+    esp_err_t adapt_ret = adaptive_controller_init(NULL);
+    if (adapt_ret != ESP_OK) {
+        ESP_LOGW(TAG, "Adaptive controller init failed: %s",
+                 esp_err_to_name(adapt_ret));
+    }
+
    /* Initialize power management. */
    power_mgmt_init(g_nvs_config.power_duty);

@@ -289,13 +316,14 @@ void app_main(void)
    }
 #endif

-    ESP_LOGI(TAG, "CSI streaming active → %s:%d (edge_tier=%u, OTA=%s, WASM=%s, mmWave=%s, swarm=%s)",
+    ESP_LOGI(TAG, "CSI streaming active → %s:%d (edge_tier=%u, OTA=%s, WASM=%s, mmWave=%s, swarm=%s, adapt=%s)",
             g_nvs_config.target_ip, g_nvs_config.target_port,
             g_nvs_config.edge_tier,
             (ota_ret == ESP_OK) ? "ready" : "off",
             (wasm_ret == ESP_OK) ? "ready" : "off",
             (mmwave_ret == ESP_OK) ? "active" : "off",
-             (swarm_ret == ESP_OK) ? g_nvs_config.seed_url : "off");
+             (swarm_ret == ESP_OK) ? g_nvs_config.seed_url : "off",
+             (adapt_ret == ESP_OK) ? "on" : "off");

    /* Main loop — keep alive */
    while (1) {
@@ -0,0 +1,44 @@
+/**
+ * @file rv_feature_state.c
+ * @brief ADR-081 Layer 4 — Feature state packet helpers.
+ */
+
+#include "rv_feature_state.h"
+
+#include <string.h>
+
+uint32_t rv_feature_state_crc32(const uint8_t *data, size_t len)
+{
+    /* IEEE CRC32 (poly 0xEDB88320), bit-by-bit. Small (~80 byte) input at
+     * low cadence — no need for a 1 KB lookup table. */
+    uint32_t crc = 0xFFFFFFFFu;
+    for (size_t i = 0; i < len; i++) {
+        crc ^= data[i];
+        for (int b = 0; b < 8; b++) {
+            uint32_t mask = -(crc & 1u);
+            crc = (crc >> 1) ^ (0xEDB88320u & mask);
+        }
+    }
+    return ~crc;
+}
+
+void rv_feature_state_finalize(rv_feature_state_t *pkt,
+                               uint8_t node_id,
+                               uint16_t seq,
+                               uint64_t ts_us,
+                               uint8_t mode)
+{
+    if (pkt == NULL) {
+        return;
+    }
+    pkt->magic    = RV_FEATURE_STATE_MAGIC;
+    pkt->node_id  = node_id;
+    pkt->mode     = mode;
+    pkt->seq      = seq;
+    pkt->ts_us    = ts_us;
+    pkt->reserved = 0;
+
+    /* CRC32 over everything except the trailing crc32 field itself. */
+    const size_t crc_offset = sizeof(rv_feature_state_t) - sizeof(uint32_t);
+    pkt->crc32 = rv_feature_state_crc32((const uint8_t *)pkt, crc_offset);
+}
@@ -0,0 +1,110 @@
+/**
+ * @file rv_feature_state.h
+ * @brief ADR-081 Layer 4 — Compact on-wire feature state packet.
+ *
+ * The default upstream payload from a node. Replaces raw ADR-018 CSI as the
+ * primary stream; ADR-018 raw frames remain available as a debug stream
+ * gated by the controller / channel plan.
+ *
+ * Magic numbers in use across the firmware:
+ *   0xC5110001 — ADR-018 raw CSI frame  (csi_collector.h)
+ *   0xC5110002 — ADR-039 vitals packet  (edge_processing.h)
+ *   0xC5110003 — ADR-069 feature vector (edge_processing.h)
+ *   0xC5110004 — ADR-063 fused vitals   (edge_processing.h)
+ *   0xC5110005 — ADR-039 compressed CSI (edge_processing.h)
+ *   0xC5110006 — ADR-081 feature state  (this file) ← new
+ */
+
+#ifndef RV_FEATURE_STATE_H
+#define RV_FEATURE_STATE_H
+
+#include <stdint.h>
+#include <stdbool.h>
+#include <stddef.h>
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+/** Magic number for ADR-081 rv_feature_state_t. */
+#define RV_FEATURE_STATE_MAGIC  0xC5110006u
+
+/** Quality flag bits. */
+#define RV_QFLAG_PRESENCE_VALID      (1u << 0)
+#define RV_QFLAG_RESPIRATION_VALID   (1u << 1)
+#define RV_QFLAG_HEARTBEAT_VALID     (1u << 2)
+#define RV_QFLAG_ANOMALY_TRIGGERED   (1u << 3)
+#define RV_QFLAG_ENV_SHIFT_DETECTED  (1u << 4)
+#define RV_QFLAG_DEGRADED_MODE       (1u << 5)
+#define RV_QFLAG_CALIBRATING         (1u << 6)
+#define RV_QFLAG_RECOMMEND_RECAL     (1u << 7)
+
+/**
+ * Compact per-node sensing state. Sent at 1-10 Hz by default, replacing the
+ * raw ADR-018 stream as the primary upstream payload.
+ *
+ * Mode field carries the rv_capture_profile_t value of the dominant window
+ * — receivers can use it to weight features (a sample emitted under
+ * RV_PROFILE_FAST_MOTION will have a stale respiration_bpm, etc.).
+ *
+ * CRC32 is the IEEE polynomial computed over bytes [0 .. sizeof - 4].
+ */
+typedef struct __attribute__((packed)) {
+    uint32_t magic;             /**< RV_FEATURE_STATE_MAGIC. */
+    uint8_t  node_id;           /**< Source node id. */
+    uint8_t  mode;              /**< rv_capture_profile_t at emit time. */
+    uint16_t seq;               /**< Monotonic per-node sequence. */
+    uint64_t ts_us;             /**< Node-local microseconds. */
+    float    motion_score;      /**< 0..1, 100 ms window. */
+    float    presence_score;    /**< 0..1, 1 s window. */
+    float    respiration_bpm;   /**< Breaths per minute. */
+    float    respiration_conf;  /**< 0..1. */
+    float    heartbeat_bpm;     /**< Beats per minute. */
+    float    heartbeat_conf;    /**< 0..1. */
+    float    anomaly_score;     /**< 0..1, z-score-derived. */
+    float    env_shift_score;   /**< 0..1, baseline drift. */
+    float    node_coherence;    /**< 0..1, multi-link agreement. */
+    uint16_t quality_flags;     /**< RV_QFLAG_* bitmap. */
+    uint16_t reserved;
+    uint32_t crc32;             /**< IEEE CRC32 over bytes [0..end-4]. */
+} rv_feature_state_t;
+
+_Static_assert(sizeof(rv_feature_state_t) == 60,
+               "rv_feature_state_t must be 60 bytes on the wire");
+
+/**
+ * Compute IEEE CRC32 over a byte buffer.
+ *
+ * Provided here (not in a separate util) because the firmware does not yet
+ * have a shared CRC32 helper — only zlib's via lwIP, which is not always
+ * exposed. This implementation is bit-by-bit; ~80 bytes/packet at low
+ * cadence has negligible CPU cost.
+ *
+ * @param data  Input buffer.
+ * @param len   Input length in bytes.
+ * @return IEEE CRC32 of the input.
+ */
+uint32_t rv_feature_state_crc32(const uint8_t *data, size_t len);
+
+/**
+ * Finalize an rv_feature_state_t by populating magic, seq, ts_us, and crc32.
+ * Caller fills the remaining fields in-place before calling this. After
+ * finalize() the packet is ready to send on the wire.
+ *
+ * @param pkt        Packet to finalize (caller-owned).
+ * @param node_id    Source node id (typically csi_collector_get_node_id()).
+ * @param seq        Monotonic sequence (caller-managed).
+ * @param ts_us      Node-local microseconds (typically esp_timer_get_time()).
+ * @param mode       Active rv_capture_profile_t.
+ */
+void rv_feature_state_finalize(rv_feature_state_t *pkt,
+                               uint8_t node_id,
+                               uint16_t seq,
+                               uint64_t ts_us,
+                               uint8_t mode);
+
+#ifdef __cplusplus
+}
+#endif
+
+#endif /* RV_FEATURE_STATE_H */
@@ -0,0 +1,251 @@
+/**
+ * @file rv_mesh.c
+ * @brief ADR-081 Layer 3 — Mesh Sensing Plane implementation.
+ *
+ * Encoder/decoder are pure functions (no ESP-IDF deps) and therefore
+ * host-unit-testable. The send helpers wrap stream_sender so the
+ * firmware can use a single upstream socket for all payload types.
+ */
+
+#include "rv_mesh.h"
+#include "rv_feature_state.h"
+#include "rv_radio_ops.h"
+
+#include <string.h>
+
+#ifndef RV_MESH_HOST_TEST
+#include "esp_log.h"
+#include "esp_timer.h"
+#include "stream_sender.h"
+#include "csi_collector.h"
+#include "adaptive_controller.h"
+static const char *TAG = "rv_mesh";
+#endif
+
+/* ---- Encoder ---- */
+
+size_t rv_mesh_encode(uint8_t type,
+                      uint8_t sender_role,
+                      uint8_t auth_class,
+                      uint32_t epoch,
+                      const void *payload,
+                      uint16_t payload_len,
+                      uint8_t *buf,
+                      size_t buf_cap)
+{
+    if (buf == NULL) return 0;
+    if (payload == NULL && payload_len != 0) return 0;
+    if (payload_len > RV_MESH_MAX_PAYLOAD) return 0;
+
+    size_t total = sizeof(rv_mesh_header_t) + (size_t)payload_len + 4u;
+    if (buf_cap < total) return 0;
+
+    rv_mesh_header_t hdr;
+    hdr.magic       = RV_MESH_MAGIC;
+    hdr.version     = (uint8_t)RV_MESH_VERSION;
+    hdr.type        = type;
+    hdr.sender_role = sender_role;
+    hdr.auth_class  = auth_class;
+    hdr.epoch       = epoch;
+    hdr.payload_len = payload_len;
+    hdr.reserved    = 0;
+
+    memcpy(buf, &hdr, sizeof(hdr));
+    if (payload_len > 0) {
+        memcpy(buf + sizeof(hdr), payload, payload_len);
+    }
+
+    /* IEEE CRC32 over header + payload. Reuses the CRC32 from
+     * rv_feature_state.c so there is exactly one implementation. */
+    uint32_t crc = rv_feature_state_crc32(buf, sizeof(hdr) + payload_len);
+    memcpy(buf + sizeof(hdr) + payload_len, &crc, 4);
+
+    return total;
+}
+
+esp_err_t rv_mesh_decode(const uint8_t *buf, size_t buf_len,
+                         rv_mesh_header_t *out_hdr,
+                         const uint8_t **out_payload,
+                         uint16_t *out_payload_len)
+{
+    if (buf == NULL || out_hdr == NULL ||
+        out_payload == NULL || out_payload_len == NULL) {
+        return ESP_ERR_INVALID_ARG;
+    }
+    if (buf_len < sizeof(rv_mesh_header_t) + 4u) {
+        return ESP_ERR_INVALID_SIZE;
+    }
+
+    rv_mesh_header_t hdr;
+    memcpy(&hdr, buf, sizeof(hdr));
+
+    if (hdr.magic != RV_MESH_MAGIC) {
+        return ESP_ERR_INVALID_VERSION;  /* repurpose: wrong magic */
+    }
+    if (hdr.version != RV_MESH_VERSION) {
+        return ESP_ERR_INVALID_VERSION;
+    }
+    if (hdr.payload_len > RV_MESH_MAX_PAYLOAD) {
+        return ESP_ERR_INVALID_SIZE;
+    }
+
+    size_t needed = sizeof(hdr) + (size_t)hdr.payload_len + 4u;
+    if (buf_len < needed) {
+        return ESP_ERR_INVALID_SIZE;
+    }
+
+    uint32_t got_crc;
+    memcpy(&got_crc, buf + sizeof(hdr) + hdr.payload_len, 4);
+    uint32_t want_crc = rv_feature_state_crc32(buf,
+                          sizeof(hdr) + hdr.payload_len);
+    if (got_crc != want_crc) {
+        return ESP_ERR_INVALID_CRC;
+    }
+
+    *out_hdr         = hdr;
+    *out_payload     = (hdr.payload_len > 0) ? buf + sizeof(hdr) : NULL;
+    *out_payload_len = hdr.payload_len;
+    return ESP_OK;
+}
+
+/* ---- Typed convenience encoders ---- */
+
+size_t rv_mesh_encode_health(uint8_t sender_role,
+                             uint32_t epoch,
+                             const rv_node_status_t *status,
+                             uint8_t *buf, size_t buf_cap)
+{
+    if (status == NULL) return 0;
+    return rv_mesh_encode(RV_MSG_HEALTH, sender_role, RV_AUTH_NONE,
+                          epoch, status, sizeof(*status), buf, buf_cap);
+}
+
+size_t rv_mesh_encode_anomaly_alert(uint8_t sender_role,
+                                    uint32_t epoch,
+                                    const rv_anomaly_alert_t *alert,
+                                    uint8_t *buf, size_t buf_cap)
+{
+    if (alert == NULL) return 0;
+    return rv_mesh_encode(RV_MSG_ANOMALY_ALERT, sender_role, RV_AUTH_NONE,
+                          epoch, alert, sizeof(*alert), buf, buf_cap);
+}
+
+size_t rv_mesh_encode_feature_delta(uint8_t sender_role,
+                                    uint32_t epoch,
+                                    const rv_feature_state_t *fs,
+                                    uint8_t *buf, size_t buf_cap)
+{
+    if (fs == NULL) return 0;
+    return rv_mesh_encode(RV_MSG_FEATURE_DELTA, sender_role, RV_AUTH_NONE,
+                          epoch, fs, sizeof(*fs), buf, buf_cap);
+}
+
+size_t rv_mesh_encode_time_sync(uint8_t sender_role,
+                                uint32_t epoch,
+                                const rv_time_sync_t *ts,
+                                uint8_t *buf, size_t buf_cap)
+{
+    if (ts == NULL) return 0;
+    return rv_mesh_encode(RV_MSG_TIME_SYNC, sender_role, RV_AUTH_HMAC_SESSION,
+                          epoch, ts, sizeof(*ts), buf, buf_cap);
+}
+
+size_t rv_mesh_encode_role_assign(uint8_t sender_role,
+                                  uint32_t epoch,
+                                  const rv_role_assign_t *ra,
+                                  uint8_t *buf, size_t buf_cap)
+{
+    if (ra == NULL) return 0;
+    return rv_mesh_encode(RV_MSG_ROLE_ASSIGN, sender_role, RV_AUTH_HMAC_SESSION,
+                          epoch, ra, sizeof(*ra), buf, buf_cap);
+}
+
+size_t rv_mesh_encode_channel_plan(uint8_t sender_role,
+                                   uint32_t epoch,
+                                   const rv_channel_plan_t *cp,
+                                   uint8_t *buf, size_t buf_cap)
+{
+    if (cp == NULL) return 0;
+    return rv_mesh_encode(RV_MSG_CHANNEL_PLAN, sender_role, RV_AUTH_ED25519_BATCH,
+                          epoch, cp, sizeof(*cp), buf, buf_cap);
+}
+
+size_t rv_mesh_encode_calibration_start(uint8_t sender_role,
+                                        uint32_t epoch,
+                                        const rv_calibration_start_t *cs,
+                                        uint8_t *buf, size_t buf_cap)
+{
+    if (cs == NULL) return 0;
+    return rv_mesh_encode(RV_MSG_CALIBRATION_START, sender_role,
+                          RV_AUTH_ED25519_BATCH, epoch, cs, sizeof(*cs),
+                          buf, buf_cap);
+}
+
+/* ---- Send helpers (firmware-only; hidden from host tests) ---- */
+
+#ifndef RV_MESH_HOST_TEST
+
+esp_err_t rv_mesh_send(const uint8_t *frame, size_t len)
+{
+    if (frame == NULL || len == 0) return ESP_ERR_INVALID_ARG;
+    int sent = stream_sender_send(frame, len);
+    if (sent < 0) {
+        ESP_LOGW(TAG, "rv_mesh_send: stream_sender failed (len=%u)",
+                 (unsigned)len);
+        return ESP_FAIL;
+    }
+    return ESP_OK;
+}
+
+esp_err_t rv_mesh_send_health(uint8_t role, uint32_t epoch,
+                              const uint8_t node_id[8])
+{
+    if (node_id == NULL) return ESP_ERR_INVALID_ARG;
+
+    rv_node_status_t st;
+    memset(&st, 0, sizeof(st));
+    memcpy(st.node_id, node_id, 8);
+    st.local_time_us = (uint64_t)esp_timer_get_time();
+    st.role          = role;
+
+    const rv_radio_ops_t *ops = rv_radio_ops_get();
+    if (ops != NULL && ops->get_health != NULL) {
+        rv_radio_health_t h;
+        if (ops->get_health(&h) == ESP_OK) {
+            st.current_channel = h.current_channel;
+            st.current_bw      = h.current_bw_mhz;
+            st.noise_floor_dbm = h.noise_floor_dbm;
+            st.pkt_yield       = h.pkt_yield_per_sec;
+        }
+    }
+
+    uint8_t buf[RV_MESH_MAX_FRAME_BYTES];
+    size_t n = rv_mesh_encode_health(role, epoch, &st, buf, sizeof(buf));
+    if (n == 0) return ESP_FAIL;
+    return rv_mesh_send(buf, n);
+}
+
+esp_err_t rv_mesh_send_anomaly(uint8_t role, uint32_t epoch,
+                               const uint8_t node_id[8],
+                               uint8_t reason,
+                               uint8_t severity,
+                               float anomaly_score,
+                               float motion_score)
+{
+    if (node_id == NULL) return ESP_ERR_INVALID_ARG;
+    rv_anomaly_alert_t a;
+    memset(&a, 0, sizeof(a));
+    memcpy(a.node_id, node_id, 8);
+    a.ts_us         = (uint64_t)esp_timer_get_time();
+    a.reason        = reason;
+    a.severity      = severity;
+    a.anomaly_score = anomaly_score;
+    a.motion_score  = motion_score;
+
+    uint8_t buf[RV_MESH_MAX_FRAME_BYTES];
+    size_t n = rv_mesh_encode_anomaly_alert(role, epoch, &a, buf, sizeof(buf));
+    if (n == 0) return ESP_FAIL;
+    return rv_mesh_send(buf, n);
+}
+
+#endif /* !RV_MESH_HOST_TEST */
@@ -0,0 +1,296 @@
+/**
+ * @file rv_mesh.h
+ * @brief ADR-081 Layer 3 — Mesh Sensing Plane.
+ *
+ * Defines node roles, the 7 on-wire message types, and the
+ * rv_node_status_t health payload that nodes exchange to behave as a
+ * distributed sensor rather than a collection of independent radios.
+ *
+ * Framing: every mesh message starts with rv_mesh_header_t (magic,
+ * version, type, sender_role, epoch, length) so a receiver can dispatch
+ * without reading the whole body. The trailing 4 bytes of every message
+ * are an IEEE CRC32 over the preceding bytes. Authentication
+ * (HMAC-SHA256 + replay window) is layered on top by
+ * wifi-densepose-hardware/src/esp32/secure_tdm.rs (ADR-032) for control
+ * messages that cross the swarm; FEATURE_DELTA uses the integrity
+ * protection already present in rv_feature_state_t (CRC + monotonic seq).
+ */
+
+#ifndef RV_MESH_H
+#define RV_MESH_H
+
+#include <stdint.h>
+#include <stdbool.h>
+#include <stddef.h>
+#include "esp_err.h"
+#include "rv_feature_state.h"
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+/* ---- Magic + version ---- */
+
+/** ADR-081 mesh envelope magic. Distinct from the ADR-018 CSI magic. */
+#define RV_MESH_MAGIC        0xC5118100u
+
+/** Protocol version. Bumped on any wire-format change. */
+#define RV_MESH_VERSION      1u
+
+/** Maximum mesh payload size (excluding header + CRC). */
+#define RV_MESH_MAX_PAYLOAD  256u
+
+/* ---- Node roles (ADR-081 Layer 3) ---- */
+
+typedef enum {
+    RV_ROLE_UNASSIGNED   = 0,
+    RV_ROLE_ANCHOR       = 1,  /**< Emits timed probes + global time beacons. */
+    RV_ROLE_OBSERVER     = 2,  /**< Captures CSI + local metadata. */
+    RV_ROLE_FUSION_RELAY = 3,  /**< Aggregates summaries, forwards deltas. */
+    RV_ROLE_COORDINATOR  = 4,  /**< Elects channels, assigns roles. */
+    RV_ROLE_COUNT
+} rv_mesh_role_t;
+
+/* ---- Authorization classes for control messages ---- */
+
+typedef enum {
+    RV_AUTH_NONE          = 0,  /**< Telemetry; integrity via CRC only. */
+    RV_AUTH_HMAC_SESSION  = 1,  /**< HMAC-SHA256 with session key (ADR-032). */
+    RV_AUTH_ED25519_BATCH = 2,  /**< Ed25519 signature at batch/session. */
+} rv_mesh_auth_class_t;
+
+/* ---- Message types ---- */
+
+typedef enum {
+    RV_MSG_TIME_SYNC         = 0x01,
+    RV_MSG_ROLE_ASSIGN       = 0x02,
+    RV_MSG_CHANNEL_PLAN      = 0x03,
+    RV_MSG_CALIBRATION_START = 0x04,
+    RV_MSG_FEATURE_DELTA     = 0x05,  /**< Carries rv_feature_state_t. */
+    RV_MSG_HEALTH            = 0x06,
+    RV_MSG_ANOMALY_ALERT     = 0x07,
+} rv_mesh_msg_type_t;
+
+/* ---- Common envelope header (16 bytes) ---- */
+
+typedef struct __attribute__((packed)) {
+    uint32_t magic;        /**< RV_MESH_MAGIC. */
+    uint8_t  version;      /**< RV_MESH_VERSION. */
+    uint8_t  type;         /**< rv_mesh_msg_type_t. */
+    uint8_t  sender_role;  /**< rv_mesh_role_t of the sender at send time. */
+    uint8_t  auth_class;   /**< rv_mesh_auth_class_t. */
+    uint32_t epoch;        /**< Monotonic epoch or session counter. */
+    uint16_t payload_len;  /**< Body length excluding header + trailing CRC. */
+    uint16_t reserved;
+} rv_mesh_header_t;
+
+_Static_assert(sizeof(rv_mesh_header_t) == 16,
+               "rv_mesh_header_t must be 16 bytes");
+
+/* ---- Node health payload (RV_MSG_HEALTH) ---- */
+
+typedef struct __attribute__((packed)) {
+    uint8_t  node_id[8];      /**< 8-byte node identity. */
+    uint64_t local_time_us;   /**< Sender-local microseconds. */
+    uint8_t  role;            /**< rv_mesh_role_t. */
+    uint8_t  current_channel;
+    uint8_t  current_bw;      /**< MHz (20, 40). */
+    int8_t   noise_floor_dbm;
+    uint16_t pkt_yield;       /**< CSI callbacks/sec over the last window. */
+    uint16_t sync_error_us;   /**< Absolute drift vs. anchor. */
+    uint16_t health_flags;
+    uint16_t reserved;
+} rv_node_status_t;
+
+_Static_assert(sizeof(rv_node_status_t) == 28,
+               "rv_node_status_t must be 28 bytes");
+
+/* ---- TIME_SYNC payload ---- */
+
+typedef struct __attribute__((packed)) {
+    uint64_t anchor_time_us;  /**< Anchor's local µs at emit. */
+    uint32_t cycle_id;
+    uint32_t cycle_period_us;
+} rv_time_sync_t;
+
+_Static_assert(sizeof(rv_time_sync_t) == 16,
+               "rv_time_sync_t must be 16 bytes");
+
+/* ---- ROLE_ASSIGN payload ---- */
+
+typedef struct __attribute__((packed)) {
+    uint8_t  target_node_id[8];
+    uint8_t  new_role;     /**< rv_mesh_role_t. */
+    uint8_t  reserved[3];
+    uint32_t effective_epoch;
+} rv_role_assign_t;
+
+_Static_assert(sizeof(rv_role_assign_t) == 16,
+               "rv_role_assign_t must be 16 bytes");
+
+/* ---- CHANNEL_PLAN payload ---- */
+
+#define RV_CHANNEL_PLAN_MAX 8
+
+typedef struct __attribute__((packed)) {
+    uint8_t  target_node_id[8];
+    uint8_t  channel_count;
+    uint8_t  dwell_ms_hi;     /**< dwell_ms, big-endian to fit u16 in two bytes */
+    uint8_t  dwell_ms_lo;
+    uint8_t  debug_raw_csi;   /**< 1 = enable raw ADR-018 stream; 0 = feature_state only. */
+    uint8_t  channels[RV_CHANNEL_PLAN_MAX];
+    uint32_t effective_epoch;
+} rv_channel_plan_t;
+
+_Static_assert(sizeof(rv_channel_plan_t) == 24,
+               "rv_channel_plan_t must be 24 bytes");
+
+/* ---- CALIBRATION_START payload ---- */
+
+typedef struct __attribute__((packed)) {
+    uint64_t t0_anchor_us;    /**< Start time on anchor clock. */
+    uint32_t duration_ms;
+    uint32_t effective_epoch;
+    uint8_t  calibration_profile;  /**< rv_capture_profile_t (usually CALIBRATION). */
+    uint8_t  reserved[3];
+} rv_calibration_start_t;
+
+_Static_assert(sizeof(rv_calibration_start_t) == 20,
+               "rv_calibration_start_t must be 20 bytes");
+
+/* ---- ANOMALY_ALERT payload ---- */
+
+typedef struct __attribute__((packed)) {
+    uint8_t  node_id[8];
+    uint64_t ts_us;
+    uint8_t  severity;        /**< 0..255 scaled anomaly. */
+    uint8_t  reason;          /**< rv_anomaly_reason_t. */
+    uint16_t reserved;
+    float    anomaly_score;
+    float    motion_score;
+} rv_anomaly_alert_t;
+
+_Static_assert(sizeof(rv_anomaly_alert_t) == 28,
+               "rv_anomaly_alert_t must be 28 bytes");
+
+typedef enum {
+    RV_ANOMALY_NONE              = 0,
+    RV_ANOMALY_PHYSICS_VIOLATION = 1,
+    RV_ANOMALY_MULTI_LINK_MISMATCH = 2,
+    RV_ANOMALY_PKT_YIELD_COLLAPSE = 3,
+    RV_ANOMALY_FALL               = 4,
+    RV_ANOMALY_COHERENCE_LOSS     = 5,
+} rv_anomaly_reason_t;
+
+/* ---- Encoder / decoder API ---- */
+
+/** Maximum on-wire mesh frame: header + max payload + crc. */
+#define RV_MESH_MAX_FRAME_BYTES  (sizeof(rv_mesh_header_t) + RV_MESH_MAX_PAYLOAD + 4u)
+
+/**
+ * Encode a typed mesh message into a contiguous buffer.
+ *
+ * Writes header(16) + payload(payload_len) + crc32(4). The caller owns
+ * the buffer; buf_cap must be at least sizeof(rv_mesh_header_t) +
+ * payload_len + 4. The payload pointer may be NULL iff payload_len == 0.
+ *
+ * @return bytes written on success, or 0 on error (bad args / overflow).
+ */
+size_t rv_mesh_encode(uint8_t type,
+                      uint8_t sender_role,
+                      uint8_t auth_class,
+                      uint32_t epoch,
+                      const void *payload,
+                      uint16_t payload_len,
+                      uint8_t *buf,
+                      size_t buf_cap);
+
+/**
+ * Validate + parse a mesh frame received from the wire.
+ *
+ * Checks magic, version, sizeof(rv_mesh_header_t) bounds, payload_len
+ * bounds, and CRC32. On success, fills *out_hdr with the header and sets
+ * *out_payload to point at the payload inside buf (aliasing, not copied)
+ * plus *out_payload_len to the payload byte count.
+ *
+ * @return ESP_OK on success, or an ESP_ERR_* code on failure.
+ */
+esp_err_t rv_mesh_decode(const uint8_t *buf, size_t buf_len,
+                         rv_mesh_header_t *out_hdr,
+                         const uint8_t **out_payload,
+                         uint16_t *out_payload_len);
+
+/**
+ * Convenience helpers — encode a specific message type into buf.
+ * Each returns the number of bytes written, 0 on error.
+ */
+size_t rv_mesh_encode_health(uint8_t sender_role,
+                             uint32_t epoch,
+                             const rv_node_status_t *status,
+                             uint8_t *buf, size_t buf_cap);
+
+size_t rv_mesh_encode_anomaly_alert(uint8_t sender_role,
+                                    uint32_t epoch,
+                                    const rv_anomaly_alert_t *alert,
+                                    uint8_t *buf, size_t buf_cap);
+
+size_t rv_mesh_encode_feature_delta(uint8_t sender_role,
+                                    uint32_t epoch,
+                                    const rv_feature_state_t *fs,
+                                    uint8_t *buf, size_t buf_cap);
+
+size_t rv_mesh_encode_time_sync(uint8_t sender_role,
+                                uint32_t epoch,
+                                const rv_time_sync_t *ts,
+                                uint8_t *buf, size_t buf_cap);
+
+size_t rv_mesh_encode_role_assign(uint8_t sender_role,
+                                  uint32_t epoch,
+                                  const rv_role_assign_t *ra,
+                                  uint8_t *buf, size_t buf_cap);
+
+size_t rv_mesh_encode_channel_plan(uint8_t sender_role,
+                                   uint32_t epoch,
+                                   const rv_channel_plan_t *cp,
+                                   uint8_t *buf, size_t buf_cap);
+
+size_t rv_mesh_encode_calibration_start(uint8_t sender_role,
+                                        uint32_t epoch,
+                                        const rv_calibration_start_t *cs,
+                                        uint8_t *buf, size_t buf_cap);
+
+/* ---- Send API ---- */
+
+/**
+ * Send a pre-encoded mesh frame over the primary upstream UDP socket
+ * (the same one stream_sender uses for ADR-018 and rv_feature_state_t).
+ *
+ * @return ESP_OK on success.
+ */
+esp_err_t rv_mesh_send(const uint8_t *frame, size_t len);
+
+/**
+ * Convenience: build + send a HEALTH message for this node.
+ *
+ * Fills the rv_node_status_t from the live radio ops + controller
+ * observation, then encodes and sends in one call. Safe to call from a
+ * FreeRTOS timer.
+ */
+esp_err_t rv_mesh_send_health(uint8_t role, uint32_t epoch,
+                              const uint8_t node_id[8]);
+
+/**
+ * Convenience: build + send an ANOMALY_ALERT.
+ */
+esp_err_t rv_mesh_send_anomaly(uint8_t role, uint32_t epoch,
+                               const uint8_t node_id[8],
+                               uint8_t reason,
+                               uint8_t severity,
+                               float anomaly_score,
+                               float motion_score);
+
+#ifdef __cplusplus
+}
+#endif
+
+#endif /* RV_MESH_H */
@@ -0,0 +1,142 @@
+/**
+ * @file rv_radio_ops.h
+ * @brief ADR-081 Layer 1 — Radio Abstraction Layer.
+ *
+ * A single function-pointer vtable (rv_radio_ops_t) that isolates chipset
+ * specific capture details from the layers above (adaptive controller, mesh
+ * plane, feature extraction, Rust handoff).
+ *
+ * Two bindings ship today:
+ *   - rv_radio_ops_esp32.c — wraps csi_collector + esp_wifi_*
+ *   - rv_radio_ops_mock.c  — wraps mock_csi.c (when CONFIG_CSI_MOCK_ENABLED)
+ *
+ * A third binding (Nexmon-patched Broadcom/Cypress) is reserved but not
+ * implemented here. The whole point of the vtable is that the controller
+ * and mesh-plane code above never need to know which one is active.
+ */
+
+#ifndef RV_RADIO_OPS_H
+#define RV_RADIO_OPS_H
+
+#include <stdint.h>
+#include <stdbool.h>
+#include "esp_err.h"
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+/* ---- Modes ---- */
+
+/** Radio operating modes (set_mode argument). */
+typedef enum {
+    RV_RADIO_MODE_DISABLED       = 0,  /**< Receiver off. */
+    RV_RADIO_MODE_PASSIVE_RX     = 1,  /**< Listen-only, no TX. */
+    RV_RADIO_MODE_ACTIVE_PROBE   = 2,  /**< Inject NDP frames at high rate. */
+    RV_RADIO_MODE_CALIBRATION    = 3,  /**< Synchronized calibration burst. */
+} rv_radio_mode_t;
+
+/* ---- Capture profiles ---- */
+
+/**
+ * Named capture profiles. The adaptive controller selects one of these
+ * via set_capture_profile(); the binding maps it to chipset-specific
+ * register/driver state.
+ */
+typedef enum {
+    RV_PROFILE_PASSIVE_LOW_RATE  = 0,  /**< Default idle: minimum cadence. */
+    RV_PROFILE_ACTIVE_PROBE      = 1,  /**< High-rate NDP injection. */
+    RV_PROFILE_RESP_HIGH_SENS    = 2,  /**< Quietest channel, vitals-only. */
+    RV_PROFILE_FAST_MOTION       = 3,  /**< Short window, high cadence. */
+    RV_PROFILE_CALIBRATION       = 4,  /**< Synchronized burst across nodes. */
+    RV_PROFILE_COUNT
+} rv_capture_profile_t;
+
+/* ---- Health snapshot ---- */
+
+/** Radio-layer health, polled by the adaptive controller. */
+typedef struct {
+    uint16_t pkt_yield_per_sec;   /**< CSI callbacks/second observed. */
+    uint16_t send_fail_count;     /**< UDP/socket send failures since last poll. */
+    int8_t   rssi_median_dbm;     /**< Median RSSI over the last 1 s. */
+    int8_t   noise_floor_dbm;     /**< Latest noise floor estimate. */
+    uint8_t  current_channel;     /**< Channel currently configured. */
+    uint8_t  current_bw_mhz;      /**< Bandwidth currently configured. */
+    uint8_t  current_profile;     /**< Active rv_capture_profile_t. */
+    uint8_t  reserved;
+} rv_radio_health_t;
+
+/* ---- The vtable ---- */
+
+/**
+ * Radio Abstraction Layer ops.
+ *
+ * All function pointers are required (no NULL slots). Each binding must
+ * provide all six. Return values follow ESP-IDF conventions: 0/ESP_OK on
+ * success, negative or ESP_ERR_* on failure.
+ */
+typedef struct {
+    /** One-time init (driver register, callback wire-up). */
+    int (*init)(void);
+
+    /**
+     * Tune to a primary channel with the given bandwidth.
+     * @param ch  Channel number (1-13 for 2.4 GHz, 36-177 for 5 GHz).
+     * @param bw  Bandwidth in MHz (20 or 40; 80/160 reserved for future).
+     */
+    int (*set_channel)(uint8_t ch, uint8_t bw);
+
+    /** Switch operating mode (rv_radio_mode_t). */
+    int (*set_mode)(uint8_t mode);
+
+    /** Enable or disable the CSI capture path. */
+    int (*set_csi_enabled)(bool en);
+
+    /** Apply a named capture profile (rv_capture_profile_t). */
+    int (*set_capture_profile)(uint8_t profile_id);
+
+    /** Snapshot the radio-layer health (non-blocking). */
+    int (*get_health)(rv_radio_health_t *out);
+} rv_radio_ops_t;
+
+/* ---- Registration ---- */
+
+/**
+ * Register the active radio ops binding.
+ *
+ * Called once at boot by the chipset binding's init code (e.g.
+ * rv_radio_ops_esp32_register()). The pointer must remain valid for the
+ * lifetime of the process — typically a static const inside the binding.
+ */
+void rv_radio_ops_register(const rv_radio_ops_t *ops);
+
+/**
+ * Get the active radio ops binding.
+ *
+ * @return Pointer to the registered ops table, or NULL if no binding has
+ *         been registered yet (e.g. before init).
+ */
+const rv_radio_ops_t *rv_radio_ops_get(void);
+
+/* ---- Convenience: ESP32 binding registration ---- */
+
+/**
+ * Register the ESP32 binding as the active radio ops.
+ *
+ * Call this once at boot, after csi_collector_init() has run. Idempotent.
+ * Defined in rv_radio_ops_esp32.c.
+ */
+void rv_radio_ops_esp32_register(void);
+
+/**
+ * Register the mock binding (QEMU / offline) as the active radio ops.
+ *
+ * Defined in rv_radio_ops_mock.c; only built when CONFIG_CSI_MOCK_ENABLED.
+ */
+void rv_radio_ops_mock_register(void);
+
+#ifdef __cplusplus
+}
+#endif
+
+#endif /* RV_RADIO_OPS_H */
@@ -0,0 +1,176 @@
+/**
+ * @file rv_radio_ops_esp32.c
+ * @brief ADR-081 Layer 1 — ESP32 binding for rv_radio_ops_t.
+ *
+ * Wraps the existing csi_collector + esp_wifi_* surface so the adaptive
+ * controller, mesh plane, and feature-extraction layers can address the
+ * radio through a single chipset-agnostic vtable.
+ *
+ * This is intentionally thin. The heavy lifting still lives in
+ * csi_collector.c (CSI callback, channel hopping, NDP injection); this file
+ * is the contract that lets a second chipset (Nexmon Broadcom, custom
+ * silicon) drop in without touching the layers above.
+ */
+
+#include "rv_radio_ops.h"
+#include "csi_collector.h"
+
+#include <string.h>
+#include "esp_err.h"
+#include "esp_log.h"
+#include "esp_wifi.h"
+
+static const char *TAG = "rv_radio_esp32";
+
+/* ---- Active ops registry ---- */
+
+static const rv_radio_ops_t *s_active_ops = NULL;
+
+void rv_radio_ops_register(const rv_radio_ops_t *ops)
+{
+    s_active_ops = ops;
+}
+
+const rv_radio_ops_t *rv_radio_ops_get(void)
+{
+    return s_active_ops;
+}
+
+/* ---- ESP32 binding state ---- */
+
+static uint8_t  s_current_channel = 1;
+static uint8_t  s_current_bw      = 20;
+static uint8_t  s_current_profile = RV_PROFILE_PASSIVE_LOW_RATE;
+static uint8_t  s_current_mode    = RV_RADIO_MODE_PASSIVE_RX;
+static bool     s_csi_enabled     = true;
+
+/* ---- Vtable implementations ---- */
+
+static int esp32_init(void)
+{
+    /* csi_collector_init() is called from app_main() before the controller
+     * starts; nothing to do here for the ESP32 binding. We just confirm a
+     * valid current channel was captured by csi_collector_init(). */
+    ESP_LOGI(TAG, "ESP32 radio ops: init (current ch=%u bw=%u)",
+             (unsigned)s_current_channel, (unsigned)s_current_bw);
+    return ESP_OK;
+}
+
+static int esp32_set_channel(uint8_t ch, uint8_t bw)
+{
+    wifi_second_chan_t second = WIFI_SECOND_CHAN_NONE;
+    if (bw == 40) {
+        /* HT40+: secondary channel above primary. The controller never asks
+         * for HT40 today (sensing prefers HT20), but the mapping is here so
+         * a future profile can. */
+        second = WIFI_SECOND_CHAN_ABOVE;
+    } else if (bw != 20) {
+        ESP_LOGW(TAG, "set_channel: unsupported bw=%u, treating as 20 MHz",
+                 (unsigned)bw);
+        bw = 20;
+    }
+
+    esp_err_t err = esp_wifi_set_channel(ch, second);
+    if (err != ESP_OK) {
+        ESP_LOGW(TAG, "set_channel(%u, bw=%u) failed: %s",
+                 (unsigned)ch, (unsigned)bw, esp_err_to_name(err));
+        return (int)err;
+    }
+    s_current_channel = ch;
+    s_current_bw      = bw;
+    return ESP_OK;
+}
+
+static int esp32_set_mode(uint8_t mode)
+{
+    /* Persist the mode for the health snapshot; actual TX behavior is
+     * triggered by the controller calling csi_inject_ndp_frame() directly
+     * once the controller PR lands. For now this is bookkeeping plus a
+     * passive/active probe gate. */
+    switch (mode) {
+    case RV_RADIO_MODE_DISABLED:
+    case RV_RADIO_MODE_PASSIVE_RX:
+    case RV_RADIO_MODE_ACTIVE_PROBE:
+    case RV_RADIO_MODE_CALIBRATION:
+        s_current_mode = mode;
+        return ESP_OK;
+    default:
+        ESP_LOGW(TAG, "set_mode: unknown mode %u", (unsigned)mode);
+        return ESP_ERR_INVALID_ARG;
+    }
+}
+
+static int esp32_set_csi_enabled(bool en)
+{
+    esp_err_t err = esp_wifi_set_csi(en);
+    if (err != ESP_OK) {
+        ESP_LOGW(TAG, "set_csi(%d) failed: %s", (int)en, esp_err_to_name(err));
+        return (int)err;
+    }
+    s_csi_enabled = en;
+    return ESP_OK;
+}
+
+static int esp32_set_capture_profile(uint8_t profile_id)
+{
+    if (profile_id >= RV_PROFILE_COUNT) {
+        ESP_LOGW(TAG, "set_capture_profile: invalid id %u", (unsigned)profile_id);
+        return ESP_ERR_INVALID_ARG;
+    }
+
+    /* Profiles are advisory at this layer — the controller uses them to
+     * decide cadence/window/threshold for the layers above. The radio
+     * binding records the active profile for health reporting and may
+     * adjust the underlying TX/RX mode in future bindings. */
+    s_current_profile = profile_id;
+
+    /* For ACTIVE_PROBE and CALIBRATION, switch the radio mode to match. */
+    if (profile_id == RV_PROFILE_ACTIVE_PROBE) {
+        esp32_set_mode(RV_RADIO_MODE_ACTIVE_PROBE);
+    } else if (profile_id == RV_PROFILE_CALIBRATION) {
+        esp32_set_mode(RV_RADIO_MODE_CALIBRATION);
+    } else {
+        esp32_set_mode(RV_RADIO_MODE_PASSIVE_RX);
+    }
+    return ESP_OK;
+}
+
+static int esp32_get_health(rv_radio_health_t *out)
+{
+    if (out == NULL) {
+        return ESP_ERR_INVALID_ARG;
+    }
+    memset(out, 0, sizeof(*out));
+
+    out->pkt_yield_per_sec = csi_collector_get_pkt_yield_per_sec();
+    out->send_fail_count   = csi_collector_get_send_fail_count();
+    out->current_channel   = s_current_channel;
+    out->current_bw_mhz    = s_current_bw;
+    out->current_profile   = s_current_profile;
+
+    wifi_ap_record_t ap = {0};
+    if (esp_wifi_sta_get_ap_info(&ap) == ESP_OK) {
+        out->rssi_median_dbm = ap.rssi;
+    }
+    return ESP_OK;
+}
+
+/* ---- The vtable instance ---- */
+
+static const rv_radio_ops_t s_esp32_ops = {
+    .init                 = esp32_init,
+    .set_channel          = esp32_set_channel,
+    .set_mode             = esp32_set_mode,
+    .set_csi_enabled      = esp32_set_csi_enabled,
+    .set_capture_profile  = esp32_set_capture_profile,
+    .get_health           = esp32_get_health,
+};
+
+void rv_radio_ops_esp32_register(void)
+{
+    if (s_active_ops == &s_esp32_ops) {
+        return;  /* idempotent */
+    }
+    rv_radio_ops_register(&s_esp32_ops);
+    ESP_LOGI(TAG, "ESP32 radio ops registered as active binding");
+}
@@ -0,0 +1,98 @@
+/**
+ * @file rv_radio_ops_mock.c
+ * @brief ADR-081 Layer 1 — Mock binding for QEMU / offline testing.
+ *
+ * When CONFIG_CSI_MOCK_ENABLED is set (ADR-061 QEMU flow), there is no
+ * real WiFi driver to wrap. This binding provides the same ops table as
+ * the ESP32 binding but records state into in-process statics and
+ * accepts every call. It exists primarily to satisfy ADR-081's
+ * portability acceptance test: a second binding must compile against
+ * the same controller and mesh-plane code without modification.
+ *
+ * Only compiled when CONFIG_CSI_MOCK_ENABLED is set. Registered from
+ * main.c in the mock branch.
+ */
+
+#include "sdkconfig.h"
+
+#ifdef CONFIG_CSI_MOCK_ENABLED
+
+#include "rv_radio_ops.h"
+#include "mock_csi.h"
+
+#include <string.h>
+#include "esp_err.h"
+#include "esp_log.h"
+
+static const char *TAG = "rv_radio_mock";
+
+static uint8_t s_channel = 6;
+static uint8_t s_bw      = 20;
+static uint8_t s_profile = RV_PROFILE_PASSIVE_LOW_RATE;
+static uint8_t s_mode    = RV_RADIO_MODE_PASSIVE_RX;
+static bool    s_csi_on  = true;
+
+static int mock_init(void)
+{
+    ESP_LOGI(TAG, "mock radio ops: init");
+    return ESP_OK;
+}
+
+static int mock_set_channel(uint8_t ch, uint8_t bw)
+{
+    s_channel = ch;
+    s_bw      = (bw == 40) ? 40 : 20;
+    return ESP_OK;
+}
+
+static int mock_set_mode(uint8_t mode)
+{
+    s_mode = mode;
+    return ESP_OK;
+}
+
+static int mock_set_csi_enabled(bool en)
+{
+    s_csi_on = en;
+    return ESP_OK;
+}
+
+static int mock_set_capture_profile(uint8_t profile_id)
+{
+    if (profile_id >= RV_PROFILE_COUNT) return ESP_ERR_INVALID_ARG;
+    s_profile = profile_id;
+    return ESP_OK;
+}
+
+static int mock_get_health(rv_radio_health_t *out)
+{
+    if (out == NULL) return ESP_ERR_INVALID_ARG;
+    memset(out, 0, sizeof(*out));
+
+    /* Mock yield: mirror mock_csi's generator rate so the adaptive
+     * controller sees a sensible pkt_yield in QEMU. */
+    out->pkt_yield_per_sec = 20;  /* MOCK_CSI_INTERVAL_MS = 50 → 20 Hz */
+    out->rssi_median_dbm   = -55;
+    out->noise_floor_dbm   = -95;
+    out->current_channel   = s_channel;
+    out->current_bw_mhz    = s_bw;
+    out->current_profile   = s_profile;
+    return ESP_OK;
+}
+
+static const rv_radio_ops_t s_mock_ops = {
+    .init                 = mock_init,
+    .set_channel          = mock_set_channel,
+    .set_mode             = mock_set_mode,
+    .set_csi_enabled      = mock_set_csi_enabled,
+    .set_capture_profile  = mock_set_capture_profile,
+    .get_health           = mock_get_health,
+};
+
+void rv_radio_ops_mock_register(void)
+{
+    rv_radio_ops_register(&s_mock_ops);
+    ESP_LOGI(TAG, "mock radio ops registered (QEMU / offline mode)");
+}
+
+#endif /* CONFIG_CSI_MOCK_ENABLED */
@@ -31,3 +31,7 @@ CONFIG_LWIP_SO_RCVBUF=y

 # FreeRTOS: increase task stack for CSI processing
 CONFIG_ESP_MAIN_TASK_STACK_SIZE=8192
+
+# ADR-081: adaptive_controller runs emit_feature_state + stream_sender
+# network I/O inside Timer Svc callbacks, exceeding the 2 KiB default.
+CONFIG_FREERTOS_TIMER_TASK_STACK_DEPTH=8192
@@ -27,3 +27,7 @@ CONFIG_LOG_DEFAULT_LEVEL_INFO=y

 CONFIG_LWIP_SO_RCVBUF=y
 CONFIG_ESP_MAIN_TASK_STACK_SIZE=8192
+
+# ADR-081: adaptive_controller runs emit_feature_state + stream_sender
+# network I/O inside Timer Svc callbacks, exceeding the 2 KiB default.
+CONFIG_FREERTOS_TIMER_TASK_STACK_DEPTH=8192
@@ -31,3 +31,7 @@ CONFIG_LWIP_SO_RCVBUF=y

 # FreeRTOS: increase task stack for CSI processing
 CONFIG_ESP_MAIN_TASK_STACK_SIZE=8192
+
+# ADR-081: adaptive_controller runs emit_feature_state + stream_sender
+# network I/O inside Timer Svc callbacks, exceeding the 2 KiB default.
+CONFIG_FREERTOS_TIMER_TASK_STACK_DEPTH=8192
@@ -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;
+}
@@ -1 +1 @@
-0.6.0
+0.6.2
@@ -139,6 +139,15 @@ version = "1.0.102"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "7f202df86484c868dbad7eaa557ef785d5c66295e41b460ef922eca0723b842c"

+[[package]]
+name = "approx"
+version = "0.4.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "3f2a05fd1bd10b2527e20a2cd32d8873d115b8b39fe219ee25f42a8aca6ba278"
+dependencies = [
+ "num-traits",
+]
+
 [[package]]
 name = "approx"
 version = "0.5.1"
@@ -623,6 +632,27 @@ version = "0.3.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "37b2a672a2cb129a2e41c10b1224bb368f9f37a2b16b612598138befd7b37eb5"

+[[package]]
+name = "cauchy"
+version = "0.4.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "9ff11ddd2af3b5e80dd0297fee6e56ac038d9bdc549573cdb51bd6d2efe7f05e"
+dependencies = [
+ "num-complex",
+ "num-traits",
+ "rand 0.8.5",
+ "serde",
+]
+
+[[package]]
+name = "cblas-sys"
+version = "0.1.4"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "b6feecd82cce51b0204cf063f0041d69f24ce83f680d87514b004248e7b0fa65"
+dependencies = [
+ "libc",
+]
+
 [[package]]
 name = "cc"
 version = "1.2.56"
@@ -1180,13 +1210,34 @@ dependencies = [
 "subtle",
 ]

+[[package]]
+name = "dirs"
+version = "5.0.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "44c45a9d03d6676652bcb5e724c7e988de1acad23a711b5217ab9cbecbec2225"
+dependencies = [
+ "dirs-sys 0.4.1",
+]
+
 [[package]]
 name = "dirs"
 version = "6.0.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "c3e8aa94d75141228480295a7d0e7feb620b1a5ad9f12bc40be62411e38cce4e"
 dependencies = [
- "dirs-sys",
+ "dirs-sys 0.5.0",
+]
+
+[[package]]
+name = "dirs-sys"
+version = "0.4.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "520f05a5cbd335fae5a99ff7a6ab8627577660ee5cfd6a94a6a929b52ff0321c"
+dependencies = [
+ "libc",
+ "option-ext",
+ "redox_users 0.4.6",
+ "windows-sys 0.48.0",
 ]

 [[package]]
@@ -1197,7 +1248,7 @@ checksum = "e01a3366d27ee9890022452ee61b2b63a67e6f13f58900b651ff5665f0bb1fab"
 dependencies = [
 "libc",
 "option-ext",
- "redox_users",
+ "redox_users 0.5.2",
 "windows-sys 0.61.2",
 ]

@@ -1420,6 +1471,17 @@ dependencies = [
 "rustc_version",
 ]

+[[package]]
+name = "filetime"
+version = "0.2.27"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "f98844151eee8917efc50bd9e8318cb963ae8b297431495d3f758616ea5c57db"
+dependencies = [
+ "cfg-if",
+ "libc",
+ "libredox",
+]
+
 [[package]]
 name = "find-msvc-tools"
 version = "0.1.9"
@@ -1908,7 +1970,7 @@ version = "0.7.18"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "24f8647af4005fa11da47cd56252c6ef030be8fa97bdbf355e7dfb6348f0a82c"
 dependencies = [
- "approx",
+ "approx 0.5.1",
 "num-traits",
 "rstar 0.10.0",
 "rstar 0.11.0",
@@ -2780,6 +2842,17 @@ dependencies = [
 "serde_json",
 ]

+[[package]]
+name = "katexit"
+version = "0.1.5"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "ccfb0b7ce7938f84a5ecbdca5d0a991e46bc9d6d078934ad5e92c5270fe547db"
+dependencies = [
+ "proc-macro2",
+ "quote",
+ "syn 2.0.117",
+]
+
 [[package]]
 name = "keyboard-types"
 version = "0.7.0"
@@ -2803,6 +2876,29 @@ dependencies = [
 "selectors",
 ]

+[[package]]
+name = "lapack-sys"
+version = "0.14.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "447f56c85fb410a7a3d36701b2153c1018b1d2b908c5fbaf01c1b04fac33bcbe"
+dependencies = [
+ "libc",
+]
+
+[[package]]
+name = "lax"
+version = "0.16.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "1f96a229d9557112e574164f8024ce703625ad9f88a90964c1780809358e53da"
+dependencies = [
+ "cauchy",
+ "katexit",
+ "lapack-sys",
+ "num-traits",
+ "openblas-src",
+ "thiserror 1.0.69",
+]
+
 [[package]]
 name = "lazy_static"
 version = "1.5.0"
@@ -2867,7 +2963,10 @@ version = "0.1.14"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "1744e39d1d6a9948f4f388969627434e31128196de472883b39f148769bfe30a"
 dependencies = [
+ "bitflags 2.11.0",
 "libc",
+ "plain",
+ "redox_syscall 0.7.4",
 ]

 [[package]]
@@ -3218,7 +3317,7 @@ version = "0.33.2"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "26aecdf64b707efd1310e3544d709c5c0ac61c13756046aaaba41be5c4f66a3b"
 dependencies = [
- "approx",
+ "approx 0.5.1",
 "matrixmultiply",
 "nalgebra-macros",
 "num-complex",
@@ -3271,6 +3370,9 @@ version = "0.15.6"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "adb12d4e967ec485a5f71c6311fe28158e9d6f4bc4a447b474184d0f91a8fa32"
 dependencies = [
+ "approx 0.4.0",
+ "cblas-sys",
+ "libc",
 "matrixmultiply",
 "num-complex",
 "num-integer",
@@ -3310,6 +3412,22 @@ dependencies = [
 "rawpointer",
 ]

+[[package]]
+name = "ndarray-linalg"
+version = "0.16.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "0b0e8dda0c941b64a85c5deb2b3e0144aca87aced64678adfc23eacea6d2cc42"
+dependencies = [
+ "cauchy",
+ "katexit",
+ "lax",
+ "ndarray 0.15.6",
+ "num-complex",
+ "num-traits",
+ "rand 0.8.5",
+ "thiserror 1.0.69",
+]
+
 [[package]]
 name = "ndarray-npy"
 version = "0.8.1"
@@ -3441,6 +3559,8 @@ checksum = "73f88a1307638156682bada9d7604135552957b7818057dcef22705b4d509495"
 dependencies = [
 "bytemuck",
 "num-traits",
+ "rand 0.8.5",
+ "serde",
 ]

 [[package]]
@@ -3670,6 +3790,32 @@ dependencies = [
 "pathdiff",
 ]

+[[package]]
+name = "openblas-build"
+version = "0.10.15"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "cd235aa8876fa5c4be452efde09b9b8bafa19aea0bf14a4926508213082439a3"
+dependencies = [
+ "anyhow",
+ "cc",
+ "flate2",
+ "tar",
+ "thiserror 2.0.18",
+ "ureq",
+]
+
+[[package]]
+name = "openblas-src"
+version = "0.10.15"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "fccd2c4f5271ab871f2069cb6f1a13ef2c0db50e1145ce03428ee541f4c63c4f"
+dependencies = [
+ "dirs 6.0.0",
+ "openblas-build",
+ "pkg-config",
+ "vcpkg",
+]
+
 [[package]]
 name = "openssl"
 version = "0.10.75"
@@ -3819,7 +3965,7 @@ checksum = "2621685985a2ebf1c516881c026032ac7deafcda1a2c9b7850dc81e3dfcb64c1"
 dependencies = [
 "cfg-if",
 "libc",
- "redox_syscall",
+ "redox_syscall 0.5.18",
 "smallvec",
 "windows-link 0.2.1",
 ]
@@ -4095,6 +4241,12 @@ version = "0.3.32"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "7edddbd0b52d732b21ad9a5fab5c704c14cd949e5e9a1ec5929a24fded1b904c"

+[[package]]
+name = "plain"
+version = "0.2.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "b4596b6d070b27117e987119b4dac604f3c58cfb0b191112e24771b2faeac1a6"
+
 [[package]]
 name = "plist"
 version = "1.8.0"
@@ -4694,6 +4846,26 @@ dependencies = [
 "bitflags 2.11.0",
 ]

+[[package]]
+name = "redox_syscall"
+version = "0.7.4"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "f450ad9c3b1da563fb6948a8e0fb0fb9269711c9c73d9ea1de5058c79c8d643a"
+dependencies = [
+ "bitflags 2.11.0",
+]
+
+[[package]]
+name = "redox_users"
+version = "0.4.6"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "ba009ff324d1fc1b900bd1fdb31564febe58a8ccc8a6fdbb93b543d33b13ca43"
+dependencies = [
+ "getrandom 0.2.17",
+ "libredox",
+ "thiserror 1.0.69",
+]
+
 [[package]]
 name = "redox_users"
 version = "0.5.2"
@@ -5737,7 +5909,7 @@ version = "0.9.1"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "c99284beb21666094ba2b75bbceda012e610f5479dfcc2d6e2426f53197ffd95"
 dependencies = [
- "approx",
+ "approx 0.5.1",
 "num-complex",
 "num-traits",
 "paste",
@@ -5826,7 +5998,7 @@ dependencies = [
 "objc2-foundation",
 "objc2-quartz-core",
 "raw-window-handle",
- "redox_syscall",
+ "redox_syscall 0.5.18",
 "tracing",
 "wasm-bindgen",
 "web-sys",
@@ -6098,6 +6270,17 @@ dependencies = [
 "syn 2.0.117",
 ]

+[[package]]
+name = "tar"
+version = "0.4.45"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "22692a6476a21fa75fdfc11d452fda482af402c008cdbaf3476414e122040973"
+dependencies = [
+ "filetime",
+ "libc",
+ "xattr",
+]
+
 [[package]]
 name = "target-lexicon"
 version = "0.12.16"
@@ -6113,7 +6296,7 @@ dependencies = [
 "anyhow",
 "bytes",
 "cookie",
- "dirs",
+ "dirs 6.0.0",
 "dunce",
 "embed_plist",
 "getrandom 0.3.4",
@@ -6163,7 +6346,7 @@ checksum = "4bbc990d1dbf57a8e1c7fa2327f2a614d8b757805603c1b9ba5c81bade09fd4d"
 dependencies = [
 "anyhow",
 "cargo_toml",
- "dirs",
+ "dirs 6.0.0",
 "glob",
 "heck 0.5.0",
 "json-patch",
@@ -6937,7 +7120,7 @@ source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "a5e85aa143ceb072062fc4d6356c1b520a51d636e7bc8e77ec94be3608e5e80c"
 dependencies = [
 "crossbeam-channel",
- "dirs",
+ "dirs 6.0.0",
 "libappindicator",
 "muda",
 "objc2",
@@ -7669,11 +7852,23 @@ dependencies = [
 "uuid",
 ]

+[[package]]
+name = "wifi-densepose-geo"
+version = "0.1.0"
+dependencies = [
+ "anyhow",
+ "chrono",
+ "reqwest 0.12.28",
+ "serde",
+ "serde_json",
+ "tokio",
+]
+
 [[package]]
 name = "wifi-densepose-hardware"
 version = "0.3.0"
 dependencies = [
- "approx",
+ "approx 0.5.1",
 "byteorder",
 "chrono",
 "clap",
@@ -7694,7 +7889,7 @@ name = "wifi-densepose-mat"
 version = "0.3.0"
 dependencies = [
 "anyhow",
- "approx",
+ "approx 0.5.1",
 "async-trait",
 "axum",
 "chrono",
@@ -7743,11 +7938,26 @@ dependencies = [
 "tracing",
 ]

+[[package]]
+name = "wifi-densepose-pointcloud"
+version = "0.1.0"
+dependencies = [
+ "anyhow",
+ "axum",
+ "chrono",
+ "clap",
+ "dirs 5.0.1",
+ "reqwest 0.12.28",
+ "serde",
+ "serde_json",
+ "tokio",
+]
+
 [[package]]
 name = "wifi-densepose-ruvector"
 version = "0.3.0"
 dependencies = [
- "approx",
+ "approx 0.5.1",
 "criterion",
 "ruvector-attention 2.0.4",
 "ruvector-attn-mincut",
@@ -7769,7 +7979,6 @@ dependencies = [
 "chrono",
 "clap",
 "futures-util",
- "ruvector-mincut",
 "serde",
 "serde_json",
 "tempfile",
@@ -7777,6 +7986,7 @@ dependencies = [
 "tower-http 0.5.2",
 "tracing",
 "tracing-subscriber",
+ "wifi-densepose-signal",
 "wifi-densepose-wifiscan",
 ]

@@ -7789,6 +7999,7 @@ dependencies = [
 "midstreamer-attractor",
 "midstreamer-temporal-compare",
 "ndarray 0.15.6",
+ "ndarray-linalg",
 "num-complex",
 "num-traits",
 "proptest",
@@ -7808,7 +8019,7 @@ name = "wifi-densepose-train"
 version = "0.3.0"
 dependencies = [
 "anyhow",
- "approx",
+ "approx 0.5.1",
 "chrono",
 "clap",
 "criterion",
@@ -8566,7 +8777,7 @@ dependencies = [
 "block2",
 "cookie",
 "crossbeam-channel",
- "dirs",
+ "dirs 6.0.0",
 "dpi",
 "dunce",
 "gdkx11",
@@ -8622,6 +8833,16 @@ dependencies = [
 "pkg-config",
 ]

+[[package]]
+name = "xattr"
+version = "1.6.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "32e45ad4206f6d2479085147f02bc2ef834ac85886624a23575ae137c8aa8156"
+dependencies = [
+ "libc",
+ "rustix",
+]
+
 [[package]]
 name = "yasna"
 version = "0.5.2"
@@ -17,6 +17,8 @@ members = [
    "crates/wifi-densepose-vitals",
    "crates/wifi-densepose-ruvector",
    "crates/wifi-densepose-desktop",
+    "crates/wifi-densepose-pointcloud",
+    "crates/wifi-densepose-geo",
 ]
 # ADR-040: WASM edge crate targets wasm32-unknown-unknown (no_std),
 # excluded from workspace to avoid breaking `cargo test --workspace`.
@@ -0,0 +1,13 @@
+[package]
+name = "wifi-densepose-geo"
+version = "0.1.0"
+edition = "2021"
+description = "Geospatial satellite integration — free satellite tiles, DEM, OSM, temporal tracking"
+
+[dependencies]
+serde = { workspace = true }
+serde_json = { workspace = true }
+tokio = { workspace = true }
+anyhow = { workspace = true }
+reqwest = { version = "0.12", features = ["json", "native-tls"], default-features = false }
+chrono = "0.4"
@@ -0,0 +1,105 @@
+# wifi-densepose-geo — Geospatial Satellite Integration
+
+Free satellite imagery, terrain elevation, and map data for RuView spatial sensing. No API keys required.
+
+## What It Does
+
+Integrates your local sensor data (camera + WiFi CSI point cloud) with geographic context:
+
+- **Satellite tiles** — 10m Sentinel-2 cloudless imagery for your location
+- **Elevation** — SRTM 30m DEM for terrain modeling
+- **Buildings + roads** — OpenStreetMap data via Overpass API
+- **Weather** — Open Meteo current conditions + forecast
+- **Geo-registration** — maps local sensor coordinates to WGS84
+- **Temporal tracking** — detects changes over time (construction, vegetation, weather)
+- **Brain integration** — stores geospatial context as ruOS brain memories
+
+## Data Sources (all free, no API keys)
+
+| Source | Data | Resolution | License |
+|--------|------|-----------|---------|
+| [EOX S2 Cloudless](https://s2maps.eu/) | Satellite tiles | 10m | CC-BY-4.0 |
+| [SRTM GL1](https://portal.opentopography.org/) | Elevation/DEM | 30m | Public domain |
+| [Overpass API](https://overpass-api.de/) | OSM buildings/roads | Vector | ODbL |
+| [ip-api.com](http://ip-api.com/) | IP geolocation | ~1km | Free |
+| [Open Meteo](https://open-meteo.com/) | Weather | Point | CC-BY-4.0 |
+
+## Modules
+
+| Module | LOC | Purpose |
+|--------|-----|---------|
+| `types.rs` | 140 | GeoPoint, GeoBBox, TileCoord, ElevationGrid, OsmFeature |
+| `coord.rs` | 80 | WGS84/ENU transforms, tile math, haversine distance |
+| `locate.rs` | 45 | IP geolocation with caching |
+| `cache.rs` | 55 | Disk cache (`~/.local/share/ruview/geo-cache/`) |
+| `tiles.rs` | 80 | Sentinel-2/ESRI/OSM tile fetcher |
+| `terrain.rs` | 100 | SRTM HGT parser, elevation lookup |
+| `osm.rs` | 150 | Overpass API client, building/road extraction |
+| `register.rs` | 50 | Local-to-WGS84 coordinate registration |
+| `fuse.rs` | 70 | Multi-source scene builder + summary |
+| `brain.rs` | 30 | Store geo context in ruOS brain |
+| `temporal.rs` | 100 | Weather, OSM change detection |
+
+## Usage
+
+```rust
+use wifi_densepose_geo::{fuse, brain, temporal};
+
+// Build geo scene for current location
+let scene = fuse::build_scene(500.0).await?; // 500m radius
+println!("{}", fuse::summarize(&scene));
+// "Location: 43.6532N, 79.3832W, elevation 76m ASL.
+//  23 buildings within view. 8 roads nearby (King St, Queen St).
+//  12 satellite tiles at zoom 16."
+
+// Store in brain
+brain::store_geo_context(&scene).await?;
+
+// Fetch weather
+let weather = temporal::fetch_weather(&scene.location).await?;
+// temperature: 12°C, partly cloudy, humidity 65%
+```
+
+## Brain Integration
+
+Geospatial context is stored as brain memories:
+
+| Category | Content | Frequency |
+|----------|---------|-----------|
+| `spatial-geo` | Location, elevation, buildings, roads | On startup + daily |
+| `spatial-weather` | Temperature, conditions, humidity, wind | Nightly |
+| `spatial-change` | New/removed buildings, road changes | Nightly diff |
+
+The ruOS agent can search: "what buildings are near me?" or "what's the weather?" and get geospatial context from the brain.
+
+## Security
+
+- No API keys stored or transmitted
+- IP geolocation uses HTTP (not HTTPS) — location is approximate (~1km)
+- All tile fetches use HTTPS except ip-api.com
+- Path traversal protection in cache key sanitization
+- No user data sent to external services
+- All data cached locally after first fetch
+
+## Architecture
+
+```
+IP Geolocation ──→ (lat, lon)
+                      │
+        ┌─────────────┼─────────────┐
+        ▼             ▼             ▼
+   Sentinel-2     SRTM DEM     Overpass API
+   (tiles)       (elevation)   (buildings/roads)
+        │             │             │
+        └─────────────┼─────────────┘
+                      ▼
+               GeoScene (fused)
+                      │
+              ┌───────┴───────┐
+              ▼               ▼
+        Brain Memory    Three.js Viewer
+```
+
+## License
+
+MIT (same as RuView)
@@ -0,0 +1,47 @@
+use wifi_densepose_geo::*;
+
+#[tokio::main]
+async fn main() -> anyhow::Result<()> {
+    println!("╔══════════════════════════════════════════════╗");
+    println!("║  ruview-geo — Real Data Validation           ║");
+    println!("╚══════════════════════════════════════════════╝\n");
+
+    let t0 = std::time::Instant::now();
+    let cache = cache::TileCache::new("/tmp/ruview-geo-validate");
+
+    let loc = locate::get_location(&format!("{}/location.json", cache.base_dir.display())).await?;
+    println!("  Location: {:.4}N, {:.4}W", loc.lat, loc.lon);
+
+    let bbox = GeoBBox::from_center(&loc, 300.0);
+    let tiles_list = tiles::fetch_area(&tiles::TileProvider::Sentinel2Cloudless, &bbox, 16, &cache).await?;
+    println!("  Tiles: {} ({:.0}KB)", tiles_list.len(),
+        tiles_list.iter().map(|t| t.data.len()).sum::<usize>() as f64 / 1024.0);
+
+    let dem = terrain::fetch_elevation(&loc, &cache).await?;
+    println!("  Elevation: {:.0}m (grid {}x{})", terrain::elevation_at(&dem, &loc), dem.cols, dem.rows);
+
+    let buildings = osm::fetch_buildings(&loc, 300.0).await.unwrap_or_default();
+    let roads = osm::fetch_roads(&loc, 300.0).await.unwrap_or_default();
+    println!("  OSM: {} buildings, {} roads", buildings.len(), roads.len());
+
+    let weather = temporal::fetch_weather(&loc).await?;
+    println!("  Weather: {:.0}°C humidity={:.0}% wind={:.1}m/s",
+        weather.temperature_c, weather.humidity_pct, weather.wind_speed_ms);
+
+    let scene = GeoScene {
+        location: loc.clone(), bbox, elevation_m: terrain::elevation_at(&dem, &loc),
+        buildings, roads, tile_count: tiles_list.len(),
+        registration: register::auto_register(&loc),
+        last_updated: chrono::Utc::now().to_rfc3339(),
+    };
+    println!("\n  {}", fuse::summarize(&scene));
+
+    match brain::store_geo_context(&scene).await {
+        Ok(n) => println!("  Brain: {} memories stored", n),
+        Err(e) => println!("  Brain: {e}"),
+    }
+
+    println!("\n  Total: {}ms | Cache: {:.0}KB",
+        t0.elapsed().as_millis(), cache.size_bytes() as f64 / 1024.0);
+    Ok(())
+}
@@ -0,0 +1,42 @@
+//! Brain integration — store geospatial context in ruOS brain.
+//!
+//! Brain URL is read from `RUVIEW_BRAIN_URL` env var (default
+//! `http://127.0.0.1:9876`). The resolved URL is logged once on first use.
+
+use crate::fuse;
+use crate::types::GeoScene;
+use anyhow::Result;
+use std::sync::OnceLock;
+
+const DEFAULT_BRAIN_URL: &str = "http://127.0.0.1:9876";
+
+pub(crate) fn brain_url() -> &'static str {
+    static BRAIN_URL: OnceLock<String> = OnceLock::new();
+    BRAIN_URL.get_or_init(|| {
+        let url = std::env::var("RUVIEW_BRAIN_URL")
+            .unwrap_or_else(|_| DEFAULT_BRAIN_URL.to_string());
+        eprintln!("  wifi-densepose-geo: using brain URL {url}");
+        url
+    })
+}
+
+/// Store geospatial context in the brain.
+pub async fn store_geo_context(scene: &GeoScene) -> Result<u32> {
+    let client = reqwest::Client::builder()
+        .timeout(std::time::Duration::from_secs(5))
+        .build()?;
+
+    let mut stored = 0u32;
+
+    // Store location summary
+    let summary = fuse::summarize(scene);
+    let body = serde_json::json!({
+        "category": "spatial-geo",
+        "content": summary,
+    });
+    if client.post(format!("{}/memories", brain_url())).json(&body).send().await.is_ok() {
+        stored += 1;
+    }
+
+    Ok(stored)
+}
@@ -0,0 +1,61 @@
+//! Disk cache for tiles, DEM, and OSM data.
+
+use anyhow::Result;
+use std::path::{Path, PathBuf};
+
+pub struct TileCache {
+    pub base_dir: PathBuf,
+}
+
+impl TileCache {
+    pub fn new(base_dir: &str) -> Self {
+        let expanded = base_dir.replace('~', &std::env::var("HOME").unwrap_or_default());
+        let path = PathBuf::from(expanded);
+        let _ = std::fs::create_dir_all(&path);
+        Self { base_dir: path }
+    }
+
+    pub fn default_cache() -> Self {
+        Self::new("~/.local/share/ruview/geo-cache")
+    }
+
+    pub fn get(&self, key: &str) -> Option<Vec<u8>> {
+        let path = self.key_path(key);
+        std::fs::read(&path).ok()
+    }
+
+    pub fn put(&self, key: &str, data: &[u8]) -> Result<()> {
+        let path = self.key_path(key);
+        if let Some(parent) = path.parent() {
+            std::fs::create_dir_all(parent)?;
+        }
+        std::fs::write(&path, data)?;
+        Ok(())
+    }
+
+    pub fn has(&self, key: &str) -> bool {
+        self.key_path(key).exists()
+    }
+
+    pub fn size_bytes(&self) -> u64 {
+        walkdir(self.base_dir.as_path())
+    }
+
+    fn key_path(&self, key: &str) -> PathBuf {
+        // Sanitize key to prevent path traversal
+        let safe_key = key.replace("..", "_").replace('/', "_");
+        self.base_dir.join(safe_key)
+    }
+}
+
+fn walkdir(path: &Path) -> u64 {
+    std::fs::read_dir(path)
+        .into_iter()
+        .flatten()
+        .filter_map(|e| e.ok())
+        .map(|e| {
+            if e.path().is_dir() { walkdir(&e.path()) }
+            else { e.metadata().map(|m| m.len()).unwrap_or(0) }
+        })
+        .sum()
+}
@@ -0,0 +1,74 @@
+//! Coordinate transforms — WGS84, UTM, ENU, tile math.
+
+use crate::types::{GeoPoint, GeoBBox, TileCoord};
+
+const WGS84_A: f64 = 6_378_137.0;
+#[allow(dead_code)]
+const WGS84_F: f64 = 1.0 / 298.257_223_563;
+#[allow(dead_code)]
+const WGS84_E2: f64 = 2.0 * WGS84_F - WGS84_F * WGS84_F;
+
+/// Haversine distance in meters.
+pub fn haversine(a: &GeoPoint, b: &GeoPoint) -> f64 {
+    let dlat = (b.lat - a.lat).to_radians();
+    let dlon = (b.lon - a.lon).to_radians();
+    let lat1 = a.lat.to_radians();
+    let lat2 = b.lat.to_radians();
+    let h = (dlat / 2.0).sin().powi(2) + lat1.cos() * lat2.cos() * (dlon / 2.0).sin().powi(2);
+    2.0 * WGS84_A * h.sqrt().asin()
+}
+
+/// WGS84 to local ENU (East-North-Up) relative to origin, in meters.
+pub fn wgs84_to_enu(point: &GeoPoint, origin: &GeoPoint) -> [f64; 3] {
+    let dlat = (point.lat - origin.lat).to_radians();
+    let dlon = (point.lon - origin.lon).to_radians();
+    let lat = origin.lat.to_radians();
+    let east = dlon * WGS84_A * lat.cos();
+    let north = dlat * WGS84_A;
+    let up = point.alt - origin.alt;
+    [east, north, up]
+}
+
+/// Local ENU to WGS84.
+pub fn enu_to_wgs84(enu: &[f64; 3], origin: &GeoPoint) -> GeoPoint {
+    let lat = origin.lat.to_radians();
+    let dlat = enu[1] / WGS84_A;
+    let dlon = enu[0] / (WGS84_A * lat.cos());
+    GeoPoint {
+        lat: origin.lat + dlat.to_degrees(),
+        lon: origin.lon + dlon.to_degrees(),
+        alt: origin.alt + enu[2],
+    }
+}
+
+/// WGS84 to XYZ tile coordinates (Slippy Map).
+pub fn wgs84_to_tile(lat: f64, lon: f64, zoom: u8) -> TileCoord {
+    let n = 2f64.powi(zoom as i32);
+    let x = ((lon + 180.0) / 360.0 * n).floor() as u32;
+    let lat_rad = lat.to_radians();
+    let y = ((1.0 - lat_rad.tan().asinh() / std::f64::consts::PI) / 2.0 * n).floor() as u32;
+    TileCoord { z: zoom, x, y }
+}
+
+/// Tile bounds in WGS84.
+pub fn tile_bounds(coord: &TileCoord) -> GeoBBox {
+    let n = 2f64.powi(coord.z as i32);
+    let west = coord.x as f64 / n * 360.0 - 180.0;
+    let east = (coord.x + 1) as f64 / n * 360.0 - 180.0;
+    let north = (std::f64::consts::PI * (1.0 - 2.0 * coord.y as f64 / n)).sinh().atan().to_degrees();
+    let south = (std::f64::consts::PI * (1.0 - 2.0 * (coord.y + 1) as f64 / n)).sinh().atan().to_degrees();
+    GeoBBox { south, west, north, east }
+}
+
+/// Get all tile coordinates covering a bounding box at a zoom level.
+pub fn tiles_for_bbox(bbox: &GeoBBox, zoom: u8) -> Vec<TileCoord> {
+    let tl = wgs84_to_tile(bbox.north, bbox.west, zoom);
+    let br = wgs84_to_tile(bbox.south, bbox.east, zoom);
+    let mut tiles = Vec::new();
+    for y in tl.y..=br.y {
+        for x in tl.x..=br.x {
+            tiles.push(TileCoord { z: zoom, x, y });
+        }
+    }
+    tiles
+}
@@ -0,0 +1,72 @@
+//! Multi-source fusion — satellite + terrain + OSM + local sensor data.
+
+use crate::cache::TileCache;
+use crate::types::*;
+use crate::{locate, osm, terrain, tiles};
+use anyhow::Result;
+
+/// Build a complete geo scene for a location.
+pub async fn build_scene(radius_m: f64) -> Result<GeoScene> {
+    let cache = TileCache::default_cache();
+
+    // 1. Locate
+    let cache_path = cache.base_dir.join("location.json");
+    let location = locate::get_location(cache_path.to_str().unwrap_or("")).await?;
+    eprintln!("  Geo: located at {:.4}N, {:.4}W", location.lat, location.lon);
+
+    // 2. Fetch satellite tiles
+    let bbox = GeoBBox::from_center(&location, radius_m);
+    let tile_list = tiles::fetch_area(&tiles::TileProvider::Sentinel2Cloudless, &bbox, 16, &cache).await?;
+    eprintln!("  Geo: fetched {} satellite tiles", tile_list.len());
+
+    // 3. Fetch elevation
+    let dem = terrain::fetch_elevation(&location, &cache).await?;
+    let elevation = terrain::elevation_at(&dem, &location);
+    eprintln!("  Geo: elevation {:.0}m ASL", elevation);
+
+    // 4. Fetch OSM buildings + roads
+    let buildings = osm::fetch_buildings(&location, radius_m).await.unwrap_or_default();
+    let roads = osm::fetch_roads(&location, radius_m).await.unwrap_or_default();
+    eprintln!("  Geo: {} buildings, {} roads", buildings.len(), roads.len());
+
+    // 5. Build registration
+    let mut reg_origin = location.clone();
+    reg_origin.alt = elevation as f64;
+    let registration = crate::register::auto_register(&reg_origin);
+
+    Ok(GeoScene {
+        location: reg_origin,
+        bbox,
+        elevation_m: elevation,
+        buildings,
+        roads,
+        tile_count: tile_list.len(),
+        registration,
+        last_updated: chrono::Utc::now().to_rfc3339(),
+    })
+}
+
+/// Generate a text summary of the geo scene.
+pub fn summarize(scene: &GeoScene) -> String {
+    let building_count = scene.buildings.len();
+    let road_count = scene.roads.len();
+    let road_names: Vec<&str> = scene.roads.iter()
+        .filter_map(|r| match r {
+            OsmFeature::Road { name, .. } => name.as_deref(),
+            _ => None,
+        })
+        .take(3)
+        .collect();
+
+    format!(
+        "Location: {:.4}N, {:.4}W, elevation {:.0}m ASL. \
+         {} buildings within view. {} roads nearby{}. \
+         {} satellite tiles at zoom 16. Updated: {}.",
+        scene.location.lat, scene.location.lon, scene.elevation_m,
+        building_count, road_count,
+        if road_names.is_empty() { String::new() }
+        else { format!(" ({})", road_names.join(", ")) },
+        scene.tile_count,
+        &scene.last_updated[..10],
+    )
+}
@@ -0,0 +1,19 @@
+//! wifi-densepose-geo — geospatial satellite integration for RuView.
+//!
+//! Provides: IP geolocation, satellite tile fetching (Sentinel-2),
+//! SRTM elevation, OSM buildings/roads, coordinate transforms,
+//! temporal change tracking, and brain memory integration.
+
+pub mod types;
+pub mod coord;
+pub mod locate;
+pub mod cache;
+pub mod tiles;
+pub mod terrain;
+pub mod osm;
+pub mod register;
+pub mod fuse;
+pub mod brain;
+pub mod temporal;
+
+pub use types::*;
@@ -0,0 +1,40 @@
+//! IP geolocation — determine location from public IP.
+
+use crate::types::GeoPoint;
+use anyhow::Result;
+
+/// Locate by IP address (free, no API key).
+pub async fn locate_by_ip() -> Result<GeoPoint> {
+    let client = reqwest::Client::builder()
+        .timeout(std::time::Duration::from_secs(5))
+        .build()?;
+
+    // Primary: ip-api.com (free, 45 req/min)
+    let resp: serde_json::Value = client
+        .get("http://ip-api.com/json/?fields=lat,lon,city,regionName,country")
+        .send().await?
+        .json().await?;
+
+    let lat = resp.get("lat").and_then(|v| v.as_f64()).unwrap_or(0.0);
+    let lon = resp.get("lon").and_then(|v| v.as_f64()).unwrap_or(0.0);
+
+    if lat == 0.0 && lon == 0.0 {
+        anyhow::bail!("IP geolocation returned (0,0)");
+    }
+
+    Ok(GeoPoint { lat, lon, alt: 0.0 })
+}
+
+/// Get location with caching.
+pub async fn get_location(cache_path: &str) -> Result<GeoPoint> {
+    // Check cache
+    if let Ok(data) = std::fs::read_to_string(cache_path) {
+        if let Ok(point) = serde_json::from_str::<GeoPoint>(&data) {
+            return Ok(point);
+        }
+    }
+
+    let point = locate_by_ip().await?;
+    let _ = std::fs::write(cache_path, serde_json::to_string(&point)?);
+    Ok(point)
+}
@@ -0,0 +1,216 @@
+//! OpenStreetMap data via Overpass API — buildings, roads, land use.
+
+use crate::types::{GeoBBox, GeoPoint, OsmFeature};
+use anyhow::{anyhow, Result};
+
+const OVERPASS_URL: &str = "https://overpass-api.de/api/interpreter";
+
+/// Maximum radius (in metres) accepted by the OSM fetchers. Requests larger
+/// than this would produce Overpass queries covering hundreds of square
+/// kilometres — which hammers the public endpoint and returns unworkably
+/// large response payloads. Callers wanting wider areas must tile the queries.
+pub const MAX_RADIUS_M: f64 = 5000.0;
+
+fn check_radius(radius_m: f64) -> Result<()> {
+    if !radius_m.is_finite() || radius_m <= 0.0 {
+        return Err(anyhow!("radius_m must be positive and finite (got {radius_m})"));
+    }
+    if radius_m > MAX_RADIUS_M {
+        return Err(anyhow!(
+            "radius_m {radius_m} exceeds MAX_RADIUS_M ({MAX_RADIUS_M}); \
+             tile the query into smaller chunks"
+        ));
+    }
+    Ok(())
+}
+
+/// Fetch buildings within radius of a point.
+///
+/// Uses an inclusive `["building"]` filter that matches all building values
+/// (residential, commercial, yes, etc.) and also queries relations for
+/// multipolygon buildings.  Default recommended radius: 500 m. Max 5000 m.
+pub async fn fetch_buildings(center: &GeoPoint, radius_m: f64) -> Result<Vec<OsmFeature>> {
+    check_radius(radius_m)?;
+    let bbox = GeoBBox::from_center(center, radius_m);
+    let query = format!(
+        r#"[out:json][timeout:25];(way["building"]({},{},{},{});relation["building"]({},{},{},{}););out body;>;out skel qt;"#,
+        bbox.south, bbox.west, bbox.north, bbox.east,
+        bbox.south, bbox.west, bbox.north, bbox.east,
+    );
+    let resp = overpass_query(&query).await?;
+    parse_buildings(&resp)
+}
+
+/// Fetch roads within radius. Max 5000 m; returns an error otherwise.
+pub async fn fetch_roads(center: &GeoPoint, radius_m: f64) -> Result<Vec<OsmFeature>> {
+    check_radius(radius_m)?;
+    let bbox = GeoBBox::from_center(center, radius_m);
+    let query = format!(
+        r#"[out:json][timeout:10];way["highway"]({},{},{},{});out body;>;out skel qt;"#,
+        bbox.south, bbox.west, bbox.north, bbox.east
+    );
+    let resp = overpass_query(&query).await?;
+    parse_roads(&resp)
+}
+
+async fn overpass_query(query: &str) -> Result<serde_json::Value> {
+    let client = reqwest::Client::builder()
+        .timeout(std::time::Duration::from_secs(15))
+        .user_agent("RuView/0.1")
+        .build()?;
+
+    let resp = client.post(OVERPASS_URL)
+        .form(&[("data", query)])
+        .send().await?;
+
+    if !resp.status().is_success() {
+        anyhow::bail!("Overpass API error: {}", resp.status());
+    }
+    Ok(resp.json().await?)
+}
+
+/// Parse an Overpass JSON response into building features.
+///
+/// Returns an error if the response is not a JSON object or is missing the
+/// top-level `elements` array (indicative of a malformed/non-Overpass payload).
+pub fn parse_overpass_json(data: &serde_json::Value) -> Result<Vec<OsmFeature>> {
+    if !data.is_object() || data.get("elements").and_then(|e| e.as_array()).is_none() {
+        return Err(anyhow!("malformed Overpass response: missing `elements` array"));
+    }
+    parse_buildings(data)
+}
+
+pub(crate) fn parse_buildings(data: &serde_json::Value) -> Result<Vec<OsmFeature>> {
+    let mut buildings = Vec::new();
+    let mut nodes: std::collections::HashMap<u64, [f64; 2]> = std::collections::HashMap::new();
+
+    let elements = data.get("elements").and_then(|e| e.as_array()).cloned().unwrap_or_default();
+
+    // First pass: collect nodes
+    for el in &elements {
+        if el.get("type").and_then(|t| t.as_str()) == Some("node") {
+            if let (Some(id), Some(lat), Some(lon)) = (
+                el.get("id").and_then(|v| v.as_u64()),
+                el.get("lat").and_then(|v| v.as_f64()),
+                el.get("lon").and_then(|v| v.as_f64()),
+            ) {
+                nodes.insert(id, [lat, lon]);
+            }
+        }
+    }
+
+    // Second pass: build ways
+    for el in &elements {
+        if el.get("type").and_then(|t| t.as_str()) != Some("way") { continue; }
+        let tags = el.get("tags").cloned().unwrap_or(serde_json::json!({}));
+        if tags.get("building").is_none() { continue; }
+
+        let node_ids = el.get("nodes").and_then(|n| n.as_array()).cloned().unwrap_or_default();
+        let outline: Vec<[f64; 2]> = node_ids.iter()
+            .filter_map(|id| id.as_u64().and_then(|id| nodes.get(&id).copied()))
+            .collect();
+
+        if outline.len() < 3 { continue; }
+
+        let height = tags.get("height").and_then(|h| h.as_str())
+            .and_then(|s| s.trim_end_matches('m').trim().parse::<f32>().ok())
+            .or(Some(8.0)); // default building height
+
+        let name = tags.get("name").and_then(|n| n.as_str()).map(|s| s.to_string());
+
+        buildings.push(OsmFeature::Building { outline, height, name });
+    }
+
+    Ok(buildings)
+}
+
+fn parse_roads(data: &serde_json::Value) -> Result<Vec<OsmFeature>> {
+    let mut roads = Vec::new();
+    let mut nodes: std::collections::HashMap<u64, [f64; 2]> = std::collections::HashMap::new();
+
+    let elements = data.get("elements").and_then(|e| e.as_array()).cloned().unwrap_or_default();
+
+    for el in &elements {
+        if el.get("type").and_then(|t| t.as_str()) == Some("node") {
+            if let (Some(id), Some(lat), Some(lon)) = (
+                el.get("id").and_then(|v| v.as_u64()),
+                el.get("lat").and_then(|v| v.as_f64()),
+                el.get("lon").and_then(|v| v.as_f64()),
+            ) {
+                nodes.insert(id, [lat, lon]);
+            }
+        }
+    }
+
+    for el in &elements {
+        if el.get("type").and_then(|t| t.as_str()) != Some("way") { continue; }
+        let tags = el.get("tags").cloned().unwrap_or(serde_json::json!({}));
+        let highway = tags.get("highway").and_then(|h| h.as_str());
+        if highway.is_none() { continue; }
+
+        let node_ids = el.get("nodes").and_then(|n| n.as_array()).cloned().unwrap_or_default();
+        let path: Vec<[f64; 2]> = node_ids.iter()
+            .filter_map(|id| id.as_u64().and_then(|id| nodes.get(&id).copied()))
+            .collect();
+
+        if path.len() < 2 { continue; }
+
+        let name = tags.get("name").and_then(|n| n.as_str()).map(|s| s.to_string());
+
+        roads.push(OsmFeature::Road {
+            path,
+            road_type: highway.unwrap_or("unknown").to_string(),
+            name,
+        });
+    }
+
+    Ok(roads)
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn parse_overpass_json_accepts_minimal_fixture() {
+        // Minimal fixture: three nodes forming a triangular building.
+        let j = serde_json::json!({
+            "elements": [
+                { "type": "node", "id": 1, "lat": 43.0, "lon": -79.0 },
+                { "type": "node", "id": 2, "lat": 43.0001, "lon": -79.0 },
+                { "type": "node", "id": 3, "lat": 43.0, "lon": -79.0001 },
+                {
+                    "type": "way", "id": 100,
+                    "nodes": [1, 2, 3, 1],
+                    "tags": { "building": "yes", "name": "Test Hall" }
+                }
+            ]
+        });
+        let features = parse_overpass_json(&j).expect("minimal payload should parse");
+        assert_eq!(features.len(), 1);
+        match &features[0] {
+            OsmFeature::Building { outline, name, .. } => {
+                assert_eq!(outline.len(), 4);
+                assert_eq!(name.as_deref(), Some("Test Hall"));
+            }
+            _ => panic!("expected a Building"),
+        }
+    }
+
+    #[test]
+    fn parse_overpass_json_rejects_malformed() {
+        // Missing the `elements` array entirely.
+        let j = serde_json::json!({ "version": 0.6 });
+        assert!(parse_overpass_json(&j).is_err());
+        // Not even an object.
+        let arr = serde_json::json!([1, 2, 3]);
+        assert!(parse_overpass_json(&arr).is_err());
+    }
+
+    #[tokio::test]
+    async fn fetch_buildings_rejects_oversized_radius() {
+        let center = GeoPoint { lat: 43.0, lon: -79.0, alt: 0.0 };
+        let err = fetch_buildings(&center, MAX_RADIUS_M + 1.0).await.err();
+        assert!(err.is_some(), "should reject radius > MAX_RADIUS_M");
+    }
+}
@@ -0,0 +1,41 @@
+//! Geo-registration — maps local sensor coordinates to WGS84.
+
+use crate::coord;
+use crate::types::{GeoPoint, GeoRegistration};
+
+/// Auto-register using IP location (sensor at IP location, facing north).
+pub fn auto_register(ip_location: &GeoPoint) -> GeoRegistration {
+    GeoRegistration {
+        origin: ip_location.clone(),
+        heading_deg: 0.0,
+        scale: 1.0,
+    }
+}
+
+/// Transform local point [x, y, z] to WGS84.
+pub fn local_to_wgs84(reg: &GeoRegistration, local: &[f32; 3]) -> GeoPoint {
+    let heading_rad = reg.heading_deg.to_radians();
+    let cos_h = heading_rad.cos();
+    let sin_h = heading_rad.sin();
+
+    // Rotate local by heading (local X → East when heading=0)
+    let east = (local[0] as f64 * cos_h - local[2] as f64 * sin_h) * reg.scale;
+    let north = (local[0] as f64 * sin_h + local[2] as f64 * cos_h) * reg.scale;
+    let up = local[1] as f64 * reg.scale;
+
+    coord::enu_to_wgs84(&[east, north, up], &reg.origin)
+}
+
+/// Transform WGS84 to local point.
+pub fn wgs84_to_local(reg: &GeoRegistration, geo: &GeoPoint) -> [f32; 3] {
+    let enu = coord::wgs84_to_enu(geo, &reg.origin);
+    let heading_rad = (-reg.heading_deg).to_radians();
+    let cos_h = heading_rad.cos();
+    let sin_h = heading_rad.sin();
+
+    let x = ((enu[0] * cos_h - enu[1] * sin_h) / reg.scale) as f32;
+    let z = ((enu[0] * sin_h + enu[1] * cos_h) / reg.scale) as f32;
+    let y = (enu[2] / reg.scale) as f32;
+
+    [x, y, z]
+}
@@ -0,0 +1,312 @@
+//! Temporal change tracking — detect changes in satellite/OSM/weather over time.
+
+use crate::cache::TileCache;
+use crate::types::GeoPoint;
+#[allow(unused_imports)]
+use crate::types::GeoScene;
+use anyhow::Result;
+
+/// Fetch current weather (Open Meteo, free, no key).
+pub async fn fetch_weather(point: &GeoPoint) -> Result<WeatherData> {
+    let url = format!(
+        "https://api.open-meteo.com/v1/forecast?latitude={:.4}&longitude={:.4}&current=temperature_2m,relative_humidity_2m,wind_speed_10m,weather_code",
+        point.lat, point.lon
+    );
+
+    let client = reqwest::Client::builder()
+        .timeout(std::time::Duration::from_secs(10))
+        .build()?;
+
+    let resp: serde_json::Value = client.get(&url).send().await?.json().await?;
+    let current = resp.get("current").cloned().unwrap_or(serde_json::json!({}));
+
+    Ok(WeatherData {
+        temperature_c: current.get("temperature_2m").and_then(|v| v.as_f64()).unwrap_or(0.0) as f32,
+        humidity_pct: current.get("relative_humidity_2m").and_then(|v| v.as_f64()).unwrap_or(0.0) as f32,
+        wind_speed_ms: current.get("wind_speed_10m").and_then(|v| v.as_f64()).unwrap_or(0.0) as f32,
+        weather_code: current.get("weather_code").and_then(|v| v.as_u64()).unwrap_or(0) as u16,
+    })
+}
+
+/// Check for OSM changes since last fetch.
+pub async fn check_osm_changes(scene: &GeoScene, cache: &TileCache) -> Result<Vec<String>> {
+    let mut changes = Vec::new();
+
+    let cache_key = "osm_building_count";
+    let prev_count: usize = cache.get(cache_key)
+        .and_then(|d| String::from_utf8(d).ok())
+        .and_then(|s| s.trim().parse().ok())
+        .unwrap_or(0);
+
+    let current_count = scene.buildings.len();
+    if prev_count > 0 && current_count != prev_count {
+        let diff = current_count as i64 - prev_count as i64;
+        changes.push(format!("Building count changed: {} → {} ({:+})", prev_count, current_count, diff));
+    }
+
+    cache.put(cache_key, current_count.to_string().as_bytes())?;
+    Ok(changes)
+}
+
+/// Generate temporal summary for brain storage.
+pub fn temporal_summary(weather: &WeatherData, changes: &[String]) -> String {
+    let weather_desc = match weather.weather_code {
+        0 => "clear sky",
+        1..=3 => "partly cloudy",
+        45 | 48 => "foggy",
+        51..=57 => "drizzle",
+        61..=67 => "rain",
+        71..=77 => "snow",
+        80..=82 => "showers",
+        95..=99 => "thunderstorm",
+        _ => "unknown",
+    };
+
+    let mut summary = format!(
+        "Weather: {:.0}°C, {weather_desc}, humidity {:.0}%, wind {:.1}m/s.",
+        weather.temperature_c, weather.humidity_pct, weather.wind_speed_ms,
+    );
+
+    for change in changes {
+        summary.push_str(&format!(" Change: {change}."));
+    }
+
+    summary
+}
+
+#[derive(Clone, Debug, serde::Serialize, serde::Deserialize)]
+pub struct WeatherData {
+    pub temperature_c: f32,
+    pub humidity_pct: f32,
+    pub wind_speed_ms: f32,
+    pub weather_code: u16,
+}
+
+// ---------------------------------------------------------------------------
+// Satellite tile change detection
+// ---------------------------------------------------------------------------
+
+/// Result of comparing two tile snapshots.
+#[derive(Clone, Debug, serde::Serialize, serde::Deserialize)]
+pub struct TileChangeResult {
+    /// 0.0 = identical, 1.0 = completely different.
+    pub diff_score: f64,
+    /// Number of pixels that changed.
+    pub changed_pixels: usize,
+    /// Total pixels compared.
+    pub total_pixels: usize,
+}
+
+/// Compare a newly-fetched tile against its previously-cached version.
+///
+/// Returns a `TileChangeResult` with a diff score between 0.0 (identical) and
+/// 1.0 (completely different).  When the diff exceeds 0.1 the function stores
+/// a change event as a brain memory via the local ruOS brain endpoint.
+pub async fn detect_tile_changes(
+    cache_key: &str,
+    new_data: &[u8],
+    cache: &TileCache,
+) -> Result<TileChangeResult> {
+    let previous = cache.get(cache_key);
+
+    let result = match previous {
+        Some(ref old_data) => {
+            let total = old_data.len().max(new_data.len()).max(1);
+            let comparable = old_data.len().min(new_data.len());
+            let mut changed: usize = 0;
+            for i in 0..comparable {
+                if old_data[i] != new_data[i] {
+                    changed += 1;
+                }
+            }
+            // Any extra bytes in the longer slice count as changed.
+            changed += total - comparable;
+
+            TileChangeResult {
+                diff_score: changed as f64 / total as f64,
+                changed_pixels: changed,
+                total_pixels: total,
+            }
+        }
+        None => {
+            // No previous data — treat as fully new (score 1.0).
+            TileChangeResult {
+                diff_score: 1.0,
+                changed_pixels: new_data.len(),
+                total_pixels: new_data.len().max(1),
+            }
+        }
+    };
+
+    // Persist new snapshot into cache for future comparisons.
+    cache.put(cache_key, new_data)?;
+
+    // When significant change is detected, store a brain memory.
+    if result.diff_score > 0.1 {
+        let _ = store_change_event(cache_key, &result).await;
+    }
+
+    Ok(result)
+}
+
+/// Post a change event to the local ruOS brain.
+///
+/// Brain URL honours `RUVIEW_BRAIN_URL` via [`crate::brain::brain_url`].
+async fn store_change_event(cache_key: &str, result: &TileChangeResult) -> Result<()> {
+    let client = reqwest::Client::builder()
+        .timeout(std::time::Duration::from_secs(5))
+        .build()?;
+
+    let body = serde_json::json!({
+        "category": "spatial-change",
+        "content": format!(
+            "Tile change detected for {cache_key}: diff={:.3}, changed={}/{}",
+            result.diff_score, result.changed_pixels, result.total_pixels,
+        ),
+    });
+
+    client
+        .post(format!("{}/memories", crate::brain::brain_url()))
+        .json(&body)
+        .send()
+        .await?;
+
+    Ok(())
+}
+
+// ---------------------------------------------------------------------------
+// Night mode detection
+// ---------------------------------------------------------------------------
+
+/// Approximate check whether the current time is "night" at a given latitude.
+///
+/// Uses a simplified sunrise/sunset model based on the solar declination and
+/// hour angle.  When it is night the system should rely on CSI data only
+/// (satellite imagery is not useful in darkness).
+pub fn is_night(lat_deg: f64) -> bool {
+    let now = chrono::Utc::now();
+    is_night_at(lat_deg, now)
+}
+
+/// Testable version of [`is_night`] that accepts an explicit timestamp.
+pub fn is_night_at(lat_deg: f64, utc: chrono::DateTime<chrono::Utc>) -> bool {
+    use chrono::Datelike;
+    use std::f64::consts::PI;
+
+    let day_of_year = utc.ordinal() as f64;
+    let hour_utc = utc.timestamp() % 86400;
+    let solar_hour = (hour_utc as f64) / 3600.0; // 0..24
+
+    // Solar declination (Spencer, 1971 — simplified)
+    let gamma = 2.0 * PI * (day_of_year - 1.0) / 365.0;
+    let decl = 0.006918
+        - 0.399912 * gamma.cos()
+        + 0.070257 * gamma.sin()
+        - 0.006758 * (2.0 * gamma).cos()
+        + 0.000907 * (2.0 * gamma).sin();
+
+    let lat_rad = lat_deg.to_radians();
+
+    // Cosine of the hour angle at sunrise/sunset (geometric, no refraction)
+    let cos_ha = -(lat_rad.tan() * decl.tan());
+
+    // Polar day / polar night
+    if cos_ha < -1.0 {
+        return false; // midnight sun — never night
+    }
+    if cos_ha > 1.0 {
+        return true; // polar night — always night
+    }
+
+    let ha_sunrise = cos_ha.acos(); // radians, symmetric about solar noon
+    let daylight_hours = 2.0 * ha_sunrise * 12.0 / PI;
+    let solar_noon = 12.0; // approximation (ignores longitude offset)
+    let sunrise = solar_noon - daylight_hours / 2.0;
+    let sunset = solar_noon + daylight_hours / 2.0;
+
+    solar_hour < sunrise || solar_hour > sunset
+}
+
+// ---------------------------------------------------------------------------
+// Tests
+// ---------------------------------------------------------------------------
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn test_is_night_at_equator_noon() {
+        // Noon UTC at equator on March 20 — should be daytime.
+        let dt = chrono::NaiveDate::from_ymd_opt(2025, 3, 20)
+            .unwrap()
+            .and_hms_opt(12, 0, 0)
+            .unwrap()
+            .and_utc();
+        assert!(!is_night_at(0.0, dt));
+    }
+
+    #[test]
+    fn test_is_night_at_equator_midnight() {
+        // Midnight UTC at equator — should be night.
+        let dt = chrono::NaiveDate::from_ymd_opt(2025, 3, 20)
+            .unwrap()
+            .and_hms_opt(2, 0, 0)
+            .unwrap()
+            .and_utc();
+        assert!(is_night_at(0.0, dt));
+    }
+
+    #[test]
+    fn test_midnight_sun_arctic() {
+        // Late June at 70 N — midnight sun, never night.
+        let dt = chrono::NaiveDate::from_ymd_opt(2025, 6, 21)
+            .unwrap()
+            .and_hms_opt(0, 0, 0)
+            .unwrap()
+            .and_utc();
+        assert!(!is_night_at(70.0, dt));
+    }
+
+    #[test]
+    fn test_polar_night_arctic() {
+        // Late December at 80 N — polar night, always night.
+        let dt = chrono::NaiveDate::from_ymd_opt(2025, 12, 21)
+            .unwrap()
+            .and_hms_opt(12, 0, 0)
+            .unwrap()
+            .and_utc();
+        assert!(is_night_at(80.0, dt));
+    }
+
+    #[test]
+    fn test_detect_tile_changes_identical() {
+        let cache = TileCache::new("/tmp/ruview-test-tile-changes");
+        let data = vec![1u8, 2, 3, 4, 5];
+        // Prime the cache.
+        cache.put("test_tile_ident", &data).unwrap();
+
+        let rt = tokio::runtime::Builder::new_current_thread()
+            .enable_all()
+            .build()
+            .unwrap();
+        let result = rt.block_on(detect_tile_changes("test_tile_ident", &data, &cache)).unwrap();
+        assert!((result.diff_score - 0.0).abs() < 1e-9);
+        assert_eq!(result.changed_pixels, 0);
+    }
+
+    #[test]
+    fn test_detect_tile_changes_fully_different() {
+        let cache = TileCache::new("/tmp/ruview-test-tile-changes");
+        let old = vec![0u8; 100];
+        let new = vec![255u8; 100];
+        cache.put("test_tile_diff", &old).unwrap();
+
+        let rt = tokio::runtime::Builder::new_current_thread()
+            .enable_all()
+            .build()
+            .unwrap();
+        let result = rt.block_on(detect_tile_changes("test_tile_diff", &new, &cache)).unwrap();
+        assert!((result.diff_score - 1.0).abs() < 1e-9);
+    }
+}
@@ -0,0 +1,110 @@
+//! SRTM DEM parser — elevation data from NASA 1-arcsecond HGT files.
+
+use crate::cache::TileCache;
+use crate::types::{ElevationGrid, GeoPoint};
+use anyhow::Result;
+
+/// Download and parse SRTM HGT for a location.
+pub async fn fetch_elevation(point: &GeoPoint, cache: &TileCache) -> Result<ElevationGrid> {
+    let lat_int = point.lat.floor() as i32;
+    let lon_int = point.lon.floor() as i32;
+    let ns = if lat_int >= 0 { 'N' } else { 'S' };
+    let ew = if lon_int >= 0 { 'E' } else { 'W' };
+    let filename = format!("{}{:02}{}{:03}.hgt", ns, lat_int.unsigned_abs(), ew, lon_int.unsigned_abs());
+    let cache_key = format!("srtm_{filename}");
+
+    if let Some(data) = cache.get(&cache_key) {
+        return parse_hgt(&data, lat_int as f64, lon_int as f64);
+    }
+
+    let client = reqwest::Client::builder()
+        .timeout(std::time::Duration::from_secs(30))
+        .build()?;
+
+    // Primary: NASA SRTM public mirror (no auth required for .hgt)
+    let nasa_url = format!(
+        "https://e4ftl01.cr.usgs.gov/MEASURES/SRTMGL1.003/2000.02.11/{filename}"
+    );
+
+    if let Ok(resp) = client.get(&nasa_url).send().await {
+        if resp.status().is_success() {
+            let data = resp.bytes().await?.to_vec();
+            cache.put(&cache_key, &data)?;
+            return parse_hgt(&data, lat_int as f64, lon_int as f64);
+        }
+    }
+
+    // Fallback: viewfinderpanoramas.org
+    // Files are grouped by continent zip, but individual .hgt files can be
+    // fetched directly when the server exposes them.
+    let vfp_url = format!(
+        "http://viewfinderpanoramas.org/dem1/{filename}"
+    );
+
+    if let Ok(resp) = client.get(&vfp_url).send().await {
+        if resp.status().is_success() {
+            let data = resp.bytes().await?.to_vec();
+            cache.put(&cache_key, &data)?;
+            return parse_hgt(&data, lat_int as f64, lon_int as f64);
+        }
+    }
+
+    // Final fallback: flat terrain when all downloads fail
+    Ok(ElevationGrid {
+        origin_lat: lat_int as f64,
+        origin_lon: lon_int as f64,
+        cell_size_deg: 1.0 / 3600.0,
+        cols: 100, rows: 100,
+        heights: vec![0.0; 10000],
+    })
+}
+
+/// Parse SRTM HGT binary (3601x3601 big-endian i16).
+pub fn parse_hgt(data: &[u8], origin_lat: f64, origin_lon: f64) -> Result<ElevationGrid> {
+    let n_samples = data.len() / 2;
+    let side = (n_samples as f64).sqrt() as usize;
+
+    let heights: Vec<f32> = data.chunks_exact(2)
+        .map(|c| {
+            let v = i16::from_be_bytes([c[0], c[1]]);
+            if v == -32768 { 0.0 } else { v as f32 } // -32768 = void
+        })
+        .collect();
+
+    Ok(ElevationGrid {
+        origin_lat, origin_lon,
+        cell_size_deg: 1.0 / (side - 1) as f64,
+        cols: side, rows: side,
+        heights,
+    })
+}
+
+/// Get elevation at a specific point from a grid.
+pub fn elevation_at(grid: &ElevationGrid, point: &GeoPoint) -> f32 {
+    grid.get(point.lat, point.lon).unwrap_or(0.0)
+}
+
+/// Extract a small subgrid around a point.
+pub fn extract_subgrid(grid: &ElevationGrid, center: &GeoPoint, radius_m: f64) -> ElevationGrid {
+    let radius_deg = radius_m / 111_320.0;
+    let min_row = ((grid.origin_lat + (grid.rows as f64 * grid.cell_size_deg) - center.lat - radius_deg) / grid.cell_size_deg).max(0.0) as usize;
+    let max_row = ((grid.origin_lat + (grid.rows as f64 * grid.cell_size_deg) - center.lat + radius_deg) / grid.cell_size_deg).min(grid.rows as f64) as usize;
+    let min_col = ((center.lon - radius_deg - grid.origin_lon) / grid.cell_size_deg).max(0.0) as usize;
+    let max_col = ((center.lon + radius_deg - grid.origin_lon) / grid.cell_size_deg).min(grid.cols as f64) as usize;
+
+    let rows = max_row.saturating_sub(min_row);
+    let cols = max_col.saturating_sub(min_col);
+    let mut heights = Vec::with_capacity(rows * cols);
+    for r in min_row..max_row {
+        for c in min_col..max_col {
+            heights.push(grid.heights.get(r * grid.cols + c).copied().unwrap_or(0.0));
+        }
+    }
+
+    ElevationGrid {
+        origin_lat: grid.origin_lat + (grid.rows - max_row) as f64 * grid.cell_size_deg,
+        origin_lon: grid.origin_lon + min_col as f64 * grid.cell_size_deg,
+        cell_size_deg: grid.cell_size_deg,
+        cols, rows, heights,
+    }
+}
@@ -0,0 +1,80 @@
+//! Satellite tile fetcher — XYZ/TMS tile download with caching.
+
+use crate::cache::TileCache;
+use crate::coord;
+use crate::types::{GeoBBox, RasterTile, TileCoord};
+use anyhow::Result;
+
+/// Tile provider (all free, no API keys).
+pub enum TileProvider {
+    /// Sentinel-2 cloudless mosaic (EOX, 10m, CC-BY-4.0)
+    Sentinel2Cloudless,
+    /// ESRI World Imagery (sub-meter, free tier)
+    EsriWorldImagery,
+    /// OpenStreetMap (map tiles, not satellite)
+    Osm,
+}
+
+impl TileProvider {
+    pub fn url(&self, coord: &TileCoord) -> String {
+        match self {
+            Self::Sentinel2Cloudless => format!(
+                "https://tiles.maps.eox.at/wmts/1.0.0/s2cloudless-2021_3857/default/g/{}/{}/{}.jpg",
+                coord.z, coord.y, coord.x
+            ),
+            Self::EsriWorldImagery => format!(
+                "https://server.arcgisonline.com/ArcGIS/rest/services/World_Imagery/MapServer/tile/{}/{}/{}",
+                coord.z, coord.y, coord.x
+            ),
+            Self::Osm => format!(
+                "https://tile.openstreetmap.org/{}/{}/{}.png",
+                coord.z, coord.x, coord.y
+            ),
+        }
+    }
+
+    pub fn name(&self) -> &str {
+        match self {
+            Self::Sentinel2Cloudless => "sentinel2",
+            Self::EsriWorldImagery => "esri",
+            Self::Osm => "osm",
+        }
+    }
+}
+
+/// Fetch a single tile with caching.
+pub async fn fetch_tile(provider: &TileProvider, coord: &TileCoord, cache: &TileCache) -> Result<RasterTile> {
+    let cache_key = format!("tiles_{}_{}_{}.dat", coord.z, coord.x, coord.y);
+
+    if let Some(data) = cache.get(&cache_key) {
+        return Ok(RasterTile { coord: coord.clone(), data, bounds: coord::tile_bounds(coord) });
+    }
+
+    let url = provider.url(coord);
+    let client = reqwest::Client::builder()
+        .timeout(std::time::Duration::from_secs(10))
+        .user_agent("RuView/0.1 (https://github.com/ruvnet/RuView)")
+        .build()?;
+
+    let resp = client.get(&url).send().await?;
+    if !resp.status().is_success() {
+        anyhow::bail!("Tile fetch failed: {} → {}", url, resp.status());
+    }
+    let data = resp.bytes().await?.to_vec();
+    cache.put(&cache_key, &data)?;
+
+    Ok(RasterTile { coord: coord.clone(), data, bounds: coord::tile_bounds(coord) })
+}
+
+/// Fetch all tiles covering a bounding box.
+pub async fn fetch_area(provider: &TileProvider, bbox: &GeoBBox, zoom: u8, cache: &TileCache) -> Result<Vec<RasterTile>> {
+    let coords = coord::tiles_for_bbox(bbox, zoom);
+    let mut tiles = Vec::with_capacity(coords.len());
+    for c in &coords {
+        match fetch_tile(provider, c, cache).await {
+            Ok(t) => tiles.push(t),
+            Err(e) => eprintln!("  Tile {}/{}/{} failed: {}", c.z, c.x, c.y, e),
+        }
+    }
+    Ok(tiles)
+}
@@ -0,0 +1,118 @@
+//! Core geospatial types.
+
+use serde::{Deserialize, Serialize};
+
+/// WGS84 geographic coordinate.
+#[derive(Clone, Debug, Serialize, Deserialize)]
+pub struct GeoPoint {
+    pub lat: f64,
+    pub lon: f64,
+    pub alt: f64,
+}
+
+/// Axis-aligned bounding box in WGS84.
+#[derive(Clone, Debug, Serialize, Deserialize)]
+pub struct GeoBBox {
+    pub south: f64,
+    pub west: f64,
+    pub north: f64,
+    pub east: f64,
+}
+
+impl GeoBBox {
+    pub fn from_center(center: &GeoPoint, radius_m: f64) -> Self {
+        let dlat = radius_m / 111_320.0;
+        let dlon = radius_m / (111_320.0 * center.lat.to_radians().cos());
+        Self {
+            south: center.lat - dlat,
+            west: center.lon - dlon,
+            north: center.lat + dlat,
+            east: center.lon + dlon,
+        }
+    }
+}
+
+/// XYZ tile address.
+#[derive(Clone, Debug, Serialize, Deserialize)]
+pub struct TileCoord {
+    pub z: u8,
+    pub x: u32,
+    pub y: u32,
+}
+
+/// Satellite raster tile.
+#[derive(Clone, Debug)]
+pub struct RasterTile {
+    pub coord: TileCoord,
+    pub data: Vec<u8>,
+    pub bounds: GeoBBox,
+}
+
+/// Elevation grid from SRTM DEM.
+#[derive(Clone, Debug, Serialize, Deserialize)]
+pub struct ElevationGrid {
+    pub origin_lat: f64,
+    pub origin_lon: f64,
+    pub cell_size_deg: f64,
+    pub cols: usize,
+    pub rows: usize,
+    pub heights: Vec<f32>,
+}
+
+impl ElevationGrid {
+    pub fn get(&self, lat: f64, lon: f64) -> Option<f32> {
+        let row = ((self.origin_lat + (self.rows as f64 * self.cell_size_deg) - lat) / self.cell_size_deg) as usize;
+        let col = ((lon - self.origin_lon) / self.cell_size_deg) as usize;
+        if row < self.rows && col < self.cols {
+            Some(self.heights[row * self.cols + col])
+        } else {
+            None
+        }
+    }
+}
+
+/// OpenStreetMap feature.
+#[derive(Clone, Debug, Serialize, Deserialize)]
+pub enum OsmFeature {
+    Building {
+        outline: Vec<[f64; 2]>,
+        height: Option<f32>,
+        name: Option<String>,
+    },
+    Road {
+        path: Vec<[f64; 2]>,
+        road_type: String,
+        name: Option<String>,
+    },
+}
+
+/// Geo-registration transform.
+#[derive(Clone, Debug, Serialize, Deserialize)]
+pub struct GeoRegistration {
+    pub origin: GeoPoint,
+    pub heading_deg: f64,
+    pub scale: f64,
+}
+
+impl Default for GeoRegistration {
+    fn default() -> Self {
+        Self {
+            origin: GeoPoint { lat: 0.0, lon: 0.0, alt: 0.0 },
+            heading_deg: 0.0,
+            scale: 1.0,
+        }
+    }
+}
+
+/// Complete geo scene.
+#[derive(Clone, Debug, Serialize, Deserialize)]
+pub struct GeoScene {
+    pub location: GeoPoint,
+    pub bbox: GeoBBox,
+    pub elevation_m: f32,
+    pub buildings: Vec<OsmFeature>,
+    pub roads: Vec<OsmFeature>,
+    pub tile_count: usize,
+    pub registration: GeoRegistration,
+    pub last_updated: String,
+}
@@ -0,0 +1,84 @@
+use wifi_densepose_geo::*;
+use wifi_densepose_geo::coord;
+
+#[test]
+fn test_haversine() {
+    let toronto = GeoPoint { lat: 43.6532, lon: -79.3832, alt: 0.0 };
+    let ottawa = GeoPoint { lat: 45.4215, lon: -75.6972, alt: 0.0 };
+    let dist = coord::haversine(&toronto, &ottawa);
+    assert!((dist - 353_000.0).abs() < 5_000.0, "Toronto-Ottawa ~353km, got {:.0}m", dist);
+}
+
+#[test]
+fn test_wgs84_to_enu() {
+    let origin = GeoPoint { lat: 43.0, lon: -79.0, alt: 100.0 };
+    let point = GeoPoint { lat: 43.001, lon: -79.0, alt: 100.0 };
+    let enu = coord::wgs84_to_enu(&point, &origin);
+    assert!((enu[1] - 111.0).abs() < 5.0, "0.001 deg lat ~111m north, got {:.1}m", enu[1]);
+    assert!(enu[0].abs() < 1.0, "same longitude should have ~0 east, got {:.1}m", enu[0]);
+}
+
+#[test]
+fn test_enu_roundtrip() {
+    let origin = GeoPoint { lat: 43.6532, lon: -79.3832, alt: 76.0 };
+    let local = [100.0, 200.0, 5.0]; // 100m east, 200m north, 5m up
+    let geo = coord::enu_to_wgs84(&local, &origin);
+    let back = coord::wgs84_to_enu(&geo, &origin);
+    assert!((back[0] - local[0]).abs() < 0.01);
+    assert!((back[1] - local[1]).abs() < 0.01);
+    assert!((back[2] - local[2]).abs() < 0.01);
+}
+
+#[test]
+fn test_tile_coords() {
+    let tile = coord::wgs84_to_tile(43.6532, -79.3832, 16);
+    assert!(tile.x > 0 && tile.y > 0);
+    assert_eq!(tile.z, 16);
+    let bounds = coord::tile_bounds(&tile);
+    assert!(bounds.south < 43.66 && bounds.north > 43.64);
+}
+
+#[test]
+fn test_tiles_for_bbox() {
+    let bbox = GeoBBox::from_center(
+        &GeoPoint { lat: 43.6532, lon: -79.3832, alt: 0.0 },
+        500.0,
+    );
+    let tiles = coord::tiles_for_bbox(&bbox, 16);
+    assert!(tiles.len() >= 4 && tiles.len() <= 25, "500m radius should need 4-25 tiles, got {}", tiles.len());
+}
+
+#[test]
+fn test_geo_bbox_from_center() {
+    let center = GeoPoint { lat: 43.0, lon: -79.0, alt: 0.0 };
+    let bbox = GeoBBox::from_center(&center, 1000.0);
+    assert!(bbox.south < 43.0 && bbox.north > 43.0);
+    assert!(bbox.west < -79.0 && bbox.east > -79.0);
+}
+
+#[test]
+fn test_hgt_parse() {
+    // Create minimal 3x3 HGT data (big-endian i16)
+    let mut data = Vec::new();
+    for h in [100i16, 110, 120, 105, 115, 125, 110, 120, 130] {
+        data.extend_from_slice(&h.to_be_bytes());
+    }
+    let grid = wifi_densepose_geo::terrain::parse_hgt(&data, 43.0, -79.0).unwrap();
+    assert_eq!(grid.heights[0], 100.0);
+    assert_eq!(grid.heights[4], 115.0);
+}
+
+#[test]
+fn test_registration() {
+    let origin = GeoPoint { lat: 43.6532, lon: -79.3832, alt: 76.0 };
+    let reg = wifi_densepose_geo::register::auto_register(&origin);
+    
+    let local = [10.0f32, 0.0, 20.0]; // 10m east, 20m forward
+    let geo = wifi_densepose_geo::register::local_to_wgs84(&reg, &local);
+    assert!((geo.lat - origin.lat).abs() < 0.001);
+    assert!((geo.lon - origin.lon).abs() < 0.001);
+    
+    let back = wifi_densepose_geo::register::wgs84_to_local(&reg, &geo);
+    assert!((back[0] - local[0]).abs() < 0.1);
+    assert!((back[2] - local[2]).abs() < 0.1);
+}
@@ -41,7 +41,20 @@ pub mod aggregator;
 mod bridge;
 pub mod esp32;

+// ADR-081: Rust mirror of the firmware radio abstraction layer (L1) and
+// mesh sensing plane (L3). Lets host tests, simulators, and future
+// coordinator-node Rust code drive the controller stack without
+// touching any downstream signal/ruvector/train/mat crate.
+pub mod radio_ops;
+
 pub use csi_frame::{CsiFrame, CsiMetadata, SubcarrierData, Bandwidth, AntennaConfig};
 pub use error::ParseError;
 pub use esp32_parser::Esp32CsiParser;
 pub use bridge::CsiData;
+pub use radio_ops::{
+    RadioOps, RadioMode, CaptureProfile, RadioHealth, RadioError, MockRadio,
+    MeshRole, MeshMsgType, AuthClass, MeshHeader, NodeStatus, AnomalyAlert,
+    MeshError, MESH_MAGIC, MESH_VERSION, MESH_HEADER_SIZE, MESH_MAX_PAYLOAD,
+    crc32_ieee, decode_mesh, decode_node_status, decode_anomaly_alert,
+    encode_health,
+};
@@ -0,0 +1,535 @@
+//! ADR-081 Layer 1 Rust mirror + Layer 3 mesh-plane decoder.
+//!
+//! Mirrors the C vtable `rv_radio_ops_t` defined in
+//! `firmware/esp32-csi-node/main/rv_radio_ops.h` so that test harnesses,
+//! simulators, and future coordinator-node Rust code can drive the
+//! controller logic against a mock backend without touching
+//! `wifi-densepose-signal`, `-ruvector`, `-train`, or `-mat`. That
+//! portability is the ADR-081 acceptance test: "swap one radio family
+//! for another without changing the Rust memory and reasoning layers".
+//!
+//! The mesh-plane types (`MeshHeader`, `NodeStatus`, `AnomalyAlert`,
+//! etc.) mirror `rv_mesh.h` and deserialize the wire format produced by
+//! `rv_mesh_encode*()`. This lets a Rust-side aggregator or test node
+//! decode live traffic from the ESP32 nodes without re-implementing
+//! the framing.
+
+use std::convert::TryFrom;
+
+// ---------------------------------------------------------------------------
+// Layer 1 — Radio Abstraction Layer (mirror of rv_radio_ops_t)
+// ---------------------------------------------------------------------------
+
+/// Operating modes, mirror of `rv_radio_mode_t`.
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+#[repr(u8)]
+pub enum RadioMode {
+    Disabled     = 0,
+    PassiveRx    = 1,
+    ActiveProbe  = 2,
+    Calibration  = 3,
+}
+
+/// Named capture profiles, mirror of `rv_capture_profile_t`.
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+#[repr(u8)]
+pub enum CaptureProfile {
+    PassiveLowRate = 0,
+    ActiveProbe    = 1,
+    RespHighSens   = 2,
+    FastMotion     = 3,
+    Calibration    = 4,
+}
+
+impl TryFrom<u8> for CaptureProfile {
+    type Error = RadioError;
+    fn try_from(v: u8) -> Result<Self, Self::Error> {
+        match v {
+            0 => Ok(CaptureProfile::PassiveLowRate),
+            1 => Ok(CaptureProfile::ActiveProbe),
+            2 => Ok(CaptureProfile::RespHighSens),
+            3 => Ok(CaptureProfile::FastMotion),
+            4 => Ok(CaptureProfile::Calibration),
+            _ => Err(RadioError::UnknownProfile(v)),
+        }
+    }
+}
+
+/// Health snapshot, mirror of `rv_radio_health_t`.
+#[derive(Debug, Clone, Copy, Default, PartialEq)]
+pub struct RadioHealth {
+    pub pkt_yield_per_sec: u16,
+    pub send_fail_count:   u16,
+    pub rssi_median_dbm:   i8,
+    pub noise_floor_dbm:   i8,
+    pub current_channel:   u8,
+    pub current_bw_mhz:    u8,
+    pub current_profile:   u8,
+}
+
+#[derive(Debug, thiserror::Error)]
+pub enum RadioError {
+    #[error("unknown capture profile id: {0}")]
+    UnknownProfile(u8),
+    #[error("backend error: {0}")]
+    Backend(String),
+}
+
+/// Rust mirror of the `rv_radio_ops_t` vtable.
+///
+/// Any Rust-side driver (mock, simulator, future coordinator node) that
+/// wants to participate in the ADR-081 controller stack must implement
+/// this trait. The controller's pure decision policy lives in
+/// `adaptive_controller_decide.c` on the C side today; when the Rust
+/// coordinator lands, it will reuse the decoded `NodeStatus` messages
+/// this module parses and feed decisions back through these ops.
+pub trait RadioOps: Send + Sync {
+    fn init(&mut self) -> Result<(), RadioError>;
+    fn set_channel(&mut self, ch: u8, bw: u8) -> Result<(), RadioError>;
+    fn set_mode(&mut self, mode: RadioMode) -> Result<(), RadioError>;
+    fn set_csi_enabled(&mut self, en: bool) -> Result<(), RadioError>;
+    fn set_capture_profile(&mut self, p: CaptureProfile) -> Result<(), RadioError>;
+    fn get_health(&self) -> Result<RadioHealth, RadioError>;
+}
+
+/// A zero-hardware radio backend for host tests and CI.
+#[derive(Debug, Clone, Default)]
+pub struct MockRadio {
+    pub health:        RadioHealth,
+    pub init_count:    u32,
+    pub channel_calls: Vec<(u8, u8)>,
+    pub profile_calls: Vec<CaptureProfile>,
+    pub mode_calls:    Vec<RadioMode>,
+    pub csi_enabled:   bool,
+}
+
+impl RadioOps for MockRadio {
+    fn init(&mut self) -> Result<(), RadioError> {
+        self.init_count += 1;
+        Ok(())
+    }
+    fn set_channel(&mut self, ch: u8, bw: u8) -> Result<(), RadioError> {
+        self.channel_calls.push((ch, bw));
+        self.health.current_channel = ch;
+        self.health.current_bw_mhz  = bw;
+        Ok(())
+    }
+    fn set_mode(&mut self, mode: RadioMode) -> Result<(), RadioError> {
+        self.mode_calls.push(mode);
+        Ok(())
+    }
+    fn set_csi_enabled(&mut self, en: bool) -> Result<(), RadioError> {
+        self.csi_enabled = en;
+        Ok(())
+    }
+    fn set_capture_profile(&mut self, p: CaptureProfile) -> Result<(), RadioError> {
+        self.profile_calls.push(p);
+        self.health.current_profile = p as u8;
+        Ok(())
+    }
+    fn get_health(&self) -> Result<RadioHealth, RadioError> {
+        Ok(self.health)
+    }
+}
+
+// ---------------------------------------------------------------------------
+// Layer 3 — Mesh plane (mirror of rv_mesh.h)
+// ---------------------------------------------------------------------------
+
+/// `RV_MESH_MAGIC` from rv_mesh.h.
+pub const MESH_MAGIC: u32   = 0xC511_8100;
+/// `RV_MESH_VERSION` from rv_mesh.h.
+pub const MESH_VERSION: u8  = 1;
+/// `RV_MESH_MAX_PAYLOAD` from rv_mesh.h.
+pub const MESH_MAX_PAYLOAD: usize = 256;
+/// `sizeof(rv_mesh_header_t)`.
+pub const MESH_HEADER_SIZE: usize = 16;
+
+/// `rv_mesh_role_t`.
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+#[repr(u8)]
+pub enum MeshRole {
+    Unassigned  = 0,
+    Anchor      = 1,
+    Observer    = 2,
+    FusionRelay = 3,
+    Coordinator = 4,
+}
+
+impl TryFrom<u8> for MeshRole {
+    type Error = MeshError;
+    fn try_from(v: u8) -> Result<Self, Self::Error> {
+        match v {
+            0 => Ok(MeshRole::Unassigned),
+            1 => Ok(MeshRole::Anchor),
+            2 => Ok(MeshRole::Observer),
+            3 => Ok(MeshRole::FusionRelay),
+            4 => Ok(MeshRole::Coordinator),
+            _ => Err(MeshError::UnknownRole(v)),
+        }
+    }
+}
+
+/// `rv_mesh_msg_type_t`.
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+#[repr(u8)]
+pub enum MeshMsgType {
+    TimeSync         = 0x01,
+    RoleAssign       = 0x02,
+    ChannelPlan      = 0x03,
+    CalibrationStart = 0x04,
+    FeatureDelta     = 0x05,
+    Health           = 0x06,
+    AnomalyAlert     = 0x07,
+}
+
+impl TryFrom<u8> for MeshMsgType {
+    type Error = MeshError;
+    fn try_from(v: u8) -> Result<Self, Self::Error> {
+        match v {
+            0x01 => Ok(MeshMsgType::TimeSync),
+            0x02 => Ok(MeshMsgType::RoleAssign),
+            0x03 => Ok(MeshMsgType::ChannelPlan),
+            0x04 => Ok(MeshMsgType::CalibrationStart),
+            0x05 => Ok(MeshMsgType::FeatureDelta),
+            0x06 => Ok(MeshMsgType::Health),
+            0x07 => Ok(MeshMsgType::AnomalyAlert),
+            _    => Err(MeshError::UnknownMsgType(v)),
+        }
+    }
+}
+
+/// `rv_mesh_auth_class_t`.
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+#[repr(u8)]
+pub enum AuthClass {
+    None         = 0,
+    HmacSession  = 1,
+    Ed25519Batch = 2,
+}
+
+/// `rv_mesh_header_t`, 16 bytes.
+#[derive(Debug, Clone, Copy)]
+pub struct MeshHeader {
+    pub msg_type:    MeshMsgType,
+    pub sender_role: MeshRole,
+    pub auth_class:  AuthClass,
+    pub epoch:       u32,
+    pub payload_len: u16,
+}
+
+/// `rv_node_status_t`, 28 bytes.
+#[derive(Debug, Clone, Copy, PartialEq)]
+pub struct NodeStatus {
+    pub node_id:         [u8; 8],
+    pub local_time_us:   u64,
+    pub role:            MeshRole,
+    pub current_channel: u8,
+    pub current_bw:      u8,
+    pub noise_floor_dbm: i8,
+    pub pkt_yield:       u16,
+    pub sync_error_us:   u16,
+    pub health_flags:    u16,
+}
+
+/// `rv_anomaly_alert_t`, 28 bytes.
+#[derive(Debug, Clone, Copy, PartialEq)]
+pub struct AnomalyAlert {
+    pub node_id:       [u8; 8],
+    pub ts_us:         u64,
+    pub severity:      u8,
+    pub reason:        u8,
+    pub anomaly_score: f32,
+    pub motion_score:  f32,
+}
+
+#[derive(Debug, thiserror::Error)]
+pub enum MeshError {
+    #[error("frame too short: {0} bytes")]
+    TooShort(usize),
+    #[error("bad magic: 0x{0:08X}")]
+    BadMagic(u32),
+    #[error("unsupported version: {0}")]
+    BadVersion(u8),
+    #[error("payload too large: {0}")]
+    PayloadTooLarge(u16),
+    #[error("CRC mismatch: got 0x{got:08X}, want 0x{want:08X}")]
+    CrcMismatch { got: u32, want: u32 },
+    #[error("unknown role id: {0}")]
+    UnknownRole(u8),
+    #[error("unknown msg type: 0x{0:02X}")]
+    UnknownMsgType(u8),
+    #[error("unknown auth class: {0}")]
+    UnknownAuth(u8),
+    #[error("payload size mismatch for {which}: got {got}, want {want}")]
+    PayloadSizeMismatch { which: &'static str, got: usize, want: usize },
+}
+
+/// IEEE CRC32 — matches the bit-by-bit implementation in
+/// `rv_feature_state.c`. Poly 0xEDB88320, init 0xFFFFFFFF, xor out.
+pub fn crc32_ieee(data: &[u8]) -> u32 {
+    let mut crc: u32 = 0xFFFF_FFFF;
+    for &b in data {
+        crc ^= b as u32;
+        for _ in 0..8 {
+            let mask = (crc & 1).wrapping_neg();
+            crc = (crc >> 1) ^ (0xEDB8_8320 & mask);
+        }
+    }
+    !crc
+}
+
+/// Parse one mesh frame. Returns the decoded header and a slice view of
+/// the payload inside the input buffer (no copy).
+pub fn decode_mesh(buf: &[u8]) -> Result<(MeshHeader, &[u8]), MeshError> {
+    if buf.len() < MESH_HEADER_SIZE + 4 {
+        return Err(MeshError::TooShort(buf.len()));
+    }
+
+    let magic = u32::from_le_bytes([buf[0], buf[1], buf[2], buf[3]]);
+    if magic != MESH_MAGIC { return Err(MeshError::BadMagic(magic)); }
+
+    let version = buf[4];
+    if version != MESH_VERSION { return Err(MeshError::BadVersion(version)); }
+
+    let ty          = buf[5];
+    let sender_role = buf[6];
+    let auth_class  = buf[7];
+    let epoch       = u32::from_le_bytes([buf[8], buf[9], buf[10], buf[11]]);
+    let payload_len = u16::from_le_bytes([buf[12], buf[13]]);
+
+    if payload_len as usize > MESH_MAX_PAYLOAD {
+        return Err(MeshError::PayloadTooLarge(payload_len));
+    }
+
+    let total = MESH_HEADER_SIZE + payload_len as usize + 4;
+    if buf.len() < total { return Err(MeshError::TooShort(buf.len())); }
+
+    let want_crc = crc32_ieee(&buf[..MESH_HEADER_SIZE + payload_len as usize]);
+    let crc_off  = MESH_HEADER_SIZE + payload_len as usize;
+    let got_crc  = u32::from_le_bytes([
+        buf[crc_off], buf[crc_off + 1], buf[crc_off + 2], buf[crc_off + 3],
+    ]);
+    if got_crc != want_crc {
+        return Err(MeshError::CrcMismatch { got: got_crc, want: want_crc });
+    }
+
+    let msg_type    = MeshMsgType::try_from(ty)?;
+    let sender_role = MeshRole::try_from(sender_role)?;
+    let auth_class  = match auth_class {
+        0 => AuthClass::None,
+        1 => AuthClass::HmacSession,
+        2 => AuthClass::Ed25519Batch,
+        v => return Err(MeshError::UnknownAuth(v)),
+    };
+
+    Ok((
+        MeshHeader { msg_type, sender_role, auth_class, epoch, payload_len },
+        &buf[MESH_HEADER_SIZE .. MESH_HEADER_SIZE + payload_len as usize],
+    ))
+}
+
+/// Decode a `HEALTH` payload (28 bytes).
+pub fn decode_node_status(p: &[u8]) -> Result<NodeStatus, MeshError> {
+    if p.len() != 28 {
+        return Err(MeshError::PayloadSizeMismatch {
+            which: "HEALTH", got: p.len(), want: 28,
+        });
+    }
+    let mut node_id = [0u8; 8];
+    node_id.copy_from_slice(&p[0..8]);
+    let local_time_us = u64::from_le_bytes([
+        p[8], p[9], p[10], p[11], p[12], p[13], p[14], p[15],
+    ]);
+    Ok(NodeStatus {
+        node_id,
+        local_time_us,
+        role: MeshRole::try_from(p[16])?,
+        current_channel: p[17],
+        current_bw:      p[18],
+        noise_floor_dbm: p[19] as i8,
+        pkt_yield:       u16::from_le_bytes([p[20], p[21]]),
+        sync_error_us:   u16::from_le_bytes([p[22], p[23]]),
+        health_flags:    u16::from_le_bytes([p[24], p[25]]),
+    })
+}
+
+/// Decode an `ANOMALY_ALERT` payload (28 bytes).
+pub fn decode_anomaly_alert(p: &[u8]) -> Result<AnomalyAlert, MeshError> {
+    if p.len() != 28 {
+        return Err(MeshError::PayloadSizeMismatch {
+            which: "ANOMALY_ALERT", got: p.len(), want: 28,
+        });
+    }
+    let mut node_id = [0u8; 8];
+    node_id.copy_from_slice(&p[0..8]);
+    let ts_us = u64::from_le_bytes([
+        p[8], p[9], p[10], p[11], p[12], p[13], p[14], p[15],
+    ]);
+    let anomaly_score = f32::from_le_bytes([p[20], p[21], p[22], p[23]]);
+    let motion_score  = f32::from_le_bytes([p[24], p[25], p[26], p[27]]);
+    Ok(AnomalyAlert {
+        node_id, ts_us,
+        severity: p[16],
+        reason:   p[17],
+        anomaly_score, motion_score,
+    })
+}
+
+/// Encode a `HEALTH` payload. Produces the 16-byte header, 28-byte
+/// payload, and 4-byte CRC — bit-identical to what the firmware emits.
+pub fn encode_health(
+    sender_role: MeshRole,
+    epoch: u32,
+    status: &NodeStatus,
+) -> Vec<u8> {
+    let payload_len: u16 = 28;
+    let mut buf = Vec::with_capacity(MESH_HEADER_SIZE + payload_len as usize + 4);
+
+    // header
+    buf.extend_from_slice(&MESH_MAGIC.to_le_bytes());
+    buf.push(MESH_VERSION);
+    buf.push(MeshMsgType::Health as u8);
+    buf.push(sender_role as u8);
+    buf.push(AuthClass::None as u8);
+    buf.extend_from_slice(&epoch.to_le_bytes());
+    buf.extend_from_slice(&payload_len.to_le_bytes());
+    buf.extend_from_slice(&0u16.to_le_bytes());  // reserved
+
+    // payload
+    buf.extend_from_slice(&status.node_id);
+    buf.extend_from_slice(&status.local_time_us.to_le_bytes());
+    buf.push(status.role as u8);
+    buf.push(status.current_channel);
+    buf.push(status.current_bw);
+    buf.push(status.noise_floor_dbm as u8);
+    buf.extend_from_slice(&status.pkt_yield.to_le_bytes());
+    buf.extend_from_slice(&status.sync_error_us.to_le_bytes());
+    buf.extend_from_slice(&status.health_flags.to_le_bytes());
+    buf.extend_from_slice(&0u16.to_le_bytes());  // reserved
+
+    let crc = crc32_ieee(&buf);
+    buf.extend_from_slice(&crc.to_le_bytes());
+    buf
+}
+
+// ---------------------------------------------------------------------------
+// Tests
+// ---------------------------------------------------------------------------
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn mock_radio_tracks_calls() {
+        let mut r = MockRadio::default();
+        assert!(r.init().is_ok());
+        assert_eq!(r.init_count, 1);
+        r.set_channel(6, 20).unwrap();
+        r.set_capture_profile(CaptureProfile::FastMotion).unwrap();
+        r.set_mode(RadioMode::ActiveProbe).unwrap();
+        r.set_csi_enabled(true).unwrap();
+        assert_eq!(r.channel_calls, vec![(6, 20)]);
+        assert_eq!(r.profile_calls, vec![CaptureProfile::FastMotion]);
+        assert_eq!(r.mode_calls, vec![RadioMode::ActiveProbe]);
+        assert!(r.csi_enabled);
+        let h = r.get_health().unwrap();
+        assert_eq!(h.current_channel, 6);
+        assert_eq!(h.current_bw_mhz, 20);
+        assert_eq!(h.current_profile, CaptureProfile::FastMotion as u8);
+    }
+
+    #[test]
+    fn crc32_matches_firmware_vectors() {
+        // Same vectors as test_rv_feature_state.c
+        assert_eq!(crc32_ieee(b"123456789"), 0xCBF43926);
+        assert_eq!(crc32_ieee(&[]),           0x00000000);
+        assert_eq!(crc32_ieee(&[0u8]),        0xD202EF8D);
+    }
+
+    #[test]
+    fn health_roundtrip() {
+        let st = NodeStatus {
+            node_id: [9, 0, 0, 0, 0, 0, 0, 0],
+            local_time_us: 42_000_000,
+            role: MeshRole::Observer,
+            current_channel: 11,
+            current_bw: 20,
+            noise_floor_dbm: -95,
+            pkt_yield: 20,
+            sync_error_us: 7,
+            health_flags: 0x0001,
+        };
+
+        let wire = encode_health(MeshRole::Observer, 5, &st);
+        assert_eq!(wire.len(), MESH_HEADER_SIZE + 28 + 4);
+        assert_eq!(wire.len(), 48);
+
+        let (hdr, payload) = decode_mesh(&wire).expect("decode");
+        assert_eq!(hdr.msg_type, MeshMsgType::Health);
+        assert_eq!(hdr.sender_role, MeshRole::Observer);
+        assert_eq!(hdr.epoch, 5);
+        assert_eq!(hdr.payload_len, 28);
+
+        let back = decode_node_status(payload).expect("payload decode");
+        assert_eq!(back, st);
+    }
+
+    #[test]
+    fn decode_rejects_bad_crc() {
+        let st = NodeStatus {
+            node_id: [1, 0, 0, 0, 0, 0, 0, 0],
+            local_time_us: 0,
+            role: MeshRole::Observer,
+            current_channel: 1,
+            current_bw: 20,
+            noise_floor_dbm: -90,
+            pkt_yield: 0,
+            sync_error_us: 0,
+            health_flags: 0,
+        };
+        let mut wire = encode_health(MeshRole::Observer, 0, &st);
+        let p0 = MESH_HEADER_SIZE;  // first payload byte
+        wire[p0] ^= 0xFF;
+        let err = decode_mesh(&wire).unwrap_err();
+        assert!(matches!(err, MeshError::CrcMismatch { .. }));
+    }
+
+    #[test]
+    fn decode_rejects_bad_magic() {
+        let buf = [0u8; MESH_HEADER_SIZE + 4];
+        let err = decode_mesh(&buf).unwrap_err();
+        assert!(matches!(err, MeshError::BadMagic(_)));
+    }
+
+    #[test]
+    fn decode_rejects_short() {
+        let buf = [0u8; 3];
+        let err = decode_mesh(&buf).unwrap_err();
+        assert!(matches!(err, MeshError::TooShort(_)));
+    }
+
+    #[test]
+    fn profiles_are_bidirectional() {
+        for p in [
+            CaptureProfile::PassiveLowRate,
+            CaptureProfile::ActiveProbe,
+            CaptureProfile::RespHighSens,
+            CaptureProfile::FastMotion,
+            CaptureProfile::Calibration,
+        ] {
+            let v = p as u8;
+            assert_eq!(CaptureProfile::try_from(v).unwrap(), p);
+        }
+    }
+
+    #[test]
+    fn mesh_constants_match_firmware() {
+        // These must match rv_mesh.h byte-for-byte.
+        assert_eq!(MESH_MAGIC, 0xC511_8100);
+        assert_eq!(MESH_VERSION, 1);
+        assert_eq!(MESH_HEADER_SIZE, 16);
+        assert_eq!(MESH_MAX_PAYLOAD, 256);
+    }
+}
@@ -0,0 +1,24 @@
+[package]
+name = "wifi-densepose-pointcloud"
+version = "0.1.0"
+edition = "2021"
+description = "Real-time dense point cloud from camera depth + WiFi CSI tomography"
+
+[[bin]]
+name = "ruview-pointcloud"
+path = "src/main.rs"
+
+[dependencies]
+serde = { workspace = true }
+serde_json = { workspace = true }
+tokio = { workspace = true }
+anyhow = { workspace = true }
+axum = { workspace = true }
+clap = { version = "4", features = ["derive"] }
+chrono = "0.4"
+dirs = "5"
+reqwest = { version = "0.12", features = ["json"], default-features = false }
+
+[target.'cfg(target_os = "linux")'.dependencies]
+v4l = "0.14"
+jpeg-decoder = "0.3"
@@ -0,0 +1,92 @@
+//! Brain bridge — sends spatial observations to the ruOS brain.
+//!
+//! Periodically summarizes the sensor pipeline state and stores it
+//! as brain memories for the agent to reason about.
+//!
+//! The brain URL is read from the `RUVIEW_BRAIN_URL` env var on first use,
+//! defaulting to `http://127.0.0.1:9876`.
+
+use crate::csi_pipeline::PipelineOutput;
+use anyhow::Result;
+use std::sync::OnceLock;
+
+/// Default brain URL if `RUVIEW_BRAIN_URL` is not set.
+const DEFAULT_BRAIN_URL: &str = "http://127.0.0.1:9876";
+
+fn brain_url() -> &'static str {
+    static BRAIN_URL: OnceLock<String> = OnceLock::new();
+    BRAIN_URL.get_or_init(|| {
+        let url = std::env::var("RUVIEW_BRAIN_URL")
+            .unwrap_or_else(|_| DEFAULT_BRAIN_URL.to_string());
+        eprintln!("  brain_bridge: using brain URL {url}");
+        url
+    })
+}
+
+/// Store a spatial observation in the brain.
+async fn store_memory(category: &str, content: &str) -> Result<()> {
+    let client = reqwest::Client::builder()
+        .timeout(std::time::Duration::from_secs(5))
+        .build()?;
+
+    let body = serde_json::json!({
+        "category": category,
+        "content": content,
+    });
+
+    client.post(format!("{}/memories", brain_url()))
+        .json(&body)
+        .send()
+        .await?;
+    Ok(())
+}
+
+/// Summarize pipeline state and store in brain (called every 60 seconds).
+pub async fn sync_to_brain(pipeline: &PipelineOutput, camera_frames: u64) {
+    // Only store if there's meaningful data
+    if pipeline.total_frames < 10 && camera_frames < 5 { return; }
+
+    // Store spatial summary
+    let motion_str = if pipeline.motion_detected { "detected" } else { "absent" };
+    let skeleton_str = if let Some(ref sk) = pipeline.skeleton {
+        format!("{} keypoints ({:.0}% conf)", sk.keypoints.len(), sk.confidence * 100.0)
+    } else {
+        "inactive".to_string()
+    };
+
+    let summary = format!(
+        "Room scan: {} camera frames, {} CSI frames from {} nodes. \
+         Motion {} ({:.0}%). Breathing {:.0} BPM. Skeleton: {}. \
+         Occupancy grid {}x{}x{} with {} occupied voxels.",
+        camera_frames,
+        pipeline.total_frames,
+        pipeline.num_nodes,
+        motion_str,
+        pipeline.vitals.motion_score * 100.0,
+        pipeline.vitals.breathing_rate,
+        skeleton_str,
+        pipeline.occupancy_dims.0,
+        pipeline.occupancy_dims.1,
+        pipeline.occupancy_dims.2,
+        pipeline.occupancy.iter().filter(|&&d| d > 0.3).count(),
+    );
+
+    let _ = store_memory("spatial-observation", &summary).await;
+
+    // Store motion events
+    if pipeline.motion_detected && pipeline.vitals.motion_score > 0.3 {
+        let _ = store_memory("spatial-motion",
+            &format!("Strong motion detected: {:.0}% score, {} CSI frames",
+                pipeline.vitals.motion_score * 100.0, pipeline.total_frames)
+        ).await;
+    }
+
+    // Store vital signs if available
+    if pipeline.vitals.breathing_rate > 5.0 && pipeline.vitals.breathing_rate < 35.0 {
+        let _ = store_memory("spatial-vitals",
+            &format!("Vital signs: breathing {:.0} BPM, motion {:.0}%",
+                pipeline.vitals.breathing_rate, pipeline.vitals.motion_score * 100.0)
+        ).await;
+    }
+}
+
@@ -0,0 +1,297 @@
+//! Camera capture — cross-platform frame grabber.
+//!
+//! Linux: direct V4L2 via `v4l` crate (no subprocess, no orphans)
+//! macOS: ffmpeg -f avfoundation (subprocess)
+//! Fallback: ffmpeg subprocess on all platforms
+#![allow(dead_code)]
+
+use anyhow::{bail, Result};
+use std::path::PathBuf;
+use std::process::Command;
+
+/// Captured frame with raw RGB data.
+pub struct Frame {
+    pub width: u32,
+    pub height: u32,
+    pub rgb: Vec<u8>,
+    pub timestamp_ms: i64,
+}
+
+/// Camera source configuration.
+pub struct CameraConfig {
+    pub device_index: u32,
+    pub width: u32,
+    pub height: u32,
+    pub fps: u32,
+}
+
+impl Default for CameraConfig {
+    fn default() -> Self {
+        Self { device_index: 0, width: 640, height: 480, fps: 15 }
+    }
+}
+
+/// Capture a single frame from the camera.
+///
+/// On Linux: uses direct V4L2 (no subprocess, no orphans).
+/// On macOS: uses ffmpeg subprocess.
+pub fn capture_frame(config: &CameraConfig) -> Result<Frame> {
+    // Linux: direct V4L2 (preferred — no subprocess)
+    #[cfg(target_os = "linux")]
+    {
+        match capture_v4l2_direct(config) {
+            Ok(frame) => return Ok(frame),
+            Err(e) => eprintln!("[camera] V4L2 direct failed: {e}, falling back to ffmpeg"),
+        }
+    }
+
+    // Fallback: ffmpeg subprocess (with timeout to prevent orphans)
+    let tmp = tmp_path();
+    if let Ok(frame) = capture_ffmpeg_safe(config, &tmp) {
+        return Ok(frame);
+    }
+
+    // macOS: screencapture
+    #[cfg(target_os = "macos")]
+    if let Ok(frame) = capture_macos(config, &tmp) {
+        return Ok(frame);
+    }
+
+    bail!("No camera backend available")
+}
+
+// ============================================================
+// Linux: Direct V4L2 capture (no subprocess, no orphans)
+// ============================================================
+
+#[cfg(target_os = "linux")]
+fn capture_v4l2_direct(config: &CameraConfig) -> Result<Frame> {
+    use v4l::buffer::Type;
+    use v4l::io::mmap::Stream;
+    use v4l::io::traits::CaptureStream;
+    use v4l::video::Capture;
+    use v4l::{Device, FourCC};
+
+    let device_path = format!("/dev/video{}", config.device_index);
+    if !std::path::Path::new(&device_path).exists() {
+        bail!("no camera at {device_path}");
+    }
+
+    let dev = Device::with_path(&device_path)?;
+
+    // Try MJPG first (most webcams support it), fall back to YUYV
+    let mut fmt = dev.format()?;
+    fmt.width = config.width;
+    fmt.height = config.height;
+    fmt.fourcc = FourCC::new(b"MJPG");
+    let use_mjpg = dev.set_format(&fmt).is_ok();
+
+    if !use_mjpg {
+        fmt.fourcc = FourCC::new(b"YUYV");
+        dev.set_format(&fmt)?;
+    }
+
+    let fmt = dev.format()?;
+    let actual_w = fmt.width;
+    let actual_h = fmt.height;
+
+    // Stream one frame via mmap
+    let mut stream = Stream::with_buffers(&dev, Type::VideoCapture, 2)?;
+    let (buf, _meta) = stream.next()?;
+
+    let rgb = if use_mjpg {
+        decode_mjpeg_to_rgb(buf, actual_w, actual_h)?
+    } else {
+        yuyv_to_rgb(buf, actual_w, actual_h)
+    };
+
+    // Stream is dropped here — device released cleanly, no orphan process
+
+    Ok(Frame {
+        width: actual_w,
+        height: actual_h,
+        rgb,
+        timestamp_ms: chrono::Utc::now().timestamp_millis(),
+    })
+}
+
+#[cfg(target_os = "linux")]
+fn decode_mjpeg_to_rgb(data: &[u8], _w: u32, _h: u32) -> Result<Vec<u8>> {
+    // Use a minimal JPEG decoder
+    let mut decoder = jpeg_decoder::Decoder::new(std::io::Cursor::new(data));
+    let pixels = decoder.decode()?;
+    let info = decoder.info().ok_or_else(|| anyhow::anyhow!("no JPEG info"))?;
+
+    if info.pixel_format == jpeg_decoder::PixelFormat::RGB24 {
+        Ok(pixels)
+    } else if info.pixel_format == jpeg_decoder::PixelFormat::L8 {
+        // Grayscale → RGB
+        Ok(pixels.iter().flat_map(|&g| [g, g, g]).collect())
+    } else {
+        bail!("unsupported JPEG pixel format: {:?}", info.pixel_format)
+    }
+}
+
+#[cfg(target_os = "linux")]
+fn yuyv_to_rgb(data: &[u8], w: u32, h: u32) -> Vec<u8> {
+    let pixel_count = (w * h) as usize;
+    let mut rgb = Vec::with_capacity(pixel_count * 3);
+
+    for chunk in data.chunks(4) {
+        if chunk.len() < 4 { break; }
+        let (y0, u, y1, v) = (chunk[0] as f32, chunk[1] as f32, chunk[2] as f32, chunk[3] as f32);
+
+        for y in [y0, y1] {
+            let r = (y + 1.402 * (v - 128.0)).clamp(0.0, 255.0) as u8;
+            let g = (y - 0.344136 * (u - 128.0) - 0.714136 * (v - 128.0)).clamp(0.0, 255.0) as u8;
+            let b = (y + 1.772 * (u - 128.0)).clamp(0.0, 255.0) as u8;
+            rgb.extend_from_slice(&[r, g, b]);
+        }
+    }
+    rgb.truncate(pixel_count * 3);
+    rgb
+}
+
+// ============================================================
+// Fallback: ffmpeg subprocess (with timeout + cleanup)
+// ============================================================
+
+fn capture_ffmpeg_safe(config: &CameraConfig, tmp: &PathBuf) -> Result<Frame> {
+    let input = if cfg!(target_os = "macos") {
+        format!("{}:none", config.device_index)
+    } else {
+        format!("/dev/video{}", config.device_index)
+    };
+    let format = if cfg!(target_os = "macos") { "avfoundation" } else { "v4l2" };
+
+    // Spawn with timeout to prevent orphans
+    let mut child = Command::new("ffmpeg")
+        .args([
+            "-y", "-f", format,
+            "-video_size", &format!("{}x{}", config.width, config.height),
+            "-framerate", &config.fps.to_string(),
+            "-i", &input,
+            "-frames:v", "1",
+            "-f", "rawvideo",
+            "-pix_fmt", "rgb24",
+            tmp.to_str().unwrap_or("/tmp/ruview-frame.raw"),
+        ])
+        .stdout(std::process::Stdio::null())
+        .stderr(std::process::Stdio::piped())
+        .spawn()?;
+
+    // Wait with 10-second timeout
+    let timeout = std::time::Duration::from_secs(10);
+    let start = std::time::Instant::now();
+
+    loop {
+        match child.try_wait()? {
+            Some(status) => {
+                if !status.success() {
+                    bail!("ffmpeg capture failed (exit {})", status.code().unwrap_or(-1));
+                }
+                break;
+            }
+            None => {
+                if start.elapsed() > timeout {
+                    // Kill the stuck process — this is the orphan prevention
+                    let _ = child.kill();
+                    let _ = child.wait();
+                    bail!("ffmpeg capture timed out after 10s — killed");
+                }
+                std::thread::sleep(std::time::Duration::from_millis(100));
+            }
+        }
+    }
+
+    let rgb = std::fs::read(tmp)?;
+    let expected = (config.width * config.height * 3) as usize;
+    let _ = std::fs::remove_file(tmp);
+
+    if rgb.len() < expected {
+        bail!("frame too small: {} bytes, expected {}", rgb.len(), expected);
+    }
+
+    Ok(Frame {
+        width: config.width,
+        height: config.height,
+        rgb: rgb[..expected].to_vec(),
+        timestamp_ms: chrono::Utc::now().timestamp_millis(),
+    })
+}
+
+/// macOS: capture via swift/screencapture.
+#[cfg(target_os = "macos")]
+fn capture_macos(config: &CameraConfig, tmp: &PathBuf) -> Result<Frame> {
+    let jpg_path = tmp.with_extension("jpg");
+    let swift = format!(
+        r#"import AVFoundation; import AppKit
+let sem = DispatchSemaphore(value: 0)
+let s = AVCaptureSession(); s.sessionPreset = .medium
+guard let d = AVCaptureDevice.default(for: .video) else {{ exit(1) }}
+let i = try! AVCaptureDeviceInput(device: d); s.addInput(i)
+let o = AVCapturePhotoOutput(); s.addOutput(o)
+class D: NSObject, AVCapturePhotoCaptureDelegate {{
+    func photoOutput(_ o: AVCapturePhotoOutput, didFinishProcessingPhoto p: AVCapturePhoto, error: Error?) {{
+        if let d = p.fileDataRepresentation() {{ try! d.write(to: URL(fileURLWithPath: "{path}")) }}
+        exit(0)
+    }}
+}}
+let dl = D(); s.startRunning(); Thread.sleep(forTimeInterval: 1)
+o.capturePhoto(with: AVCapturePhotoSettings(), delegate: dl)
+Thread.sleep(forTimeInterval: 3)"#,
+        path = jpg_path.display()
+    );
+    let _ = Command::new("swift").args(["-e", &swift]).output();
+    if jpg_path.exists() {
+        let data = std::fs::read(&jpg_path)?;
+        let _ = std::fs::remove_file(&jpg_path);
+        return Ok(Frame {
+            width: config.width,
+            height: config.height,
+            rgb: data,
+            timestamp_ms: chrono::Utc::now().timestamp_millis(),
+        });
+    }
+    bail!("macOS camera capture requires GUI session with camera permission")
+}
+
+fn tmp_path() -> PathBuf {
+    std::env::temp_dir().join(format!("ruview-frame-{}.raw", std::process::id()))
+}
+
+/// Check if a camera is available.
+pub fn camera_available() -> bool {
+    if cfg!(target_os = "macos") {
+        Command::new("system_profiler")
+            .args(["SPCameraDataType"])
+            .output()
+            .map(|o| String::from_utf8_lossy(&o.stdout).contains("Camera"))
+            .unwrap_or(false)
+    } else {
+        std::path::Path::new("/dev/video0").exists()
+    }
+}
+
+/// List available cameras.
+pub fn list_cameras() -> Vec<String> {
+    let mut cameras = Vec::new();
+    if cfg!(target_os = "macos") {
+        if let Ok(output) = Command::new("system_profiler").args(["SPCameraDataType"]).output() {
+            let text = String::from_utf8_lossy(&output.stdout);
+            for line in text.lines() {
+                let trimmed = line.trim();
+                if trimmed.ends_with(':') && !trimmed.starts_with("Camera") && trimmed.len() > 2 {
+                    cameras.push(trimmed.trim_end_matches(':').to_string());
+                }
+            }
+        }
+    } else {
+        for i in 0..10 {
+            if std::path::Path::new(&format!("/dev/video{i}")).exists() {
+                cameras.push(format!("/dev/video{i}"));
+            }
+        }
+    }
+    cameras
+}
@@ -0,0 +1,663 @@
+//! Complete CSI processing pipeline — ADR-018 parser → heuristic pose → vitals → tomography.
+//!
+//! Receives raw UDP frames from ESP32 nodes, extracts I/Q subcarrier data,
+//! detects motion, estimates vitals, and produces 3D occupancy + skeleton
+//! for fusion with camera depth.
+//!
+//! **Note on pose**: the pose estimator here is an amplitude-energy
+//! heuristic — NOT a trained WiFlow model. See
+//! [`CsiPipelineState::heuristic_pose_from_amplitude`] for the exact shape.
+//! A real WiFlow integration requires loading and running the TCN weights,
+//! which this crate does not currently do.
+
+use std::collections::VecDeque;
+use std::net::UdpSocket;
+use std::sync::{Arc, Mutex};
+
+// ADR-018 parser moved to src/parser.rs. Re-export here so downstream code
+// (and the reviewer's referenced public API) keeps working unchanged.
+pub use crate::parser::{parse_adr018, CsiFrame};
+
+// ─── CSI Fingerprint Database ──────────────────────────────────────────────
+
+#[derive(Clone, Debug, serde::Serialize)]
+pub struct CsiFingerprint {
+    pub name: String,
+    pub mean_amplitudes: Vec<f32>,
+    pub rssi_mean: f32,
+    pub rssi_std: f32,
+    pub samples: u32,
+}
+
+// ─── CSI State — accumulates frames for heuristic pose + vitals ───────────
+
+#[derive(Clone, Debug)]
+pub struct Skeleton {
+    /// 17 COCO keypoints: [(x, y), ...] in [0, 1] normalized coordinates
+    pub keypoints: Vec<[f32; 2]>,
+    pub confidence: f32,
+}
+
+#[derive(Clone, Debug)]
+pub struct VitalSigns {
+    pub breathing_rate: f32,  // breaths per minute
+    pub heart_rate: f32,      // beats per minute
+    pub motion_score: f32,    // 0.0 = still, 1.0 = strong motion
+}
+
+pub struct CsiPipelineState {
+    /// Per-node frame history (node_id → last N frames)
+    pub node_frames: std::collections::HashMap<u8, VecDeque<CsiFrame>>,
+    /// Latest skeleton from the amplitude-energy heuristic (NOT ML-derived)
+    pub skeleton: Option<Skeleton>,
+    /// Latest vital signs
+    pub vitals: VitalSigns,
+    /// Occupancy grid from RF tomography
+    pub occupancy: Vec<f64>,
+    pub occupancy_dims: (usize, usize, usize), // nx, ny, nz
+    /// Total frames received
+    pub total_frames: u64,
+    /// Motion detection
+    pub motion_detected: bool,
+    /// CSI fingerprint database for room/location identification
+    pub fingerprints: Vec<CsiFingerprint>,
+    /// Current identified location (name, confidence) — updated every 100 frames
+    pub current_location: Option<(String, f32)>,
+    /// Night mode — true when camera luminance is below threshold
+    pub is_dark: bool,
+    /// Metadata from the on-disk WiFlow JSON, if one is present. NOTE: the
+    /// weights themselves are NOT loaded or executed in this crate — this
+    /// flag merely enables the amplitude-energy heuristic pose code path.
+    pose_model_present: Option<PoseModelMetadata>,
+}
+
+/// Placeholder tag indicating the `wiflow-v1.json` file is present on disk.
+/// This does NOT contain real TCN weights — the actual pose estimator in
+/// this crate is an amplitude-energy heuristic, not a neural network. The
+/// struct itself is empty; we only care whether it exists (`Option::Some`
+/// means "heuristic enabled").
+struct PoseModelMetadata;
+
+impl Default for CsiPipelineState {
+    fn default() -> Self {
+        Self {
+            node_frames: std::collections::HashMap::new(),
+            skeleton: None,
+            vitals: VitalSigns { breathing_rate: 0.0, heart_rate: 0.0, motion_score: 0.0 },
+            occupancy: vec![0.0; 8 * 8 * 4],
+            occupancy_dims: (8, 8, 4),
+            total_frames: 0,
+            motion_detected: false,
+            fingerprints: Vec::new(),
+            current_location: None,
+            is_dark: false,
+            pose_model_present: detect_pose_model_metadata(),
+        }
+    }
+}
+
+// ─── Pose Model Metadata Probe ──────────────────────────────────────────────
+//
+// NOTE: This only reads the shape metadata from `wiflow-v1.json` on disk.
+// The weights are NOT loaded or evaluated. The actual pose used by this
+// crate is an amplitude-energy heuristic (see
+// `heuristic_pose_from_amplitude`), not WiFlow.
+
+fn detect_pose_model_metadata() -> Option<PoseModelMetadata> {
+    let paths = [
+        "/tmp/ruview-firmware/wiflow-v1.json",
+        "~/.local/share/ruview/wiflow-v1.json",
+    ];
+    for p in &paths {
+        let expanded = p.replace('~', &std::env::var("HOME").unwrap_or_default());
+        if let Ok(data) = std::fs::read_to_string(&expanded) {
+            if let Ok(model) = serde_json::from_str::<serde_json::Value>(&data) {
+                if model.get("weightsBase64").and_then(|v| v.as_str()).is_some() {
+                    eprintln!(
+                        "  pose: amplitude-energy heuristic enabled (metadata from {expanded}, {} params — weights NOT loaded)",
+                        model.get("totalParams").and_then(|v| v.as_u64()).unwrap_or(0)
+                    );
+                    return Some(PoseModelMetadata);
+                }
+            }
+        }
+    }
+    eprintln!("  pose: amplitude-energy heuristic disabled (no metadata file found)");
+    None
+}
+
+// ─── Pipeline Processing ────────────────────────────────────────────────────
+
+impl CsiPipelineState {
+    /// Process a new CSI frame — updates motion, vitals, skeleton, occupancy.
+    pub fn process_frame(&mut self, frame: CsiFrame) {
+        let node_id = frame.node_id;
+        self.total_frames += 1;
+
+        // Once every 500 frames log a one-line node stats summary. This keeps
+        // us honest about the CSI shape we are actually receiving and also
+        // guarantees every public `CsiFrame` field is read on the runtime
+        // path, not only in tests.
+        if self.total_frames % 500 == 0 {
+            eprintln!(
+                "  CSI node={} ch={} ant={} sub={} rssi={} nf={} ts_us={} iq_bytes={}",
+                frame.node_id,
+                frame.channel,
+                frame.n_antennas,
+                frame.n_subcarriers,
+                frame.rssi,
+                frame.noise_floor,
+                frame.timestamp_us,
+                frame.iq_data.len(),
+            );
+        }
+
+        // Store frame in per-node history
+        {
+            let history = self.node_frames.entry(node_id).or_insert_with(|| VecDeque::with_capacity(100));
+            history.push_back(frame.clone());
+            if history.len() > 100 { history.pop_front(); }
+        }
+
+        // 1. Motion detection (amplitude variance over last 20 frames)
+        self.detect_motion(node_id);
+
+        // 2. Vital signs (phase analysis over last 100 frames)
+        let has_enough = self.node_frames.get(&node_id).map(|h| h.len() >= 30).unwrap_or(false);
+        if has_enough {
+            self.estimate_vitals(node_id);
+        }
+
+        // 3. Heuristic pose estimation (every 20 frames = 1 second at ~20fps)
+        if self.total_frames % 20 == 0 {
+            self.heuristic_pose_from_amplitude();
+        }
+
+        // 4. RF tomography (update occupancy grid)
+        self.update_tomography();
+
+        // 5. Location fingerprint identification (every 100 frames)
+        if self.total_frames % 100 == 0 {
+            self.current_location = self.identify_location();
+        }
+    }
+
+    fn detect_motion(&mut self, node_id: u8) {
+        if let Some(history) = self.node_frames.get(&node_id) {
+            let recent: Vec<&CsiFrame> = history.iter().rev().take(20).collect();
+            if recent.len() < 5 { return; }
+
+            // Compute mean amplitude across subcarriers for each frame
+            let mean_amps: Vec<f32> = recent.iter()
+                .map(|f| f.amplitudes.iter().sum::<f32>() / f.amplitudes.len().max(1) as f32)
+                .collect();
+
+            let mean = mean_amps.iter().sum::<f32>() / mean_amps.len() as f32;
+            let variance = mean_amps.iter().map(|a| (a - mean).powi(2)).sum::<f32>() / mean_amps.len() as f32;
+
+            // High variance = motion
+            self.vitals.motion_score = (variance / 100.0).min(1.0);
+            self.motion_detected = self.vitals.motion_score > 0.15;
+        }
+    }
+
+    fn estimate_vitals(&mut self, node_id: u8) {
+        if let Some(history) = self.node_frames.get(&node_id) {
+            let frames: Vec<&CsiFrame> = history.iter().rev().take(100).collect();
+            if frames.len() < 30 { return; }
+
+            // Extract phase from a stable subcarrier (pick one with low variance)
+            let n_sub = frames[0].phases.len().min(35);
+            if n_sub == 0 { return; }
+
+            // Use subcarrier 15 (mid-band, typically stable)
+            let sub_idx = n_sub / 2;
+            let phase_series: Vec<f32> = frames.iter().rev()
+                .map(|f| f.phases.get(sub_idx).copied().unwrap_or(0.0))
+                .collect();
+
+            // Simple peak counting for breathing rate (0.15-0.5 Hz = 9-30 BPM)
+            let mut peaks = 0;
+            for i in 1..phase_series.len() - 1 {
+                if phase_series[i] > phase_series[i-1] && phase_series[i] > phase_series[i+1] {
+                    peaks += 1;
+                }
+            }
+
+            // Assuming ~20fps capture, 100 frames = 5 seconds
+            let capture_secs = frames.len() as f32 / 20.0;
+            let breathing_bpm = (peaks as f32 / capture_secs) * 60.0;
+            self.vitals.breathing_rate = breathing_bpm.clamp(5.0, 40.0);
+
+            // Heart rate estimation (0.8-2.5 Hz) — need higher sampling rate
+            // For now, estimate from amplitude modulation
+            self.vitals.heart_rate = 0.0; // requires FFT for accurate detection
+        }
+    }
+
+    /// STUB: not real WiFlow inference; returns an amplitude-energy heuristic
+    /// "pose" built by bucketing CSI subcarrier energy into 17 fake keypoints.
+    ///
+    /// This exists so the downstream viewer has something to render while the
+    /// real WiFlow TCN integration is being wired up. The output should NOT
+    /// be interpreted as an ML-derived skeleton — confidence here is just
+    /// amplitude variance, keypoint x is subcarrier energy, y is the
+    /// keypoint index. Callers that need real pose must use the (yet to be
+    /// wired) WiFlow model directly.
+    fn heuristic_pose_from_amplitude(&mut self) {
+        if self.pose_model_present.is_none() { return; }
+
+        // Collect 20 frames from the primary node
+        let primary_node = self.node_frames.keys().next().copied();
+        if let Some(node_id) = primary_node {
+            if let Some(history) = self.node_frames.get(&node_id) {
+                let frames: Vec<&CsiFrame> = history.iter().rev().take(20).collect();
+                if frames.len() < 20 { return; }
+
+                // Build input: 35 subcarriers × 20 time steps. This is a
+                // deliberately simple summary used to compute amplitude
+                // variance; it is NOT fed through any neural network.
+                let n_sub = frames[0].amplitudes.len().min(35);
+                let mut input = vec![0.0f32; 35 * 20];
+                for (t, frame) in frames.iter().rev().enumerate().take(20) {
+                    for s in 0..n_sub {
+                        input[t * 35 + s] = frame.amplitudes.get(s).copied().unwrap_or(0.0) / 128.0;
+                    }
+                }
+
+                let mean_amp = input.iter().sum::<f32>() / input.len() as f32;
+                let amp_var = input.iter().map(|a| (a - mean_amp).powi(2)).sum::<f32>() / input.len() as f32;
+
+                // If motion detected, emit a placeholder skeleton derived from
+                // signal characteristics. NOT a real pose.
+                if self.motion_detected {
+                    let mut keypoints = vec![[0.5f32; 2]; 17];
+                    for (i, kp) in keypoints.iter_mut().enumerate() {
+                        let sub_range = (i * n_sub / 17)..((i + 1) * n_sub / 17).min(n_sub);
+                        let energy: f32 = sub_range.clone()
+                            .filter_map(|s| frames.last().and_then(|f| f.amplitudes.get(s)))
+                            .sum();
+                        let norm_energy = energy / (sub_range.len().max(1) as f32 * 128.0);
+                        kp[0] = 0.3 + norm_energy * 0.4; // x: subcarrier energy
+                        kp[1] = (i as f32 / 17.0) * 0.8 + 0.1; // y: keypoint index
+                    }
+                    self.skeleton = Some(Skeleton {
+                        keypoints,
+                        confidence: amp_var.min(1.0),
+                    });
+                } else {
+                    self.skeleton = None;
+                }
+            }
+        }
+    }
+
+    /// Record a CSI fingerprint for the current location/room.
+    /// Computes mean amplitude and RSSI statistics from the last 50 frames
+    /// across all nodes and saves as a named fingerprint.
+    pub fn record_fingerprint(&mut self, name: &str) {
+        // Collect last 50 frames from all nodes
+        let mut all_amplitudes: Vec<Vec<f32>> = Vec::new();
+        let mut rssi_values: Vec<f32> = Vec::new();
+
+        for history in self.node_frames.values() {
+            for frame in history.iter().rev().take(50) {
+                all_amplitudes.push(frame.amplitudes.clone());
+                rssi_values.push(frame.rssi as f32);
+            }
+        }
+
+        if all_amplitudes.is_empty() {
+            return;
+        }
+
+        // Compute mean amplitude per subcarrier across all collected frames
+        let n_sub = all_amplitudes.iter().map(|a| a.len()).max().unwrap_or(0);
+        if n_sub == 0 {
+            return;
+        }
+        let mut mean_amplitudes = vec![0.0f32; n_sub];
+        let mut counts = vec![0u32; n_sub];
+        for amps in &all_amplitudes {
+            for (i, &a) in amps.iter().enumerate() {
+                if i < n_sub {
+                    mean_amplitudes[i] += a;
+                    counts[i] += 1;
+                }
+            }
+        }
+        for i in 0..n_sub {
+            if counts[i] > 0 {
+                mean_amplitudes[i] /= counts[i] as f32;
+            }
+        }
+
+        // RSSI statistics
+        let rssi_mean = rssi_values.iter().sum::<f32>() / rssi_values.len() as f32;
+        let rssi_var = rssi_values.iter()
+            .map(|r| (r - rssi_mean).powi(2))
+            .sum::<f32>() / rssi_values.len() as f32;
+        let rssi_std = rssi_var.sqrt();
+
+        let fingerprint = CsiFingerprint {
+            name: name.to_string(),
+            mean_amplitudes,
+            rssi_mean,
+            rssi_std,
+            samples: all_amplitudes.len() as u32,
+        };
+
+        // Replace existing fingerprint with same name, or append
+        if let Some(existing) = self.fingerprints.iter_mut().find(|f| f.name == name) {
+            *existing = fingerprint;
+        } else {
+            self.fingerprints.push(fingerprint);
+        }
+    }
+
+    /// Compare current CSI signals against saved fingerprints using cosine
+    /// similarity. Returns (name, confidence) if the best match exceeds 0.7.
+    pub fn identify_location(&self) -> Option<(String, f32)> {
+        if self.fingerprints.is_empty() {
+            return None;
+        }
+
+        // Build current mean amplitude vector from last 50 frames
+        let mut all_amplitudes: Vec<Vec<f32>> = Vec::new();
+        for history in self.node_frames.values() {
+            for frame in history.iter().rev().take(50) {
+                all_amplitudes.push(frame.amplitudes.clone());
+            }
+        }
+        if all_amplitudes.is_empty() {
+            return None;
+        }
+
+        let n_sub = all_amplitudes.iter().map(|a| a.len()).max().unwrap_or(0);
+        if n_sub == 0 {
+            return None;
+        }
+        let mut current = vec![0.0f32; n_sub];
+        let mut counts = vec![0u32; n_sub];
+        for amps in &all_amplitudes {
+            for (i, &a) in amps.iter().enumerate() {
+                if i < n_sub {
+                    current[i] += a;
+                    counts[i] += 1;
+                }
+            }
+        }
+        for i in 0..n_sub {
+            if counts[i] > 0 {
+                current[i] /= counts[i] as f32;
+            }
+        }
+
+        // Find best matching fingerprint by cosine similarity
+        let mut best: Option<(String, f32)> = None;
+        for fp in &self.fingerprints {
+            let sim = cosine_similarity(&current, &fp.mean_amplitudes);
+            if sim > 0.7 {
+                if best.as_ref().map_or(true, |(_, s)| sim > *s) {
+                    best = Some((fp.name.clone(), sim));
+                }
+            }
+        }
+        best
+    }
+
+    /// Set the ambient light level from camera frame average luminance.
+    /// When luminance < 30 (out of 255), enables night/dark mode which
+    /// increases CSI processing frequency and skips camera depth.
+    pub fn set_light_level(&mut self, avg_luminance: f32) {
+        self.is_dark = avg_luminance < 30.0;
+    }
+
+    fn update_tomography(&mut self) {
+        let (nx, ny, nz) = self.occupancy_dims;
+        let total = nx * ny * nz;
+
+        // Simple backprojection from per-node RSSI
+        let mut new_occ = vec![0.0f64; total];
+        for (node_id, history) in &self.node_frames {
+            if let Some(latest) = history.back() {
+                // RSSI-based attenuation → voxel density
+                let atten = -(latest.rssi as f64);
+                let contribution = atten / 100.0; // normalize
+
+                // Distribute based on node ID position (simplified ray model)
+                let cx = match node_id {
+                    1 => nx / 4,
+                    2 => nx * 3 / 4,
+                    _ => nx / 2,
+                };
+                let cy = ny / 2;
+
+                for iz in 0..nz {
+                    for iy in 0..ny {
+                        for ix in 0..nx {
+                            let dx = (ix as f64 - cx as f64) / nx as f64;
+                            let dy = (iy as f64 - cy as f64) / ny as f64;
+                            let dist = (dx * dx + dy * dy).sqrt();
+                            let idx = iz * ny * nx + iy * nx + ix;
+                            // Gaussian-weighted contribution
+                            new_occ[idx] += contribution * (-dist * dist * 8.0).exp();
+                        }
+                    }
+                }
+            }
+        }
+
+        // Normalize
+        let max = new_occ.iter().cloned().fold(0.0f64, f64::max);
+        if max > 0.0 {
+            for d in &mut new_occ { *d /= max; }
+        }
+
+        // Exponential moving average with previous occupancy
+        for i in 0..total {
+            self.occupancy[i] = self.occupancy[i] * 0.7 + new_occ[i] * 0.3;
+        }
+    }
+}
+
+/// Cosine similarity between two vectors. Returns 0.0 if either has zero magnitude.
+fn cosine_similarity(a: &[f32], b: &[f32]) -> f32 {
+    let len = a.len().min(b.len());
+    if len == 0 {
+        return 0.0;
+    }
+    let mut dot = 0.0f32;
+    let mut mag_a = 0.0f32;
+    let mut mag_b = 0.0f32;
+    for i in 0..len {
+        dot += a[i] * b[i];
+        mag_a += a[i] * a[i];
+        mag_b += b[i] * b[i];
+    }
+    let denom = mag_a.sqrt() * mag_b.sqrt();
+    if denom < 1e-9 {
+        0.0
+    } else {
+        dot / denom
+    }
+}
+
+// ─── UDP Receiver ───────────────────────────────────────────────────────────
+
+/// Start the complete CSI pipeline — UDP receiver + processing.
+///
+/// Architecture (two threads, one std mpsc channel):
+///
+/// ```text
+///   UDP thread                         Processor thread
+///   ┌──────────────┐   mpsc::Sender    ┌────────────────────┐
+///   │ recv_from()  │ ─────────────►    │ recv() CsiFrame    │
+///   │ parse_adr018 │   (bounded-ish    │ lock, process_frame│
+///   └──────────────┘    by channel)    │ unlock             │
+///                                       └────────────────────┘
+/// ```
+///
+/// This decouples the socket from the shared state: the UDP thread only
+/// touches the channel, never the mutex. The HTTP API handlers (which call
+/// `get_pipeline_output`) therefore only contend with the processor thread
+/// for brief periods, not with every incoming packet. Heavy work (pose,
+/// tomography, fingerprinting) runs outside the lock.
+pub fn start_pipeline(bind_addr: &str) -> Arc<Mutex<CsiPipelineState>> {
+    let state = Arc::new(Mutex::new(CsiPipelineState::default()));
+    let processor_state = state.clone();
+
+    let (tx, rx) = std::sync::mpsc::channel::<CsiFrame>();
+
+    // --- UDP thread: read + parse, push to channel (no lock held) ---
+    let addr = bind_addr.to_string();
+    std::thread::spawn(move || {
+        let socket = match UdpSocket::bind(&addr) {
+            Ok(s) => s,
+            Err(e) => {
+                eprintln!("  CSI pipeline: bind failed on {addr}: {e}");
+                return;
+            }
+        };
+        socket.set_read_timeout(Some(std::time::Duration::from_secs(1))).unwrap();
+        eprintln!("  CSI pipeline: listening on {addr}");
+
+        let mut buf = [0u8; 2048];
+        loop {
+            match socket.recv_from(&mut buf) {
+                Ok((n, _)) => {
+                    if let Some(frame) = parse_adr018(&buf[..n]) {
+                        // Non-blocking w.r.t. the shared state lock. If the
+                        // processor thread has died, send() fails and we
+                        // exit the receiver.
+                        if tx.send(frame).is_err() {
+                            eprintln!("  CSI pipeline: processor gone, exiting receiver");
+                            return;
+                        }
+                    }
+                }
+                Err(e) if e.kind() == std::io::ErrorKind::WouldBlock => continue,
+                Err(_) => continue,
+            }
+        }
+    });
+
+    // --- Processor thread: drain channel, take lock briefly to publish ---
+    std::thread::spawn(move || {
+        while let Ok(frame) = rx.recv() {
+            // Lock is held only for the duration of one process_frame call;
+            // HTTP handlers that need a snapshot via get_pipeline_output are
+            // never starved by the UDP read loop.
+            if let Ok(mut st) = processor_state.lock() {
+                st.process_frame(frame);
+            }
+        }
+    });
+
+    state
+}
+
+/// Send synthetic ADR-018 binary CSI frames for local testing without real
+/// ESP32 hardware. Each frame carries `n_subcarriers` subcarriers of fake
+/// I/Q data. Targets `target` (e.g. `127.0.0.1:3333`).
+pub fn send_test_frames(target: &str, count: usize) -> anyhow::Result<()> {
+    use crate::parser::{build_test_frame, MAGIC_V1};
+    let socket = UdpSocket::bind("0.0.0.0:0")?;
+    for i in 0..count {
+        let buf = build_test_frame(MAGIC_V1, (i % 4) as u8, 56, i);
+        socket.send_to(&buf, target)?;
+        std::thread::sleep(std::time::Duration::from_millis(10));
+    }
+    Ok(())
+}
+
+/// Get current pipeline output for fusion.
+pub fn get_pipeline_output(state: &Arc<Mutex<CsiPipelineState>>) -> PipelineOutput {
+    let st = state.lock().unwrap();
+    PipelineOutput {
+        skeleton: st.skeleton.clone(),
+        vitals: st.vitals.clone(),
+        occupancy: st.occupancy.clone(),
+        occupancy_dims: st.occupancy_dims,
+        motion_detected: st.motion_detected,
+        total_frames: st.total_frames,
+        num_nodes: st.node_frames.len(),
+        current_location: st.current_location.clone(),
+        is_dark: st.is_dark,
+    }
+}
+
+#[derive(Clone, Debug, serde::Serialize)]
+pub struct PipelineOutput {
+    pub skeleton: Option<Skeleton>,
+    pub vitals: VitalSigns,
+    pub occupancy: Vec<f64>,
+    pub occupancy_dims: (usize, usize, usize),
+    pub motion_detected: bool,
+    pub total_frames: u64,
+    pub num_nodes: usize,
+    pub current_location: Option<(String, f32)>,
+    pub is_dark: bool,
+}
+
+// Serialize implementations
+impl serde::Serialize for Skeleton {
+    fn serialize<S: serde::Serializer>(&self, s: S) -> Result<S::Ok, S::Error> {
+        use serde::ser::SerializeStruct;
+        let mut st = s.serialize_struct("Skeleton", 2)?;
+        st.serialize_field("keypoints", &self.keypoints)?;
+        st.serialize_field("confidence", &self.confidence)?;
+        st.end()
+    }
+}
+
+impl serde::Serialize for VitalSigns {
+    fn serialize<S: serde::Serializer>(&self, s: S) -> Result<S::Ok, S::Error> {
+        use serde::ser::SerializeStruct;
+        let mut st = s.serialize_struct("VitalSigns", 3)?;
+        st.serialize_field("breathing_rate", &self.breathing_rate)?;
+        st.serialize_field("heart_rate", &self.heart_rate)?;
+        st.serialize_field("motion_score", &self.motion_score)?;
+        st.end()
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use crate::parser::{build_test_frame, parse_adr018, MAGIC_V1};
+
+    fn seed_state_with_frames(state: &mut CsiPipelineState, n: usize) {
+        for i in 0..n {
+            let bytes = build_test_frame(MAGIC_V1, 1, 32, i);
+            let frame = parse_adr018(&bytes).expect("synthetic frame must parse");
+            state.process_frame(frame);
+        }
+    }
+
+    #[test]
+    fn set_light_level_toggles_night_mode() {
+        let mut s = CsiPipelineState::default();
+        assert!(!s.is_dark, "default should be daylight");
+        s.set_light_level(10.0);
+        assert!(s.is_dark, "luminance below 30 → dark");
+        s.set_light_level(200.0);
+        assert!(!s.is_dark, "high luminance → not dark");
+    }
+
+    #[test]
+    fn record_fingerprint_stores_and_matches() {
+        let mut s = CsiPipelineState::default();
+        seed_state_with_frames(&mut s, 30);
+        s.record_fingerprint("lab");
+        assert_eq!(s.fingerprints.len(), 1);
+        assert_eq!(s.fingerprints[0].name, "lab");
+        // Identify against its own fingerprint should succeed.
+        let found = s.identify_location();
+        assert!(found.is_some(), "should identify the just-recorded location");
+        if let Some((name, conf)) = found {
+            assert_eq!(name, "lab");
+            assert!(conf > 0.7, "self-similarity should exceed match threshold");
+        }
+    }
+}
@@ -0,0 +1,263 @@
+//! Monocular depth estimation via MiDaS ONNX + backprojection to 3D points.
+#![allow(dead_code)]
+
+use crate::pointcloud::{PointCloud, ColorPoint};
+use anyhow::Result;
+
+/// Default camera intrinsics (approximate for HD webcam)
+pub struct CameraIntrinsics {
+    pub fx: f32,  // focal length x (pixels)
+    pub fy: f32,  // focal length y (pixels)
+    pub cx: f32,  // principal point x
+    pub cy: f32,  // principal point y
+    pub width: u32,
+    pub height: u32,
+}
+
+impl Default for CameraIntrinsics {
+    fn default() -> Self {
+        Self {
+            fx: 525.0, fy: 525.0,   // typical webcam focal length
+            cx: 320.0, cy: 240.0,   // center of 640x480
+            width: 640, height: 480,
+        }
+    }
+}
+
+/// Backproject a depth map to 3D points using camera intrinsics.
+///
+/// depth_map: row-major [height x width] in meters
+/// rgb: optional row-major [height x width x 3] color
+pub fn backproject_depth(
+    depth_map: &[f32],
+    intrinsics: &CameraIntrinsics,
+    rgb: Option<&[u8]>,
+    downsample: u32,
+) -> PointCloud {
+    let mut cloud = PointCloud::new("camera_depth");
+    let w = intrinsics.width;
+    let h = intrinsics.height;
+    let step = downsample.max(1);
+
+    for y in (0..h).step_by(step as usize) {
+        for x in (0..w).step_by(step as usize) {
+            let idx = (y * w + x) as usize;
+            let z = depth_map[idx];
+
+            // Skip invalid depths
+            if z <= 0.01 || z > 10.0 || z.is_nan() { continue; }
+
+            // Backproject: (u, v, z) → (X, Y, Z)
+            let px = (x as f32 - intrinsics.cx) * z / intrinsics.fx;
+            let py = (y as f32 - intrinsics.cy) * z / intrinsics.fy;
+
+            let (r, g, b) = if let Some(rgb_data) = rgb {
+                let ri = idx * 3;
+                if ri + 2 < rgb_data.len() {
+                    (rgb_data[ri], rgb_data[ri + 1], rgb_data[ri + 2])
+                } else {
+                    (128, 128, 128)
+                }
+            } else {
+                // Color by depth (blue=near, red=far)
+                let t = ((z - 0.5) / 4.0).clamp(0.0, 1.0);
+                ((t * 255.0) as u8, ((1.0 - t) * 128.0) as u8, ((1.0 - t) * 255.0) as u8)
+            };
+
+            cloud.points.push(ColorPoint { x: px, y: py, z, r, g, b, intensity: 1.0 });
+        }
+    }
+    cloud
+}
+
+/// Run depth estimation on an image.
+///
+/// Tries MiDaS GPU server (127.0.0.1:9885) first, falls back to luminance+edges.
+pub fn estimate_depth(
+    image_data: &[u8],
+    width: u32,
+    height: u32,
+) -> Result<Vec<f32>> {
+    // Try MiDaS GPU server
+    if let Ok(depth) = estimate_depth_midas_server(image_data, width, height) {
+        return Ok(depth);
+    }
+
+    // Fallback: luminance + edge-based pseudo-depth
+    let w = width as usize;
+    let h = height as usize;
+    let mut lum = vec![0.0f32; w * h];
+    for i in 0..w * h {
+        let ri = i * 3;
+        if ri + 2 < image_data.len() {
+            lum[i] = (0.299 * image_data[ri] as f32
+                    + 0.587 * image_data[ri + 1] as f32
+                    + 0.114 * image_data[ri + 2] as f32) / 255.0;
+        }
+    }
+    let mut edges = vec![0.0f32; w * h];
+    for y in 1..h - 1 {
+        for x in 1..w - 1 {
+            let gx = -lum[(y-1)*w+x-1] + lum[(y-1)*w+x+1]
+                   - 2.0*lum[y*w+x-1] + 2.0*lum[y*w+x+1]
+                   - lum[(y+1)*w+x-1] + lum[(y+1)*w+x+1];
+            let gy = -lum[(y-1)*w+x-1] - 2.0*lum[(y-1)*w+x] - lum[(y-1)*w+x+1]
+                   + lum[(y+1)*w+x-1] + 2.0*lum[(y+1)*w+x] + lum[(y+1)*w+x+1];
+            edges[y * w + x] = (gx * gx + gy * gy).sqrt().min(1.0);
+        }
+    }
+    let mut depth_map = vec![3.0f32; w * h];
+    for i in 0..w * h {
+        let base = 1.0 + (1.0 - lum[i]) * 3.5;
+        let edge_boost = edges[i] * 1.5;
+        depth_map[i] = (base - edge_boost).max(0.3);
+    }
+    Ok(depth_map)
+}
+
+/// Call MiDaS depth server running on GPU (127.0.0.1:9885).
+fn estimate_depth_midas_server(rgb: &[u8], width: u32, height: u32) -> Result<Vec<f32>> {
+    let expected = (width * height * 3) as usize;
+    if rgb.len() < expected { anyhow::bail!("rgb too small"); }
+
+    // Send RGB as JSON array to depth server
+    let rgb_list: Vec<u8> = rgb[..expected].to_vec();
+    let body = serde_json::json!({
+        "width": width,
+        "height": height,
+        "rgb": rgb_list,
+    });
+    let body_bytes = serde_json::to_vec(&body)?;
+
+    let client = std::net::TcpStream::connect_timeout(
+        &"127.0.0.1:9885".parse()?, std::time::Duration::from_millis(500)
+    )?;
+    client.set_read_timeout(Some(std::time::Duration::from_secs(5)))?;
+    client.set_write_timeout(Some(std::time::Duration::from_secs(2)))?;
+
+    use std::io::{Read, Write};
+    let mut stream = client;
+    let req = format!(
+        "POST /depth HTTP/1.1\r\nHost: 127.0.0.1\r\nContent-Type: application/json\r\nContent-Length: {}\r\n\r\n",
+        body_bytes.len()
+    );
+    stream.write_all(req.as_bytes())?;
+    stream.write_all(&body_bytes)?;
+
+    // Read response
+    let mut resp = Vec::new();
+    stream.read_to_end(&mut resp)?;
+
+    // Skip HTTP headers
+    let body_start = resp.windows(4).position(|w| w == b"\r\n\r\n")
+        .map(|p| p + 4).unwrap_or(0);
+    let depth_bytes = &resp[body_start..];
+
+    let n = (width * height) as usize;
+    if depth_bytes.len() < n * 4 { anyhow::bail!("depth response too small"); }
+
+    let depth: Vec<f32> = depth_bytes[..n * 4].chunks_exact(4)
+        .map(|c| f32::from_le_bytes([c[0], c[1], c[2], c[3]]))
+        .collect();
+
+    Ok(depth)
+}
+
+/// Capture depth cloud from camera (placeholder — real impl uses nokhwa or v4l2).
+pub async fn capture_depth_cloud(_frames: usize) -> Result<PointCloud> {
+    eprintln!("Camera capture not available (no camera on this machine).");
+    eprintln!("Use --demo for synthetic data, or run on a machine with a camera.");
+    Ok(demo_depth_cloud())
+}
+
+/// Generate a demo depth point cloud (synthetic room scene).
+pub fn demo_depth_cloud() -> PointCloud {
+    let _cloud = PointCloud::new("demo_camera_depth");
+    let intrinsics = CameraIntrinsics::default();
+
+    // Simulate a depth map: room with walls at 3m, floor, and a person at 2m
+    let w = 160;  // downsampled
+    let h = 120;
+    let mut depth = vec![3.0f32; w * h];
+
+    // Floor plane (bottom third)
+    for y in (h * 2 / 3)..h {
+        for x in 0..w {
+            depth[y * w + x] = 1.0 + (y - h * 2 / 3) as f32 * 0.05;
+        }
+    }
+
+    // Person silhouette (center, depth=2m)
+    for y in (h / 4)..(h * 3 / 4) {
+        for x in (w * 2 / 5)..(w * 3 / 5) {
+            let dy = (y as f32 - h as f32 / 2.0).abs() / (h as f32 / 4.0);
+            let dx = (x as f32 - w as f32 / 2.0).abs() / (w as f32 / 5.0);
+            if dx * dx + dy * dy < 1.0 {
+                depth[y * w + x] = 2.0 + (dx * dx + dy * dy) * 0.3;
+            }
+        }
+    }
+
+    let scaled_intrinsics = CameraIntrinsics {
+        fx: intrinsics.fx * w as f32 / intrinsics.width as f32,
+        fy: intrinsics.fy * h as f32 / intrinsics.height as f32,
+        cx: w as f32 / 2.0,
+        cy: h as f32 / 2.0,
+        width: w as u32,
+        height: h as u32,
+    };
+
+    backproject_depth(&depth, &scaled_intrinsics, None, 1)
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn backproject_2x2_depth_yields_four_points() {
+        // 2x2 image, depth=1m everywhere; trivial intrinsics.
+        let intr = CameraIntrinsics {
+            fx: 1.0, fy: 1.0, cx: 0.5, cy: 0.5,
+            width: 2, height: 2,
+        };
+        let depth = vec![1.0f32; 4];
+        let cloud = backproject_depth(&depth, &intr, None, 1);
+        assert_eq!(cloud.points.len(), 4, "2x2 depth → 4 backprojected points");
+        // Every point should be at z=1.0.
+        for p in &cloud.points {
+            assert!((p.z - 1.0).abs() < 1e-6, "z should be 1.0, got {}", p.z);
+        }
+        // With cx=0.5, cy=0.5 the four pixel centers backproject symmetrically
+        // about the optical axis: x in {-0.5, 0.5}, y in {-0.5, 0.5}.
+        let mut xs: Vec<f32> = cloud.points.iter().map(|p| p.x).collect();
+        xs.sort_by(|a, b| a.partial_cmp(b).unwrap());
+        assert!((xs[0] + 0.5).abs() < 1e-6);
+        assert!((xs.last().unwrap() - 0.5).abs() < 1e-6);
+    }
+
+    #[test]
+    fn backproject_rejects_invalid_depth() {
+        let intr = CameraIntrinsics {
+            fx: 1.0, fy: 1.0, cx: 0.5, cy: 0.5,
+            width: 2, height: 2,
+        };
+        // All pixels NaN → no points.
+        let depth = vec![f32::NAN; 4];
+        let cloud = backproject_depth(&depth, &intr, None, 1);
+        assert_eq!(cloud.points.len(), 0);
+    }
+}
+
+#[allow(dead_code)]
+fn find_midas_model() -> Result<String> {
+    let paths = [
+        dirs::home_dir().unwrap_or_default().join(".local/share/ruview/midas_v21_small_256.onnx"),
+        dirs::home_dir().unwrap_or_default().join(".cache/ruview/midas_v21_small_256.onnx"),
+        std::path::PathBuf::from("/usr/local/share/ruview/midas_v21_small_256.onnx"),
+    ];
+    for p in &paths {
+        if p.exists() { return Ok(p.to_string_lossy().to_string()); }
+    }
+    anyhow::bail!("MiDaS ONNX model not found. Download:\n  wget https://github.com/isl-org/MiDaS/releases/download/v3_1/midas_v21_small_256.onnx -O ~/.local/share/ruview/midas_v21_small_256.onnx")
+}
@@ -0,0 +1,163 @@
+//! Multi-modal fusion: camera depth + WiFi RF tomography → unified point cloud.
+
+use crate::pointcloud::{PointCloud, ColorPoint};
+use std::collections::HashMap;
+
+/// Occupancy volume from WiFi RF tomography (mirrors RuView's OccupancyVolume).
+#[derive(Clone, Debug, serde::Serialize, serde::Deserialize)]
+pub struct OccupancyVolume {
+    pub densities: Vec<f64>,   // [nz][ny][nx] voxel densities
+    pub nx: usize,
+    pub ny: usize,
+    pub nz: usize,
+    pub bounds: [f64; 6],      // [x_min, y_min, z_min, x_max, y_max, z_max]
+    pub occupied_count: usize,
+}
+
+/// Convert WiFi occupancy volume to a sparse point cloud.
+///
+/// Each occupied voxel (density > threshold) becomes a point at the voxel center.
+pub fn occupancy_to_pointcloud(vol: &OccupancyVolume) -> PointCloud {
+    let mut cloud = PointCloud::new("wifi_occupancy");
+    let threshold = 0.3;
+
+    let dx = (vol.bounds[3] - vol.bounds[0]) / vol.nx as f64;
+    let dy = (vol.bounds[4] - vol.bounds[1]) / vol.ny as f64;
+    let dz = (vol.bounds[5] - vol.bounds[2]) / vol.nz as f64;
+
+    for iz in 0..vol.nz {
+        for iy in 0..vol.ny {
+            for ix in 0..vol.nx {
+                let idx = iz * vol.ny * vol.nx + iy * vol.nx + ix;
+                let density = vol.densities[idx];
+                if density > threshold {
+                    let x = vol.bounds[0] + (ix as f64 + 0.5) * dx;
+                    let y = vol.bounds[1] + (iy as f64 + 0.5) * dy;
+                    let z = vol.bounds[2] + (iz as f64 + 0.5) * dz;
+
+                    // Color by density (green=low, red=high)
+                    let t = ((density - threshold) / (1.0 - threshold)).min(1.0);
+                    let r = (t * 255.0) as u8;
+                    let g = ((1.0 - t) * 200.0) as u8;
+
+                    cloud.points.push(ColorPoint {
+                        x: x as f32,
+                        y: y as f32,
+                        z: z as f32,
+                        r, g, b: 50,
+                        intensity: density as f32,
+                    });
+                }
+            }
+        }
+    }
+    cloud
+}
+
+/// Fuse multiple point clouds with voxel-grid downsampling.
+///
+/// Points from all clouds are binned into voxels of the given size.
+/// Each voxel produces one averaged point (position, color, max intensity).
+pub fn fuse_clouds(clouds: &[&PointCloud], voxel_size: f32) -> PointCloud {
+    let mut cells: HashMap<(i32, i32, i32), (f32, f32, f32, f32, f32, f32, f32, u32)> = HashMap::new();
+    // (sum_x, sum_y, sum_z, sum_r, sum_g, sum_b, max_intensity, count)
+
+    for cloud in clouds {
+        for p in &cloud.points {
+            let key = (
+                (p.x / voxel_size).floor() as i32,
+                (p.y / voxel_size).floor() as i32,
+                (p.z / voxel_size).floor() as i32,
+            );
+            let entry = cells.entry(key).or_insert((0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0));
+            entry.0 += p.x;
+            entry.1 += p.y;
+            entry.2 += p.z;
+            entry.3 += p.r as f32;
+            entry.4 += p.g as f32;
+            entry.5 += p.b as f32;
+            entry.6 = entry.6.max(p.intensity);
+            entry.7 += 1;
+        }
+    }
+
+    let mut fused = PointCloud::new("fused");
+    for (_, (sx, sy, sz, sr, sg, sb, mi, n)) in &cells {
+        let n = *n as f32;
+        fused.points.push(ColorPoint {
+            x: sx / n, y: sy / n, z: sz / n,
+            r: (sr / n) as u8, g: (sg / n) as u8, b: (sb / n) as u8,
+            intensity: *mi,
+        });
+    }
+    fused
+}
+
+/// Generate a demo occupancy volume (room with person).
+pub fn demo_occupancy() -> OccupancyVolume {
+    let nx = 10;
+    let ny = 10;
+    let nz = 5;
+    let mut densities = vec![0.0f64; nx * ny * nz];
+
+    // Walls (high density at edges)
+    for iz in 0..nz {
+        for iy in 0..ny {
+            for ix in 0..nx {
+                let idx = iz * ny * nx + iy * nx + ix;
+                // Edges = walls
+                if ix == 0 || ix == nx - 1 || iy == 0 || iy == ny - 1 {
+                    densities[idx] = 0.8;
+                }
+                // Floor
+                if iz == 0 {
+                    densities[idx] = 0.6;
+                }
+                // Person at center (iz=1-3, ix=4-6, iy=4-6)
+                if (4..=6).contains(&ix) && (4..=6).contains(&iy) && (1..=3).contains(&iz) {
+                    densities[idx] = 0.9;
+                }
+            }
+        }
+    }
+
+    let occupied_count = densities.iter().filter(|&&d| d > 0.3).count();
+    OccupancyVolume {
+        densities, nx, ny, nz,
+        bounds: [0.0, 0.0, 0.0, 5.0, 5.0, 3.0],
+        occupied_count,
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    fn cloud_with(name: &str, pts: &[(f32, f32, f32)]) -> PointCloud {
+        let mut c = PointCloud::new(name);
+        for &(x, y, z) in pts {
+            c.points.push(ColorPoint { x, y, z, r: 10, g: 20, b: 30, intensity: 0.5 });
+        }
+        c
+    }
+
+    #[test]
+    fn fuse_clouds_merges_non_overlapping() {
+        let a = cloud_with("a", &[(0.0, 0.0, 0.0)]);
+        let b = cloud_with("b", &[(5.0, 5.0, 5.0)]);
+        let fused = fuse_clouds(&[&a, &b], 0.1);
+        assert_eq!(fused.points.len(), 2, "two far-apart points should yield two voxels");
+    }
+
+    #[test]
+    fn fuse_clouds_voxel_dedup() {
+        // Points all within one voxel must collapse to a single averaged point.
+        let a = cloud_with("a", &[
+            (0.01, 0.02, 0.03),
+            (0.04, 0.01, 0.02),
+            (0.03, 0.03, 0.01),
+        ]);
+        let fused = fuse_clouds(&[&a], 0.5);
+        assert_eq!(fused.points.len(), 1, "three close points → one voxel");
+    }
+}
@@ -0,0 +1,272 @@
+//! ruview-pointcloud — real-time dense point cloud from camera + WiFi CSI
+//!
+//! Pipeline: Camera → Depth → Backproject → Fuse with WiFi occupancy → Stream
+//!
+//! Usage:
+//!   ruview-pointcloud serve               # HTTP + Three.js viewer
+//!   ruview-pointcloud capture --frames 1  # capture to PLY
+//!   ruview-pointcloud demo                # synthetic demo
+//!   ruview-pointcloud train               # calibration training
+//!   ruview-pointcloud csi-test            # send test CSI frames (ADR-018 binary)
+
+mod brain_bridge;
+mod camera;
+mod csi_pipeline;
+mod depth;
+mod fusion;
+mod parser;
+mod pointcloud;
+mod stream;
+mod training;
+
+use anyhow::Result;
+use clap::{Parser, Subcommand};
+
+const VERSION: &str = env!("CARGO_PKG_VERSION");
+
+#[derive(Parser)]
+#[command(name = "ruview-pointcloud", version = VERSION)]
+struct Cli {
+    #[command(subcommand)]
+    command: Commands,
+}
+
+#[derive(Subcommand)]
+enum Commands {
+    /// Start real-time point cloud server.
+    ///
+    /// By default the HTTP server binds to `127.0.0.1:9880` — exposing it on
+    /// `0.0.0.0` leaks live camera/CSI/vitals data to the network and must
+    /// be an explicit opt-in via `--bind 0.0.0.0:9880`.
+    Serve {
+        /// Bind address for the HTTP/viewer server. Default
+        /// `127.0.0.1:9880` (loopback only — safe by default).
+        #[arg(long, default_value = "127.0.0.1:9880")]
+        bind: String,
+        /// Brain URL for storing observations
+        #[arg(long)]
+        brain: Option<String>,
+    },
+    /// Capture frames to PLY file
+    Capture {
+        #[arg(long, default_value = "1")]
+        frames: usize,
+        #[arg(long, default_value = "output.ply")]
+        output: String,
+    },
+    /// Generate demo point cloud
+    Demo,
+    /// List available cameras
+    Cameras,
+    /// Training and calibration
+    Train {
+        #[arg(long, default_value = "~/.local/share/ruview/training")]
+        data_dir: String,
+        /// Brain URL for submitting results
+        #[arg(long)]
+        brain: Option<String>,
+    },
+    /// Send synthetic ADR-018 binary CSI frames (for local testing without ESP32).
+    CsiTest {
+        #[arg(long, default_value = "127.0.0.1:3333")]
+        target: String,
+        #[arg(long, default_value = "100")]
+        count: usize,
+    },
+    /// Record a CSI fingerprint for the current location.
+    ///
+    /// Listens on UDP 3333 for `--seconds` seconds, accumulates CSI frames,
+    /// and stores a named fingerprint that future sessions can match
+    /// against to identify the room.
+    Fingerprint {
+        /// Human-readable name for the fingerprint (e.g. "office", "lab").
+        name: String,
+        /// How long to listen before recording (default 5 s).
+        #[arg(long, default_value = "5")]
+        seconds: u64,
+    },
+}
+
+#[tokio::main]
+async fn main() -> Result<()> {
+    let cli = Cli::parse();
+
+    match cli.command {
+        Commands::Serve { bind, brain } => {
+            stream::serve(&bind, brain.as_deref()).await?;
+        }
+        Commands::Capture { frames: _, output } => {
+            if camera::camera_available() {
+                let config = camera::CameraConfig::default();
+                let frame = camera::capture_frame(&config)?;
+                let depth = depth::estimate_depth(&frame.rgb, frame.width, frame.height)?;
+                let intrinsics = depth::CameraIntrinsics::default();
+                let cloud = depth::backproject_depth(&depth, &intrinsics, Some(&frame.rgb), 2);
+                pointcloud::write_ply(&cloud, &output)?;
+                println!("Captured {} points to {output}", cloud.points.len());
+            } else {
+                let cloud = depth::demo_depth_cloud();
+                pointcloud::write_ply(&cloud, &output)?;
+                println!("No camera — wrote {} demo points to {output}", cloud.points.len());
+            }
+        }
+        Commands::Demo => {
+            demo().await?;
+        }
+        Commands::Cameras => {
+            let cams = camera::list_cameras();
+            if cams.is_empty() {
+                println!("No cameras found");
+            } else {
+                println!("Available cameras:");
+                for (i, c) in cams.iter().enumerate() {
+                    println!("  [{i}] {c}");
+                }
+            }
+        }
+        Commands::Train { data_dir, brain } => {
+            train(&data_dir, brain.as_deref()).await?;
+        }
+        Commands::CsiTest { target, count } => {
+            println!("Sending {count} synthetic ADR-018 CSI frames to {target}...");
+            csi_pipeline::send_test_frames(&target, count)?;
+            println!("Done");
+        }
+        Commands::Fingerprint { name, seconds } => {
+            println!("Recording CSI fingerprint '{name}' for {seconds} s on UDP 3333...");
+            let state = csi_pipeline::start_pipeline("0.0.0.0:3333");
+            std::thread::sleep(std::time::Duration::from_secs(seconds));
+            // record_fingerprint takes a brief lock on the shared state to
+            // read the last N frames from every node's history.
+            {
+                let mut st = state.lock().expect("pipeline state lock poisoned");
+                st.record_fingerprint(&name);
+                println!(
+                    "  Stored: {} fingerprint(s) total, {} total CSI frames received",
+                    st.fingerprints.len(),
+                    st.total_frames
+                );
+            }
+        }
+    }
+
+    Ok(())
+}
+
+async fn demo() -> Result<()> {
+    println!("╔══════════════════════════════════════════════╗");
+    println!("║  RuView Dense Point Cloud — Demo             ║");
+    println!("╚══════════════════════════════════════════════╝");
+    println!();
+
+    let occupancy = fusion::demo_occupancy();
+    let wifi_cloud = fusion::occupancy_to_pointcloud(&occupancy);
+    println!("WiFi occupancy: {}x{}x{} voxels → {} points",
+        occupancy.nx, occupancy.ny, occupancy.nz, wifi_cloud.points.len());
+
+    let depth_cloud = depth::demo_depth_cloud();
+    println!("Camera depth: {} points", depth_cloud.points.len());
+
+    let fused = fusion::fuse_clouds(&[&wifi_cloud, &depth_cloud], 0.05);
+    println!("Fused: {} points (voxel size=0.05m)", fused.points.len());
+
+    pointcloud::write_ply(&fused, "demo_pointcloud.ply")?;
+    println!("\nWrote: demo_pointcloud.ply");
+
+    let splats = pointcloud::to_gaussian_splats(&fused);
+    let json = serde_json::to_string_pretty(&splats)?;
+    std::fs::write("demo_splats.json", &json)?;
+    println!("Wrote: demo_splats.json ({} splats)", splats.len());
+
+    Ok(())
+}
+
+async fn train(data_dir: &str, brain_url: Option<&str>) -> Result<()> {
+    println!("╔══════════════════════════════════════════════╗");
+    println!("║  RuView Point Cloud — Training               ║");
+    println!("╚══════════════════════════════════════════════╝");
+    println!();
+
+    let expanded = data_dir.replace('~', &dirs::home_dir().unwrap_or_default().to_string_lossy());
+    // Defence-in-depth: reject path-traversal in the CLI argument before we
+    // hand it to TrainingSession (which also checks). This catches malicious
+    // CLI input early, before any I/O.
+    let _sanitised = training::sanitize_data_path(&expanded)?;
+    let mut session = training::TrainingSession::new(&expanded)?;
+    session.load_samples()?;
+
+    // Capture training samples
+    println!("==> Capturing training samples...");
+
+    // Camera samples
+    if camera::camera_available() {
+        println!("  Camera detected — capturing depth frames...");
+        let config = camera::CameraConfig::default();
+        for i in 0..5 {
+            if let Ok(frame) = camera::capture_frame(&config) {
+                let depth = depth::estimate_depth(&frame.rgb, frame.width, frame.height)?;
+                // Score based on depth variance (good frames have varied depth)
+                let mean: f32 = depth.iter().sum::<f32>() / depth.len() as f32;
+                let variance: f32 = depth.iter().map(|d| (d - mean).powi(2)).sum::<f32>() / depth.len() as f32;
+                let quality = (variance / 2.0).min(1.0);
+
+                session.add_sample(
+                    Some(depth), frame.width, frame.height,
+                    None, None, quality,
+                );
+                println!("  Frame {}: quality={:.2}", i, quality);
+            }
+            std::thread::sleep(std::time::Duration::from_millis(500));
+        }
+    } else {
+        println!("  No camera — using synthetic samples for calibration demo");
+        for i in 0..10 {
+            let w = 160u32;
+            let h = 120u32;
+            let depth: Vec<f32> = (0..w * h).map(|j| 1.0 + (j as f32 / (w * h) as f32) * 4.0 + (i as f32 * 0.1)).collect();
+            let quality = if i < 7 { 0.8 } else { 0.2 };
+            let gt = if i % 3 == 0 {
+                Some(training::GroundTruth {
+                    reference_distances: vec![
+                        training::ReferencePoint { name: "wall".into(), x_pixel: 80, y_pixel: 60, true_distance_m: 3.0 },
+                    ],
+                    occupancy_label: Some(if i < 5 { "occupied" } else { "empty" }.into()),
+                })
+            } else { None };
+            session.add_sample(Some(depth), w, h, None, gt, quality);
+        }
+    }
+
+    session.save_samples()?;
+
+    // Calibrate depth
+    println!("\n==> Calibrating depth estimation...");
+    let cal = session.calibrate_depth()?;
+    println!("  Result: scale={:.2} offset={:.2} gamma={:.2} RMSE={:.4}m",
+        cal.scale, cal.offset, cal.gamma, cal.rmse);
+
+    // Train occupancy
+    println!("\n==> Training occupancy model...");
+    let occ_cal = session.train_occupancy()?;
+    println!("  Result: threshold={:.2} accuracy={:.1}%",
+        occ_cal.density_threshold, occ_cal.accuracy * 100.0);
+
+    // Export preference pairs
+    println!("\n==> Exporting preference pairs...");
+    let pairs = session.export_preference_pairs()?;
+    println!("  Exported: {} pairs", pairs.len());
+
+    // Submit to brain if available
+    if let Some(url) = brain_url {
+        println!("\n==> Submitting to brain at {url}...");
+        let stored = session.submit_to_brain(url).await?;
+        println!("  Stored: {} observations", stored);
+    }
+
+    println!("\n==> Training complete!");
+    println!("  Data dir: {expanded}");
+    println!("  Samples: {}", session.samples.len());
+    println!("  Calibration: {expanded}/calibration.json");
+
+    Ok(())
+}
@@ -0,0 +1,163 @@
+//! ADR-018 binary CSI frame parser.
+//!
+//! Two header magics are accepted: `0xC5110001` (raw CSI, v1) and
+//! `0xC5110006` (feature state, v6). The header is 20 bytes; everything
+//! after is interleaved I/Q bytes per subcarrier per antenna.
+//!
+//! Returns `None` when the buffer is truncated or the magic is wrong —
+//! this is a hot path (one call per UDP packet) so we prefer Option over
+//! a full `anyhow::Error` that would allocate.
+
+const CSI_MAGIC_V6: u32 = 0xC511_0006;
+const CSI_MAGIC_V1: u32 = 0xC511_0001;
+pub(crate) const CSI_HEADER_SIZE: usize = 20;
+
+/// Accept both header magics — `0xC5110001` (raw CSI) and
+/// `0xC5110006` (feature state). Exposed for tests.
+#[allow(dead_code)]
+pub(crate) const MAGIC_V1: u32 = CSI_MAGIC_V1;
+#[allow(dead_code)]
+pub(crate) const MAGIC_V6: u32 = CSI_MAGIC_V6;
+
+#[derive(Clone, Debug)]
+pub struct CsiFrame {
+    pub node_id: u8,
+    pub n_antennas: u8,
+    pub n_subcarriers: u16,
+    pub channel: u8,
+    pub rssi: i8,
+    pub noise_floor: i8,
+    pub timestamp_us: u32,
+    /// Raw I/Q data: [I0, Q0, I1, Q1, ...] for each subcarrier
+    pub iq_data: Vec<i8>,
+    /// Computed amplitude per subcarrier: sqrt(I^2 + Q^2)
+    pub amplitudes: Vec<f32>,
+    /// Computed phase per subcarrier: atan2(Q, I)
+    pub phases: Vec<f32>,
+}
+
+/// Parse an ADR-018 binary CSI frame from a UDP packet.
+///
+/// Returns `None` if:
+/// - the buffer is shorter than the 20-byte header
+/// - the magic does not match either accepted value
+/// - the declared I/Q payload is truncated
+pub fn parse_adr018(data: &[u8]) -> Option<CsiFrame> {
+    if data.len() < CSI_HEADER_SIZE { return None; }
+
+    let magic = u32::from_le_bytes([data[0], data[1], data[2], data[3]]);
+    if magic != CSI_MAGIC_V6 && magic != CSI_MAGIC_V1 { return None; }
+
+    let node_id = data[4];
+    let n_antennas = data[5].max(1);
+    let n_subcarriers = u16::from_le_bytes([data[6], data[7]]);
+    let channel = data[8];
+    let rssi = data[9] as i8;
+    let noise_floor = data[10] as i8;
+    let timestamp_us = u32::from_le_bytes([data[16], data[17], data[18], data[19]]);
+
+    let iq_len = (n_subcarriers as usize) * 2 * (n_antennas as usize);
+    if data.len() < CSI_HEADER_SIZE + iq_len { return None; }
+
+    let iq_data: Vec<i8> = data[CSI_HEADER_SIZE..CSI_HEADER_SIZE + iq_len]
+        .iter().map(|&b| b as i8).collect();
+
+    // Compute amplitude and phase per subcarrier (first antenna).
+    let mut amplitudes = Vec::with_capacity(n_subcarriers as usize);
+    let mut phases = Vec::with_capacity(n_subcarriers as usize);
+    for i in 0..n_subcarriers as usize {
+        let idx = i * 2;
+        if idx + 1 < iq_data.len() {
+            let ii = iq_data[idx] as f32;
+            let qq = iq_data[idx + 1] as f32;
+            amplitudes.push((ii * ii + qq * qq).sqrt());
+            phases.push(qq.atan2(ii));
+        }
+    }
+
+    Some(CsiFrame {
+        node_id, n_antennas, n_subcarriers, channel, rssi, noise_floor,
+        timestamp_us, iq_data, amplitudes, phases,
+    })
+}
+
+/// Build a synthetic ADR-018 binary frame. Used by the `csi-test` CLI
+/// subcommand and by the unit tests in this module.
+pub fn build_test_frame(magic: u32, node_id: u8, n_subcarriers: u16, i: usize) -> Vec<u8> {
+    let mut buf = Vec::with_capacity(CSI_HEADER_SIZE + (n_subcarriers as usize) * 2);
+    buf.extend_from_slice(&magic.to_le_bytes());                 // magic (0..4)
+    buf.push(node_id);                                           // node_id (4)
+    buf.push(1u8);                                               // n_antennas (5)
+    buf.extend_from_slice(&n_subcarriers.to_le_bytes());         // n_subcarriers (6..8)
+    buf.push(6u8);                                               // channel (8)
+    buf.push((-40i8 - (i % 30) as i8) as u8);                    // rssi (9)
+    buf.push((-90i8) as u8);                                     // noise_floor (10)
+    buf.extend_from_slice(&[0u8; 5]);                            // reserved (11..16)
+    buf.extend_from_slice(&(i as u32).to_le_bytes());            // timestamp_us (16..20)
+    for j in 0..(n_subcarriers as usize) {
+        buf.push(((i + j) as i8).wrapping_mul(3) as u8);
+        buf.push(((i + j) as i8).wrapping_mul(5) as u8);
+    }
+    buf
+}
+
+// ─── Tests ──────────────────────────────────────────────────────────────────
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn parse_magic_v1_roundtrips() {
+        let frame_bytes = build_test_frame(MAGIC_V1, 0x42, 56, 7);
+        let frame = parse_adr018(&frame_bytes).expect("v1 frame should parse");
+        assert_eq!(frame.node_id, 0x42);
+        assert_eq!(frame.n_antennas, 1);
+        assert_eq!(frame.n_subcarriers, 56);
+        assert_eq!(frame.channel, 6);
+        assert_eq!(frame.timestamp_us, 7);
+        assert_eq!(frame.iq_data.len(), 56 * 2);
+        assert_eq!(frame.amplitudes.len(), 56);
+        assert_eq!(frame.phases.len(), 56);
+    }
+
+    #[test]
+    fn parse_magic_v6_roundtrips() {
+        let frame_bytes = build_test_frame(MAGIC_V6, 0x09, 114, 0);
+        let frame = parse_adr018(&frame_bytes).expect("v6 frame should parse");
+        assert_eq!(frame.node_id, 0x09);
+        assert_eq!(frame.n_antennas, 1);
+        assert_eq!(frame.n_subcarriers, 114);
+        assert_eq!(frame.channel, 6);
+        // With i=0, noise_floor=-90 per build_test_frame.
+        assert_eq!(frame.noise_floor, -90);
+        // With i=0, timestamp_us=0.
+        assert_eq!(frame.timestamp_us, 0);
+        assert_eq!(frame.iq_data.len(), 114 * 2);
+    }
+
+    #[test]
+    fn parse_rejects_wrong_magic() {
+        let mut bad = build_test_frame(MAGIC_V1, 0, 8, 0);
+        // Flip magic to something unrelated.
+        bad[0] = 0xFF;
+        bad[1] = 0xFF;
+        bad[2] = 0xFF;
+        bad[3] = 0xFF;
+        assert!(parse_adr018(&bad).is_none(), "bad magic should not parse");
+    }
+
+    #[test]
+    fn parse_rejects_truncated_header() {
+        let short = vec![0u8; CSI_HEADER_SIZE - 1];
+        assert!(parse_adr018(&short).is_none(), "truncated header must not parse");
+    }
+
+    #[test]
+    fn parse_rejects_truncated_payload() {
+        let mut frame = build_test_frame(MAGIC_V1, 0, 32, 0);
+        // Drop half the declared payload.
+        frame.truncate(CSI_HEADER_SIZE + 20);
+        assert!(parse_adr018(&frame).is_none(), "truncated payload must not parse");
+    }
+}
@@ -0,0 +1,126 @@
+//! Point cloud types + PLY export + Gaussian splat conversion.
+#![allow(dead_code)]
+
+use serde::{Deserialize, Serialize};
+use std::io::Write;
+
+#[derive(Clone, Debug, Serialize, Deserialize)]
+pub struct Point3D {
+    pub x: f32,
+    pub y: f32,
+    pub z: f32,
+}
+
+#[derive(Clone, Debug, Serialize, Deserialize)]
+pub struct ColorPoint {
+    pub x: f32,
+    pub y: f32,
+    pub z: f32,
+    pub r: u8,
+    pub g: u8,
+    pub b: u8,
+    pub intensity: f32,
+}
+
+#[derive(Clone, Debug, Serialize, Deserialize)]
+pub struct PointCloud {
+    pub points: Vec<ColorPoint>,
+    pub timestamp_ms: i64,
+    pub source: String,
+}
+
+impl PointCloud {
+    pub fn new(source: &str) -> Self {
+        Self {
+            points: Vec::new(),
+            timestamp_ms: chrono::Utc::now().timestamp_millis(),
+            source: source.to_string(),
+        }
+    }
+
+    pub fn add(&mut self, x: f32, y: f32, z: f32, r: u8, g: u8, b: u8, intensity: f32) {
+        self.points.push(ColorPoint { x, y, z, r, g, b, intensity });
+    }
+
+    pub fn bounds(&self) -> ([f32; 3], [f32; 3]) {
+        if self.points.is_empty() {
+            return ([0.0; 3], [0.0; 3]);
+        }
+        let mut min = [f32::MAX; 3];
+        let mut max = [f32::MIN; 3];
+        for p in &self.points {
+            min[0] = min[0].min(p.x); min[1] = min[1].min(p.y); min[2] = min[2].min(p.z);
+            max[0] = max[0].max(p.x); max[1] = max[1].max(p.y); max[2] = max[2].max(p.z);
+        }
+        (min, max)
+    }
+}
+
+/// Write point cloud to PLY format (ASCII).
+pub fn write_ply(cloud: &PointCloud, path: &str) -> anyhow::Result<()> {
+    let mut f = std::fs::File::create(path)?;
+    writeln!(f, "ply")?;
+    writeln!(f, "format ascii 1.0")?;
+    writeln!(f, "comment Generated by RuView Dense Point Cloud")?;
+    writeln!(f, "comment Source: {}", cloud.source)?;
+    writeln!(f, "comment Timestamp: {}", cloud.timestamp_ms)?;
+    writeln!(f, "element vertex {}", cloud.points.len())?;
+    writeln!(f, "property float x")?;
+    writeln!(f, "property float y")?;
+    writeln!(f, "property float z")?;
+    writeln!(f, "property uchar red")?;
+    writeln!(f, "property uchar green")?;
+    writeln!(f, "property uchar blue")?;
+    writeln!(f, "property float intensity")?;
+    writeln!(f, "end_header")?;
+    for p in &cloud.points {
+        writeln!(f, "{:.4} {:.4} {:.4} {} {} {} {:.4}", p.x, p.y, p.z, p.r, p.g, p.b, p.intensity)?;
+    }
+    Ok(())
+}
+
+/// Convert point cloud to Gaussian splats for 3D rendering.
+#[derive(Serialize, Deserialize)]
+pub struct GaussianSplat {
+    pub center: [f32; 3],
+    pub color: [f32; 3],
+    pub opacity: f32,
+    pub scale: [f32; 3],
+}
+
+pub fn to_gaussian_splats(cloud: &PointCloud) -> Vec<GaussianSplat> {
+    // Cluster points into voxels and create one Gaussian per cluster
+    let voxel_size = 0.08;  // smaller voxels = more detail = visible movement
+    let mut cells: std::collections::HashMap<(i32, i32, i32), Vec<&ColorPoint>> = std::collections::HashMap::new();
+
+    for p in &cloud.points {
+        let key = (
+            (p.x / voxel_size).floor() as i32,
+            (p.y / voxel_size).floor() as i32,
+            (p.z / voxel_size).floor() as i32,
+        );
+        cells.entry(key).or_default().push(p);
+    }
+
+    cells.values().map(|pts| {
+        let n = pts.len() as f32;
+        let cx = pts.iter().map(|p| p.x).sum::<f32>() / n;
+        let cy = pts.iter().map(|p| p.y).sum::<f32>() / n;
+        let cz = pts.iter().map(|p| p.z).sum::<f32>() / n;
+        let cr = pts.iter().map(|p| p.r as f32).sum::<f32>() / n / 255.0;
+        let cg = pts.iter().map(|p| p.g as f32).sum::<f32>() / n / 255.0;
+        let cb = pts.iter().map(|p| p.b as f32).sum::<f32>() / n / 255.0;
+
+        // Scale based on point spread
+        let sx = pts.iter().map(|p| (p.x - cx).abs()).sum::<f32>() / n + 0.01;
+        let sy = pts.iter().map(|p| (p.y - cy).abs()).sum::<f32>() / n + 0.01;
+        let sz = pts.iter().map(|p| (p.z - cz).abs()).sum::<f32>() / n + 0.01;
+
+        GaussianSplat {
+            center: [cx, cy, cz],
+            color: [cr, cg, cb],
+            opacity: (n / 10.0).min(1.0),
+            scale: [sx, sy, sz],
+        }
+    }).collect()
+}
@@ -0,0 +1,232 @@
+//! HTTP server — live camera + ESP32 CSI + fusion → real-time point cloud.
+
+use crate::brain_bridge;
+use crate::camera;
+use crate::csi_pipeline;
+use crate::depth;
+use crate::fusion;
+use crate::pointcloud;
+use axum::{
+    extract::State,
+    response::Html,
+    routing::get,
+    Json, Router,
+};
+use std::sync::{Arc, Mutex};
+
+struct AppState {
+    latest_cloud: Mutex<pointcloud::PointCloud>,
+    latest_splats: Mutex<Vec<pointcloud::GaussianSplat>>,
+    latest_pipeline: Mutex<Option<csi_pipeline::PipelineOutput>>,
+    frame_count: Mutex<u64>,
+    use_camera: bool,
+}
+
+/// Start the HTTP/viewer server bound to `bind` (e.g.
+/// `"127.0.0.1:9880"` — the safe default — or `"0.0.0.0:9880"` to expose
+/// the viewer to the LAN).
+///
+/// **Security**: the viewer streams live camera/CSI/vitals data. Bind to
+/// `127.0.0.1` unless you intentionally want remote viewers.
+pub async fn serve(bind: &str, _brain: Option<&str>) -> anyhow::Result<()> {
+    let has_camera = camera::camera_available();
+
+    // Start CSI pipeline — listens for UDP CSI data from ESP32 nodes.
+    // Kept on 0.0.0.0 because ESP32 nodes are remote devices on the LAN.
+    let csi_pipeline_state = csi_pipeline::start_pipeline("0.0.0.0:3333");
+    eprintln!("  CSI pipeline: UDP port 3333 (ADR-018 binary frames)");
+
+    let initial_cloud = if has_camera {
+        capture_camera_cloud()
+    } else {
+        demo_cloud()
+    };
+    let initial_splats = pointcloud::to_gaussian_splats(&initial_cloud);
+
+    let state = Arc::new(AppState {
+        latest_cloud: Mutex::new(initial_cloud),
+        latest_splats: Mutex::new(initial_splats),
+        latest_pipeline: Mutex::new(None),
+        frame_count: Mutex::new(0),
+        use_camera: has_camera,
+    });
+
+    // Background: capture + fuse every 500ms (motion-adaptive)
+    let bg = state.clone();
+    let bg_csi = csi_pipeline_state.clone();
+    let bg_cam = has_camera;
+    tokio::spawn(async move {
+        let mut skip_depth = false;
+        loop {
+            // Motion-adaptive: check CSI motion score
+            let pipeline_out = Some(csi_pipeline::get_pipeline_output(&bg_csi));
+            if let Some(ref out) = pipeline_out {
+                // Only run expensive depth when motion detected or every 5th frame
+                let frame_num = *bg.frame_count.lock().unwrap();
+                skip_depth = !out.motion_detected && frame_num % 5 != 0;
+            }
+            let pipeline_clone = pipeline_out.clone();
+            *bg.latest_pipeline.lock().unwrap() = pipeline_out;
+            let pipeline_out = pipeline_clone;
+
+            let interval = if skip_depth { 1000 } else { 500 }; // slower when no motion
+            tokio::time::sleep(std::time::Duration::from_millis(interval)).await;
+
+            let (cloud, luminance) = if bg_cam && !skip_depth {
+                tokio::task::spawn_blocking(capture_camera_cloud_with_luminance)
+                    .await.unwrap_or_else(|_| (demo_cloud(), None))
+            } else {
+                // Reuse previous cloud when no motion
+                (bg.latest_cloud.lock().unwrap().clone(), None)
+            };
+            // Feed luminance into the CSI pipeline so is_dark toggles for the
+            // viewer. The lock is held briefly here — the UDP thread never
+            // touches it (messages go through the mpsc channel).
+            if let Some(lum) = luminance {
+                if let Ok(mut st) = bg_csi.lock() {
+                    st.set_light_level(lum);
+                }
+            }
+            let splats = pointcloud::to_gaussian_splats(&cloud);
+            *bg.latest_cloud.lock().unwrap() = cloud;
+            *bg.latest_splats.lock().unwrap() = splats;
+            let frame_num = {
+                let mut fc = bg.frame_count.lock().unwrap();
+                *fc += 1;
+                *fc
+            };
+
+            // Brain sync — sparse, every 120 frames (~60 seconds)
+            if frame_num % 120 == 0 {
+                if let Some(ref out) = pipeline_out {
+                    brain_bridge::sync_to_brain(out, frame_num).await;
+                }
+            }
+        }
+    });
+
+    if has_camera { eprintln!("  Camera: LIVE (/dev/video0)"); }
+    else { eprintln!("  Camera: DEMO"); }
+
+    let app = Router::new()
+        .route("/", get(index))
+        .route("/api/cloud", get(api_cloud))
+        .route("/api/splats", get(api_splats))
+        .route("/api/status", get(api_status))
+        .route("/health", get(api_health))
+        .with_state(state);
+
+    println!("╔══════════════════════════════════════════════╗");
+    println!("║  RuView Dense Point Cloud — ALL SENSORS      ║");
+    println!("╚══════════════════════════════════════════════╝");
+    println!("  Viewer: http://{bind}/");
+    if bind.starts_with("0.0.0.0") || bind.starts_with("::") {
+        eprintln!(
+            "  WARNING: bound to {bind} — camera/CSI/vitals are exposed \
+             to the network. Use --bind 127.0.0.1:9880 to restrict to loopback."
+        );
+    }
+
+    let listener = tokio::net::TcpListener::bind(bind).await?;
+    axum::serve(listener, app).await?;
+    Ok(())
+}
+
+fn capture_camera_cloud() -> pointcloud::PointCloud {
+    capture_camera_cloud_with_luminance().0
+}
+
+/// Grab one camera frame, backproject it to a point cloud, and return the
+/// mean luminance alongside (used to drive `set_light_level` for night mode).
+fn capture_camera_cloud_with_luminance() -> (pointcloud::PointCloud, Option<f32>) {
+    let config = camera::CameraConfig::default();
+    match camera::capture_frame(&config) {
+        Ok(frame) => {
+            // Mean luminance across the RGB frame (BT.601 coefficients).
+            let pixels = (frame.width as usize) * (frame.height as usize);
+            let mut sum = 0.0f64;
+            let mut n = 0usize;
+            for chunk in frame.rgb.chunks_exact(3).take(pixels) {
+                sum += 0.299 * chunk[0] as f64
+                     + 0.587 * chunk[1] as f64
+                     + 0.114 * chunk[2] as f64;
+                n += 1;
+            }
+            let lum = if n > 0 { Some((sum / n as f64) as f32) } else { None };
+
+            let cloud = match depth::estimate_depth(&frame.rgb, frame.width, frame.height) {
+                Ok(dm) => {
+                    let intr = depth::CameraIntrinsics::default();
+                    depth::backproject_depth(&dm, &intr, Some(&frame.rgb), 2)
+                }
+                Err(_) => depth::demo_depth_cloud(),
+            };
+            (cloud, lum)
+        }
+        Err(_) => (depth::demo_depth_cloud(), None),
+    }
+}
+
+fn demo_cloud() -> pointcloud::PointCloud {
+    let occ = fusion::demo_occupancy();
+    let wc = fusion::occupancy_to_pointcloud(&occ);
+    let dc = depth::demo_depth_cloud();
+    fusion::fuse_clouds(&[&wc, &dc], 0.05)
+}
+
+async fn api_cloud(State(state): State<Arc<AppState>>) -> Json<serde_json::Value> {
+    let cloud = state.latest_cloud.lock().unwrap();
+    let (min, max) = cloud.bounds();
+    let frames = *state.frame_count.lock().unwrap();
+    let pipeline = state.latest_pipeline.lock().unwrap();
+    Json(serde_json::json!({
+        "points": cloud.points.len(),
+        "bounds_min": min, "bounds_max": max,
+        "live": state.use_camera,
+        "frame": frames,
+        "pipeline": &*pipeline,
+        "cloud": cloud.points.iter().take(1000).collect::<Vec<_>>(),
+    }))
+}
+
+async fn api_splats(State(state): State<Arc<AppState>>) -> Json<serde_json::Value> {
+    let splats = state.latest_splats.lock().unwrap();
+    let frames = *state.frame_count.lock().unwrap();
+    let pipeline = state.latest_pipeline.lock().unwrap();
+    Json(serde_json::json!({
+        "splats": &*splats,
+        "count": splats.len(),
+        "live": state.use_camera,
+        "frame": frames,
+        "pipeline": &*pipeline,
+        "timestamp": chrono::Utc::now().timestamp_millis(),
+    }))
+}
+
+async fn api_status(State(state): State<Arc<AppState>>) -> Json<serde_json::Value> {
+    let frames = *state.frame_count.lock().unwrap();
+    let pipeline = state.latest_pipeline.lock().unwrap();
+    Json(serde_json::json!({
+        "status": "ok",
+        "version": env!("CARGO_PKG_VERSION"),
+        "live": state.use_camera,
+        "camera": if state.use_camera { "/dev/video0" } else { "demo" },
+        "csi_pipeline": "active (UDP:3333)",
+        "pipeline": &*pipeline,
+        "frames_captured": frames,
+    }))
+}
+
+async fn api_health() -> Json<serde_json::Value> {
+    Json(serde_json::json!({"status": "ok"}))
+}
+
+/// Viewer HTML/JS, compiled into the binary at build time. Keep the
+/// markup in `viewer.html` to keep this file under the 500-LOC limit and
+/// to make it trivially editable (no Rust rebuild when tweaking JS).
+static VIEWER_HTML: &str = include_str!("viewer.html");
+
+async fn index() -> Html<&'static str> {
+    Html(VIEWER_HTML)
+}
+
@@ -0,0 +1,497 @@
+//! Training pipeline — collect spatial observations and train depth/occupancy models.
+//!
+//! Three training modes:
+//! 1. **Depth calibration**: capture camera frames + known distances → calibrate
+//!    the luminance-to-depth mapping parameters
+//! 2. **CSI occupancy training**: capture CSI with known occupancy ground truth →
+//!    train the tomography weights for this room geometry
+//! 3. **Brain integration**: store spatial observations as brain memories for
+//!    DPO training — "this depth estimate was correct" vs "this was wrong"
+
+use crate::fusion::OccupancyVolume;
+use anyhow::{anyhow, Result};
+use serde::{Deserialize, Serialize};
+use std::path::{Path, PathBuf};
+
+/// Reject a user-supplied path that contains `..` components (path traversal
+/// attempt) and return a normalised [`PathBuf`]. We only reject `..`; other
+/// components (including relative prefixes and `~`) are accepted verbatim —
+/// the caller is responsible for tilde expansion if needed.
+pub fn sanitize_data_path(raw: &str) -> Result<PathBuf> {
+    let p = PathBuf::from(raw);
+    for comp in p.components() {
+        if matches!(comp, std::path::Component::ParentDir) {
+            return Err(anyhow!(
+                "refusing to use data dir with `..` traversal component: {raw}"
+            ));
+        }
+    }
+    Ok(p)
+}
+
+/// Ensure `child` (after joining to `base`) stays inside the canonicalised
+/// `base` directory. Returns the canonical child path on success. Used by
+/// every filesystem write site in this module to prevent path-traversal
+/// through user-supplied names.
+fn safe_join(base: &Path, child: &str) -> Result<PathBuf> {
+    // Reject absolute children and any `..` components up front.
+    let child_path = Path::new(child);
+    if child_path.is_absolute() {
+        return Err(anyhow!("child path must be relative: {child}"));
+    }
+    for comp in child_path.components() {
+        if matches!(comp, std::path::Component::ParentDir) {
+            return Err(anyhow!("child path may not contain `..`: {child}"));
+        }
+    }
+
+    let joined = base.join(child_path);
+    // Canonicalise base (must exist) and verify joined starts with it. If the
+    // joined file doesn't exist yet we canonicalise the parent.
+    let canonical_base = base.canonicalize()
+        .map_err(|e| anyhow!("data_dir not accessible {}: {e}", base.display()))?;
+    let canonical_parent = joined
+        .parent()
+        .ok_or_else(|| anyhow!("no parent for {}", joined.display()))?;
+    let canonical_parent = canonical_parent
+        .canonicalize()
+        .map_err(|e| anyhow!("parent not accessible {}: {e}", canonical_parent.display()))?;
+    if !canonical_parent.starts_with(&canonical_base) {
+        return Err(anyhow!(
+            "refusing to write outside data_dir: {}",
+            joined.display()
+        ));
+    }
+    Ok(canonical_parent.join(
+        joined.file_name().ok_or_else(|| anyhow!("no filename for {}", joined.display()))?,
+    ))
+}
+
+/// Training data sample — a snapshot of the scene.
+#[derive(Serialize, Deserialize)]
+pub struct TrainingSample {
+    pub timestamp_ms: i64,
+    pub source: String,
+    /// Camera depth map (downsampled, in meters)
+    pub depth_map: Option<Vec<f32>>,
+    pub depth_width: u32,
+    pub depth_height: u32,
+    /// WiFi occupancy grid
+    pub occupancy: Option<OccupancyData>,
+    /// Ground truth (if available)
+    pub ground_truth: Option<GroundTruth>,
+    /// Quality score (0.0-1.0, rated by user or self-eval)
+    pub quality: f32,
+}
+
+#[derive(Serialize, Deserialize)]
+pub struct OccupancyData {
+    pub densities: Vec<f64>,
+    pub nx: usize,
+    pub ny: usize,
+    pub nz: usize,
+}
+
+impl From<&OccupancyVolume> for OccupancyData {
+    fn from(vol: &OccupancyVolume) -> Self {
+        Self {
+            densities: vol.densities.clone(),
+            nx: vol.nx, ny: vol.ny, nz: vol.nz,
+        }
+    }
+}
+
+#[derive(Serialize, Deserialize)]
+pub struct GroundTruth {
+    /// Known distances to reference points (e.g., wall at 3.0m)
+    pub reference_distances: Vec<ReferencePoint>,
+    /// Known occupancy state (person present/absent + location)
+    pub occupancy_label: Option<String>,
+}
+
+#[derive(Serialize, Deserialize)]
+pub struct ReferencePoint {
+    pub name: String,
+    pub x_pixel: u32,
+    pub y_pixel: u32,
+    pub true_distance_m: f32,
+}
+
+/// Training session — accumulates samples and learns calibration.
+pub struct TrainingSession {
+    pub samples: Vec<TrainingSample>,
+    pub calibration: DepthCalibration,
+    pub data_dir: PathBuf,
+}
+
+/// Depth calibration parameters — maps luminance to real depth.
+#[derive(Clone, Serialize, Deserialize)]
+pub struct DepthCalibration {
+    pub scale: f32,       // multiplier for depth values
+    pub offset: f32,      // additive offset
+    pub near_clip: f32,   // minimum valid depth
+    pub far_clip: f32,    // maximum valid depth
+    pub gamma: f32,       // nonlinear correction (luminance^gamma → depth)
+    pub samples_used: u32,
+    pub rmse: f32,        // root mean square error against ground truth
+}
+
+impl Default for DepthCalibration {
+    fn default() -> Self {
+        Self {
+            scale: 4.0,
+            offset: 1.0,
+            near_clip: 0.3,
+            far_clip: 8.0,
+            gamma: 1.0,
+            samples_used: 0,
+            rmse: f32::MAX,
+        }
+    }
+}
+
+impl TrainingSession {
+    /// Create a new training session rooted at `data_dir`.
+    ///
+    /// `data_dir` must not contain `..` components — we reject path traversal
+    /// attempts from CLI/API input. The directory is created if missing and
+    /// then canonicalised so every subsequent write stays inside it.
+    pub fn new(data_dir: &str) -> Result<Self> {
+        let path = sanitize_data_path(data_dir)?;
+        std::fs::create_dir_all(&path)
+            .map_err(|e| anyhow!("failed to create data_dir {}: {e}", path.display()))?;
+        // Canonicalise so path-traversal checks in safe_join have a fixed root.
+        let path = path
+            .canonicalize()
+            .map_err(|e| anyhow!("cannot canonicalise data_dir {}: {e}", path.display()))?;
+
+        // Load existing calibration if available
+        let cal_path = safe_join(&path, "calibration.json")
+            // safe_join needs the parent to exist; for initial load that's always data_dir
+            .or_else(|_| Ok::<_, anyhow::Error>(path.join("calibration.json")))?;
+        let calibration = if cal_path.exists() {
+            let data = std::fs::read_to_string(&cal_path)?;
+            serde_json::from_str(&data).unwrap_or_default()
+        } else {
+            DepthCalibration::default()
+        };
+
+        Ok(Self {
+            samples: Vec::new(),
+            calibration,
+            data_dir: path,
+        })
+    }
+
+    /// Add a training sample with optional ground truth.
+    pub fn add_sample(
+        &mut self,
+        depth_map: Option<Vec<f32>>,
+        width: u32,
+        height: u32,
+        occupancy: Option<&OccupancyVolume>,
+        ground_truth: Option<GroundTruth>,
+        quality: f32,
+    ) {
+        let sample = TrainingSample {
+            timestamp_ms: chrono::Utc::now().timestamp_millis(),
+            source: "capture".to_string(),
+            depth_map,
+            depth_width: width,
+            depth_height: height,
+            occupancy: occupancy.map(OccupancyData::from),
+            ground_truth,
+            quality,
+        };
+        self.samples.push(sample);
+    }
+
+    /// Calibrate depth estimation using ground truth reference points.
+    ///
+    /// Finds optimal scale, offset, and gamma to minimize RMSE
+    /// between estimated and true depths at reference points.
+    pub fn calibrate_depth(&mut self) -> Result<DepthCalibration> {
+        let mut best = self.calibration.clone();
+        let mut best_rmse = f32::MAX;
+
+        // Collect all reference points across samples
+        let refs: Vec<(f32, f32)> = self.samples.iter()
+            .filter_map(|s| {
+                let gt = s.ground_truth.as_ref()?;
+                let dm = s.depth_map.as_ref()?;
+                Some(gt.reference_distances.iter().filter_map(|rp| {
+                    let idx = (rp.y_pixel * s.depth_width + rp.x_pixel) as usize;
+                    dm.get(idx).map(|&est| (est, rp.true_distance_m))
+                }).collect::<Vec<_>>())
+            })
+            .flatten()
+            .collect();
+
+        if refs.is_empty() {
+            eprintln!("  No reference points — using default calibration");
+            return Ok(best);
+        }
+
+        eprintln!("  Calibrating with {} reference points...", refs.len());
+
+        // Grid search over scale, offset, gamma
+        for scale_i in 0..20 {
+            let scale = 1.0 + scale_i as f32 * 0.5;
+            for offset_i in 0..10 {
+                let offset = offset_i as f32 * 0.5;
+                for gamma_i in 5..15 {
+                    let gamma = gamma_i as f32 * 0.2;
+
+                    let rmse = refs.iter()
+                        .map(|&(est, truth)| {
+                            let calibrated = offset + est.powf(gamma) * scale;
+                            (calibrated - truth).powi(2)
+                        })
+                        .sum::<f32>() / refs.len() as f32;
+                    let rmse = rmse.sqrt();
+
+                    if rmse < best_rmse {
+                        best_rmse = rmse;
+                        best = DepthCalibration {
+                            scale, offset, gamma,
+                            near_clip: 0.3, far_clip: 8.0,
+                            samples_used: refs.len() as u32,
+                            rmse,
+                        };
+                    }
+                }
+            }
+        }
+
+        eprintln!("  Best calibration: scale={:.2} offset={:.2} gamma={:.2} RMSE={:.4}m",
+            best.scale, best.offset, best.gamma, best.rmse);
+
+        self.calibration = best.clone();
+        self.save_calibration()?;
+        Ok(best)
+    }
+
+    /// Train CSI occupancy model — adjust tomography weights.
+    ///
+    /// Uses samples with known occupancy labels to optimize the
+    /// attenuation-to-density mapping.
+    pub fn train_occupancy(&self) -> Result<OccupancyCalibration> {
+        let labeled: Vec<&TrainingSample> = self.samples.iter()
+            .filter(|s| s.ground_truth.as_ref().and_then(|g| g.occupancy_label.as_ref()).is_some())
+            .collect();
+
+        if labeled.is_empty() {
+            eprintln!("  No labeled occupancy samples — using defaults");
+            return Ok(OccupancyCalibration::default());
+        }
+
+        eprintln!("  Training occupancy model with {} samples...", labeled.len());
+
+        // Simple threshold optimization — find the density threshold
+        // that best separates occupied vs unoccupied
+        let mut best_threshold = 0.3f64;
+        let mut best_accuracy = 0.0f64;
+
+        for thresh_i in 1..20 {
+            let threshold = thresh_i as f64 * 0.05;
+            let mut correct = 0;
+            let mut total = 0;
+
+            for sample in &labeled {
+                if let Some(ref occ) = sample.occupancy {
+                    let label = sample.ground_truth.as_ref().unwrap()
+                        .occupancy_label.as_ref().unwrap();
+                    let is_occupied = label == "occupied" || label == "present";
+                    let detected = occ.densities.iter().any(|&d| d > threshold);
+                    if detected == is_occupied { correct += 1; }
+                    total += 1;
+                }
+            }
+
+            let accuracy = correct as f64 / total.max(1) as f64;
+            if accuracy > best_accuracy {
+                best_accuracy = accuracy;
+                best_threshold = threshold;
+            }
+        }
+
+        let cal = OccupancyCalibration {
+            density_threshold: best_threshold,
+            accuracy: best_accuracy,
+            samples_used: labeled.len() as u32,
+        };
+
+        eprintln!("  Occupancy threshold={:.2} accuracy={:.1}%", cal.density_threshold, cal.accuracy * 100.0);
+
+        // Save (path-traversal safe: constant filename under canonical data_dir)
+        let path = safe_join(&self.data_dir, "occupancy_calibration.json")?;
+        std::fs::write(&path, serde_json::to_string_pretty(&cal)?)?;
+
+        Ok(cal)
+    }
+
+    /// Export training data as preference pairs for DPO training on the brain.
+    ///
+    /// Good samples (quality > 0.7) → chosen
+    /// Bad samples (quality < 0.3) → rejected
+    pub fn export_preference_pairs(&self) -> Result<Vec<PreferencePair>> {
+        let mut pairs = Vec::new();
+
+        let good: Vec<&TrainingSample> = self.samples.iter()
+            .filter(|s| s.quality > 0.7)
+            .collect();
+        let bad: Vec<&TrainingSample> = self.samples.iter()
+            .filter(|s| s.quality < 0.3)
+            .collect();
+
+        for (g, b) in good.iter().zip(bad.iter()) {
+            pairs.push(PreferencePair {
+                chosen: format!(
+                    "Depth estimation at {}ms: {} points, quality {:.2}",
+                    g.timestamp_ms,
+                    g.depth_map.as_ref().map(|d| d.len()).unwrap_or(0),
+                    g.quality
+                ),
+                rejected: format!(
+                    "Depth estimation at {}ms: {} points, quality {:.2}",
+                    b.timestamp_ms,
+                    b.depth_map.as_ref().map(|d| d.len()).unwrap_or(0),
+                    b.quality
+                ),
+            });
+        }
+
+        // Save pairs (path-traversal safe: constant filename under canonical data_dir)
+        let path = safe_join(&self.data_dir, "preference_pairs.jsonl")?;
+        let mut f = std::fs::File::create(&path)?;
+        for pair in &pairs {
+            use std::io::Write;
+            writeln!(f, "{}", serde_json::to_string(pair)?)?;
+        }
+
+        eprintln!("  Exported {} preference pairs to {}", pairs.len(), path.display());
+        Ok(pairs)
+    }
+
+    /// Send training results to the ruOS brain for storage.
+    pub async fn submit_to_brain(&self, brain_url: &str) -> Result<u32> {
+        let client = reqwest::Client::builder()
+            .timeout(std::time::Duration::from_secs(10))
+            .build()?;
+
+        let mut stored = 0u32;
+
+        // Store calibration as brain memory
+        let _cal_json = serde_json::to_string(&self.calibration)?;
+        let body = serde_json::json!({
+            "category": "spatial-calibration",
+            "content": format!("Depth calibration: scale={:.2} offset={:.2} gamma={:.2} RMSE={:.4}m ({} samples)",
+                self.calibration.scale, self.calibration.offset, self.calibration.gamma,
+                self.calibration.rmse, self.calibration.samples_used),
+        });
+        if client.post(format!("{brain_url}/memories"))
+            .json(&body).send().await.is_ok() {
+            stored += 1;
+        }
+
+        // Store good observations
+        for sample in self.samples.iter().filter(|s| s.quality > 0.5) {
+            let body = serde_json::json!({
+                "category": "spatial-observation",
+                "content": format!("Point cloud capture: {} depth points, quality {:.2}, occupancy {}",
+                    sample.depth_map.as_ref().map(|d| d.len()).unwrap_or(0),
+                    sample.quality,
+                    sample.occupancy.as_ref().map(|o| format!("{}x{}x{}", o.nx, o.ny, o.nz)).unwrap_or("none".into())),
+            });
+            if client.post(format!("{brain_url}/memories"))
+                .json(&body).send().await.is_ok() {
+                stored += 1;
+            }
+        }
+
+        eprintln!("  Submitted {} observations to brain", stored);
+        Ok(stored)
+    }
+
+    /// Save current calibration to disk (path-traversal safe).
+    fn save_calibration(&self) -> Result<()> {
+        let path = safe_join(&self.data_dir, "calibration.json")?;
+        std::fs::write(&path, serde_json::to_string_pretty(&self.calibration)?)?;
+        Ok(())
+    }
+
+    /// Save all samples to disk (path-traversal safe).
+    pub fn save_samples(&self) -> Result<()> {
+        let path = safe_join(&self.data_dir, "samples.json")?;
+        std::fs::write(&path, serde_json::to_string_pretty(&self.samples)?)?;
+        eprintln!("  Saved {} samples to {}", self.samples.len(), path.display());
+        Ok(())
+    }
+
+    /// Load samples from disk (path-traversal safe).
+    pub fn load_samples(&mut self) -> Result<()> {
+        let path = safe_join(&self.data_dir, "samples.json")?;
+        if path.exists() {
+            let data = std::fs::read_to_string(&path)?;
+            self.samples = serde_json::from_str(&data)?;
+            eprintln!("  Loaded {} samples", self.samples.len());
+        }
+        Ok(())
+    }
+}
+
+#[derive(Serialize, Deserialize)]
+pub struct OccupancyCalibration {
+    pub density_threshold: f64,
+    pub accuracy: f64,
+    pub samples_used: u32,
+}
+
+impl Default for OccupancyCalibration {
+    fn default() -> Self {
+        Self { density_threshold: 0.3, accuracy: 0.0, samples_used: 0 }
+    }
+}
+
+#[derive(Serialize, Deserialize)]
+pub struct PreferencePair {
+    pub chosen: String,
+    pub rejected: String,
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn sanitize_rejects_parent_dir_traversal() {
+        assert!(sanitize_data_path("../etc/passwd").is_err());
+        assert!(sanitize_data_path("foo/../bar").is_err());
+        assert!(sanitize_data_path("/tmp/.. /evil").is_ok(), "`.. ` is not ParentDir");
+    }
+
+    #[test]
+    fn sanitize_accepts_relative_child() {
+        assert!(sanitize_data_path("data/ruview").is_ok());
+        assert!(sanitize_data_path("./foo").is_ok());
+    }
+
+    #[test]
+    fn training_session_new_rejects_traversal() {
+        // Even if the filesystem has such a path, TrainingSession should refuse.
+        let err = TrainingSession::new("../etc/passwd").err();
+        assert!(err.is_some(), "traversal path must be rejected");
+    }
+
+    #[test]
+    fn training_session_new_accepts_child_path() {
+        // Use a unique tmpdir to avoid cross-test interference.
+        let tmp = std::env::temp_dir().join(format!("ruview-train-test-{}", std::process::id()));
+        let _ = std::fs::remove_dir_all(&tmp);
+        let sess = TrainingSession::new(tmp.to_str().unwrap())
+            .expect("TrainingSession should accept a clean tmpdir");
+        // data_dir should have been canonicalised to an absolute path.
+        assert!(sess.data_dir.is_absolute());
+        let _ = std::fs::remove_dir_all(&tmp);
+    }
+}
@@ -0,0 +1,229 @@
+<!DOCTYPE html>
+<html>
+<head>
+    <title>RuView — Camera + WiFi CSI Point Cloud</title>
+    <style>
+        body { margin: 0; background: #0a0a0a; color: #e8a634; font-family: monospace; }
+        canvas { display: block; }
+        #info { position: absolute; top: 10px; left: 10px; padding: 12px; background: rgba(0,0,0,0.85); border: 1px solid #e8a634; border-radius: 6px; min-width: 240px; font-size: 13px; line-height: 1.5; }
+        .live { color: #4f4; } .demo { color: #f44; }
+        .section { margin-top: 6px; padding-top: 6px; border-top: 1px solid #333; }
+        .label { color: #888; }
+    </style>
+    <script src="https://cdnjs.cloudflare.com/ajax/libs/three.js/r128/three.min.js"></script>
+    <script src="https://cdn.jsdelivr.net/npm/three@0.128.0/examples/js/controls/OrbitControls.js"></script>
+</head>
+<body>
+    <div id="info">
+        <h3 style="margin:0 0 8px 0">RuView Point Cloud</h3>
+        <div id="stats">Loading...</div>
+    </div>
+    <script>
+        var scene = new THREE.Scene();
+        scene.background = new THREE.Color(0x0a0a0a);
+        var camera = new THREE.PerspectiveCamera(75, window.innerWidth/window.innerHeight, 0.1, 100);
+        camera.position.set(0, 2, -4);
+        camera.lookAt(0, 0, 2);
+
+        var renderer = new THREE.WebGLRenderer({ antialias: true });
+        renderer.setSize(window.innerWidth, window.innerHeight);
+        document.body.appendChild(renderer.domElement);
+
+        var controls = new THREE.OrbitControls(camera, renderer.domElement);
+        controls.enableDamping = true;
+        controls.target.set(0, 0, 2);
+
+        var pointsMesh = null;
+        var lastFrame = -1;
+        var skeletonGroup = null;
+        var prevTimestamp = 0;
+        var frameRateVal = 0;
+
+        // COCO skeleton connections: pairs of keypoint indices
+        // 0=nose 1=leftEye 2=rightEye 3=leftEar 4=rightEar
+        // 5=leftShoulder 6=rightShoulder 7=leftElbow 8=rightElbow
+        // 9=leftWrist 10=rightWrist 11=leftHip 12=rightHip
+        // 13=leftKnee 14=rightKnee 15=leftAnkle 16=rightAnkle
+        var COCO_BONES = [
+            [0,1],[0,2],[1,3],[2,4],
+            [5,6],[5,7],[7,9],[6,8],[8,10],
+            [5,11],[6,12],[11,12],
+            [11,13],[13,15],[12,14],[14,16]
+        ];
+
+        function clearSkeleton() {
+            if (skeletonGroup) {
+                scene.remove(skeletonGroup);
+                skeletonGroup.traverse(function(obj) {
+                    if (obj.geometry) obj.geometry.dispose();
+                    if (obj.material) obj.material.dispose();
+                });
+                skeletonGroup = null;
+            }
+        }
+
+        function drawSkeleton(keypoints) {
+            clearSkeleton();
+            if (!keypoints || keypoints.length < 17) return;
+            skeletonGroup = new THREE.Group();
+
+            // Map keypoints from [0,1] to scene coords
+            // x: [-2, 2], y: [2, -2] (flip y), z: fixed at 2
+            var sphereGeo = new THREE.SphereGeometry(0.04, 8, 8);
+            var sphereMat = new THREE.MeshBasicMaterial({ color: 0xffff00 });
+            var positions3D = [];
+            var i, kp, sx, sy;
+            for (i = 0; i < 17; i++) {
+                kp = keypoints[i];
+                if (!kp) { positions3D.push(null); continue; }
+                sx = (kp[0] - 0.5) * 4;
+                sy = (0.5 - kp[1]) * 4;
+                positions3D.push([sx, sy, 2]);
+                var sphere = new THREE.Mesh(sphereGeo, sphereMat);
+                sphere.position.set(sx, sy, 2);
+                skeletonGroup.add(sphere);
+            }
+
+            // Draw bones as white lines
+            var lineMat = new THREE.LineBasicMaterial({ color: 0xffffff, linewidth: 2 });
+            var b, a, bIdx;
+            for (b = 0; b < COCO_BONES.length; b++) {
+                a = COCO_BONES[b][0];
+                bIdx = COCO_BONES[b][1];
+                if (!positions3D[a] || !positions3D[bIdx]) continue;
+                var lineGeo = new THREE.BufferGeometry();
+                var verts = new Float32Array([
+                    positions3D[a][0], positions3D[a][1], positions3D[a][2],
+                    positions3D[bIdx][0], positions3D[bIdx][1], positions3D[bIdx][2]
+                ]);
+                lineGeo.setAttribute("position", new THREE.BufferAttribute(verts, 3));
+                var line = new THREE.Line(lineGeo, lineMat);
+                skeletonGroup.add(line);
+            }
+
+            scene.add(skeletonGroup);
+        }
+
+        async function fetchCloud() {
+            try {
+                var resp = await fetch("/api/splats");
+                var data = await resp.json();
+                if (data.splats && data.frame !== lastFrame) {
+                    // Compute CSI frame rate
+                    var now = Date.now();
+                    if (prevTimestamp > 0) {
+                        var dt = (now - prevTimestamp) / 1000.0;
+                        if (dt > 0) frameRateVal = (1.0 / dt).toFixed(1);
+                    }
+                    prevTimestamp = now;
+                    lastFrame = data.frame;
+                    updateSplats(data.splats);
+
+                    // Draw skeleton if available
+                    var pipe = data.pipeline;
+                    if (pipe && pipe.skeleton && pipe.skeleton.keypoints) {
+                        drawSkeleton(pipe.skeleton.keypoints);
+                    } else {
+                        clearSkeleton();
+                    }
+
+                    // Build info panel
+                    var mode = data.live
+                        ? '<span class="live">&#9679; LIVE</span>'
+                        : '<span class="demo">&#9679; DEMO</span>';
+                    var html = mode + " Camera + CSI<br>"
+                        + "Splats: " + data.count + "<br>"
+                        + "Frame: " + data.frame;
+
+                    // CSI frame rate
+                    html += '<div class="section">'
+                        + '<span class="label">CSI Rate:</span> '
+                        + frameRateVal + " fps</div>";
+
+                    // Skeleton confidence
+                    if (pipe && pipe.skeleton && pipe.skeleton.confidence !== undefined) {
+                        var conf = (pipe.skeleton.confidence * 100).toFixed(0);
+                        html += '<div class="section">'
+                            + '<span class="label">Skeleton:</span> '
+                            + conf + "% confidence</div>";
+                    }
+
+                    // Weather data
+                    if (pipe && pipe.weather) {
+                        var w = pipe.weather;
+                        html += '<div class="section">'
+                            + '<span class="label">Weather:</span> ';
+                        if (w.temperature !== undefined) {
+                            html += w.temperature + "&deg;C";
+                        }
+                        if (w.conditions) {
+                            html += " " + w.conditions;
+                        }
+                        html += "</div>";
+                    }
+
+                    // Building count from geo
+                    if (pipe && pipe.geo && pipe.geo.building_count !== undefined) {
+                        html += '<div class="section">'
+                            + '<span class="label">Buildings:</span> '
+                            + pipe.geo.building_count + "</div>";
+                    }
+
+                    // Vitals
+                    if (pipe && pipe.vitals) {
+                        var v = pipe.vitals;
+                        html += '<div class="section">'
+                            + '<span class="label">Vitals:</span> ';
+                        if (v.breathing_rate !== undefined) {
+                            html += "BR " + v.breathing_rate + "/min";
+                        }
+                        if (v.motion_score !== undefined) {
+                            html += " Motion " + (v.motion_score * 100).toFixed(0) + "%";
+                        }
+                        html += "</div>";
+                    }
+
+                    document.getElementById("stats").innerHTML = html;
+                }
+            } catch(e) {}
+        }
+        fetchCloud();
+        setInterval(fetchCloud, 500);
+
+        function updateSplats(splats) {
+            if (pointsMesh) scene.remove(pointsMesh);
+            var geometry = new THREE.BufferGeometry();
+            var positions = new Float32Array(splats.length * 3);
+            var colors = new Float32Array(splats.length * 3);
+            var i, s;
+            for (i = 0; i < splats.length; i++) {
+                s = splats[i];
+                positions[i*3] = s.center[0];
+                positions[i*3+1] = -s.center[1];
+                positions[i*3+2] = s.center[2];
+                colors[i*3] = s.color[0];
+                colors[i*3+1] = s.color[1];
+                colors[i*3+2] = s.color[2];
+            }
+            geometry.setAttribute("position", new THREE.BufferAttribute(positions, 3));
+            geometry.setAttribute("color", new THREE.BufferAttribute(colors, 3));
+            pointsMesh = new THREE.Points(geometry, new THREE.PointsMaterial({
+                size: 0.02, vertexColors: true, sizeAttenuation: true
+            }));
+            scene.add(pointsMesh);
+        }
+
+        function animate() {
+            requestAnimationFrame(animate);
+            controls.update();
+            renderer.render(scene, camera);
+        }
+        animate();
+        window.addEventListener("resize", function() {
+            camera.aspect = window.innerWidth / window.innerHeight;
+            camera.updateProjectionMatrix();
+            renderer.setSize(window.innerWidth, window.innerHeight);
+        });
+    </script>
+</body>
+</html>
@@ -2797,7 +2797,7 @@ async fn delete_model(
    if safe_id.is_empty() || safe_id != id {
        return Json(serde_json::json!({ "error": "invalid model id", "success": false }));
    }
-    let path = PathBuf::from("data/models").join(format!("{}.rvf", safe_id));
+    let path = effective_models_dir().join(format!("{}.rvf", safe_id));
    if path.exists() {
        if let Err(e) = std::fs::remove_file(&path) {
            warn!("Failed to delete model file {:?}: {}", path, e);
@@ -2842,9 +2842,18 @@ async fn activate_lora_profile(
    Json(serde_json::json!({ "success": true, "profile": profile }))
 }

-/// Scan `data/models/` for `.rvf` files and return metadata.
+/// Return the effective models directory, respecting the `MODELS_DIR`
+/// environment variable.  Defaults to `data/models`.
+fn effective_models_dir() -> PathBuf {
+    PathBuf::from(
+        std::env::var("MODELS_DIR").unwrap_or_else(|_| "data/models".to_string()),
+    )
+}
+
+/// Scan the models directory for `.rvf` files and return metadata.
+/// Respects the `MODELS_DIR` environment variable.
 fn scan_model_files() -> Vec<serde_json::Value> {
-    let dir = PathBuf::from("data/models");
+    let dir = effective_models_dir();
    let mut models = Vec::new();
    if let Ok(entries) = std::fs::read_dir(&dir) {
        for entry in entries.flatten() {
@@ -2874,9 +2883,10 @@ fn scan_model_files() -> Vec<serde_json::Value> {
    models
 }

-/// Scan `data/models/` for `.lora.json` LoRA profile files.
+/// Scan the models directory for `.lora.json` LoRA profile files.
+/// Respects the `MODELS_DIR` environment variable.
 fn scan_lora_profiles() -> Vec<serde_json::Value> {
-    let dir = PathBuf::from("data/models");
+    let dir = effective_models_dir();
    let mut profiles = Vec::new();
    if let Ok(entries) = std::fs::read_dir(&dir) {
        for entry in entries.flatten() {
@@ -4604,7 +4614,8 @@ async fn main() {
    }

    // Ensure data directories exist for models and recordings
-    let _ = std::fs::create_dir_all("data/models");
+    let models_dir = effective_models_dir();
+    let _ = std::fs::create_dir_all(&models_dir);
    let _ = std::fs::create_dir_all("data/recordings");

    // Discover model and recording files on startup
@@ -30,8 +30,19 @@ use crate::rvf_container::RvfReader;

 // ── Models data directory ────────────────────────────────────────────────────

-/// Base directory for RVF model files.
-pub const MODELS_DIR: &str = "data/models";
+/// Default base directory for RVF model files.
+///
+/// Overridden at runtime by the `MODELS_DIR` environment variable so that
+/// Docker users can point to a mounted volume without rebuilding:
+///   docker run -v /path/to/models:/app/models -e MODELS_DIR=/app/models ...
+pub const MODELS_DIR_DEFAULT: &str = "data/models";
+
+/// Return the effective models directory, respecting `MODELS_DIR` env var.
+pub fn models_dir() -> PathBuf {
+    PathBuf::from(
+        std::env::var("MODELS_DIR").unwrap_or_else(|_| MODELS_DIR_DEFAULT.to_string()),
+    )
+}

 // ── Types ────────────────────────────────────────────────────────────────────

@@ -110,7 +121,7 @@ pub type AppState = Arc<RwLock<super::AppStateInner>>;

 /// Scan the models directory and build `ModelInfo` for each `.rvf` file.
 async fn scan_models() -> Vec<ModelInfo> {
-    let dir = PathBuf::from(MODELS_DIR);
+    let dir = models_dir();
    let mut models = Vec::new();

    let mut entries = match tokio::fs::read_dir(&dir).await {
@@ -204,7 +215,7 @@ async fn scan_models() -> Vec<ModelInfo> {

 /// Load a model from disk by ID and return its `LoadedModelState`.
 fn load_model_from_disk(model_id: &str) -> Result<LoadedModelState, String> {
-    let file_path = PathBuf::from(MODELS_DIR).join(format!("{model_id}.rvf"));
+    let file_path = models_dir().join(format!("{model_id}.rvf"));
    let reader = RvfReader::from_file(&file_path)?;

    let manifest = reader.manifest().unwrap_or_default();
@@ -362,6 +362,45 @@ def validate_log(log_text: str) -> ValidationReport:
        report.add("Frame rate", Severity.SKIP,
                    "No periodic frame reports found")

+    # ---- Check 17: ADR-081 adaptive controller boot ----
+    adapt_boot_patterns = [
+        r"adaptive_ctrl:.*adaptive controller online",
+        r"adaptive_ctrl:\s*state\s+\d+\s*\xe2\x86\x92",
+        r"adapt=on",
+    ]
+    adapt_boot = any(re.search(p, log_text) for p in adapt_boot_patterns)
+    if adapt_boot:
+        report.add("ADR-081 controller", Severity.PASS,
+                   "Adaptive controller started (ADR-081 Layer 2)")
+    else:
+        report.add("ADR-081 controller", Severity.WARN,
+                   "No adaptive_ctrl: log line found "
+                   "(expected ADR-081 Layer 2 online)")
+
+    # ---- Check 18: ADR-081 mock radio binding (QEMU only) ----
+    mock_radio = re.search(r"rv_radio_mock:.*registered", log_text)
+    if mock_radio:
+        report.add("ADR-081 radio binding", Severity.PASS,
+                   "Mock radio ops binding registered "
+                   "(ADR-081 Layer 1 portability gate)")
+    else:
+        # Only required when CONFIG_CSI_MOCK_ENABLED — downgrade to SKIP.
+        report.add("ADR-081 radio binding", Severity.SKIP,
+                   "No rv_radio_mock registration line "
+                   "(expected if CONFIG_CSI_MOCK_ENABLED)")
+
+    # ---- Check 19: ADR-081 slow-loop heartbeat ----
+    slow_tick = re.search(r"adaptive_ctrl:\s*slow tick", log_text)
+    if slow_tick:
+        report.add("ADR-081 slow loop", Severity.PASS,
+                   "Slow loop heartbeat observed "
+                   "(controller is ticking at ≥30 s cadence)")
+    else:
+        # A 60s QEMU timeout may not reach the first slow tick (30s default
+        # plus boot time); treat as SKIP not WARN.
+        report.add("ADR-081 slow loop", Severity.SKIP,
+                   "No slow tick (QEMU run shorter than slow_loop_ms)")
+
    return report


@@ -0,0 +1,142 @@
+#!/bin/bash
+# Regression tests for docker-entrypoint.sh
+#
+# Validates that the entrypoint script correctly handles:
+# 1. No arguments → uses env var defaults
+# 2. Flag arguments → prepends sensing-server binary
+# 3. Explicit binary path → passes through unchanged
+# 4. CSI_SOURCE env var substitution
+# 5. MODELS_DIR env var propagation
+#
+# These tests use a stub sensing-server that just prints its args.
+
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+ENTRYPOINT="$SCRIPT_DIR/../docker/docker-entrypoint.sh"
+
+PASS=0
+FAIL=0
+
+assert_contains() {
+    local test_name="$1"
+    local haystack="$2"
+    local needle="$3"
+    if printf '%s\n' "$haystack" | grep -qF -- "$needle"; then
+        PASS=$((PASS + 1))
+        echo "  ✓ $test_name"
+    else
+        FAIL=$((FAIL + 1))
+        echo "  ✗ $test_name"
+        echo "    expected to contain: $needle"
+        echo "    got: $haystack"
+    fi
+}
+
+assert_not_contains() {
+    local test_name="$1"
+    local haystack="$2"
+    local needle="$3"
+    if printf '%s\n' "$haystack" | grep -qF -- "$needle"; then
+        FAIL=$((FAIL + 1))
+        echo "  ✗ $test_name"
+        echo "    expected NOT to contain: $needle"
+        echo "    got: $haystack"
+    else
+        PASS=$((PASS + 1))
+        echo "  ✓ $test_name"
+    fi
+}
+
+# Create a temporary stub for /app/sensing-server that just prints args
+TMPDIR=$(mktemp -d)
+trap "rm -rf $TMPDIR" EXIT
+
+STUB="$TMPDIR/sensing-server"
+cat > "$STUB" << 'EOF'
+#!/bin/sh
+echo "EXEC_ARGS: $@"
+EOF
+chmod +x "$STUB"
+
+# We'll modify the entrypoint to use our stub path for testing
+TEST_ENTRYPOINT="$TMPDIR/docker-entrypoint.sh"
+sed "s|/app/sensing-server|$STUB|g" "$ENTRYPOINT" > "$TEST_ENTRYPOINT"
+chmod +x "$TEST_ENTRYPOINT"
+
+echo "=== Docker entrypoint tests ==="
+
+# Test 1: No arguments — should use CSI_SOURCE default (auto)
+echo ""
+echo "Test 1: No arguments (default CSI_SOURCE=auto)"
+OUT=$(CSI_SOURCE=auto "$TEST_ENTRYPOINT" 2>&1)
+assert_contains "includes --source auto" "$OUT" "--source auto"
+assert_contains "includes --tick-ms 100" "$OUT" "--tick-ms 100"
+assert_contains "includes --ui-path" "$OUT" "--ui-path /app/ui"
+assert_contains "includes --http-port 3000" "$OUT" "--http-port 3000"
+assert_contains "includes --ws-port 3001" "$OUT" "--ws-port 3001"
+assert_contains "includes --bind-addr 0.0.0.0" "$OUT" "--bind-addr 0.0.0.0"
+
+# Test 2: CSI_SOURCE=esp32 — should substitute
+echo ""
+echo "Test 2: CSI_SOURCE=esp32"
+OUT=$(CSI_SOURCE=esp32 "$TEST_ENTRYPOINT" 2>&1)
+assert_contains "includes --source esp32" "$OUT" "--source esp32"
+
+# Test 3: Flag arguments — should prepend binary
+echo ""
+echo "Test 3: User passes --source wifi --tick-ms 500"
+OUT=$(CSI_SOURCE=auto "$TEST_ENTRYPOINT" --source wifi --tick-ms 500 2>&1)
+assert_contains "includes --source wifi" "$OUT" "--source wifi"
+assert_contains "includes --tick-ms 500" "$OUT" "--tick-ms 500"
+
+# Test 4: No CSI_SOURCE set — should default to auto
+echo ""
+echo "Test 4: CSI_SOURCE unset"
+OUT=$(unset CSI_SOURCE; "$TEST_ENTRYPOINT" 2>&1)
+assert_contains "includes --source auto (default)" "$OUT" "--source auto"
+
+# Test 5: User passes --model flag — should be appended
+echo ""
+echo "Test 5: User passes --model /app/models/my.rvf"
+OUT=$(CSI_SOURCE=esp32 "$TEST_ENTRYPOINT" --model /app/models/my.rvf 2>&1)
+assert_contains "includes --model" "$OUT" "--model /app/models/my.rvf"
+assert_contains "also includes default flags" "$OUT" "--source esp32"
+
+# Test 6: CSI_SOURCE=simulated
+echo ""
+echo "Test 6: CSI_SOURCE=simulated"
+OUT=$(CSI_SOURCE=simulated "$TEST_ENTRYPOINT" 2>&1)
+assert_contains "includes --source simulated" "$OUT" "--source simulated"
+
+# Test 7: Explicit binary path passed (e.g., docker run <image> /bin/sh)
+# First arg does NOT start with -, so entrypoint should exec it directly
+echo ""
+echo "Test 7: Explicit command (echo hello)"
+OUT=$("$TEST_ENTRYPOINT" echo hello 2>&1)
+assert_contains "passes through explicit command" "$OUT" "hello"
+assert_not_contains "does not inject sensing-server flags" "$OUT" "--source"
+
+# Test 8: MODELS_DIR env var is passed through to the process
+echo ""
+echo "Test 8: MODELS_DIR env var propagation"
+# Create a stub that prints MODELS_DIR
+ENV_STUB="$TMPDIR/env-sensing-server"
+cat > "$ENV_STUB" << 'ENVEOF'
+#!/bin/sh
+echo "MODELS_DIR=${MODELS_DIR:-unset}"
+ENVEOF
+chmod +x "$ENV_STUB"
+ENV_ENTRYPOINT="$TMPDIR/env-entrypoint.sh"
+sed "s|/app/sensing-server|$ENV_STUB|g" "$ENTRYPOINT" > "$ENV_ENTRYPOINT"
+chmod +x "$ENV_ENTRYPOINT"
+
+OUT=$(MODELS_DIR=/app/models CSI_SOURCE=auto "$ENV_ENTRYPOINT" 2>&1)
+assert_contains "MODELS_DIR is visible" "$OUT" "MODELS_DIR=/app/models"
+
+OUT=$(unset MODELS_DIR; CSI_SOURCE=auto "$ENV_ENTRYPOINT" 2>&1)
+assert_contains "MODELS_DIR defaults to unset" "$OUT" "MODELS_DIR=unset"
+
+echo ""
+echo "=== Results: $PASS passed, $FAIL failed ==="
+[ "$FAIL" -eq 0 ] || exit 1
@@ -1 +1 @@
 .6.0
 .6.2