wifi-densepose/docs/adr/ADR-002-ruvector-rvf-integration-strategy.md

ADR-002: RuVector RVF Integration Strategy

Status

Proposed

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):

# 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:

[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
• HNSW Algorithm
• LoRA: Low-Rank Adaptation
• Elastic Weight Consolidation
• Raft Consensus
• ML-DSA (FIPS 204)
• WiFi-DensePose Rust ADR-001: Workspace Structure