Thanks to visit codestin.com
Credit goes to github.com

Skip to content

Commit 0aab555

Browse files
ruvnetruvnet
authored
Merge pull request ruvnet#77 from ruvnet/ruvsense-full-implementation
feat: RuvSense multistatic sensing + field model + RuView fusion (ADR-029/030/031)
2 parents 08a6d5a + 0c01157 commit 0aab555

67 files changed

Lines changed: 28082 additions & 69 deletions

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎CLAUDE.md‎

Lines changed: 142 additions & 25 deletions
Original file line numberDiff line numberDiff line change
@@ -4,13 +4,49 @@
44

55
WiFi-based human pose estimation using Channel State Information (CSI).
66
Dual codebase: Python v1 (`v1/`) and Rust port (`rust-port/wifi-densepose-rs/`).
7-
87
### Key Rust Crates
9-
- `wifi-densepose-signal` — SOTA signal processing (conjugate mult, Hampel, Fresnel, BVP, spectrogram)
10-
- `wifi-densepose-train` — Training pipeline with ruvector integration (ADR-016)
11-
- `wifi-densepose-mat` — Disaster detection module (MAT, multi-AP, triage)
12-
- `wifi-densepose-nn` — Neural network inference (DensePose head, RCNN)
13-
- `wifi-densepose-hardware` — ESP32 aggregator, hardware interfaces
8+
| Crate | Description |
9+
|-------|-------------|
10+
| `wifi-densepose-core` | Core types, traits, error types, CSI frame primitives |
11+
| `wifi-densepose-signal` | SOTA signal processing + RuvSense multistatic sensing (14 modules) |
12+
| `wifi-densepose-nn` | Neural network inference (ONNX, PyTorch, Candle backends) |
13+
| `wifi-densepose-train` | Training pipeline with ruvector integration + ruview_metrics |
14+
| `wifi-densepose-mat` | Mass Casualty Assessment Tool — disaster survivor detection |
15+
| `wifi-densepose-hardware` | ESP32 aggregator, TDM protocol, channel hopping firmware |
16+
| `wifi-densepose-ruvector` | RuVector v2.0.4 integration + cross-viewpoint fusion (5 modules) |
17+
| `wifi-densepose-api` | REST API (Axum) |
18+
| `wifi-densepose-db` | Database layer (Postgres, SQLite, Redis) |
19+
| `wifi-densepose-config` | Configuration management |
20+
| `wifi-densepose-wasm` | WebAssembly bindings for browser deployment |
21+
| `wifi-densepose-cli` | CLI tool (`wifi-densepose` binary) |
22+
| `wifi-densepose-sensing-server` | Lightweight Axum server for WiFi sensing UI |
23+
| `wifi-densepose-wifiscan` | Multi-BSSID WiFi scanning (ADR-022) |
24+
| `wifi-densepose-vitals` | ESP32 CSI-grade vital sign extraction (ADR-021) |
25+
26+
### RuvSense Modules (`signal/src/ruvsense/`)
27+
| Module | Purpose |
28+
|--------|---------|
29+
| `multiband.rs` | Multi-band CSI frame fusion, cross-channel coherence |
30+
| `phase_align.rs` | Iterative LO phase offset estimation, circular mean |
31+
| `multistatic.rs` | Attention-weighted fusion, geometric diversity |
32+
| `coherence.rs` | Z-score coherence scoring, DriftProfile |
33+
| `coherence_gate.rs` | Accept/PredictOnly/Reject/Recalibrate gate decisions |
34+
| `pose_tracker.rs` | 17-keypoint Kalman tracker with AETHER re-ID embeddings |
35+
| `field_model.rs` | SVD room eigenstructure, perturbation extraction |
36+
| `tomography.rs` | RF tomography, ISTA L1 solver, voxel grid |
37+
| `longitudinal.rs` | Welford stats, biomechanics drift detection |
38+
| `intention.rs` | Pre-movement lead signals (200-500ms) |
39+
| `cross_room.rs` | Environment fingerprinting, transition graph |
40+
| `gesture.rs` | DTW template matching gesture classifier |
41+
| `adversarial.rs` | Physically impossible signal detection, multi-link consistency |
42+
43+
### Cross-Viewpoint Fusion (`ruvector/src/viewpoint/`)
44+
| Module | Purpose |
45+
|--------|---------|
46+
| `attention.rs` | CrossViewpointAttention, GeometricBias, softmax with G_bias |
47+
| `geometry.rs` | GeometricDiversityIndex, Cramer-Rao bounds, Fisher Information |
48+
| `coherence.rs` | Phase phasor coherence, hysteresis gate |
49+
| `fusion.rs` | MultistaticArray aggregate root, domain events |
1450

1551
### RuVector v2.0.4 Integration (ADR-016 complete, ADR-017 proposed)
1652
All 5 ruvector crates integrated in workspace:
@@ -21,33 +57,105 @@ All 5 ruvector crates integrated in workspace:
2157
- `ruvector-attention` → `model.rs` (apply_spatial_attention) + `bvp.rs`
2258

2359
### Architecture Decisions
24-
All ADRs in `docs/adr/` (ADR-001 through ADR-017). Key ones:
60+
32 ADRs in `docs/adr/` (ADR-001 through ADR-032). Key ones:
2561
- ADR-014: SOTA signal processing (Accepted)
2662
- ADR-015: MM-Fi + Wi-Pose training datasets (Accepted)
2763
- ADR-016: RuVector training pipeline integration (Accepted — complete)
2864
- ADR-017: RuVector signal + MAT integration (Proposed — next target)
65+
- ADR-024: Contrastive CSI embedding / AETHER (Accepted)
66+
- ADR-027: Cross-environment domain generalization / MERIDIAN (Accepted)
67+
- ADR-028: ESP32 capability audit + witness verification (Accepted)
68+
- ADR-029: RuvSense multistatic sensing mode (Proposed)
69+
- ADR-030: RuvSense persistent field model (Proposed)
70+
- ADR-031: RuView sensing-first RF mode (Proposed)
71+
- ADR-032: Multistatic mesh security hardening (Proposed)
2972

3073
### Build & Test Commands (this repo)
3174
```bash
32-
# Rust — check training crate (no GPU needed)
75+
# Rust — full workspace tests (1,031+ tests, ~2 min)
3376
cd rust-port/wifi-densepose-rs
34-
cargo check -p wifi-densepose-train --no-default-features
77+
cargo test --workspace --no-default-features
3578

36-
# Rust — run all tests
37-
cargo test -p wifi-densepose-train --no-default-features
79+
# Rust — single crate check (no GPU needed)
80+
cargo check -p wifi-densepose-train --no-default-features
3881

39-
# Rust — full workspace check
40-
cargo check --workspace --no-default-features
82+
# Rust — publish crates (dependency order)
83+
cargo publish -p wifi-densepose-core --no-default-features
84+
cargo publish -p wifi-densepose-signal --no-default-features
85+
# ... see crate publishing order below
4186

42-
# Python — proof verification
87+
# Python — deterministic proof verification (SHA-256)
4388
python v1/data/proof/verify.py
4489

4590
# Python — test suite
4691
cd v1 && python -m pytest tests/ -x -q
4792
```
4893

94+
### Crate Publishing Order
95+
Crates must be published in dependency order:
96+
1. `wifi-densepose-core` (no internal deps)
97+
2. `wifi-densepose-vitals` (no internal deps)
98+
3. `wifi-densepose-wifiscan` (no internal deps)
99+
4. `wifi-densepose-hardware` (no internal deps)
100+
5. `wifi-densepose-config` (no internal deps)
101+
6. `wifi-densepose-db` (no internal deps)
102+
7. `wifi-densepose-signal` (depends on core)
103+
8. `wifi-densepose-nn` (no internal deps, workspace only)
104+
9. `wifi-densepose-ruvector` (no internal deps, workspace only)
105+
10. `wifi-densepose-train` (depends on signal, nn)
106+
11. `wifi-densepose-mat` (depends on core, signal, nn)
107+
12. `wifi-densepose-api` (no internal deps)
108+
13. `wifi-densepose-wasm` (depends on mat)
109+
14. `wifi-densepose-sensing-server` (depends on wifiscan)
110+
15. `wifi-densepose-cli` (depends on mat)
111+
112+
### Validation & Witness Verification (ADR-028)
113+
114+
**After any significant code change, run the full validation:**
115+
116+
```bash
117+
# 1. Rust tests — must be 1,031+ passed, 0 failed
118+
cd rust-port/wifi-densepose-rs
119+
cargo test --workspace --no-default-features
120+
121+
# 2. Python proof — must print VERDICT: PASS
122+
cd ../..
123+
python v1/data/proof/verify.py
124+
125+
# 3. Generate witness bundle (includes both above + firmware hashes)
126+
bash scripts/generate-witness-bundle.sh
127+
128+
# 4. Self-verify the bundle — must be 7/7 PASS
129+
cd dist/witness-bundle-ADR028-*/
130+
bash VERIFY.sh
131+
```
132+
133+
**If the Python proof hash changes** (e.g., numpy/scipy version update):
134+
```bash
135+
# Regenerate the expected hash, then verify it passes
136+
python v1/data/proof/verify.py --generate-hash
137+
python v1/data/proof/verify.py
138+
```
139+
140+
**Witness bundle contents** (`dist/witness-bundle-ADR028-<sha>.tar.gz`):
141+
- `WITNESS-LOG-028.md` — 33-row attestation matrix with evidence per capability
142+
- `ADR-028-esp32-capability-audit.md` — Full audit findings
143+
- `proof/verify.py` + `expected_features.sha256` — Deterministic pipeline proof
144+
- `test-results/rust-workspace-tests.log` — Full cargo test output
145+
- `firmware-manifest/source-hashes.txt` — SHA-256 of all 7 ESP32 firmware files
146+
- `crate-manifest/versions.txt` — All 15 crates with versions
147+
- `VERIFY.sh` — One-command self-verification for recipients
148+
149+
**Key proof artifacts:**
150+
- `v1/data/proof/verify.py` — Trust Kill Switch: feeds reference signal through production pipeline, hashes output
151+
- `v1/data/proof/expected_features.sha256` — Published expected hash
152+
- `v1/data/proof/sample_csi_data.json` — 1,000 synthetic CSI frames (seed=42)
153+
- `docs/WITNESS-LOG-028.md` — 11-step reproducible verification procedure
154+
- `docs/adr/ADR-028-esp32-capability-audit.md` — Complete audit record
155+
49156
### Branch
50-
All development on: `claude/validate-code-quality-WNrNw`
157+
Default branch: `main`
158+
Active feature branch: `ruvsense-full-implementation` (PR #77)
51159

52160
---
53161

@@ -65,8 +173,13 @@ All development on: `claude/validate-code-quality-WNrNw`
65173
## File Organization
66174

67175
- NEVER save to root folder — use the directories below
68-
- `docs/adr/` — Architecture Decision Records
69-
- `rust-port/wifi-densepose-rs/crates/` — Rust workspace crates (signal, train, mat, nn, hardware)
176+
- `docs/adr/` — Architecture Decision Records (32 ADRs)
177+
- `docs/ddd/` — Domain-Driven Design models
178+
- `rust-port/wifi-densepose-rs/crates/` — Rust workspace crates (15 crates)
179+
- `rust-port/wifi-densepose-rs/crates/wifi-densepose-signal/src/ruvsense/` — RuvSense multistatic modules (14 files)
180+
- `rust-port/wifi-densepose-rs/crates/wifi-densepose-ruvector/src/viewpoint/` — Cross-viewpoint fusion (5 files)
181+
- `rust-port/wifi-densepose-rs/crates/wifi-densepose-hardware/src/esp32/` — ESP32 TDM protocol
182+
- `firmware/esp32-csi-node/main/` — ESP32 C firmware (channel hopping, NVS config, TDM)
70183
- `v1/src/` — Python source (core, hardware, services, api)
71184
- `v1/data/proof/` — Deterministic CSI proof bundles
72185
- `.claude-flow/` — Claude Flow coordination state (committed for team sharing)
@@ -93,14 +206,18 @@ All development on: `claude/validate-code-quality-WNrNw`
93206

94207
Before merging any PR, verify each item applies and is addressed:
95208

96-
1. **Tests pass** — `cargo test` (Rust) and `python -m pytest` (Python) green
97-
2. **README.md** — Update platform tables, crate descriptions, hardware tables, feature summaries if scope changed
98-
3. **CHANGELOG.md** — Add entry under `[Unreleased]` with what was added/fixed/changed
99-
4. **User guide** (`docs/user-guide.md`) — Update if new data sources, CLI flags, or setup steps were added
100-
5. **ADR index** — Update ADR count in README docs table if a new ADR was created
101-
6. **Docker Hub image** — Only rebuild if Dockerfile, dependencies, or runtime behavior changed (not needed for platform-gated code that doesn't affect the Linux container)
102-
7. **Crate publishing** — Only needed if a crate is published to crates.io and its public API changed (workspace-internal crates don't need publishing)
103-
8. **`.gitignore`** — Add any new build artifacts or binaries
209+
1. **Rust tests pass** — `cargo test --workspace --no-default-features` (1,031+ passed, 0 failed)
210+
2. **Python proof passes** — `python v1/data/proof/verify.py` (VERDICT: PASS)
211+
3. **README.md** — Update platform tables, crate descriptions, hardware tables, feature summaries if scope changed
212+
4. **CLAUDE.md** — Update crate table, ADR list, module tables, version if scope changed
213+
5. **CHANGELOG.md** — Add entry under `[Unreleased]` with what was added/fixed/changed
214+
6. **User guide** (`docs/user-guide.md`) — Update if new data sources, CLI flags, or setup steps were added
215+
7. **ADR index** — Update ADR count in README docs table if a new ADR was created
216+
8. **Witness bundle** — Regenerate if tests or proof hash changed: `bash scripts/generate-witness-bundle.sh`
217+
9. **Docker Hub image** — Only rebuild if Dockerfile, dependencies, or runtime behavior changed
218+
10. **Crate publishing** — Only needed if a crate is published to crates.io and its public API changed
219+
11. **`.gitignore`** — Add any new build artifacts or binaries
220+
12. **Security audit** — Run security review for new modules touching hardware/network boundaries
104221

105222
## Build & Test
106223

0 commit comments

Comments
 (0)