# ADR-320: RuView sensor HAL — abstract all sensing hardware to one Observation type - **Status**: Accepted — initial implementation (ADR-300 phase 2) - **Date**: 2026-08-11 - **Deciders**: ruv - **Tags**: hal, sensor-abstraction, ontology, fusion, adapters, category, phase-2 ## Context This ADR is primitive 20 of the perception-substrate program (ADR-300) and a phase-2 integration primitive; it is authored as **Proposed**. In the ADR-300 DAG it **consumes the canonical spatial ontology (ADR-306)** — its output is an ontology `Observation` bound to a `Sensor` entity — and **feeds real sensor fusion (ADR-311)**, which resolves many observations into one world state. It closes the "identify the hardware" clause of the ADR-300 acceptance test that phase 1 leaves open. RuView's strategic ceiling is set by how tightly it is coupled to WiFi CSI. Every new modality today lands as a bespoke ingest path with its own frame shape, its own provenance handling, and its own place in the pipeline. That is the difference between "a WiFi-DensePose project" and "an open spatial-intelligence operating layer": the category changes the moment *any* sensing hardware — {CSI, 802.11bf, BLE, UWB, mmWave, acoustic, camera, lidar, IMU, custom} — enters through one abstraction and becomes one `Observation` feeding one world model. Crucially this is a *unification*, not a green field. Adapters already exist and must be reused, not rebuilt: - ADR-279's native RF frame contract (`RfFrameV2`) already unifies ESP32, Intel, Atheros, PicoScenes, Realtek radar, and 320 MHz 802.11bk producers as `RfFrameV2` producers into a shared latent — "lightweight per-device adapters into a shared latent, not a shared tensor." The HAL generalizes that lesson beyond RF. - Existing CSI adapters (ESP32/Nexmon/FeitCSI paths), the mmWave fusion path (ADR-063), and the multistatic WiFi path (ADR-029) are concrete producers to bring under one trait. - ADR-305 already authenticates a `Sensor`/`DeviceId`; ADR-306 already defines `Sensor`, `Observation`, `Track`, and `Event` as first-class node types. The HAL is the trait that turns a heterogeneous device into that authenticated `Sensor` emitting those `Observation`s. The gap is a single **`SensorHal` trait and one `Observation` type** that every modality implements, so the world model never sees a modality-specific frame — only a provenance-bearing, evidence-labelled `Observation`. ## Options considered 1. **Continue adding per-modality ingest paths.** Rejected: O(modalities) bespoke pipelines, each re-encoding provenance and evidence, each a place the ladder can be dropped — and it keeps RuView categorically a WiFi project. 2. **Force every modality into the ADR-274/279 RF tensor/frame.** Rejected: the ADR-279 lesson is precisely that premature canonicalization discards information (bandwidth, antenna structure, phase). A camera, lidar, or IMU has no meaningful `RfFrameV2` projection; forcing one is the same mistake at a larger scale. 3. **Define a `SensorHal` trait producing one `Observation` type, with existing adapters as implementations feeding a shared latent and the ADR-306 ontology.** Chosen. ## Decision Introduce a **`SensorHal` trait** and a single **`Observation`** type. Every sensing modality is an implementation of the trait; the world model consumes only `Observation`s. ### 1. The `SensorHal` trait - A `SensorHal` describes a device's **capabilities** (which phenomena it can sense — reusing the ADR-305/ADR-141 `CapabilityAttestation`), its **native frame** (kept native, not canonicalized, per the ADR-279 shared-latent lesson), and a method that lifts a native frame into an `Observation`. - Implementations wrap the existing producers: CSI (ESP32/Nexmon/FeitCSI via the ADR-279 `RfFrameV2` path), 802.11bf (ADR-310, phase 2), BLE, UWB, mmWave (ADR-063), acoustic, camera, lidar, IMU, and `custom`. RF modalities reuse the ADR-279 per-device latent adapters wholesale; the HAL adds the non-RF and ranging modalities under the same trait. - The trait is the boundary where untrusted hardware input is validated (CLAUDE.md: validate at every hardware/FFI boundary; default to least authority). A device is authenticated as an ADR-305 `Sensor` before its observations are trusted. ### 2. The `Observation` type - One provenance-bearing `Observation`: a measurement plus its `SensorHal` source descriptor, its ADR-305 authenticated `DeviceId`, its ADR-295 `SourceState`, its native-frame reference (not a lossy projection), and exactly one `EvidenceLevel` (L0–L5, ADR-282). A camera-derived `Observation` and a CSI-derived `Observation` are the same type with different provenance — and a camera observation never lifts WiFi output to camera-grade; each carries its own honest evidence level (CLAUDE.md: never present WiFi sensing as camera-grade). - The `Observation` maps directly onto the ADR-306 ontology `Observation` node attached to its `Sensor`, so the ontology is the one representation and the HAL is its ingest funnel. ### 3. Feeding fusion - Observations from any set of modalities flow into ADR-311 fusion, which resolves them into one probabilistic world state. The HAL guarantees fusion never sees a modality-specific frame — only `Observation`s with uniform provenance and evidence — which is what makes ADR-311's "many observations → one world state" invariant implementable across heterogeneous hardware. ### Category and honesty discipline - This ADR changes RuView's category from a WiFi-DensePose pipeline to an open spatial-intelligence operating layer, but it makes **no accuracy claim**: the HAL delivers a uniform ingest boundary, not a detector. Any capability of a newly-connected sensor is still gated by ADR-302 and certified by ADR-318 for its specific environment — connecting a camera does not grant a validated capability by itself. - Hardware support for a given modality is CLAIMED until demonstrated on real silicon with captured evidence per CLAUDE.md; a passing trait test proves the abstraction, not a fielded device. ## Consequences - New sensing hardware lands as one `SensorHal` implementation instead of a bespoke pipeline; the translation matrix stays O(modalities), mirroring how ADR-306 collapsed the surface matrix. - The ADR-300 acceptance clause "identify the hardware" becomes implementable: a new sensor type is described by its HAL, authenticated as an ADR-305 `Sensor`, calibrated (ADR-301), gated (ADR-302), and certified (ADR-318) through the same phase-1 spine, closing the last open clause. - A trait boundary and an `Observation` type are added; existing RF adapters are re-expressed as implementations rather than rewritten, preserving the ADR-279 native-frame/shared-latent design. - Non-RF modalities (camera, lidar, acoustic) enter the governed plane with the same provenance and privacy discipline as RF; a camera is not a privacy-free shortcut — it inherits the ADR-277 governance and its own evidence level. - As a phase-2 Proposed ADR, the trait shape may be revised as ADR-311 fusion and ADR-310 802.11bf land; that revision is expected for a phased program. ## Validation - `cargo test` on the HAL crate (design-time, Proposed) — a fixture `SensorHal` for each of at least two modalities (CSI via ADR-279, plus one non-RF) produces uniform `Observation`s; every `Observation` carries a `DeviceId`, `SourceState`, native-frame reference, and exactly one `EvidenceLevel`; a synthetic source yields L0/`Synthetic` and cannot alias to measured (ADR-279 invariant 6); an unauthenticated device's observations are rejected at the trait boundary (ADR-305). - Cross-ADR: an `Observation` maps round-trip to an ADR-306 ontology `Observation` node with no provenance loss, and a set of `Observation`s from distinct modalities is accepted by an ADR-311 fusion fixture. - Real-silicon evidence is required before any modality's hardware support is claimed beyond CLAIMED: a captured boot/runtime log from the real device emitting `Observation`s. A successful build or simulator run is not hardware evidence (CLAUDE.md).