2d6dc66f7c
- CHANGELOG: add MERIDIAN (ADR-027) to Unreleased section - README: add "Works Everywhere" to Intelligence features, update How It Works - ADR-002: status → Superseded by ADR-016/017 - ADR-004: status → Partially realized by ADR-024, extended by ADR-027 - ADR-005: status → Partially realized by ADR-023, extended by ADR-027 - ADR-006: status → Partially realized by ADR-023, extended by ADR-027 Co-Authored-By: claude-flow <ruv@ruv.net>
220 lines
15 KiB
Markdown
220 lines
15 KiB
Markdown
# ADR-002: RuVector RVF Integration Strategy
|
|
|
|
## Status
|
|
Superseded by [ADR-016](ADR-016-ruvector-integration.md) and [ADR-017](ADR-017-ruvector-signal-mat-integration.md)
|
|
|
|
> **Note:** The vision in this ADR has been fully realized. ADR-016 integrates all 5 RuVector crates into the training pipeline. ADR-017 adds 7 signal + MAT integration points. The `wifi-densepose-ruvector` crate is [published on crates.io](https://crates.io/crates/wifi-densepose-ruvector). See also [ADR-027](ADR-027-cross-environment-domain-generalization.md) for how RuVector is extended with domain generalization.
|
|
|
|
## Date
|
|
2026-02-28
|
|
|
|
## Context
|
|
|
|
### Current System Limitations
|
|
|
|
The WiFi-DensePose system processes Channel State Information (CSI) from WiFi signals to estimate human body poses. The current architecture (Python v1 + Rust port) has several areas where intelligence and performance could be significantly improved:
|
|
|
|
1. **No persistent vector storage**: CSI feature vectors are processed transiently. Historical patterns, fingerprints, and learned representations are not persisted in a searchable vector database.
|
|
|
|
2. **Static inference models**: The modality translation network (`ModalityTranslationNetwork`) and DensePose head use fixed weights loaded at startup. There is no online learning, adaptation, or self-optimization.
|
|
|
|
3. **Naive pattern matching**: Human detection in `CSIProcessor` uses simple threshold-based confidence scoring (`amplitude_indicator`, `phase_indicator`, `motion_indicator` with fixed weights 0.4, 0.3, 0.3). No similarity search against known patterns.
|
|
|
|
4. **No cryptographic audit trail**: Life-critical disaster detection (wifi-densepose-mat) lacks tamper-evident logging for survivor detections and triage classifications.
|
|
|
|
5. **Limited edge deployment**: The WASM crate (`wifi-densepose-wasm`) provides basic bindings but lacks a self-contained runtime capable of offline operation with embedded models.
|
|
|
|
6. **Single-node architecture**: Multi-AP deployments for disaster scenarios require distributed coordination, but no consensus mechanism exists for cross-node state management.
|
|
|
|
### RuVector Capabilities
|
|
|
|
RuVector (github.com/ruvnet/ruvector) provides a comprehensive cognitive computing platform:
|
|
|
|
- **RVF (Cognitive Containers)**: Self-contained files with 25 segment types (VEC, INDEX, KERNEL, EBPF, WASM, COW_MAP, WITNESS, CRYPTO) that package vectors, models, and runtime into a single deployable artifact
|
|
- **HNSW Vector Search**: Hierarchical Navigable Small World indexing with SIMD acceleration and Hyperbolic extensions for hierarchy-aware search
|
|
- **SONA**: Self-Optimizing Neural Architecture providing <1ms adaptation via LoRA fine-tuning with EWC++ memory preservation
|
|
- **GNN Learning Layer**: Graph Neural Networks that learn from every query through message passing, attention weighting, and representation updates
|
|
- **46 Attention Mechanisms**: Including Flash Attention, Linear Attention, Graph Attention, Hyperbolic Attention, Mincut-gated Attention
|
|
- **Post-Quantum Cryptography**: ML-DSA-65, Ed25519, SLH-DSA-128s signatures with SHAKE-256 hashing
|
|
- **Witness Chains**: Tamper-evident cryptographic hash-linked audit trails
|
|
- **Raft Consensus**: Distributed coordination with multi-master replication and vector clocks
|
|
- **WASM Runtime**: 5.5 KB runtime bootable in 125ms, deployable on servers, browsers, phones, IoT
|
|
- **Git-like Branching**: Copy-on-write structure (1M vectors + 100 edits ≈ 2.5 MB branch)
|
|
|
|
## Decision
|
|
|
|
We will integrate RuVector's RVF format and intelligence capabilities into the WiFi-DensePose system through a phased, modular approach across 9 integration domains, each detailed in subsequent ADRs (ADR-003 through ADR-010).
|
|
|
|
### Integration Architecture Overview
|
|
|
|
```
|
|
┌─────────────────────────────────────────────────────────────────────────────┐
|
|
│ WiFi-DensePose + RuVector │
|
|
├─────────────────────────────────────────────────────────────────────────────┤
|
|
│ │
|
|
│ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │
|
|
│ │ CSI Input │ │ RVF Store │ │ SONA │ │ GNN Layer │ │
|
|
│ │ Pipeline │──▶│ (Vectors, │──▶│ Self-Learn │──▶│ Pattern │ │
|
|
│ │ │ │ Indices) │ │ │ │ Enhancement │ │
|
|
│ └──────┬───────┘ └──────┬───────┘ └──────┬───────┘ └──────┬───────┘ │
|
|
│ │ │ │ │ │
|
|
│ ▼ ▼ ▼ ▼ │
|
|
│ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │
|
|
│ │ Feature │ │ HNSW │ │ Adaptive │ │ Pose │ │
|
|
│ │ Extraction │ │ Search │ │ Weights │ │ Estimation │ │
|
|
│ └──────┬───────┘ └──────┬───────┘ └──────┬───────┘ └──────┬───────┘ │
|
|
│ │ │ │ │ │
|
|
│ └─────────────────┴─────────────────┴─────────────────┘ │
|
|
│ │ │
|
|
│ ┌──────────▼──────────┐ │
|
|
│ │ Output Layer │ │
|
|
│ │ • Pose Keypoints │ │
|
|
│ │ • Body Segments │ │
|
|
│ │ • UV Coordinates │ │
|
|
│ │ • Confidence Maps │ │
|
|
│ └──────────┬──────────┘ │
|
|
│ │ │
|
|
│ ┌───────────────────────────┼───────────────────────────┐ │
|
|
│ ▼ ▼ ▼ │
|
|
│ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │
|
|
│ │ Witness │ │ Raft │ │ WASM │ │
|
|
│ │ Chains │ │ Consensus │ │ Edge │ │
|
|
│ │ (Audit) │ │ (Multi-AP) │ │ Runtime │ │
|
|
│ └──────────────┘ └──────────────┘ └──────────────┘ │
|
|
│ │
|
|
│ ┌─────────────────────────────────────────────────────────────────────┐ │
|
|
│ │ Post-Quantum Crypto Layer │ │
|
|
│ │ ML-DSA-65 │ Ed25519 │ SLH-DSA-128s │ SHAKE-256 │ │
|
|
│ └─────────────────────────────────────────────────────────────────────┘ │
|
|
└─────────────────────────────────────────────────────────────────────────────┘
|
|
```
|
|
|
|
### New Crate: `wifi-densepose-rvf`
|
|
|
|
A new workspace member crate will serve as the integration layer:
|
|
|
|
```
|
|
crates/wifi-densepose-rvf/
|
|
├── Cargo.toml
|
|
├── src/
|
|
│ ├── lib.rs # Public API surface
|
|
│ ├── container.rs # RVF cognitive container management
|
|
│ ├── vector_store.rs # HNSW-backed CSI vector storage
|
|
│ ├── search.rs # Similarity search for fingerprinting
|
|
│ ├── learning.rs # SONA integration for online learning
|
|
│ ├── gnn.rs # GNN pattern enhancement layer
|
|
│ ├── attention.rs # Attention mechanism selection
|
|
│ ├── witness.rs # Witness chain audit trails
|
|
│ ├── consensus.rs # Raft consensus for multi-AP
|
|
│ ├── crypto.rs # Post-quantum crypto wrappers
|
|
│ ├── edge.rs # WASM edge runtime integration
|
|
│ └── adapters/
|
|
│ ├── mod.rs
|
|
│ ├── signal_adapter.rs # Bridges wifi-densepose-signal
|
|
│ ├── nn_adapter.rs # Bridges wifi-densepose-nn
|
|
│ └── mat_adapter.rs # Bridges wifi-densepose-mat
|
|
```
|
|
|
|
### Phased Rollout
|
|
|
|
| Phase | Timeline | ADR | Capability | Priority |
|
|
|-------|----------|-----|------------|----------|
|
|
| 1 | Weeks 1-3 | ADR-003 | RVF Cognitive Containers for CSI Data | Critical |
|
|
| 2 | Weeks 2-4 | ADR-004 | HNSW Vector Search for Signal Fingerprinting | Critical |
|
|
| 3 | Weeks 4-6 | ADR-005 | SONA Self-Learning for Pose Estimation | High |
|
|
| 4 | Weeks 5-7 | ADR-006 | GNN-Enhanced CSI Pattern Recognition | High |
|
|
| 5 | Weeks 6-8 | ADR-007 | Post-Quantum Cryptography for Secure Sensing | Medium |
|
|
| 6 | Weeks 7-9 | ADR-008 | Distributed Consensus for Multi-AP | Medium |
|
|
| 7 | Weeks 8-10 | ADR-009 | RVF WASM Runtime for Edge Deployment | Medium |
|
|
| 8 | Weeks 9-11 | ADR-010 | Witness Chains for Audit Trail Integrity | High (MAT) |
|
|
|
|
### Dependency Strategy
|
|
|
|
**Verified published crates** (crates.io, all at v2.0.4 as of 2026-02-28):
|
|
|
|
```toml
|
|
# In Cargo.toml workspace dependencies
|
|
[workspace.dependencies]
|
|
ruvector-mincut = "2.0.4" # Dynamic min-cut, O(n^1.5 log n) graph partitioning
|
|
ruvector-attn-mincut = "2.0.4" # Attention + mincut gating in one pass
|
|
ruvector-temporal-tensor = "2.0.4" # Tiered temporal compression (50-75% memory reduction)
|
|
ruvector-solver = "2.0.4" # NeumannSolver — O(√n) Neumann series convergence
|
|
ruvector-attention = "2.0.4" # ScaledDotProductAttention
|
|
```
|
|
|
|
> **Note (ADR-017 correction):** Earlier versions of this ADR specified
|
|
> `ruvector-core`, `ruvector-data-framework`, `ruvector-consensus`, and
|
|
> `ruvector-wasm` at version `"0.1"`. These crates do not exist at crates.io.
|
|
> The five crates above are the verified published API surface at v2.0.4.
|
|
> Capabilities such as RVF cognitive containers (ADR-003), HNSW search (ADR-004),
|
|
> SONA (ADR-005), GNN patterns (ADR-006), post-quantum crypto (ADR-007),
|
|
> Raft consensus (ADR-008), and WASM runtime (ADR-009) are internal capabilities
|
|
> accessible through these five crates or remain as forward-looking architecture.
|
|
> See ADR-017 for the corrected integration map.
|
|
|
|
Feature flags control which ruvector capabilities are compiled in:
|
|
|
|
```toml
|
|
[features]
|
|
default = ["mincut-matching", "solver-interpolation"]
|
|
mincut-matching = ["ruvector-mincut"]
|
|
attn-mincut = ["ruvector-attn-mincut"]
|
|
temporal-compress = ["ruvector-temporal-tensor"]
|
|
solver-interpolation = ["ruvector-solver"]
|
|
attention = ["ruvector-attention"]
|
|
full = ["mincut-matching", "attn-mincut", "temporal-compress", "solver-interpolation", "attention"]
|
|
```
|
|
|
|
## Consequences
|
|
|
|
### Positive
|
|
|
|
- **10-100x faster pattern lookup**: HNSW replaces linear scan for CSI fingerprint matching
|
|
- **Continuous improvement**: SONA enables online adaptation without full retraining
|
|
- **Self-contained deployment**: RVF containers package everything needed for field operation
|
|
- **Tamper-evident records**: Witness chains provide cryptographic proof for disaster response auditing
|
|
- **Future-proof security**: Post-quantum signatures resist quantum computing attacks
|
|
- **Distributed operation**: Raft consensus enables coordinated multi-AP sensing
|
|
- **Ultra-light edge**: 5.5 KB WASM runtime enables browser and IoT deployment
|
|
- **Git-like versioning**: COW branching enables experimental model variations with minimal storage
|
|
|
|
### Negative
|
|
|
|
- **Increased binary size**: Full feature set adds significant dependencies (~15-30 MB)
|
|
- **Complexity**: 9 integration domains require careful coordination
|
|
- **Learning curve**: Team must understand RuVector's cognitive container paradigm
|
|
- **API stability risk**: RuVector is pre-1.0; APIs may change
|
|
- **Testing surface**: Each integration point requires dedicated test suites
|
|
|
|
### Risks and Mitigations
|
|
|
|
| Risk | Severity | Mitigation |
|
|
|------|----------|------------|
|
|
| RuVector API breaking changes | High | Pin versions, adapter pattern isolates impact |
|
|
| Performance regression from abstraction layers | Medium | Benchmark each integration point, zero-cost abstractions |
|
|
| Feature flag combinatorial complexity | Medium | CI matrix testing for key feature combinations |
|
|
| Over-engineering for current use cases | Medium | Phased rollout, each phase independently valuable |
|
|
| Binary size bloat for edge targets | Low | Feature flags ensure only needed capabilities compile |
|
|
|
|
## Related ADRs
|
|
|
|
- **ADR-001**: WiFi-Mat Disaster Detection Architecture (existing)
|
|
- **ADR-003**: RVF Cognitive Containers for CSI Data
|
|
- **ADR-004**: HNSW Vector Search for Signal Fingerprinting
|
|
- **ADR-005**: SONA Self-Learning for Pose Estimation
|
|
- **ADR-006**: GNN-Enhanced CSI Pattern Recognition
|
|
- **ADR-007**: Post-Quantum Cryptography for Secure Sensing
|
|
- **ADR-008**: Distributed Consensus for Multi-AP Coordination
|
|
- **ADR-009**: RVF WASM Runtime for Edge Deployment
|
|
- **ADR-010**: Witness Chains for Audit Trail Integrity
|
|
|
|
## References
|
|
|
|
- [RuVector Repository](https://github.com/ruvnet/ruvector)
|
|
- [HNSW Algorithm](https://arxiv.org/abs/1603.09320)
|
|
- [LoRA: Low-Rank Adaptation](https://arxiv.org/abs/2106.09685)
|
|
- [Elastic Weight Consolidation](https://arxiv.org/abs/1612.00796)
|
|
- [Raft Consensus](https://raft.github.io/raft.pdf)
|
|
- [ML-DSA (FIPS 204)](https://csrc.nist.gov/pubs/fips/204/final)
|
|
- [WiFi-DensePose Rust ADR-001: Workspace Structure](../rust-port/wifi-densepose-rs/docs/adr/ADR-001-workspace-structure.md)
|