mirror of https://github.com/ruvnet/RuView synced 2026-06-09 10:13:17 +00:00

Files

T

rUv 9e7fa83210 feat(signal): ADR-134 CSI→CIR via ISTA + NeumannSolver warm-start (#837 )

* feat(signal): ADR-134 — CSI→CIR via ISTA + NeumannSolver warm-start

End-to-end first-class Channel Impulse Response estimation in the Rust
workspace. Bridges CSI (frequency domain) to CIR (delay domain) so
multistatic coherence gating, NLOS/LOS classification, and (at HT40+)
ToF ranging become tractable in `wifi-densepose-signal`.

Algorithm: ISTA L1 sparse recovery over a normalized DFT sub-matrix
sensing operator Φ ∈ ℂ^(K×G) with G = 3K (3× super-resolution). The
Tikhonov-regularised warm start re-uses `ruvector_solver::neumann::
NeumannSolver` — same call pattern as `fresnel.rs:280` and
`train/subcarrier.rs:225` — so no new crate dependencies.

Tiers supported: HT20 / HT40 / HE20 (Tier A-HE, C6) / HE40. The C6
HE-LTF tier is the preferred Tier A target whenever an 11ax AP is in
range; firmware substrate already shipped at v0.7.0-esp32 per ADR-110.

Measured performance (release, single CirEstimator shared across 12
links): HT20 2.72 ms / HE20 3.20 ms / HT40 13.43 ms / HE40 9.71 ms per
estimate(). HT20 12-link multistatic 17.7 ms — fits the 50 ms RuvSense
cycle; HT40 12-link 74 ms exceeds it and is flagged in ADR-134 §2.7 as
requiring Rayon parallelism or G=2K super-res reduction.

Measured Φ conditioning: κ(Φ) ≈ 1.00 identically across all tiers.
ADR-134 §2.3 was corrected — the C6 advantage is statistical SNR gain
(√(242/52) ≈ 2.16×) from more independent measurements, not improved
conditioning.

Witness: bit-deterministic SHA-256 over CirEstimator output on the
synthetic ADR-028 reference signal (100 frames, top-5 taps, 1e-6
quantization). Hash committed to expected_cir_features.sha256;
verify-cir-proof.sh wires the check into the existing witness bundle.

CI: cargo test --features cir + verify-cir-proof.sh added as separate
steps under the Rust Workspace Tests job; regressions are unambiguously
attributable.

Files:
- ADR + WITNESS-LOG-028 row 34 + CLAUDE.md module count (14 → 15)
- src/ruvsense/cir.rs (~540 LOC) + lib.rs re-exports + multistatic.rs
  wire-up (reversible via `use_cir_gate=false`)
- 3 integration tests + Criterion bench + 3 deterministic fixtures
- cir_proof_runner binary + sha256 + verify-cir-proof.sh

Test rate: 395 pass / 6 ignored (P2 ISTA hyperparameter tuning; see
#[ignore] reasons) / 0 fail. cargo check clean; verify-cir-proof.sh
VERDICT: PASS.

Co-Authored-By: claude-flow <ruv@ruv.net>

* fix(signal): make CIR witness cross-platform-deterministic

The first witness (Windows-generated hash 89704bfd…) failed on Linux CI
with a different hash (b36741bf…). Root cause: hashing `re`/`im` parts of
top-5 taps at 1e-6 precision is too tight against libm differences in
sin/cos/sqrt across glibc, MSVC, and Apple-clang. The previous
"top-5 sorted by magnitude" form also suffered from rank instability when
taps are near-tied — libm jitter could shuffle the ordering even when the
algorithm is unchanged.

New canonical form: full per-tap quantised-magnitude profile in natural
index order, no sort.

  - 156 taps × 2 bytes (u16 le) per frame = 312 bytes/frame.
  - Quantisation 1e-2 — robust to ~1e-3 float drift while still tripping
    on real algorithmic changes (e.g., a 10× lambda shift moves magnitudes
    by >1e-2).
  - No top-K selection — eliminates the unstable magnitude-sort step.

Regenerated expected_cir_features.sha256 — new hash 120bd7b1…

If the next CI run still mismatches, the cause is structural (rustfft SIMD
code path selection or NeumannSolver internal ordering), not magnitudes,
and the witness needs further coarsening or to be made platform-tagged.

Co-Authored-By: claude-flow <ruv@ruv.net>

2026-05-28 16:24:37 -04:00

9.8 KiB

Raw Blame History

Architecture Decision Records

This folder contains 45 Architecture Decision Records (ADRs) that document every significant technical choice in the RuView / WiFi-DensePose project.

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

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

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-115	Home Assistant integration via MQTT auto-discovery + Matter bridge (HA-DISCO + HA-FABRIC + HA-MIND)	Accepted (MQTT track) / Proposed (Matter SDK P8b)

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

DDD Domain Models — Bounded context definitions, aggregate roots, and ubiquitous language
User Guide — Setup, API reference, and hardware instructions
Build Guide — Building from source

9.8 KiB Raw Blame History