feat(adr-185): P1 AETHER bindings (wifi_densepose.aether) + parity harness

Bind the ADR-024 contrastive CSI embedding surface into the wheel behind
a gated [aether] extra / Cargo `aether` feature, per ADR-185 section 3.2.

Surface (bound against the REAL code at HEAD, not the ADR wishlist):
- AetherConfig       -> EmbeddingConfig {d_model,d_proj,temperature,normalize}
- CsiAugmenter       -> augment_pair(window, seed)
- EmbeddingExtractor -> embed(csi): 128-dim L2-normed, GIL-released
- info_nce_loss, cosine_similarity (module fns)

ADR-185 section 3.2 also names aether_loss/VICReg components,
alignment_metric, uniformity_metric, forward_dual, and vicreg_* config
fields. None exist in embedding.rs at HEAD, so they are intentionally NOT
bound (a Rust-side gap, not a binding gap) rather than fabricated.

Parity (section 4.1, release-blocking): committed fixture
aether_input.json -> native Rust reference (tests/aether_parity.rs, calls
sensing-server EmbeddingExtractor directly) locks
tests/golden/aether_embedding.sha256; pytest (tests/test_aether.py) runs
the same fixture through the binding and asserts the identical SHA-256 of
the LE f32 bytes. Both pass.

Verified: cargo test --features aether --test aether_parity -> 2/2 pass;
maturin develop --features aether + pytest tests/test_aether.py -> 9/9
pass; default cargo build clean with 0 sensing-server refs in the dep
graph (gate keeps the base wheel lean).

HONEST WHEEL-SIZE FINDING (ADR-185 section 9 / Open Q 11.1, unresolved):
wifi-densepose-sensing-server is an Axum/tokio crate whose tokio/axum/
worldgraph/ruvector deps are NON-optional (only mqtt/matter are
features), so default-features=false does NOT drop them. An [aether]
wheel therefore links the full server tree and BREAKS the ADR-117 section
5.4 <=5 MB budget. The fix is the ADR-sanctioned hoist of embedding.rs
(+ its graph_transformer/sona siblings) into a leaf crate so the wheel
links pure compute only -- a change INSIDE wifi-densepose-sensing-server,
owned by another agent this session, so deferred as a required
pre-release follow-up. P1 binds real code and proves parity today; the
hoist is a wheel-size optimization, not a functional blocker.

Note: building required initializing the worldgraph/rufield/ruvector
submodules (absent in the fresh worktree).
This commit is contained in:
ruv
2026-07-21 16:28:14 -07:00
parent 5426fe830c
commit d060998e3b
11 changed files with 4276 additions and 26 deletions
+54
View File
@@ -0,0 +1,54 @@
"""Type stubs for the AETHER bindings (ADR-185 P1).
Present only when the wheel is built with the ``[aether]`` extra. The
top-level ``wifi_densepose`` package does not re-export these names, so
``mypy --strict`` sees them only via ``from wifi_densepose.aether import ...``.
"""
from __future__ import annotations
class AetherConfig:
def __init__(
self,
d_model: int = ...,
d_proj: int = ...,
temperature: float = ...,
normalize: bool = ...,
) -> None: ...
@property
def d_model(self) -> int: ...
@property
def d_proj(self) -> int: ...
@property
def temperature(self) -> float: ...
@property
def normalize(self) -> bool: ...
def __repr__(self) -> str: ...
class CsiAugmenter:
def __init__(self) -> None: ...
def augment_pair(
self, window: list[list[float]], seed: int
) -> tuple[list[list[float]], list[list[float]]]: ...
def __repr__(self) -> str: ...
class EmbeddingExtractor:
def __init__(
self,
n_subcarriers: int,
config: AetherConfig,
n_keypoints: int = ...,
n_heads: int = ...,
n_gnn_layers: int = ...,
) -> None: ...
def embed(self, csi_features: list[list[float]]) -> list[float]: ...
@property
def embedding_dim(self) -> int: ...
def __repr__(self) -> str: ...
def info_nce_loss(
embeddings_a: list[list[float]],
embeddings_b: list[list[float]],
temperature: float = ...,
) -> float: ...
def cosine_similarity(a: list[float], b: list[float]) -> float: ...