mirror of
https://github.com/ruvnet/RuView.git
synced 2026-10-21 14:12:34 -05:00
Joeandclaude-flow
51102b3baf
Records why device-free position kept failing here, measured rather than argued, and the join key built in response. The implementing PRs land without this and are harder to read for it. **Phase is unusable on this hardware.** The bistatic tier needed a signed per-link radial velocity, which requires the common-mode component of CSI phase. Measured across three ESP32-C6 nodes over ~40,000 frames, the frame-to-frame change in common-mode phase is statistically indistinguishable from uniform random: resultant length R = 0.011-0.032 against a 0.000 reference, sd 1.78-1.81 against pi/sqrt(3) = 1.814, no lag-1 autocorrelation. A second, unwrap-free estimator agreed. The mechanism is packet-detection timing quantization. Common-mode phase is -2*pi*f_c*tau, and one ADC sample of jitter at 20 MHz is about 758 rad -- some 120 full wraps, re-randomized every packet. Not calibratable. The bistatic tier is default-off as a result. **Amplitude works but had no parallax.** The three AP->node links leave a single distant transmitter inside a 36.5 degree fan; scalar per-node energy weighting closed with a clean negative result -- magnitude responds to proximity, direction does not. What follows from both: a position tier needs several transmitters seen from several receivers, and fusing those requires knowing that two nodes observed the SAME transmission. Arrival timestamps cannot say so -- the sink sees network jitter, not capture time -- and the per-node sequence counter is private to each node. Hence (tx_mac, rx_seq): the 802.11 sequence control field is assigned by the transmitter and is identical at every receiver, so it names one transmission without any coordination between receivers, no shared clock and no negotiation. Status is Proposed, deliberately. The measurement layer is implemented and validated on hardware; localization is NOT built, and the ADR says so along with the rest of its known limitations -- peer links are ~10x weaker than data frames, three links is below the threshold for tomographic localization regardless of quality, and no position tier consumes the link table. References only ADR-018, ADR-060 and ADR-110, all already present here. Co-Authored-By: claude-flow <ruv@ruv.net> Claude-Session: https://claude.ai/code/session_01BHNNWbmKvxXrVaEDwXEBNo
Architecture Decision Records
Latest proposed decisions:
- ADR-187: archive/v1 deprecation + model-weights honest labeling (refs #509, #1125)
- ADR-186: Training progress API — wire the orphaned in-server trainer to /ws/train/progress (refs #1233)
- ADR-185: Python P6 SOTA bindings — AETHER, MERIDIAN, MAT
- ADR-184: ADR-117 completion via PyPI Trusted Publishing (refs #785)
- ADR-264: Versioned wire protocol for RTL8720F CFR and Range-FFT reports
- ADR-263: Adopt RTL8720F 2.4 GHz FMCW radar as an optional RuView sensing platform
This folder contains 210 Architecture Decision Records (ADRs) that document every significant technical choice in the RuView / WiFi-DensePose project. (The index tables below list a curated subset per domain; see the directory listing for the full set.)
Why ADRs?
Building a system that turns WiFi signals into human pose estimation involves hundreds of non-obvious decisions: which signal processing algorithms to use, how to bridge ESP32 firmware to a Rust pipeline, whether to run inference on-device or on a server, how to handle multi-person separation with limited subcarriers.
ADRs capture the context, options considered, decision made, and consequences for each of these choices. They serve three purposes:
-
Institutional memory — Six months from now, anyone (human or AI) can read why we chose IIR bandpass filters over FIR for vital sign extraction, not just see the code.
-
AI-assisted development — When an AI agent works on this codebase, ADRs give it the constraints and rationale it needs to make changes that align with the existing architecture. Without them, AI-generated code tends to drift — reinventing patterns that already exist, contradicting earlier decisions, or optimizing for the wrong tradeoffs.
-
Review checkpoints — Each ADR is a reviewable artifact. When a proposed change touches the architecture, the ADR forces the author to articulate tradeoffs before writing code, not after.
ADRs and Domain-Driven Design
The project uses Domain-Driven Design (DDD) to organize code into bounded contexts — each with its own language, types, and responsibilities. ADRs and DDD work together:
- ADRs define boundaries: ADR-029 (RuvSense) established multistatic sensing as a separate bounded context from single-node CSI. ADR-042 (CHCI) defined a new aggregate root for coherent channel imaging.
- DDD models define the language: The RuvSense domain model defines terms like "coherence gate", "dwell time", and "TDM slot" that ADRs reference precisely.
- Together they prevent drift: An AI agent reading ADR-039 knows that edge processing tiers are configured via NVS keys, not compile-time flags — because the ADR says so. The DDD model tells it which aggregate owns that configuration.
How ADRs are structured
Each ADR follows a consistent format:
- Context — What problem or gap prompted this decision
- Decision — What we chose to do and how
- Consequences — What improved, what got harder, and what risks remain
- References — Related ADRs, papers, and code paths
Statuses: Proposed (under discussion), Accepted (approved and/or implemented), Superseded (replaced by a later ADR).
ADR Index
Hardware and firmware
| ADR | Title | Status |
|---|---|---|
| ADR-012 | ESP32 CSI Sensor Mesh for Distributed Sensing | Accepted (partial) |
| ADR-018 | ESP32 Development Implementation Path | Proposed |
| ADR-028 | ESP32 Capability Audit and Witness Record | Accepted |
| ADR-029 | RuvSense Multistatic Sensing Mode (TDM, channel hopping) | Proposed |
| ADR-032 | Multistatic Mesh Security Hardening | Accepted |
| ADR-039 | ESP32-S3 Edge Intelligence Pipeline (on-device vitals) | Accepted (hardware-validated) |
| ADR-040 | WASM Programmable Sensing (Tier 3) | Accepted |
| ADR-041 | WASM Module Collection (65 edge modules) | Accepted (hardware-validated) |
| ADR-044 | Provisioning Tool Enhancements | Proposed |
| ADR-110 | ESP32-C6 firmware extension — Wi-Fi 6 / 802.15.4 / TWT / LP-core | Accepted, P1-P10 complete, firmware-side substrate closed at v0.7.0-esp32. Companion docs: WITNESS-LOG-110 (13 §A0.x entries · 99.56 % cross-board RX · 104.1 µs smoothed sync stdev · ≤100 µs target met), ADR-110-REVIEW-GUIDE (one-page reviewer tour), ADR-110-BRANCH-STATE (coordination map vs feat/adr-115-ha-mqtt-matter). Host decoders + tests: Python SyncPacketParser (10) + Rust wifi_densepose_hardware::SyncPacket (15), cross-language hex pin gates drift. |
Signal processing and sensing
| ADR | Title | Status |
|---|---|---|
| ADR-013 | Feature-Level Sensing on Commodity Gear | Accepted |
| ADR-014 | SOTA Signal Processing Algorithms | Accepted |
| ADR-021 | Vital Sign Detection (breathing, heart rate) | Partial |
| ADR-030 | Persistent Field Model and Drift Detection | Proposed |
| ADR-033 | CRV Signal Line Sensing Integration | Proposed |
| ADR-037 | Multi-Person Pose Detection from Single ESP32 | Proposed |
| ADR-042 | Coherent Human Channel Imaging (beyond CSI) | Proposed |
| ADR-134 | First-Class Channel Impulse Response (CIR) Support | Proposed |
| ADR-135 | Empty-Room Baseline Calibration (per-subcarrier Welford statistics) | Proposed |
Machine learning and training
| ADR | Title | Status |
|---|---|---|
| ADR-005 | SONA Self-Learning for Pose Estimation | Partial |
| ADR-006 | GNN-Enhanced CSI Pattern Recognition | Partial |
| ADR-015 | Public Dataset Strategy (MM-Fi, Wi-Pose) | Accepted |
| ADR-016 | RuVector Training Pipeline Integration | Accepted |
| ADR-017 | RuVector Signal + MAT Integration | Proposed |
| ADR-020 | Migrate AI Inference to Rust (ONNX Runtime) | Accepted |
| ADR-023 | Trained DensePose Model with RuVector Pipeline | Proposed |
| ADR-024 | Project AETHER: Contrastive CSI Embeddings | Required |
| ADR-027 | Project MERIDIAN: Cross-Environment Generalization | Proposed |
| ADR-149 | AetherArena: public spatial-intelligence benchmark on Hugging Face | Proposed |
| ADR-150 | RF Foundation Encoder: pose-preserving, subject/room/device-invariant CSI embedding | Proposed |
| ADR-151 | Per-Room Calibration & Specialized Model Training (room-first → bank of small ruVector specialists) | Proposed |
| ADR-152 | WiFi-Pose SOTA 2026 Intake: geometry-conditioned calibration, external benchmarks, foundation-encoder recipe | Proposed |
| ADR-345 | Per-link CSI attribution and node-to-node ranging — why phase-based position fails on this hardware (measured), and the coordination-free (tx_mac, rx_seq) join key that does not need it |
Proposed — measurement layer implemented and validated on hardware; localization not built |
| ADR-348 | Independent Rust multivariate forecasting for RuView | Proposed |
| ADR-349 | Governed local and fal.ai forecast training | Proposed |
| ADR-350 | RuVector predictive memory and RuVLLM authority boundary | Proposed |
| ADR-354 | fal.ai forecast governance and spend enforcement now real, in the vendored RuForecast submodule | Accepted |
| ADR-355 | Local empty room bootstrap prior | Accepted |
| ADR-356 | Rate truthful CSI and reliability gated room adaptation | Accepted |
Platform and UI
| ADR | Title | Status |
|---|---|---|
| ADR-019 | Sensing-Only UI with Gaussian Splats | Accepted |
| ADR-022 | Windows WiFi Enhanced Fidelity (multi-BSSID) | Partial |
| ADR-025 | macOS CoreWLAN WiFi Sensing | Proposed |
| ADR-031 | RuView Sensing-First RF Mode | Proposed |
| ADR-034 | Expo React Native Mobile App | Accepted |
| ADR-035 | Live Sensing UI Accuracy and Data Transparency | Accepted |
| ADR-036 | Training Pipeline UI Integration | Proposed |
| ADR-043 | Sensing Server UI API Completion (14 endpoints) | Accepted |
| ADR-344 | Adaptive Local Installation Discovery | Accepted (local software path) |
| ADR-346 | Fail closed ESP32 occupancy evidence | Accepted (C6 occupancy integrity qualified) |
| ADR-347 | Rate aware ESP32 temporal sensing | Accepted (C6 timing and transport qualified) |
| ADR-115 | Home Assistant integration via MQTT auto-discovery + Matter bridge (HA-DISCO + HA-FABRIC + HA-MIND) | Accepted (MQTT track) / Proposed (Matter SDK P8b) |
| ADR-169 | adam-mode — light theme toggle for the three.js realtime demo | Proposed |
| ADR-170 | yoga-mode — yoga pose detection, classification, and scoring for the three.js realtime demo | Proposed |
| ADR-324 | off-axis-mode — RF-assisted head-coupled perspective demo (clean-room Kooima projection; RF presence gating) | Proposed |
Architecture and infrastructure
| ADR | Title | Status |
|---|---|---|
| ADR-001 | WiFi-Mat Disaster Detection Architecture | Accepted |
| ADR-002 | RuVector RVF Integration Strategy | Superseded |
| ADR-003 | RVF Cognitive Containers for CSI | Proposed |
| ADR-004 | HNSW Vector Search for Fingerprinting | Partial |
| ADR-007 | Post-Quantum Cryptography for Sensing | Proposed |
| ADR-008 | Distributed Consensus for Multi-AP | Proposed |
| ADR-009 | RVF WASM Runtime for Edge Deployment | Proposed |
| ADR-010 | Witness Chains for Audit Trail Integrity | Proposed |
| ADR-011 | Proof-of-Reality and Mock Elimination | Proposed |
| ADR-026 | Survivor Track Lifecycle (MAT crate) | Accepted |
| ADR-038 | Sublinear GOAP for Roadmap Optimization | Proposed |
| ADR-095 | rvCSI — Edge RF Sensing Runtime Platform | Proposed |
| ADR-096 | rvCSI — Crate Topology, the napi-c Shim, and the napi-rs Node Surface | Proposed |
| ADR-097 | Adopt rvCSI as RuView's primary CSI runtime (phased adoption) | Proposed |
| ADR-098 | Evaluate ruvnet/midstream for RuView's CSI / WebSocket / mesh pipeline |
Rejected |
| ADR-099 | Adopt midstream as RuView's real-time introspection + low-latency tap | Proposed |
| ADR-263 | @ruvnet/ruview npm harness — deep review + optimization strategy |
Proposed |
| ADR-264 | @ruvnet/rvagent MCP server + @ruv/ruview-cli — deep review + optimization strategy |
Proposed |
| ADR-265 | RuView npm distribution strategy — CI gate, provenance, version single-sourcing, namespace | Proposed |
| ADR-273 | Unified RF spatial world model — umbrella, anti-leakage protocol, acceptance gates | Accepted (P1 implemented) |
| ADR-274 | Universal RF foundation encoder + hardware adapter registry | Accepted (P1 implemented) |
| ADR-275 | RF-aware Gaussian spatial memory | Accepted (P1 implemented) |
| ADR-276 | Physics-guided synthetic RF world generator | Accepted (P1 implemented) |
| ADR-277 | Edge sensing control plane (802.11bf / ETSI ISAC aligned) | Accepted (P1 implemented) |
| ADR-278 | Radar inverse rendering + differentiable RF SLAM research program | Proposed |
| ADR-279 | Native RF frame contract — RfFrameV2 authoritative, canonical tensor derived |
Accepted (implemented) |
| ADR-280 | Active sensing & programmable perception control plane | Accepted (implemented) |
| ADR-281 | BLE Channel Sounding, delay-Doppler tensors, P3162 import, factorized pose | Accepted (implemented) |
| ADR-282 | Ecosystem positioning + mandatory L0–L5 evidence ladder | Accepted |
| ADR-287 | wifi-densepose-sar — coherent wideband RF tomography research crate |
Accepted (implemented, published) |
| ADR-285 | WASM-first Homecore developer metaharness via npx homecore |
Accepted (implemented and validated) |
| ADR-286 | wifi-densepose-sar-harness — MetaHarness with darwin/router/flywheel |
Accepted (implemented, published) |
| ADR-288 | VEIL — compliant-waveform privacy shield against unauthorized WiFi sensing (wifi-densepose-privshield) |
Proposed (implemented, P1 reference) |
| ADR-289 | wifi-densepose-privshield-harness — npm MetaHarness for the VEIL crate (guidance/router/flywheel) |
Proposed (implemented, P1) |
| ADR-290 | VEIL end-to-end hardware implementation program — portable C core + multi-provider firmware scaffolds (openwifi/openwrt/nexmon/esp32) | Proposed (P4 scaffolding; C core host-validated) |
| ADR-291 | Public-benchmark evaluation harness — Widar3.0 ingest, split protocols, leakage guards | Accepted (initial implementation) |
| ADR-292 | Wideband 802.11ax CSI ingest — FeitCSI/AX210 adapter, subcarrier-agnostic plumbing | Accepted (initial implementation) |
| ADR-293 | Vitals ground-truth rig — reference ingest, alignment, agreement metrics | Accepted (initial implementation) |
| ADR-294 | WiFi Veil integration — emission-shaping countermeasure as advisory BFLD dependency | Accepted (initial implementation) |
| ADR-295 | Source provenance state machine — synthetic can never present as live | Accepted (initial implementation) |
| ADR-296 | Sensor data-plane hardening — UDP bind control and source allowlist (step one) | Accepted (initial implementation) |
| ADR-297 | Multi-node semantic correctness — per-node inference, node-keyed rate limiting, stale state | Accepted (initial implementation) |
| ADR-298 | Model release sanity gates — block degenerate and mislabeled model artifacts | Accepted (initial implementation) |
| ADR-299 | Repository CSI data-incident controls — ignore rules and pre-commit/CI policy check | Accepted (controls implemented; tree remediation gated) |
| ADR-300 | RuView perception substrate — phased 21-primitive program (calibration, evidence, trust, deployment) | Accepted (program; children ADR-301..317) |
| ADR-301 | Automatic domain calibration — signed, versioned, invalidatable room fingerprint | Accepted (phase 1) |
| ADR-302 | Out-of-distribution detection — KNOWN / DEGRADED / UNKNOWN gating | Accepted (phase 1) |
| ADR-303 | Ground-truth synchronization — reference sensors as a formal validation plane | Proposed (phase 2) |
| ADR-304 | Evidence engine — per-(room,device,subject) accuracy ledger | Accepted (phase 1) |
| ADR-305 | Authenticated sensor identity — RF chain of custody | Accepted (phase 1) |
| ADR-306 | Canonical spatial ontology — one Site→…→Event model for every surface | Accepted (phase 1) |
| ADR-307 | Persistent identity & tracking — privacy-preserving probabilistic tracks | Proposed (phase 2) |
| ADR-308 | Sensor placement optimizer — floorplan + inventory → recommended positions | Proposed (phase 3) |
| ADR-309 | Active sensing — closed-loop RF experiment control | Proposed (phase 3) |
| ADR-310 | 802.11bf-native architecture — standardized WLAN sensing as native measurement types | Proposed (phase 2) |
| ADR-311 | Real sensor fusion — uncertainty-aware, multiple observations → one world state | Proposed (phase 2) |
| ADR-312 | Long-term spatial memory — learn the normal physics of a location | Proposed (phase 3) |
| ADR-313 | Counterfactual inference — generative spatial reasoning | Proposed (phase 3) |
| ADR-314 | Information-gain scheduler — sample the most informative radios | Proposed (phase 3) |
| ADR-315 | Digital RF twin — persistent per-deployment RF model | Proposed (phase 3) |
| ADR-316 | Fleet control plane — provisioning to audit trails | Proposed (phase 2) |
| ADR-317 | Multi-domain benchmark scorecard — regressions cannot hide behind pooled accuracy | Accepted (phase 1) |
| ADR-318 | Capability certificates — validated-for-this-environment claims | Accepted (phase 1) |
| ADR-319 | Witness chain — staged, signed epistemic envelope | Accepted (phase 1) |
| ADR-320 | RuView sensor HAL — abstract all sensing hardware to one Observation type | Proposed (phase 2) |
| ADR-321 | Decision policy — action authorization conditioned on certificate class, freshness, uncertainty, evidence | Accepted (phase 1) |
| ADR-323 | Native Rust physics-constrained pose refinement | Proposed |
Related
- DDD Domain Models — Bounded context definitions, aggregate roots, and ubiquitous language
- User Guide — Setup, API reference, and hardware instructions
- Build Guide — Building from source