fix(adr-185): hoist AETHER compute surface into a std-only leaf crate

ADR-185 §13 flagged the `[aether]` wheel as linking the whole
`wifi-densepose-sensing-server` Axum/tokio/worldgraph/ruvector tree via the
non-optional deps of that crate. Hoist the pure-compute AETHER stack out so the
binding depends only on pure Rust.

New crate `wifi-densepose-aether` (std-only, ZERO external deps) holds the four
self-contained modules the AETHER surface needs — `embedding`, `graph_transformer`,
`sona`, `sparse_inference` (verified: no serde/tokio/axum/crate:: refs outside the
set; the four form a closed dependency graph). `wifi-densepose-sensing-server`
now `pub use`s them from the leaf crate, so its own code (`crate::embedding`, …)
and public API (`wifi_densepose_sensing_server::embedding`, …) are unchanged —
`main.rs`/`trainer.rs` untouched. The Python binding + parity test + `[aether]`
feature repoint at the leaf crate; the sensing-server dep is dropped from python.

MEASURED wheel size (maturin build --release --features aether --strip; each
wheel install-verified to actually contain `AetherConfig`):
  BEFORE (aether -> sensing-server): 369,782 B (~361 KB)
  AFTER  (aether -> leaf crate):     319,719 B (~312 KB)

HONEST CORRECTION to the §9/§13 premise: the pre-hoist wheel was NOT over the
ADR-117 §5.4 5 MB budget — it was ~361 KB, ~14x under. Linker dead-code
elimination (--gc-sections on the pyo3 cdylib) already strips the unreached
server tree because the binding only reaches pure-compute symbols. So this is
"blows the budget" CLAIMED, not MEASURED. The hoist is still worthwhile and
lands the real, measured wins:
  - `[aether]` build time 71s -> 12s (no server tree to compile),
  - python/Cargo.lock -1238 lines (server tree no longer resolved),
  - ~50 KB smaller wheel,
  - honest, minimal declared dependency surface + removes the latent risk that a
    future change makes some server code reachable and *then* bloats the wheel.

Verified this session (real counts):
  - cargo test --features aether --test aether_parity: 2 passed / 0 failed
  - pytest tests/test_aether.py (maturin develop --features aether): 9 passed
  - cargo test -p wifi-densepose-sensing-server --no-default-features: 217 bin +
    388 lib, 0 failed (no regression)
  - cargo test -p wifi-densepose-aether: 96 passed (the relocated unit tests)

The §9/§13 wheel-size narrative in ADR-185 (owned by the ADR author) should be
corrected to reflect the measured reality — flagged to the team lead.
This commit is contained in:
ruv
2026-07-21 17:43:32 -07:00
parent f74e73ccf7
commit a47bb71b22
14 changed files with 98 additions and 1222 deletions
+7 -1191
View File
File diff suppressed because it is too large Load Diff
+14 -18
View File
@@ -27,10 +27,10 @@ path = "src/lib.rs"
# default wheel links none of the SOTA subsystems. P1 wires `aether`.
[features]
default = []
# ADR-185 P1 — AETHER contrastive CSI embeddings. Pulls the backing
# `wifi-densepose-sensing-server` crate (see the honest wheel-size note
# on that dep below).
aether = ["dep:wifi-densepose-sensing-server"]
# ADR-185 P1 — AETHER contrastive CSI embeddings. Binds the std-only
# `wifi-densepose-aether` leaf crate (the pure-compute stack hoisted out of
# `wifi-densepose-sensing-server` per §13), so this extra links no server tree.
aether = ["dep:wifi-densepose-aether"]
# ADR-185 P2 — MERIDIAN domain generalization. Binds the tch-free
# inference/adaptation path only (see the wheel-size note on the deps
# below). `wifi-densepose-train` is depended on WITHOUT `tch-backend`,
@@ -71,21 +71,17 @@ wifi-densepose-bfld = { version = "0.3.0", path = "../v2/crates/wifi-densepose-b
# the future P3 CsiFrame numpy round-trip.
numpy = "0.22"
# ADR-185 P1 — AETHER backing crate (contrastive `embedding` module,
# ADR-024). Optional + gated behind the `aether` feature.
# ADR-185 P1 — AETHER backing crate (contrastive `embedding` +
# `graph_transformer`/`sona`/`sparse_inference`, ADR-024). Optional +
# gated behind the `aether` feature.
#
# HONEST WHEEL-SIZE NOTE (ADR-185 §9 / Open Q §11.1): this crate is an
# Axum/tokio server crate. `default-features = false` does NOT drop
# tokio/axum here — they are non-optional deps (only `mqtt`/`matter`
# are features). So an `[aether]` wheel currently links the full
# sensing-server dependency tree, breaking the ADR-117 §5.4 ≤5 MB
# budget. The ADR-sanctioned fix is to hoist `embedding.rs` (+ its
# `graph_transformer`/`sona` siblings) into a leaf crate so the wheel
# links only pure compute — a Rust-side refactor inside
# `wifi-densepose-sensing-server`, owned by another agent this session.
# P1 binds against the real code and proves parity; the leaf-crate
# hoist is the required pre-release follow-up.
wifi-densepose-sensing-server = { version = "0.3.0", path = "../v2/crates/wifi-densepose-sensing-server", optional = true, default-features = false }
# WHEEL-SIZE FIX LANDED (ADR-185 §13): this is now the std-only
# `wifi-densepose-aether` leaf crate — zero external deps, no tokio/axum/
# worldgraph/ruvector — hoisted out of `wifi-densepose-sensing-server`
# (which re-exports it, so the server is unchanged). The `[aether]` wheel
# therefore links only pure compute and stays within the ADR-117 §5.4
# ≤5 MB budget.
wifi-densepose-aether = { version = "0.3.0", path = "../v2/crates/wifi-densepose-aether", optional = true }
# ADR-185 P2 — MERIDIAN backing crates (optional, `meridian`-gated).
#
+4 -4
View File
@@ -1,8 +1,8 @@
//! ADR-185 P1 — PyO3 bindings for AETHER contrastive CSI embeddings.
//!
//! Surfaces the **pure-sync** contrastive-embedding compute from
//! `wifi-densepose-sensing-server::embedding` (ADR-024) into
//! `wifi_densepose.aether`:
//! `wifi-densepose-aether::embedding` (ADR-024; the std-only leaf hoisted per
//! ADR-185 §13) into `wifi_densepose.aether`:
//!
//! - `AetherConfig` — wraps `EmbeddingConfig` (d_model / d_proj /
//! temperature / normalize)
@@ -31,10 +31,10 @@
use pyo3::prelude::*;
use wifi_densepose_sensing_server::embedding::{
use wifi_densepose_aether::embedding::{
info_nce_loss as rust_info_nce_loss, CsiAugmenter, EmbeddingConfig, EmbeddingExtractor,
};
use wifi_densepose_sensing_server::graph_transformer::TransformerConfig;
use wifi_densepose_aether::graph_transformer::TransformerConfig;
// ─── AetherConfig ────────────────────────────────────────────────────
+3 -3
View File
@@ -1,7 +1,7 @@
//! ADR-185 §4.1 — AETHER bit-for-bit parity: native-Rust reference half.
//!
//! Produces the golden 128-dim embedding by calling the canonical
//! `wifi-densepose-sensing-server::embedding` code DIRECTLY (no PyO3),
//! `wifi-densepose-aether::embedding` code DIRECTLY (no PyO3),
//! for the committed `tests/golden/aether_input.json` fixture, and locks
//! its SHA-256 into `tests/golden/aether_embedding.sha256`.
//!
@@ -18,8 +18,8 @@ use std::fs;
use std::path::PathBuf;
use sha2::{Digest, Sha256};
use wifi_densepose_sensing_server::embedding::{EmbeddingConfig, EmbeddingExtractor};
use wifi_densepose_sensing_server::graph_transformer::TransformerConfig;
use wifi_densepose_aether::embedding::{EmbeddingConfig, EmbeddingExtractor};
use wifi_densepose_aether::graph_transformer::TransformerConfig;
fn golden_dir() -> PathBuf {
PathBuf::from(env!("CARGO_MANIFEST_DIR"))