ruvnet--RuView/docs/adr/ADR-303-ground-truth-synchronization.md

ADR-303: Ground-truth synchronization — reference sensors as a formal validation plane

• Status: Accepted — initial implementation (ADR-300 phase 2)
• Date: 2026-08-11
• Deciders: ruv
• Tags: ground-truth, validation, fusion, evidence, benchmark, honesty, substrate

Context

This ADR is primitive 3 of the perception-substrate program (ADR-300), authored as Proposed in phase 2: it is design intent and a validation plan, not implemented by the phase-1 swarm. It sits on top of the phase-1 certificate spine and feeds the evidence engine (ADR-304) and the real benchmark service (ADR-317). It generalizes the vitals ground-truth rig (ADR-293) from a single measurand to a modality-agnostic plane.

RuView's evidence discipline (CLAUDE.md; ADR-282 ladder) requires MEASURED accuracy claims to be backed by an independent reference. ADR-293 built exactly this for vitals: reference-series ingest, time alignment (cross-correlation lag + optional clock-drift fit), and agreement statistics (MAE/RMSE/bias/ Bland–Altman/within-tolerance), with an EvidenceGrade that is only constructible as Measured when a real reference, non-zero paired samples, minimum coverage, and a reproducer are present. That machinery is measurand- and device-shaped: it knows about heart rate and breathing rate.

The substrate needs the same discipline for every phenomenon RuView senses — presence, count, localization, pose, posture, activity — and for reference sources of many modalities (cameras, mmWave, pressure mats, wearables, pulse oximeters, microphones, manual labels). The critical design decision is that these reference sensors form a validation plane, not additional inference inputs.

Options considered

1. Fuse reference sensors as extra inference inputs. Rejected on principle: folding cameras/mmWave into the estimator would make RuView's RF claims unfalsifiable — the reference would be training the thing it is meant to check, and a camera-fed result is no longer a camera-free RF result. It would also violate the ADR-282 layering (RuView is probabilistic exteroception, never ground truth) and the honesty rule against presenting fused-with-camera output as WiFi sensing.
2. One-off rigs per measurand (extend ADR-293 ad hoc each time). Rejected: duplicates alignment/agreement code per phenomenon and never yields a shared validation surface for the benchmark.
3. A first-class, modality-agnostic GroundTruth API that is strictly a validation plane. Chosen.

Decision

Introduce a GroundTruth API — a modality-agnostic validation plane that compares RF inference against independent observation and never feeds it.

1. Modality-agnostic reference ingest

• A ReferenceObservation generalizing ADR-293's ReferenceSeries: a timestamped, typed observation of a Phenomenon (presence, count, localization, pose keypoints, posture, activity, heart rate, breathing rate) from a ReferenceModality (camera, mmWave, pressure, wearable, pulse oximeter, microphone, manual label), with device/source metadata and the measurement principle recorded.
• Untrusted reference files are validated at the boundary (row-numbered rejections, non-monotonic timestamps are errors), reusing ADR-293's ingest discipline. Camera/mmWave references arrive as exported label/keypoint streams, not live model feeds.

2. Synchronization

• Generalize ADR-293's time alignment (bounded-lag normalized cross-correlation
  • optional linear clock-drift fit) to arbitrary measurands on a common resampled grid, with no interpolation across gaps beyond a configurable limit. Alignment parameters are always reported, never silently applied.
• Spatial synchronization where relevant: reference observations are expressed in the ADR-306 spatial ontology so an RF localization/pose result and a camera/mmWave observation are compared in one coordinate frame.

3. Agreement as validation, not fusion

• A modality-appropriate AgreementReport per phenomenon: continuous measurands reuse ADR-293's MAE/RMSE/bias/Bland–Altman/within-tolerance; categorical/detection phenomena (presence, activity) report confusion-matrix metrics; spatial phenomena report localization error percentiles and pose PCK with the mandatory mean-pose baseline and leakage-free split (CLAUDE.md; ADR-291).
• Session scope is mandatory metadata (subject count, motion state, LOS/NLOS/ through-wall, distance band) — a report without scope cannot be constructed, as in ADR-293.

4. Evidence and isolation guarantees

• The plane is one-directional by type: the inference path has no read access to GroundTruth at runtime. A build/test-time isolation check (and the type boundary) prevents a reference observation from becoming an estimator input.
• Reports carry an EvidenceLevel (ADR-282) and an EvidenceGrade constructible as Measured only with a real reference, paired samples, coverage, and a reproducer (ADR-293 rule). Reports feed the ADR-304 evidence engine and are the substrate ADR-317 scores against.

Consequences

• Every phenomenon RuView senses gets the same MEASURED-vs-independent-observer discipline vitals already has, in one shared surface.
• Keeping references strictly as validation preserves the falsifiability and the camera-free identity of RF results; it costs the (tempting) accuracy a camera-fused estimator would show, which is the correct trade.
• Reference capture is an operational burden (a camera/mmWave rig per validated session); acceptable because it is a validation activity, not a runtime requirement, and it is what turns CLAIMED into MEASURED.
• Because this is Proposed (phase 2), the API shape may be revised once the phase-1 spine (ADR-301/299/301/303) lands and the benchmark (ADR-317) exercises it.

Validation

• Unit tests (planned): modality-agnostic ingest rejection cases; alignment recovery of known synthetic offsets/drifts across measurands; agreement math per phenomenon against hand-computed fixtures; pose PCK path requires a mean-pose baseline and rejects leaky splits; evidence-grade constructibility; the isolation check fails a build that wires a reference into the inference path.
• Cross-ADR: an ADR-317 benchmark scenario consumes GroundTruth reports as its scored reference; ADR-304 ingests the agreement reports as evidence records.
• Real-session validation (RF capture synchronized with a real camera/mmWave/ pressure/wearable reference) is the phase-2 exit and requires hardware evidence per CLAUDE.md; a synthetic run is not hardware evidence.