//! # 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>;