mirror of
https://github.com/ruvnet/RuView
synced 2026-08-11 20:41:44 +00:00
docs(user-guide): add Perception Certificate Spine developer-preview section (ADR-297)
Documents the 9 new spine crates (calibrate -> certify -> govern) as a composable library, explicit about current status: each crate is tested in isolation but not yet wired together or into the live sensing-server request path (DomainState is 3 separate enum types across ruview-ood/certify/policy with no automatic bridge). Contrasts against the two ADR-292-296 remediation items that ARE genuinely enforced today: UDP source allowlisting (checked on every packet) and the CSI data-policy CI guard.
This commit is contained in:
@@ -38,6 +38,7 @@ WiFi DensePose turns commodity WiFi signals into real-time human pose estimation
|
|||||||
14. [Training a Model](#training-a-model)
|
14. [Training a Model](#training-a-model)
|
||||||
- [CRV Signal-Line Protocol](#crv-signal-line-protocol)
|
- [CRV Signal-Line Protocol](#crv-signal-line-protocol)
|
||||||
14. [RVF Model Containers](#rvf-model-containers)
|
14. [RVF Model Containers](#rvf-model-containers)
|
||||||
|
14. [Perception Certificate Spine (Developer Preview, ADR-297)](#perception-certificate-spine-developer-preview-adr-297)
|
||||||
14. [Hardware Setup](#hardware-setup)
|
14. [Hardware Setup](#hardware-setup)
|
||||||
- [ESP32-S3 Mesh](#esp32-s3-mesh)
|
- [ESP32-S3 Mesh](#esp32-s3-mesh)
|
||||||
- [Intel 5300 / Atheros NIC](#intel-5300--atheros-nic)
|
- [Intel 5300 / Atheros NIC](#intel-5300--atheros-nic)
|
||||||
@@ -1493,6 +1494,78 @@ An RVF file contains: model weights, HNSW vector index, quantization codebooks,
|
|||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
|
## Perception Certificate Spine (Developer Preview, ADR-297)
|
||||||
|
|
||||||
|
RuView's perception substrate program (ADR-297) is building a `signal → observation →
|
||||||
|
calibration → inference → uncertainty → evidence → certificate → policy → governed
|
||||||
|
action` pipeline, where a downstream consumer either gets a calibrated, provenance-backed
|
||||||
|
answer or an explicit `UNKNOWN` — never a confident-looking guess outside the sensor's
|
||||||
|
proven operating envelope.
|
||||||
|
|
||||||
|
**Status: developer preview.** Phase 1 shipped nine new crates with their own test
|
||||||
|
suites, and each one works correctly in isolation. **They are not yet wired together or
|
||||||
|
into the live `sensing-server` request path** — there is currently no code path where a
|
||||||
|
real drift signal from a running sensor flows through calibration → certificate
|
||||||
|
invalidation → policy denial. Treat everything below as a library you can compose
|
||||||
|
yourself today, not a safety guarantee the server enforces for you yet.
|
||||||
|
|
||||||
|
### The crates
|
||||||
|
|
||||||
|
| Crate | Role |
|
||||||
|
|---|---|
|
||||||
|
| `ruview-ontology` | Canonical `Site → … → Event` types |
|
||||||
|
| `ruview-attest` | Signed measurement / RF chain-of-custody |
|
||||||
|
| `ruview-evidence` | Append-only per-context ledger (no pooling, no evidence upgrade) |
|
||||||
|
| `wifi-densepose-calibration` | Signed, drift-invalidatable calibration certificate |
|
||||||
|
| `ruview-ood` | `Known` / `Degraded` / `Unknown` staleness-guard domain gating |
|
||||||
|
| `ruview-witness` | Hash-linked staged provenance chain |
|
||||||
|
| `ruview-certify` | Capability certificate, conditional on a live domain signature |
|
||||||
|
| `ruview-scorecard` | Multi-domain scorecard, worst-domain promotion gate |
|
||||||
|
| `ruview-policy` | Fail-closed action authorization gate |
|
||||||
|
|
||||||
|
### Minting and checking a certificate
|
||||||
|
|
||||||
|
```rust
|
||||||
|
use ruview_certify::{mint, CapabilityCertificate, DomainState};
|
||||||
|
|
||||||
|
// `signer`, `request`, and `evidence_slice` come from your own calibration run —
|
||||||
|
// see each crate's README for how to build them.
|
||||||
|
let cert = mint(&signer, request, &evidence_slice)?;
|
||||||
|
|
||||||
|
// A certificate is only valid at a given instant AND domain state — the same
|
||||||
|
// signed certificate is rejected the moment the live domain degrades:
|
||||||
|
assert!(cert.is_valid(now_ms, DomainState::Known));
|
||||||
|
assert!(!cert.is_valid(now_ms, DomainState::Degraded));
|
||||||
|
assert!(!cert.is_valid(now_ms, DomainState::Unknown));
|
||||||
|
```
|
||||||
|
|
||||||
|
### Gating an action
|
||||||
|
|
||||||
|
```rust
|
||||||
|
use ruview_policy::{authorize, ActionClass, DomainState};
|
||||||
|
|
||||||
|
let decision = authorize(ActionClass::SafetyCritical, &inputs);
|
||||||
|
// Deny with a named FailedCondition (e.g. `domain_not_known`) rather than a
|
||||||
|
// silent false-positive, whenever the domain isn't KNOWN.
|
||||||
|
```
|
||||||
|
|
||||||
|
**Important:** `ruview_certify::DomainState` and `ruview_policy::DomainState` (and
|
||||||
|
`ruview_ood`'s) are currently three separate enum types — `ruview-ood`'s `Degraded`
|
||||||
|
variant even carries different data. There is no automatic conversion between them.
|
||||||
|
If you compose these crates yourself today, you own writing that bridge; don't assume
|
||||||
|
one crate's domain read automatically reaches another's gate.
|
||||||
|
|
||||||
|
### What's genuinely enforced today, for comparison
|
||||||
|
|
||||||
|
Not every ADR-292–296 remediation item is preview-only. Two are live now:
|
||||||
|
|
||||||
|
- **UDP data-plane bind hardening (ADR-293)** — `sensing-server`'s `UdpSourceAllowlist`
|
||||||
|
is checked on every incoming packet (`main.rs`), not just defined.
|
||||||
|
- **CSI data-incident repo controls (ADR-296)** — `scripts/csi-data-policy-check.sh`
|
||||||
|
runs in CI on every push/PR and fails the build on a policy violation.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
## Hardware Setup
|
## Hardware Setup
|
||||||
|
|
||||||
### Supported targets
|
### Supported targets
|
||||||
|
|||||||
Reference in New Issue
Block a user