ADR-027: Project MERIDIAN — Cross-Environment Domain Generalization for WiFi Pose Estimation

[ruvnet]

The Problem: WiFi Models Break When You Move Them

Train a WiFi pose estimation model in your living room -- it works great. Move it to the kitchen -- accuracy drops 40-70%. Deploy it in a different building -- it fails completely.

This is the domain gap problem, and it is the single biggest barrier to real-world WiFi sensing deployment.

Why it happens

Every room has a unique WiFi "personality":

1. Layout memorization -- the model memorizes where the router and receiver are, instead of learning how human bodies disturb WiFi signals
2. Multipath fingerprinting -- walls, furniture, and room geometry create a unique reflection pattern that the model uses as a shortcut
3. Hardware differences -- an ESP32 (64 subcarriers) produces completely different CSI than an Intel 5300 (30 subcarriers)

The current wifi-densepose system trains and evaluates in a single environment. There is zero mechanism to handle new rooms, new buildings, or mixed hardware.

---

The Solution: Project MERIDIAN (ADR-027)

Multi-Environment Robust Inference via Domain-Invariant Alignment Networks

MERIDIAN adds a domain generalization layer to the existing pipeline. The core idea: explicitly separate what the model knows about the room from what it knows about the person.

CSI Frame --> HardwareNormalizer --> Existing Pipeline --> DomainFactorizer
                                                              |-> h_pose (person info -- used for pose)
                                                              |-> h_env  (room info -- discarded at inference)

The model is trained to maximize confusion about which room the data came from (adversarial training), while minimizing pose error. This forces it to learn environment-agnostic human motion features.

---

What MERIDIAN Adds (6 New Modules)

1. Hardware Normalizer (hardware_norm.rs)

Resamples any WiFi hardware CSI to a canonical 56-subcarrier format. ESP32 (64 sub), Intel 5300 (30 sub), Atheros (56 sub) all produce identical input shape.

Uses Catmull-Rom cubic interpolation + z-score normalization + phase sanitization.

2. Domain Factorizer + Gradient Reversal (domain.rs)

Splits the neural network internal representation into two paths:

• Pose path (h_pose) -- environment-invariant features for body tracking
• Environment path (h_env) -- room-specific information, discarded at inference

A Gradient Reversal Layer (GRL) trains the pose path to be maximally confusing to a room classifier -- forcing it to drop all room-specific shortcuts.

3. Geometry Encoder + FiLM Conditioning (geometry.rs)

Enables zero-shot deployment: tell the model where the WiFi APs are located, and it adjusts its coordinate frame automatically. No retraining needed.

Uses Fourier positional encoding + permutation-invariant DeepSets + Feature-wise Linear Modulation (FiLM).

4. Virtual Domain Augmentation (virtual_aug.rs)

Generates synthetic "virtual rooms" during training by simulating:

• Different room sizes (path loss scaling)
• Different wall materials (reflection coefficients)
• Different furniture layouts (virtual scatterers)
• Different hardware noise profiles

Each training batch sees 4x more environment diversity than real data alone.

5. Few-Shot Rapid Adaptation (rapid_adapt.rs)

10 seconds of WiFi data in a new room produces automatic environment-specific fine-tuning. No pose labels needed.

Combines SONA LoRA adapters (ADR-005) with contrastive test-time training from AETHER (ADR-024).

6. Cross-Domain Evaluation (eval.rs)

Rigorous 6-metric evaluation protocol following PerceptAlign methodology:

• In-domain MPJPE, Cross-domain MPJPE, Few-shot MPJPE
• Cross-hardware MPJPE, Domain gap ratio, Adaptation speedup

---

How It Compares

Approach	Cross-Layout	Cross-Hardware	Zero-Shot	Few-Shot	Edge (ESP32)	Multi-Person
MERIDIAN	Yes	Yes	Yes	Yes	Yes (+12K params)	Yes
PerceptAlign (2026)	Yes	No	Partial	No	No (20M params)	No
X-Fi (ICLR 2025)	Yes	Yes	Yes	Yes	No (large)	Yes
AM-FM (2026)	Yes	Yes	Yes	Yes	No (foundation)	Unknown
DGSense (2025)	Yes	Yes	Yes	No	No (ResNet)	No
Current wifi-densepose	No	No	No	Partial	Yes	Yes

MERIDIAN key differentiator: it is additive (small modules on top of existing pipeline), edge-compatible (+12K parameters, 67K total, still fits ESP32), and the first open-source WiFi pose system with cross-environment generalization.

---

Gap Closure: Proposed ADRs Addressed

MERIDIAN also closes gaps from 10 earlier proposed ADRs (002-011):

Status	ADRs	What is Resolved
Directly addressed	ADR-004, 005, 006	HNSW fingerprints become cross-room; SONA gets unsupervised adaptation; GNN gets adversarial regularization
Superseded	ADR-002	Already implemented by ADR-016/017
Enabled	ADR-003, 008, 009	Cognitive containers, multi-AP consensus, and WASM runtime all build on MERIDIAN infrastructure
Independent	ADR-007, 010, 011	Post-quantum crypto, witness chains, and Python proof-of-reality remain separate tracks

---

Model Size Impact

Component	Parameters	Memory
Existing model (ADR-023 + ADR-024)	~55,000	55 KB
+ GeometryEncoder	~8,000	8 KB
+ DomainFactorizer (PoseEncoder only)	~4,000	4 KB
MERIDIAN Total	~67,000	67 KB
ESP32 available SRAM	--	520 KB

---

SOTA Research Foundation

MERIDIAN draws from 10 peer-reviewed papers (2024-2026):

1. PerceptAlign (Chen et al., 2026) -- geometry-conditioned WiFi pose, 60% cross-domain improvement
2. AdaPose (Zhou et al., 2024) -- first cross-site WiFi pose estimation
3. Person-in-WiFi 3D (Yan et al., CVPR 2024) -- end-to-end multi-person 3D from WiFi
4. DGSense (Zhou et al., 2025) -- virtual data + episodic training for zero-shot sensing
5. CAPC (IEEE OJCOMS, 2024) -- self-supervised predictive coding for WiFi
6. X-Fi (Chen and Yang, ICLR 2025) -- modality-invariant foundation model, 24.8% improvement
7. AM-FM (2026) -- first WiFi foundation model, 9.2M samples, 20 device types
8. LatentCSI (Ramesh et al., 2025) -- CSI-to-image via diffusion models
9. Ganin et al. (JMLR 2016) -- domain-adversarial neural networks (GRL)
10. FiLM (Perez et al., AAAI 2018) -- feature-wise linear modulation

---

Implementation Status

Phase	Module	Lines	Tests	Status
1	hardware_norm.rs	399	14	Complete
2	domain.rs	392	20	Complete
3	geometry.rs	364	14	Complete
4	virtual_aug.rs	297	10	Complete
5	rapid_adapt.rs	255	7	Complete
6	eval.rs	151	7	Complete
7	RVF container segments	--	--	Planned
Total	6 modules	1,858	72	6/7 phases done

Branch: adr-027-cross-environment-domain-generalization

Full ADR: docs/adr/ADR-027-cross-environment-domain-generalization.md

---

Quick Start (After Merge)

# Train with MERIDIAN domain generalization
cargo run -p wifi-densepose-sensing-server -- \
  --train --dataset data/mmfi/ --epochs 100 \
  --meridian --n-virtual-domains 3 \
  --save-rvf model-meridian.rvf

# Deploy with zero-shot geometry conditioning
cargo run -p wifi-densepose-sensing-server -- \
  --model model-meridian.rvf \
  --ap-positions "0,0,2.5;3.5,0,2.5;1.75,4,2.5"

# 10-second calibration in new environment
cargo run -p wifi-densepose-sensing-server -- \
  --model model-meridian.rvf --calibrate --calibrate-duration 10

[ruvnet]

ADR-027 Project MERIDIAN — Implementation Status

✅ Complete — All 7 Phases Implemented & Published

All six core modules plus the full training pipeline integration are implemented, tested, security-hardened, and published to crates.io.

---

Modules Delivered

Module	File	Description
Gradient Reversal Layer	domain.rs	λ-scheduled GRL with AdversarialSchedule (linear / exponential / cosine)
Domain Classifier	domain.rs	3-layer MLP with DomainFactorizer for multi-factor decomposition
Geometry Encoder	geometry.rs	Fourier positional encoding → DeepSets → FiLM conditioning
Cross-Domain Evaluator	eval.rs	Leave-one-out + per-environment PCK/OKS metrics
Virtual Domain Augmentation	virtual_aug.rs	Synthetic WiFi environments (room scale, reflections, scatterers, noise)
Rapid Adaptation (TTT)	rapid_adapt.rs	Contrastive test-time training with LoRA weight generation

Security Audit — All Findings Resolved

• F1-HIGH: Unbounded calibration buffer → bounded ring-buffer (max 10,000 frames)
• F10: Zero LoRA rank panic → AdaptError::InvalidRank error return
• C3: Deterministic Linear weights → atomic instance counter for unique seeds
• C5: adapt() panics → returns Result<AdaptationResult, AdaptError>
• C2: PRNG precision loss → 24-bit mantissa-matching uniform distribution
• F6: Division by zero in virtual aug → room_scale guard

Test Results

• 201 tests passing (96 train unit + signal + integration + doctests)
• All existing tests unaffected — zero regressions

Published Artifacts

• 15 crates published at v0.2.0 on crates.io:
  core, config, db, signal, nn, api, hardware, mat, train, ruvector, wasm, vitals, wifiscan, sensing-server, cli

Documentation

• User guide updated with MERIDIAN cross-environment adaptation section
• Training pipeline expanded from 8 → 10 phases
• ADR-027 fully documented in docs/adr/

PR Ready to Merge

PR #69 — feat: ADR-027 MERIDIAN cross-environment domain generalization (all 7 phases)

• Merge state: CLEAN ✅
• Branch: adr-027-cross-environment-domain-generalization

---

This issue can be closed once PR #69 is merged.