ruvnet--RuView/api-docs/adr/ADR-309-active-sensing.md

# ADR-309: Active sensing — closed-loop RF experiment control

- **Status**: Accepted — initial implementation (ADR-300 phase 3)
- **Date**: 2026-08-11
- **Deciders**: ruv
- **Tags**: active-sensing, control-plane, closed-loop, information-gain, actuation, phase-3

## Context

This ADR is a child of **ADR-300** and owns primitive #9, *active sensing*. In
the ADR-300 phasing it is a phase-3 primitive that sits on top of the fused
world state produced by **ADR-311** (real sensor fusion) and is driven by the
information budget of **ADR-314** (information-gain scheduler). It is authored
as **Proposed**: design intent and validation plan, not a phase-1 build.

The default posture of every current RuView path is **passive**: RF traffic
happens for its own reasons (a device transmits, a beacon fires), RuView
observes whatever CSI/CIR arrives, and the pipeline extracts what it can from
that incidental signal. The strategic assessment behind ADR-300 named the next
step: move from *RF-happens → observe* to **RuView-controls-RF → observe the
response → optimize the next measurement**. That turns sensing into a
closed-loop experiment — the system chooses what to measure to resolve the
uncertainty it currently has, rather than accepting the measurements the
environment happens to offer.

Substantial control-plane scaffolding already exists and must be
**reused/extended, not rebuilt**:

- **ADR-280** (active sensing / programmable perception, *implemented* in
  `ruview-unified/src/control.rs`) already defines the governed control surface
  this ADR closes the loop over: `SensingTask` (evidence-aware, fail-closed
  admission), `SensingAction` + `InformationGoal` (a deliberate act of
  evidence-gathering against a stated hypothesis, bounded by a `PrivacyClass`
  P0–P5 ceiling), `ActiveSensingPlanner` (age-of-information scheduler),
  `CoherentSensorGroup` (coherent fusion fails closed), and `request_actuation`
  → `ActuationReceipt` for governed RIS/movable/fluid-antenna actuation.
- ADR-280 explicitly recorded that **information-gain *estimation* is not
  implemented** — "the planner uses staleness heuristics, not mutual
  information; RIS drivers, actual multi-AP coherence measurement, and OTFS
  waveform control are hardware-dependent roadmap items." ADR-309 is the ADR
  that closes exactly those gaps, in coordination with ADR-314.

The missing piece is not the actuation surface — ADR-280 built that and made it
fail closed — but the **loop**: a controller that reads the current fused-state
uncertainty, selects a *controllable measurement configuration* expected to
reduce it most, requests it through the ADR-280 governed surface, observes the
response, and updates its belief before choosing the next measurement.

## Options considered

1. **Stay passive; only schedule which incidental observations to keep.** This
   is roughly today's `ActiveSensingPlanner` (staleness-priority over regions).
   Rejected as the endpoint: it optimizes *attention* over uncontrolled RF, not
   the *measurement* itself. It remains the fallback when nothing is
   controllable.
2. **Open-loop measurement scripting** (a fixed sweep of channels/bandwidths).
   Rejected: a fixed sweep spends the RF/energy/privacy budget the same way
   regardless of what is already known; it cannot concentrate measurement where
   uncertainty actually is.
3. **Closed-loop experiment control** — read uncertainty, pick the controllable
   configuration with highest expected information gain per unit cost/privacy,
   actuate through the ADR-280 governed surface, observe, update, repeat.
   Chosen.

## Decision

Adopt **closed-loop RF experiment control** as a phase-3 controller layered on
the ADR-280 surface. RuView selects and drives the controllable degrees of
freedom of the RF measurement, then optimizes the next measurement from the
observed response.

### 1. Controllable degrees of freedom

Define an `ExperimentControl` vocabulary over the configuration axes RuView can
influence on hardware that exposes them (each axis is optional and
capability-gated by ADR-320's HAL, so an ESP32-only deployment simply has an
empty controllable set and degrades to the passive planner):

- **Channel / band** and **bandwidth** (which spectrum to probe; reuses the
  ADR-292 wideband subcarrier-agnostic metadata).
- **Packet timing / cadence** (when to solicit a sounding, and at what rate).
- **Antenna / chain selection** (which subset of a distributed aperture to
  activate — bounded by the ADR-280 `CoherentSensorGroup` compatibility proof).
- **Beam / RIS configuration** (which rooms and people become observable —
  governed exactly as ADR-280 §6 requires, via `request_actuation` and an
  `ActuationReceipt`).
- **802.11bf measurement parameters** (TB/non-TB, reporting config) once
  ADR-310 exposes standardized sensing as a native measurement type.

### 2. The loop

```
fused-state uncertainty (ADR-311)
        │
        ▼
info-gain ranking of ExperimentControl options (ADR-314)
        │  select argmax  E[ΔI] / (cost, energy, privacy ceiling)
        ▼
governed request  (ADR-280 admit_task / request_actuation, fail-closed)
        │
        ▼
observe response → update belief (ADR-311) → repeat
```

The controller never bypasses the ADR-280 admission and actuation gates: every
solicited measurement is a `SensingTask`/`SensingAction`, every environment
change is an `ActuationReceipt`, and every step composes with the ADR-277
policy engine. Information gain is what **ADR-314** supplies (the mutual-
information estimate ADR-280 deferred); ADR-309 owns the *control loop* that
consumes that estimate and drives the hardware.

### 3. Governance and honesty boundary

- Actuation and solicitation stay fail-closed and privacy-ceilinged: a
  closed-loop experiment cannot widen the P0–P5 ceiling of the task it serves,
  and cannot steer a beam into a zone that does not grant the purpose (ADR-280
  `actuation_requires_policy_authorization`).
- Any accuracy or "traffic-reduction" claim from the closed loop is tagged
  **MEASURED** only with a named reproducer over a stated scenario, **SYNTHETIC**
  for simulated apertures, and **CLAIMED** otherwise. Real multi-AP coherent
  measurement and RIS actuation remain **hardware-dependent** and require
  real-silicon evidence (a captured runtime log) before any hardware claim, per
  CLAUDE.md. No number is invented here.

## Consequences

- Sensing becomes an experiment: RuView spends its RF/energy/privacy budget on
  the measurements that most reduce current uncertainty, instead of processing
  whatever incidental traffic arrives.
- The loop is only as strong as its two dependencies: ADR-311 must expose a
  usable uncertainty surface and ADR-314 must produce trustworthy information-
  gain estimates. Where either is absent, the controller degrades to the
  ADR-280 staleness planner rather than acting on a fabricated gain estimate.
- Controllability is hardware-bounded. On commodity ESP32 sensors the
  controllable set may be limited to cadence; the full loop (bandwidth, antenna,
  beam) needs NICs/RIS that expose those axes, surfaced through ADR-320.
- This ADR adds a controller; it does not re-open ADR-280's raw-export or
  actuation-governance decisions, which remain authoritative and fail-closed.

## Validation

- Design-level acceptance (phase 3): a simulated closed loop over a synthetic
  scene reduces terminal fused-state uncertainty faster than (a) the passive
  ADR-280 staleness planner and (b) an open-loop fixed sweep, at equal
  measurement budget — reported **SYNTHETIC**, with the scenario and seed named.
- Governance tests: every solicited measurement and actuation in the loop is
  admitted through the ADR-280 fail-closed path; a loop step that would exceed
  the task's privacy ceiling or steer into an ungranted zone is denied.
- Degradation test: with an empty controllable set (ESP32-only), the controller
  falls back to the staleness planner with no error and no fabricated gain.
- Hardware validation of bandwidth/antenna/beam actuation is explicitly out of
  scope until real silicon exposes those axes and produces a captured log.