ruvnet--RuView/api-docs/adr/ADR-304-evidence-engine.md

# ADR-304: Evidence engine — MLflow for physical sensing

- **Status**: Accepted — initial implementation planned (ADR-300 phase 1)
- **Date**: 2026-08-11
- **Deciders**: ruv
- **Tags**: evidence, provenance, ledger, accuracy, drift, benchmark, honesty, substrate

## Context

This ADR is primitive 4 of the perception-substrate program (ADR-300) and a
central pillar of the phase-1 certificate spine. It consumes the domain state
from out-of-distribution detection (ADR-302) and the calibration age from the
calibration certificate (ADR-301), it is the store that capability certificates
(ADR-318) are minted from, and it is the accuracy source the real benchmark
service (ADR-317) reads. In phase 2 it ingests agreement reports from the
ground-truth plane (ADR-303).

The strategic assessment (ADR-300) judged this primitive **more commercially
important than another pose architecture**: what unblocks OEM and integrator
conversations is not a higher headline number but a defensible, auditable record
of how a model actually performs, per room, per device, per subject, over time.
MLflow made ML experiments trackable; physical sensing needs the equivalent for
deployed accuracy, drift, and evidence level — an append-only ledger, not a
dashboard that overwrites yesterday's number.

RuView already has the constituent evidence types; what is missing is the ledger
that unifies them per deployment context:

- RuField provenance/signature types (ADR-260/262/277/279) — the signed,
  provenance-bearing record types to reuse rather than reinvent.
- The AetherArena witness-ledger pattern (ADR-149) — an append-only,
  witness-anchored ledger of scored results, the structural template here.
- `frame::EvidenceLevel` L0–L5 (ADR-282) — the mandatory evidence tag every
  record carries.
- ADR-302 `DomainState`, ADR-137 `QualityScore`, ADR-301 certificate version
  and age — the per-inference signals to accumulate.

## Options considered

1. **Log accuracy to flat files / metrics dashboards.** Rejected: mutable,
   un-signed, un-scoped, and not comparable over time — the exact gap.
2. **Reuse a general experiment tracker (MLflow itself).** Rejected: it is
   experiment-time, not deployment-time; it has no notion of room/device/
   subject context, calibration age, evidence level, or signed provenance, and
   it would add an external service dependency contrary to the substrate's
   edge-first, dependency-light direction.
3. **A native append-only evidence ledger reusing RuField record types and the
   AetherArena ledger pattern.** Chosen.

## Decision

Build an **evidence engine**: a per-`(room, device, subject)` append-only
accuracy ledger that every model automatically writes to.

### 1. The evidence record

- An `EvidenceRecord` keyed by context — space id (ADR-306), signed device id
  (ADR-305), and subject id where consented and available — carrying: model
  version; calibration certificate version and **age** (ADR-301); the ADR-302
  `DomainState` (KNOWN/DEGRADED/UNKNOWN) and its four inputs; the ADR-137
  quality signals; predictive uncertainty; and, when a reference is present
  (ADR-303), the agreement result (accuracy, false-positive rate). Each record
  carries exactly one `EvidenceLevel` (L0–L5, ADR-282).
- Records are **append-only** and signed with RuField signature types
  (ADR-260/262/277/279); the ledger is anchored in the witness chain (ADR-319),
  following the AetherArena witness-ledger pattern (ADR-149). No record is ever
  mutated in place — a correction is a new record.

### 2. Per-context accuracy accounting

- The engine maintains, per `(room, device, subject)` context: measured
  accuracy (only where an ADR-303 reference backs it — otherwise the record is
  CLAIMED/SYNTHETIC, never MEASURED), false-positive rate, drift trajectory
  (fingerprint distance over time from ADR-301), the fraction of inferences in
  each domain state, calibration age distribution, and model-version history.
- Aggregation is a pure function over the append-only log at a queried time —
  the ledger is the source of truth; summaries are derived, never authoritative
  (mirroring CLAUDE.md's "source over summaries" rule).

### 3. Honesty enforced in the record

- The engine cannot upgrade an evidence level; a level is set by the record's
  provenance at write time (synthetic input → L0/`Synthetic`; no reference →
  CLAIMED; reference + reproducer → MEASURED), reusing the ADR-282/ADR-291/
  ADR-293 constructor discipline. A benchmark or certificate reading the ledger
  gets the honest level, not an optimistic rollup.
- No benchmark numbers are invented by this ADR; it delivers the ledger and the
  accounting. Empty contexts report "no evidence," which downstream (ADR-318)
  must treat as no capability.

## Consequences

- RuView gains a single auditable answer to "how well does this model actually
  work, here, on this device, for this subject, and how fresh is the
  calibration?" — the artifact OEM/integrator diligence actually asks for.
- ADR-318 capability certificates become derivable (a certificate is a signed
  attestation over a slice of the ledger) and ADR-317 gains a real accuracy
  source per PR instead of self-reported numbers.
- The append-only, signed design has storage and key-management cost; bounded
  by per-context retention policy and by reusing the existing RuField/witness
  infrastructure rather than a new store.
- Some contexts will show sparse or unflattering evidence. Surfacing that is the
  point; the engine must never paper over a thin context with a global average.

## Validation

- `cargo test` on the evidence-engine crate — append-only invariant (no
  in-place mutation; corrections are new records); per-context aggregation math
  against fixtures; evidence-level is set by provenance and cannot be upgraded;
  signature round-trip and tamper rejection; witness anchoring; empty-context
  queries return "no evidence" not a fabricated number.
- Cross-ADR: ingests ADR-302 `DomainState` and (phase 2) ADR-303 agreement
  reports; an ADR-318 test mints a certificate from a ledger slice and an
  ADR-317 test reads accuracy from the ledger.
- Real-deployment evidence (a populated ledger from live ESP32 captures with
  ADR-303 references) is the maturity milestone and requires hardware evidence
  per CLAUDE.md; a synthetic ledger is L0 by construction.