Introducing a new way to review your PRs.

Read the announcement

ruvnet / ruview

π RuView turns commodity WiFi signals into real-time spatial intelligence, vital sign monitoring, and presence detection — all without a single pixel of video.

View on GitHub

13 documents · Updated Nov 19, 2026

docs / v2-ruview-spatial-intelligence

Rust v2 Ruview Spatial Intelligence

Overview

The v2 Ruview spatial/intelligence subsystem is a set of Rust crates registered in v2/Cargo.toml as the ADR-300 perception substrate spine and phase-3 spatial primitives. The canonical vocabulary starts in v2/…/lib.rs: WorldGraph stores the Site → Building → Floor → Space → Zone containment hierarchy plus Sensor, Observation, Person, Track, Object, and Event leaves. v2/…/graph.rs is the insertion boundary: parents and containers must already exist, duplicate IDs are rejected, and space_of/zone_of resolve leaf locations. All leaves carry EvidenceLevel and SemanticProvenance from v2/…/provenance.rs, and typed IDs are bounded in v2/…/id.rs.

Observations become spatial state through fusion first. v2/…/observation.rs defines PresenceObservation as a ruview_hal::HalObservation plus a presence Claim; degraded HAL observations and explicit Claim::Unknown abstain but still remain as provenance. v2/…/engine.rs groups observations by ontology Container, sorts them deterministically by observation ID, combines usable estimates with inverse-variance weighting from v2/…/estimate.rs, and emits one WorldState from v2/…/world.rs. Each ZoneState is either Presence::Estimated { probability, variance } or first-class Presence::Unknown for insufficient coverage or irreconcilable chi-square conflict; every Contribution records the source observation, sensor, modality, evidence level, estimate, and normalized weight.

Persistent movement state is represented separately by v2/…/manager.rs. A TrackManager ingests per-frame Detections containing an ontology Container, 2-D position, bounded coarse feature, and injected timestamp. Association is gated by Topology adjacency from v2/…/topology.rs, position/feature thresholds and lifecycle timing from v2/…/config.rs, then greedily assigned one-to-one per frame. Ambiguous, gated-out, contested, or unmatched detections return Association::Unknown and spawn tentative tracks rather than forcing a join. to_track and to_person project manager state back into ontology Track/Person nodes, with tentative tracks floored to L0. Privacy is enforced by v2/…/feature.rs: CoarseFeature quantizes bounded vectors into eight buckets and has no de-quantizer.

Longer-term spatial state has two forms. v2/…/lib.rs is a synthetic learned-normal model keyed by ZoneId: SpatialMemory::observe scores a ZoneObservation against the existing ZoneBaseline, emits AnomalyEvents for unusual occupancy hours, propagation changes, or modality changes, then folds the current snapshot into the baseline. v2/…/baseline.rs stores 24 hourly occupancy RunningStats, per-link LinkStats keyed by ruview_twin::LinkId, modality channels, update count, and an evidence floor. v2/…/stat.rs implements deterministic exponentially weighted mean/variance with a forgetting factor. seed_zone_propagation_from_twin initializes link baselines from the RF twin's expected distributions, so propagation anomalies are scored against a modeled prior immediately. v2/…/anomaly.rs projects anomalies into ruview_evidence::EvidenceRecords as synthetic L0 records carrying drift and significance, not accuracy rates.

v2/…/lib.rs is the tenant/workspace-scoped semantic history store. It only accepts bounded semantic MemoryRecords with tenant/workspace PartitionKey, site/space scope, fixed-dimensional features, uncertainty, evidence grade, provenance and optional witness digests, replay IDs, source sequence, expiry, retention, and derivation links. Each partition owns its own wifi_densepose_ruvector::HnswIndex, so SpatialMemory::search selects the exact tenant/workspace index before ANN and then applies site/space/schema/time filters. Ingest enforces id/message replay defense, monotonic source sequences, derivation existence, expiry, and dimensionality. Persistence uses XChaCha20-Poly1305 envelopes with bounded file size, authenticated key ID AAD, create-if-absent writes, and key rotation through load + save_new.

v2/…/twin.rs defines the RF digital twin: a per-deployment synthetic L0 model containing ontology SpaceId/Container references, RadioNodes keyed by SensorId, wall segments, propagation parameters, multipath variance, calibration version, provenance, evidence level, and monotonic baseline version. v2/…/predict.rs predicts an ExpectedDistribution per LinkId with log-distance path loss plus wall attenuation and recorded multipath variance; missing nodes, self-links, zero distance, or non-finite results produce ExpectedDistribution::Unknown. v2/…/delta.rs compares caller-supplied ObservationSets with predictions and returns a TwinDelta with per-link deviations, significance, unknown links, and a model-relative total magnitude. v2/…/infer.rs consumes that twin as a generative model: hypotheses from v2/…/hypothesis.rs describe bounded occupant sets over a SpaceId; scoring attenuates links near hypothesized occupants, computes Gaussian log-likelihoods against observed link values, ranks hypotheses, and returns either BestExplanation::Explained or first-class UNKNOWN for no hypotheses, no evaluable links, low margin, or no hypothesis explaining the observation.

Planning and orchestration are pure model outputs. v2/…/scheduler.rs ranks SensorActions from v2/…/candidate.rs by expected uncertainty reduction over weighted Cost from v2/…/cost.rs, subject to compute/energy/bandwidth budgets. Unknown informativeness is handled by UnknownPolicy (probe or defer), never as zero, and the plan records both selected and deferred sensors so fusion/OOD can account for under-sampling. v2/…/policy.rs is the closed-loop controller: a ZoneBelief with Uncertainty, last response, and cycle maps through deployment ControlCapability from v2/…/control.rs into a synthetic ControlProposal or passive fallback. It emits a plan only; no crate here actuates hardware.

Sensor-placement and survey crates operate around the same spatial state. v2/…/coverage.rs builds a temporary RfTwin from a candidate Placement, scores objective targets by sample points inside Fresnel clearance over predictable links, and reports Observability::Known { score, uncertainty } or first-class UNKNOWN. v2/…/plan.rs greedily adds radios from Inventory (v2/…/inventory.rs) over a seeded candidate grid and returns a synthetic L0 PlacementPlan with a monotonic score trace. v2/…/check.rs is warn-only node-position check mode: it compares configured positions from v2/…/positions.rs with bounded RangeObservations from v2/…/observation.rs, producing link residuals, scale/unit findings, ID-swap suggestions, moved-node findings, and a verdict. v2/…/calibration.rs applies per-link/per-responder-boot FTM offsets only within the same boot, and v2/…/fill.rs keeps fill/write mode gated off unless a ranging source has measured p90 error within the configured bound.

Boundary and export crates keep the state consumable. v2/…/gaussian.rs, link.rs, and wire.rs serialize ruview_unified RF Gaussians and RF link observations as validated spatial.evidence.v1 JSONL, with proof tags and bounded wire validation. v2/…/domain.rs, gate.rs, and certificate.rs attach KNOWN/DEGRADED/UNKNOWN to inferences by fusing calibration certificate compatibility, fingerprint drift, signal quality, and model uncertainty; UNKNOWN suppresses the class and emits a recalibration request instead of returning a stale label. v2/…/lib.rs is a read-only HTTPS Cognitum Spaces client for tenant/workspace-scoped P2/P3 semantic pages; it rejects raw CSI/CIR/RF tensor/recording/pose/vital/identity payloads, requires workspace IDs for API-key spatial reads, bounds JSON size/depth, and validates parent/id/privacy contracts. v2/…/lib.rs is adjacent visualization support: off-axis projection, one-euro filtering, and bounded RF coarse parallax for browser demos; it consumes signal-field peaks but does not assert localization accuracy.

Coupling

  • If ontology containers or evidence/provenance fields change in v2/…/entity.rs or provenance.rs, update v2/…/engine.rs, v2/…/manager.rs, v2/…/twin.rs, v2/…/coverage.rs, and v2/…/hypothesis.rs; these crates exchange Container, SpaceId/ZoneId, SensorId, and EvidenceLevel directly rather than through an adapter.
  • If ruview_hal::HalObservation uncertainty or evidence semantics change, verify v2/…/observation.rs and v2/…/engine.rs; degraded HAL frames abstain from fusion, and fused evidence is the minimum contributing level.
  • If ruview_twin::LinkId, ObservationSet, or ExpectedDistribution changes, update v2/…/baseline.rs, v2/…/lib.rs, v2/…/coverage.rs, and v2/…/infer.rs; memory baselines, placement scoring, and counterfactual likelihoods reuse the twin's link vocabulary and prediction contract.
  • If information-gain scheduling starts omitting deferred reasons in v2/…/scheduler.rs, verify OOD/fusion consumers still know which sensors were not sampled; the plan's skipped-sensor record is what lets downstream state become UNKNOWN instead of silently stale.
  • If the spatial.evidence.v1 wire contract changes in v2/…/wire.rs, update both Gaussian export in gaussian.rs and link export in link.rs; to_line validates every record before serialization, so any new required field must be populated before JSONL output succeeds.
  • If Cognitum spatial resource shapes change, update v2/…/lib.rs validation alongside any producer changes; the client independently enforces privacy exclusions, parent fields, entity anonymity for person/track records, UUID workspace IDs, timestamps, and bounded JSON.

Risks

  • v2/…/manager.rs uses greedy one-to-one association rather than a global optimizer. In crowded or symmetric frames, a lower-cost early assignment can cause later detections to spawn Association::Unknown as Contested; this is privacy-safe under-linking, but downstream histories can fragment.
  • v2/…/engine.rs assumes observation variance is honest. If an upstream source reports overconfident variance, inverse-variance weighting and the reduced chi-square gate can let that source dominate the fused ZoneState or force UNKNOWN across otherwise reasonable observations.
  • v2/…/lib.rs scores anomalies before updating the baseline, then immediately folds the same snapshot into the learned normal. Repeated abnormal snapshots can be absorbed by the forgetting model in v2/…/stat.rs; alerting code should treat early anomalies as candidates to corroborate, not durable incident labels.
  • v2/…/lib.rs rebuilds partition indexes after erasure/purge and rejects stale source sequences. If a source legitimately resets its sequence without changing source_id, ingest fails with StaleSequence; operators need a new source ID or explicit partition erasure path.
  • v2/…/check.rs can suggest ID swaps only up to MAX_SWAP_NODES and distance-only layouts have reflection/rotation ambiguity. For larger or symmetric deployments the report may warn without a unique correction; this crate intentionally never writes positions.