RuView/docs/adr/ADR-305-sensor-placement-optimizer.md

ADR-305: Sensor placement optimizer — floorplan + inventory → recommended positions

• Status: Accepted — initial implementation (ADR-297 phase 3)
• Date: 2026-08-11
• Deciders: ruv
• Tags: placement, planning, rf-twin, coverage, worldgraph, phase-3

Context

This ADR is a child of ADR-297 and owns primitive #8, sensor placement optimizer. In the ADR-297 DAG it is a phase-3, research-forward primitive that sits on top of the fused world state and is tightly coupled to ADR-312 (digital RF twin): the twin provides the propagation simulation this optimizer plans against. It reads the ADR-303 canonical ontology for the physical scene and, after install, compares its predictions against ADR-299 observability and the ADR-315 capability certificate.

The problem it solves is the single most common cause of a bad RuView deployment: sensors placed by guesswork. Whether a room can be reliably sensed depends on AP/sensor geometry relative to walls, Fresnel-zone clearance, multipath structure, and where people actually move. Today an installer has no principled way to answer "where do I put the two nodes I have so the kitchen is observable?" — and no way, after install, to know whether reality matched the plan. This is a genuine differentiator: it turns RuView from "sense whatever the given placement happens to allow" into "recommend the placement that makes the requested sensing feasible."

Relevant existing assets to build on rather than duplicate:

• The worldgraph crate models the physical scene the optimizer plans over: Room/Space with bounds_enu, Wall { rf_attenuation_db } (drywall ≈ 3 dB, brick ≈ 12 dB), Doorway, and Zone — enough geometry and coarse RF attenuation to seed a coverage model, plus Sensor nodes (ADR-303) for candidate positions.
• ADR-312 (RF twin, phase 3) is the propagation/multipath simulator; this optimizer is a consumer of the twin, not a second simulator.
• ADR-299 (OOD/observability) and ADR-315 (capability certificate) define what "reliably sense the requested phenomenon" means, so the optimizer can optimize against the same observability metric the runtime later gates on.
• ADR-029 (multistatic) and ADR-063 (mmWave fusion) inform which link geometries are useful for which phenomena.

Options considered

1. Static placement guidelines in docs (e.g. "one node per room, opposite the door"). Rejected: ignores the specific floorplan, wall materials, and the actual hardware inventory; gives no uncertainty and no post-install feedback.
2. Full electromagnetic solver per site. Rejected for the default path: too heavy for an installer workflow and overkill relative to the coarse rf_attenuation_db scene RuView actually has; reserved as an optional high-fidelity backend inside ADR-312.
3. A coverage optimizer that consumes the ADR-312 RF twin over the ADR-303 scene, then validates predicted vs. measured observability after install. Chosen.

Decision

Define a placement optimizer that takes a floor plan (ADR-303 scene) and a hardware inventory and recommends sensor positions, then closes the loop after install.

1. Inputs

• The ADR-303 canonical scene: Space/Zone bounds, Wall segments with rf_attenuation_db, Doorway topology, and any already-placed Sensor nodes.
• A hardware inventory: the count and type of available radios (ESP32-S3/C6 nodes, mmWave, adapters) with their capability envelopes (what each can sense, per ADR-315 / ADR-317 HAL descriptors).
• A sensing objective: which phenomenon must be observable in which Space/Zone (presence, vitals, pose), expressed against the ADR-299 observability metric.

2. Prediction

• For a candidate placement, query the ADR-312 RF twin for simulated RF coverage: path loss through Wall attenuation, Fresnel-zone clearance between link endpoints, and coarse multipath structure. From that derive an expected observability and an uncertainty for each objective in each space — reusing the same observability definition ADR-299 gates on so the plan and the runtime speak one language.
• Search over candidate positions (the inventory bounds the count; the scene bounds the geometry) to recommend the placement that maximizes objective observability, reporting expected observability and its uncertainty per space — never a single confident number for a simulated result.

3. Post-install loop

• After install, compare predicted vs. measured observability using the ADR-299 runtime observability signal from the freshly enrolled (ADR-302), calibrated (ADR-298) sensors. Where measurement disagrees with prediction, recommend adjustments (move, re-aim, add a node) and feed the residual back to improve the ADR-312 twin's scene parameters (e.g. a wall's effective attenuation).

Evidence discipline

• Predicted coverage is a simulation (evidence level L0 per ADR-282) and is labelled SYNTHETIC; it is a recommendation, never a sensing claim.
• The predicted-vs-measured comparison is the only place a MEASURED statement appears, and only with a reproducer and real-silicon observability data (CLAUDE.md hardware rule). The optimizer never presents a simulated coverage map as evidence that a room is being sensed.

Consequences

• Installers get a principled, floorplan-specific placement plan and, crucially, a post-install check that says whether reality matched the plan — a differentiating capability over guess-and-check deployment.
• Quality is bounded by the fidelity of the ADR-312 RF twin and the coarseness of the worldgraph scene (2D walls, coarse attenuation). The optimizer reports uncertainty rather than overstating a coarse model; higher fidelity is an ADR-312 concern.
• Hard dependency on ADR-312 (twin), ADR-299 (observability metric), and ADR-303 (scene); this ADR does not build a simulator or an observability metric of its own.
• Being phase 3, this is design intent sitting on the fused world state; it is expected to be revised as ADR-312 and the phase-1 spine land.
• No claim that recommended placement guarantees sensing — it maximizes modelled observability subject to inventory and geometry, with explicit uncertainty.

Validation

• Unit tests: coverage/observability prediction is a deterministic function of scene + placement + twin parameters; Fresnel-zone and wall-attenuation math against known analytic cases; search returns the modelled-optimal placement on small synthetic scenes.
• Integration test: on a synthetic floorplan with a known-good and a known-bad placement, the optimizer ranks them correctly and reports higher uncertainty for the marginal case.
• Post-install loop test: injected predicted-vs-measured disagreement produces a sensible adjustment recommendation and a twin-parameter residual.
• Field validation (deferred, real-silicon): predicted vs. measured observability on an instrumented real site, reported as MEASURED with a reproducer. Until then all coverage output is SYNTHETIC/L0. No coverage or accuracy number is asserted by this ADR.