mirror of
https://github.com/ruvnet/RuView
synced 2026-07-28 18:21:42 +00:00
rUv
2e018f4f19
Native frame contract, universal RF encoder, RF-aware Gaussian spatial memory, physics-guided synthetic RF worlds, edge sensing control plane, BLE-CS + factorized pose. All 10 ADRs (273-282) fully implemented and tested (99 tests); ADR-278 (radar inverse rendering) honestly gated with zero code as a future research program. Deep-reviewed and hardware-tested against a live ESP32-C6 CSI node before merge: fixed a reachable panic, a silent NaN-corruption path, a cross-entity Gaussian conflation bug, and a wrong-center-frequency bug in the WiFi adapter (confirmed live: was misreporting channel 4 as 2437 MHz, now correctly reports 2427 MHz matching the hardware parser exactly). Added a standing hardware-in-the-loop test (examples/esp32_live_hardware_test.rs). Also fixed unrelated pre-existing issues surfaced during validation (wifi-densepose-core clippy warnings, a ruview-auth Windows build break, a sensing-server test flake). Full review: https://gist.github.com/ruvnet/89795f3c4b8ea166cff5ac35ae4c7651
89 lines
3.9 KiB
Rust
89 lines
3.9 KiB
Rust
//! # ruview-unified — Unified RF Spatial World Model (ADR-273)
|
|
//!
|
|
//! One shared representation where WiFi CSI, cellular SRS, FMCW radar, UWB
|
|
//! CIR, geometry, semantics, uncertainty, and time all update the same
|
|
//! persistent scene memory, instead of another isolated RF classifier.
|
|
//!
|
|
//! The crate implements the five ADR-273 pillars as bounded modules:
|
|
//!
|
|
//! | Pillar | Module | ADR |
|
|
//! |--------|--------|-----|
|
|
//! | Canonical RF tensor + hardware adapter registry | [`tensor`], [`adapters`] | ADR-274 |
|
|
//! | Universal RF foundation encoder (masked-reconstruction pretraining, age/geometry/uncertainty fusion, ≤1 % task adapters) | [`tokenizer`], [`encoder`], [`pretrain`], [`heads`] | ADR-274 |
|
|
//! | Anti-leakage evaluation: strict partitions, calibration, abstention | [`eval`] | ADR-273 §5 |
|
|
//! | RF-aware Gaussian spatial memory + task-gated scene graph | [`gaussian`] | ADR-275 |
|
|
//! | Physics-guided synthetic RF world generator | [`synth`] | ADR-276 |
|
|
//! | Edge sensing control plane (802.11bf / ETSI ISAC-aligned policy) | [`policy`] | ADR-277 |
|
|
//!
|
|
//! ## Design commitments
|
|
//!
|
|
//! - **Deterministic**: every stochastic step (weight init, masking, domain
|
|
//! randomization) is seeded ChaCha20; same seed ⇒ identical results across
|
|
//! machines (the nvsim commitment).
|
|
//! - **Proven, not asserted**: the encoder's backward pass is verified against
|
|
//! finite differences; the ray tracer is verified against Friis, reciprocity,
|
|
//! and image-method geometry; the Gaussian gain model degrades to exact
|
|
//! free-space when the map is empty.
|
|
//! - **Honest labeling**: every accuracy number produced by this crate's tests
|
|
//! is SYNTHETIC (generated by [`synth`]) until validated on measured data.
|
|
//! - **Privacy fail-closed**: raw RF never crosses the trust boundary; only
|
|
//! [`policy::BoundedEvent`] (uncertainty + provenance + model version +
|
|
//! purpose, all mandatory) is exportable, and unknown zones/purposes deny.
|
|
|
|
// The numeric kernels (encoder forward/backward, low-rank heads) index
|
|
// several parallel arrays per iteration; index loops are the clearest and
|
|
// equally fast form there.
|
|
#![allow(clippy::needless_range_loop)]
|
|
|
|
pub mod adapters;
|
|
pub mod control;
|
|
pub mod encoder;
|
|
pub mod eval;
|
|
pub mod frame;
|
|
pub mod gaussian;
|
|
pub mod heads;
|
|
pub mod math;
|
|
pub mod policy;
|
|
pub mod pretrain;
|
|
pub mod synth;
|
|
pub mod tensor;
|
|
pub mod tokenizer;
|
|
|
|
pub use adapters::{AdapterRegistry, RawCapture, RfAdapter};
|
|
pub use encoder::{EncoderConfig, RfEncoder, WindowContext};
|
|
pub use tensor::{CalibrationMeta, LinkGeometry, RfModality, RfTensor};
|
|
|
|
/// Errors produced at the crate's system boundaries.
|
|
///
|
|
/// Input validation happens at construction ([`RfTensor::new`]) and at
|
|
/// adapter normalization; downstream modules may assume validated tensors.
|
|
#[derive(Debug, thiserror::Error)]
|
|
pub enum UnifiedError {
|
|
/// A numeric field was non-finite or out of its documented range.
|
|
#[error("invalid input at boundary: {0}")]
|
|
InvalidInput(String),
|
|
/// Tensor shape does not match its declared link geometry.
|
|
#[error("shape mismatch: {0}")]
|
|
ShapeMismatch(String),
|
|
/// An adapter was handed a capture of the wrong modality.
|
|
#[error("modality mismatch: adapter {adapter} cannot normalize {got:?}")]
|
|
ModalityMismatch {
|
|
/// Hardware id of the adapter that rejected the capture.
|
|
adapter: String,
|
|
/// Modality of the capture that was offered.
|
|
got: tensor::RfModality,
|
|
},
|
|
/// No adapter registered for the requested hardware id.
|
|
#[error("no adapter registered for hardware id {0:?}")]
|
|
UnknownHardware(String),
|
|
/// Model/data dimension disagreement (programmer error surfaced safely).
|
|
#[error("dimension mismatch: {0}")]
|
|
DimensionMismatch(String),
|
|
/// The sensing control plane denied the operation (fail-closed).
|
|
#[error("policy denied: {0}")]
|
|
PolicyDenied(String),
|
|
}
|
|
|
|
/// Crate-wide result alias.
|
|
pub type Result<T> = std::result::Result<T, UnifiedError>;
|