feat: connect iPhone LiDAR to RuView HAL, ground-truth, and uncertainty-aware RF fusion

Problem

The iPhone LiDAR integration merged in #1684 on 2026-08-22 captures ARKit scene depth, confidence, intrinsics, tracked pose, a compact depth wire format, authenticated development relay, and browser point-cloud visualization. ADR-340 intentionally leaves the production RuView HAL and fusion receiver as follow-up.

That makes the current integration useful for visualization but not yet a first-class RuView sensor, calibration source, or RF benchmark ground truth.

Why it matters

Metric depth plus tracked camera pose is the fastest available path to improve RuView's real-world spatial validation. It can provide independent geometry for RF localization, occupancy fields, material/reflector experiments, and cross-sensor alignment without making LiDAR mandatory at runtime.

GaussianCaR, accepted at ICRA 2026 with Apache-2.0 code and weights, demonstrates a useful representation pattern: Gaussian primitives can act as a common view transformer for heterogeneous camera/radar observations. The reported nuScenes BEV segmentation path is 3.2x faster than its compared fusion baseline while retaining or improving task accuracy. The exact automotive model is not a direct RuView dependency; the transferable idea is uncertainty-aware Gaussian lifting into a shared spatial carrier.

Current architecture

Merged #1684:

iPhone ARKit sceneDepth
  -> depth + confidence + intrinsics + tracked pose
  -> ruvview.lidar.depth.v1 compact frame
  -> development WebSocket relay
  -> browser point cloud
  -> future RuView HAL / fusion ingest

The current ADR correctly states that physical-device latency and confidence behavior remain unverified and that ordinary browser code cannot directly acquire ARKit scene depth.

Proposed architecture

iPhone LiDAR frame
   -> bounded decoder
   -> authenticated sensor identity
   -> coordinate/frame validation
   -> ruvview-hal Observation
   -> ruvview-groundtruth optional reference stream
   -> uncertainty-aware spatial fusion
   -> RuVector / spatial memory

RF-only inference -------------------------^

Keep two distinct modes:

1. ground_truth: LiDAR is used only to score/calibrate RF and is excluded from the candidate RF model input.
2. fusion: LiDAR is an explicit runtime modality and metrics are labeled multimodal.

Never report fusion accuracy as RF-only accuracy.

Target packages

Confirm exact APIs on main before implementation, but prioritize existing crates:

• integrations/iphone-lidar
• ruview-hal
• ruview-groundtruth
• ruview-fusion
• spatial memory / RuVector adapter
• existing benchmark runner

No new repository.

Data model

HAL observation should preserve:

• source frame ID and sequence
• depth dimensions and quantization
• per-pixel confidence or a bounded summary plus referenced local payload
• camera intrinsics
• ARKit world transform
• wall-clock capture time
• monotonic capture time
• sensor session ID
• calibration ID
• evidence/provenance receipt
• explicit coordinate frame and transform uncertainty

Raw depth remains local by default. Persist derived spatial primitives unless a benchmark explicitly requires raw ground truth retention.

Implementation phases

Phase 1: production receiver

Add bounded binary/WebSocket decode inside the RuView trust boundary with WSS, authenticated sensor identity, sequence/replay protection, message-size limits, rate limits, and per-sensor quotas.

Phase 2: HAL adapter

Convert frames to typed observations with coordinate transforms and covariance. Reject unsupported coordinate states, missing intrinsics, non-finite transforms, stale calibration, sequence rollback, and impossible depth values.

Phase 3: ground-truth mode

Register LiDAR as an independent benchmark reference for RF localization and spatial occupancy. Candidate RF models may not read the LiDAR stream in this mode.

Phase 4: multimodal fusion

Lift LiDAR observations and RF spatial observations into the existing Gaussian/spatial field representation. Fuse by covariance and evidence independence, not raw confidence multiplication.

Phase 5: RuVector persistence

Persist compact spatial primitives and evidence references. Do not persist RGB by default. Do not make the browser relay authoritative.

Security plan

Threats:

• unauthenticated WebSocket injection
• replayed LiDAR frames
• malicious oversized depth payloads
• NaN/Inf or transform bombs
• forged sensor identity
• stale or cross-session sequence reuse
• coordinate-frame confusion
• location privacy leakage
• resource exhaustion from high-rate frames

Controls:

• WSS only for production
• capability-scoped sensor identity
• monotonic sequence watermark per session
• max frame dimensions, bytes, and FPS
• strict numeric bounds and finite checks
• authenticated calibration/transform receipts
• per-tenant and per-device rate limits
• raw depth retention disabled by default
• RGB capability remains separate and off by default
• no automatic fallback to simulated depth under a live evidence label

Benchmark plan

Before/after comparison must include RF-only baseline and preserve identical RF inputs.

Ground-truth validation:

• 5 rooms minimum
• at least 2 buildings if available
• 3 sensor poses per room
• static reflectors plus moving people
• at least 30 minutes per room across multiple sessions

Metrics:

• physical-device stream p50/p95 latency
• packet loss and replay rejection
• HAL conversion latency
• point-to-plane or Chamfer geometry error where reference geometry exists
• RF localization p50/p90 error measured against LiDAR truth
• RF occupancy precision/recall measured against LiDAR-derived occupancy
• fusion localization p50/p90
• memory bytes per spatial primitive
• network bytes/s
• CPU and memory on ARM64 gateway

Run at least five repetitions for latency and throughput tests.

Expected measurable improvement

Primary success is better measurement quality, not an assumed model gain.

Targets:

• physical iPhone stream below 150 ms p95 on local WiFi, matching ADR-340's existing target
• zero accepted replayed frames
• 100% coordinate-frame/provenance coverage
• RF-only benchmark gains must be measured independently and cannot use LiDAR inputs
• multimodal fusion should reduce RF localization p90 by at least 20% on the same held-out sessions before it is promoted

Dependencies and licensing

Use Apple ARKit APIs already present and existing RuView/RuVector crates. GaussianCaR is an architectural reference, not a required dependency. If code is reused later, preserve Apache-2.0 attribution and audit its transitive model/data licenses.

Backward compatibility

Additive sensor adapter and feature flag. Existing CSI/radar paths are unchanged.

Rollback

Disable the LiDAR HAL/fusion feature and remove its stored derived primitives. RF-only pipelines and the existing standalone viewer remain functional.

Definition of done

A physical LiDAR-capable iPhone streams to an authenticated RuView receiver for 60 minutes without sequence ambiguity, malformed input bypass, or unbounded memory growth; the HAL emits fully provenance-bound observations; RF-only metrics are scored against LiDAR truth without leakage; multimodal results are reported separately; ARM64 and x86 integration tests pass.

Start by reading ADR-340 and confirming the APIs in integrations/iphone-lidar, ruview-hal, ruview-groundtruth, ruview-fusion, the spatial memory/RuVector adapter, and the existing benchmark runner. Trace the current depth frame through the development relay, then define the receiver, typed observation, ground-truth, fusion, persistence, and benchmark boundaries. Done means the stated security, provenance, RF-only separation, multimodal metrics, physical-stream, and ARM64/x86 integration requirements are met.