ruvnet--RuView/api-docs/adr/ADR-316-fleet-control-plane.md

# ADR-316: Fleet control plane — provisioning to audit trails

- **Status**: Proposed (ADR-300 phase 2)
- **Date**: 2026-08-11
- **Deciders**: ruv
- **Tags**: fleet, operations, provisioning, firmware, updates, audit, identity, phase-2

## Context

This ADR is a child of **ADR-300** (perception substrate program) and owns
primitive #16, *fleet control plane*. In the ADR-300 DAG it is a phase-2
integration-and-operations primitive that sits on the phase-1 spine: it
**consumes ADR-305** (authenticated sensor identity) for per-device identity and
enrollment, and **ADR-318** (capability certificate) for the signed models,
calibration validity, and capability envelopes a device is allowed to run. It is
authored as Proposed and is not implemented by the phase-1 swarm.

The external and internal reviews both named the same operational gap: RuView
has strong per-device primitives but no **release identity** and no **bill of
materials** binding a fielded sensor to the exact firmware, model, and
calibration it is running — and no plane to manage that across many devices.
Without this, a handful of nodes is fine but *hundreds* of sensors become an
operational nightmare: no coherent way to provision, roll certificates, verify
firmware compatibility, distribute signed models, track calibration lifecycle,
watch health, stage updates, roll back, diagnose remotely, enforce data
retention, or produce an audit trail. This ADR addresses that release-identity /
BOM gap directly.

The scope is deliberately the **control plane**, not the data plane. The
authenticated measurement path is **ADR-296** (bind + allowlist) plus **ADR-305**
(signed envelope); this ADR governs the *devices and artifacts*, not the
per-frame stream.

Relevant existing assets to build on rather than duplicate:

- **ADR-305** already defines per-device keypairs, the `DeviceId → public key →
  capabilities` enrollment record, key rotation and revocation *semantics* — and
  explicitly deferred their **fleet distribution** to this ADR. The control
  plane is the distribution and lifecycle layer over ADR-305 identity, not a new
  identity scheme.
- **ADR-318** (capability certificate) defines the signed, expiring artifact a
  device is authorized to run; the fleet plane is what *distributes, stages, and
  revokes* those certificates and the signed models they point at.
- **ADR-301** (calibration) owns calibration validity/expiry; the fleet plane
  tracks calibration *lifecycle* across the fleet (which nodes are due, which are
  stale) rather than redefining calibration.
- **ADR-319** (witness chain) provides the append-only, re-verifiable record;
  fleet audit trails are witness-chain entries, not a parallel log format.
- **ADR-320** (RuView sensor HAL, phase 2) provides hardware/firmware capability
  descriptors used for firmware-compatibility checks before staging an update.
- `wifi-densepose-bfld` `CapabilityAttestation` (ADR-141) is the device-side
  attestation the plane checks against declared cohort capabilities.

## Options considered

1. **Manual per-device operations (SSH/flash by hand).** Rejected: does not
   scale past a handful of nodes, produces no release identity, no audit trail,
   and no safe rollback — exactly the operational nightmare the reviews named.
2. **Adopt a generic third-party IoT device-management platform wholesale.**
   Rejected as the core: generic platforms do not understand RuView's signed
   capability certificate, calibration validity, or witness chain, and would
   fork trust away from the phase-1 spine. A generic transport/agent *may* be a
   backend, but identity, certificates, and audit remain RuView's.
3. **A RuView-native control plane layered on ADR-305 identity, ADR-318
   certificates, ADR-301 calibration lifecycle, and ADR-319 audit — covering
   provisioning through rollback and retention.** Chosen.

## Decision

Define a **fleet control plane** that manages RuView sensors and their signed
artifacts across their lifecycle, built on the phase-1 identity/certificate
spine.

### 1. Release identity and bill of materials

- Each fielded device has a **BOM record** binding `DeviceId` (ADR-305) → exact
  firmware version → signed model set → active capability certificate (ADR-318)
  → current calibration record (ADR-301) → HAL/hardware descriptor (ADR-320).
  This *is* the release identity the reviews found missing: given a device you
  can state precisely what it is running and prove it is signed.

### 2. Provisioning, certificates, firmware compatibility

- **Provisioning** is the authorized ADR-305 enrollment step at fleet scale:
  minting a keypair, registering the public key and capabilities, and issuing
  the initial ADR-318 certificate. A device is untrusted until provisioned.
- **Certificate lifecycle**: issue, rotate, expire, and **revoke** ADR-318
  certificates and the ADR-305 keys behind them; revocation lists are
  distributed here (the distribution ADR-305 deferred).
- **Firmware compatibility**: before staging a firmware or model, check the
  target's ADR-320 HAL descriptor and ADR-141 capability attestation so an
  incompatible or under-capable device is never sent an artifact it cannot
  honestly run.

### 3. Cohorts, staged updates, rollback

- Devices group into **cohorts** (by site, hardware, capability). Updates —
  signed models and firmware — roll out **staged** (canary → cohort → fleet)
  with health gates between stages, and **roll back** to the previously recorded
  BOM on a failed health check. Only signed artifacts are ever staged.

### 4. Health telemetry, remote diagnostics, retention, audit

- **Health telemetry** and **remote diagnostics** report device liveness,
  calibration staleness (ADR-301), certificate expiry (ADR-318), and error
  state — read-only diagnostics by default, mutations authorized explicitly.
- **Data retention** policy is enforced per cohort, and P0/CSI/person data never
  leaves the edge except under the ADR-277/280 governance already in force
  (CLAUDE.md: never commit or exfiltrate CSI/person data).
- Every lifecycle action — provision, rotate, revoke, stage, roll back — is
  written as an **ADR-319 witness-chain** entry, giving a re-verifiable **audit
  trail** rather than a mutable log.

### Authority and least privilege

- The control plane is default-deny (CLAUDE.md: default to least authority).
  Provisioning, key rotation, revocation, staging, and rollback are each
  separately authorized operations; no fleet action is implied by another.
  Credentials and private keys are never logged or committed.

## Consequences

- Hundreds of sensors become operable: coherent release identity, signed-artifact
  distribution, staged updates with rollback, and a re-verifiable audit trail —
  closing the release-identity / BOM gap the reviews raised.
- The plane concentrates operational authority; that is mitigated by
  default-deny, per-action authorization, signed-only artifacts, and
  witness-chained audit. A compromised plane must still forge signatures the
  phase-1 spine verifies.
- Hard dependency on ADR-305 (identity), ADR-318 (certificate), ADR-301
  (calibration lifecycle), ADR-319 (audit), and ADR-320 (firmware/HAL
  compatibility). This ADR distributes and sequences those artifacts; it does
  not redefine identity, certificates, calibration, or the witness format.
- Being phase 2, this is design intent depending on the spine; it is expected to
  be revised as ADR-318, ADR-319, and ADR-320 land.
- **No fielded fleet-operation claim is MEASURED without real-silicon evidence**
  (CLAUDE.md hardware rule): staged update and rollback on real nodes require a
  captured runtime log. A passing simulation is not fleet evidence.

## Validation

- Unit tests: BOM records bind identity/firmware/model/certificate/calibration
  consistently and reject inconsistent bindings; certificate issue/rotate/revoke
  transitions are correct; a firmware-incompatible target is refused staging;
  every lifecycle action emits a well-formed ADR-319 witness entry.
- Integration test: a synthetic cohort undergoes a canary→cohort→fleet staged
  update; an injected health failure triggers rollback to the prior BOM; the
  full sequence is re-verifiable from the witness chain offline; a revoked
  certificate is rejected fleet-wide.
- Security test (`npm run test:security` analogue for the plane): default-deny
  is enforced; unauthorized provision/rotate/revoke/stage is rejected and
  counted; no credential or P0 data appears in telemetry or audit output.
- Field validation (deferred, real-silicon): a real multi-node staged update and
  rollback with a captured boot/runtime log, reported as `MEASURED` with a
  reproducer. Until then all fleet-operation results are simulator-level. No
  fielded reliability number is asserted by this ADR.