ruvnet--RuView/docs/adr/ADR-319-witness-chain.md

# ADR-319: Witness chain — epistemic infrastructure for physical AI

- **Status**: Accepted — initial implementation planned (ADR-300 phase 1)
- **Date**: 2026-08-11
- **Deciders**: ruv
- **Tags**: provenance, witness, evidence, signature, epistemics, ontology, substrate

## Context

This ADR is primitive 19 of the perception-substrate program (ADR-300) and a
spine root of its phase-1 certificate stack. In the ADR-300 dependency DAG it
**extends the source-provenance state machine (ADR-295)** and the RuField
provenance types, **ties to the signature machinery (ADR-305 /
ADR-260/262/277/279)**, and anchors the artifacts produced by ADR-301
(calibration certificates), ADR-304 (evidence records), ADR-317 (benchmark
scorecards), and ADR-318 (capability certificates). In phase 2 it carries the
independent-corroboration link from ADR-303.

The strategic assessment (ADR-300) framed RuView's real product as **epistemic
infrastructure for physical AI**: the value is not the claim "a person is
present" but the *auditable reasoning* behind it. A bare boolean output discards
everything a downstream system needs to trust or contest it — which radio
observed it, what DSP evidence supported it, which model inferred it, whether an
independent sensor agreed, what spatial state it updated, and what policy acted
on it. Once the answer is a boolean, "why do you believe that?" has no answer.

RuView already has the pieces of a chain but not the chain itself. ADR-295
defines a canonical `SourceState` (`Synthetic` / `LiveVerified` /
`LiveUnverified` / `Stale` / `Disconnected`) with `Unknown` structurally
forbidden from collapsing to live. ADR-305 defines the signed
`device → measurement → sequence → timestamp → … → signed event` chain of
custody. RuField carries `FrameProvenance`, `SemanticProvenance`, and signature
types; the AetherArena witness ledger (ADR-149) demonstrates an append-only,
witness-anchored ledger. What is missing is a single **staged, signed envelope**
that travels the whole pipeline and records, at each stage, the confidence and
provenance of that stage.

## Options considered

1. **Keep provenance as scattered per-stage fields (status quo).** Rejected:
   `FrameProvenance`, `SourceState`, calibration state, and model uncertainty
   live in different structures and are re-encoded per surface; there is no
   single object a consumer can re-verify offline to answer "why."
2. **Log a free-form audit trail alongside the output.** Rejected: mutable,
   unsigned, and not structurally tied to the output — the classic
   dashboard-that-overwrites-yesterday failure the evidence engine (ADR-304)
   already rejects.
3. **A staged, signed witness envelope carried through the pipeline, each stage
   appended and signed, anchored in an append-only ledger.** Chosen.

## Decision

Define the **witness chain**: a staged, append-only, signed envelope that
accompanies an observation from radio to policy decision. Instead of emitting
"person present," RuView emits a chain whose stages are:

```
RF observation ▸ DSP evidence ▸ model inference ▸ independent corroboration
              ▸ spatial state ▸ policy decision
```

### 1. The staged envelope

- Each stage is a signed record carrying its **confidence** and its
  **provenance**:
  - **RF observation** — the ADR-305 authenticated frame envelope
    (`DeviceId`, sequence, timestamp, measurement hash) and its ADR-295
    `SourceState`. This is the root link; a `Synthetic` root can never present
    as a `LiveVerified` one (ADR-295 invariant).
  - **DSP evidence** — the deterministic signal features and the ADR-137
    quality signals that support (or fail to support) an inference.
  - **model inference** — the model version, its raw output, and its predictive
    uncertainty; the ADR-302 `DomainState` (KNOWN / DEGRADED / UNKNOWN) gate
    result, so a low-confidence or out-of-distribution inference is recorded as
    such, not silently promoted.
  - **independent corroboration** — the phase-2 ADR-303 agreement link
    (a reference/second modality that agreed or disagreed); absent in phase 1,
    the stage records "no corroboration," never a fabricated one.
  - **spatial state** — the ADR-306 ontology `Observation`/`Track`/`Event` the
    inference updated, carrying `SemanticProvenance` and its `EvidenceLevel`.
  - **policy decision** — the governed action taken (or withheld), with the
    certificate (ADR-318) it relied on.
- Each stage carries exactly one `EvidenceLevel` (L0–L5, ADR-282); the envelope's
  effective level is the **minimum** across its stages — a synthetic root or an
  unreferenced inference caps the whole chain, so the chain cannot claim more
  than its weakest link.

### 2. Signing and anchoring

- Each stage is signed with RuField signature types (ADR-305 /
  ADR-260/262/277/279) over the canonical serialization of that stage plus the
  hash of the prior stage, so the chain is tamper-evident end to end and any
  broken link is detectable. The completed chain is anchored in an append-only,
  witness-anchored ledger following the AetherArena pattern (ADR-149); it is the
  same anchoring ADR-301/ADR-304/ADR-317/ADR-318 write into.
- The chain is **append-only**: a correction is a new chain referencing the
  prior one, never an in-place edit (mirroring ADR-304 and CLAUDE.md's "source
  over summaries").

### 3. Offline re-verification

- A consumer with the enrolled public keys (ADR-305) can re-verify a chain
  offline: check each stage signature, check each prior-stage hash, and read the
  per-stage confidence and evidence level — answering "why do you believe this?"
  without trusting the emitting host. This is the property store-and-forward
  channel authentication (rejected in ADR-305) cannot provide.

### Provenance and honesty discipline

- The witness chain never manufactures confidence: a stage that lacks evidence
  records the absence. A `Synthetic` root, a missing corroboration, or an
  UNKNOWN gate is carried faithfully and caps the chain's evidence level. No
  accuracy number is invented here; the chain records the numbers the other
  primitives produce at their honest level.

## Consequences

- Every RuView output becomes contestable and auditable: a downstream physical-AI
  system can inspect the reasoning, weight it by per-stage confidence, and reject
  a chain whose weakest link is too weak — the defining property of epistemic
  infrastructure the strategic assessment asked for.
- The certificate spine (ADR-301/301/314/315) gains a single anchoring substrate;
  each of those artifacts is a specialization of a witness record rather than a
  bespoke signed blob.
- Carrying and signing a staged envelope adds per-observation size and CPU cost;
  bounded by reusing RuField signatures and the existing ledger, and by the
  minimum-level rule keeping the object honest rather than exhaustive.
- The chain will frequently reveal weak links (synthetic root, no corroboration,
  DEGRADED gate). Surfacing that is the point; the envelope must never smooth a
  weak stage into a confident summary.

## Validation

- `cargo test` on the witness-chain crate — stage-by-stage signature round-trip
  and tamper rejection (a mutated stage or a broken prior-stage hash fails
  verification); effective evidence level equals the minimum across stages; a
  `Synthetic` root caps the chain and cannot present as `LiveVerified`
  (ADR-295 invariant); an UNKNOWN gate (ADR-302) and a "no corroboration" stage
  are recorded faithfully; append-only correction produces a new chain
  referencing the prior one.
- Cross-ADR: an ADR-305 signed frame lineage serializes into a chain that
  re-verifies offline with only the enrolled public keys; ADR-301/301/314/315
  artifacts anchor into the same ledger.
- Real-deployment chains (from live ESP32 captures with ADR-303 corroboration)
  are the maturity milestone and require hardware evidence per CLAUDE.md; a
  chain rooted in synthetic input is L0 by construction.