mirror of
https://github.com/ruvnet/RuView
synced 2026-08-11 20:41:44 +00:00
Merge remote-tracking branch 'origin/main' into resolve-1579-conflict
# Conflicts: # docs/adr/README.md
This commit is contained in:
ruv
@@ -0,0 +1,231 @@
|
||||
# ADR-288: VEIL — a compliant-waveform privacy shield against unauthorized WiFi sensing
|
||||
|
||||
| Field | Value |
|
||||
|-------|-------|
|
||||
| **Status** | Proposed — implemented (P1 reference model) |
|
||||
| **Date** | 2026-08-09 |
|
||||
| **Deciders** | ruv |
|
||||
| **Codename** | **VEIL** — Verifiable Emission-shaping for Identity-Leakage prevention |
|
||||
| **Codebase target** | new leaf crate `v2/crates/wifi-densepose-privshield` |
|
||||
| **Parent** | ADR-118 (BFLD — the detection layer VEIL is the countermeasure to), ADR-282 (mandatory L0–L5 evidence ladder) |
|
||||
| **Relates to** | ADR-120/121 (BFLD privacy class + identity-risk scoring — the trigger source), ADR-141 (privacy control plane / runtime attestation — the audit consumer), ADR-280 (active sensing / governed actuation — VEIL is a defensive sensing action), ADR-185 §13 (`wifi-densepose-aether` — the pure-compute leaf pattern this crate follows) |
|
||||
| **Research bundle** | [`docs/research/privacy-shield/`](../research/privacy-shield/) (9 files) |
|
||||
| **Tracking issue** | TBD |
|
||||
|
||||
## 0. PROOF discipline
|
||||
|
||||
Every defense number this crate produces is **SYNTHETIC / evidence level L0**
|
||||
(ADR-282): generated by the crate's own model (`identity::Channel`), attacked by
|
||||
the crate's own classifier (`attacker::NearestCentroidAttacker`), and scored
|
||||
against its own known labels. Nothing here has been validated against real WiFi
|
||||
silicon, and the crate contains no radio integration and cannot emit RF. External
|
||||
attack/defense results cited from the literature (BFId, LeakyBeam, DySPAN-2026,
|
||||
IRShield, FCC statutes) are **EXTERNAL** evidence and labelled MEASURED/CLAIMED in
|
||||
the research bundle. The single measured claim about *our own behavior* is the
|
||||
pinned deterministic witness in `proof.rs`.
|
||||
|
||||
## 1. Context
|
||||
|
||||
### 1.1 The gap
|
||||
|
||||
IEEE 802.11ac/ax beamforming feedback (BFI) — the compressed Givens-rotation
|
||||
angle matrices (φ/ψ) a client sends the AP — is transmitted **unencrypted on the
|
||||
management plane**. Any device in monitor mode can capture it for every station
|
||||
at once, no network access, and the target need carry no device. The literature
|
||||
establishes the severity: **BFId** (ACM CCS 2025) re-identifies individuals from
|
||||
BFI; **LeakyBeam** (NDSS 2025) detects occupancy through walls at 20 m from BFI;
|
||||
**BeamSense** recognizes activities at up to 99.28%. IEEE Std **802.11bf-2025**
|
||||
(published 26 Sep 2025) standardizes the sensing measurement/feedback surface
|
||||
these attacks abuse — and a 2023 proposal for a BFI secure-transmission mechanism
|
||||
(802.11-23/0782) was **withdrawn**, so the standard shipped with no privacy
|
||||
protections.
|
||||
|
||||
RuView already has a *detection* layer for this: **BFLD** (ADR-118/121) measures
|
||||
the identity-leakage of each frame and gates what leaves the node. But BFLD
|
||||
protects *RuView's own outputs*; it does nothing about a **third-party sniffer**
|
||||
capturing the room's plaintext BFI off the air. There is no RuView component, and
|
||||
per our market survey no shipping product anywhere, that prevents that.
|
||||
|
||||
### 1.2 Constraint: compliant waveform controls, never jamming
|
||||
|
||||
The defense must preserve normal communications and must not interfere with any
|
||||
other station. Jamming (47 U.S.C. §333/§302a) is defined by *adding energy to
|
||||
interfere with others' transmissions*. Any acceptable control must shape only the
|
||||
node's **own** standards-conformant emission.
|
||||
|
||||
### 1.3 The separability insight
|
||||
|
||||
Identity leaks through the *fine* cross-subcarrier phase structure of a
|
||||
beamforming report; data throughput rides the *dominant* beam direction. These
|
||||
are (mostly) separable subspaces — so a transform confined to the fine subspace
|
||||
can wreck re-identification while sparing the beam the link depends on. DySPAN-2026
|
||||
independently MEASURED that shaping fine-resolution feedback is near-free in
|
||||
throughput, corroborating the insight.
|
||||
|
||||
## 2. Decision
|
||||
|
||||
Ship **`wifi-densepose-privshield`** (VEIL) as a standalone pure-compute leaf
|
||||
crate (the `wifi-densepose-aether`/`nvsim` pattern: dependency-free, deterministic,
|
||||
WASM-ready, zero coupling to any radio or ingestion path), implementing:
|
||||
|
||||
1. **A SYNTHETIC two-subspace BFI model** (`identity.rs`): each identity owns a
|
||||
stable fine-block signature; sessions add environmental nuisance; the comm
|
||||
block is identity-free and carries throughput.
|
||||
2. **The protector** (`protector.rs`): compliant waveform controls, primarily a
|
||||
**per-session keyed orthogonal rotation of the fine subspace, composed from
|
||||
extra Givens rotations** — the report's native primitive. Plus feedback
|
||||
quantization/dither, sounding-cadence randomization, and a `SensingDetector`
|
||||
that engages the shield only when sensing activity is observed.
|
||||
3. **The adversary** (`attacker.rs`): a passive nearest-centroid re-identifier
|
||||
modeling the BFId threat, with selectable Euclidean/Cosine metrics.
|
||||
4. **A throughput model** (`throughput.rs`):
|
||||
`(1 − sounding − feedback_airtime) · C(SNR·(1−ρ))/C(SNR)`, where the residual
|
||||
`ρ` falls with feedback bits and the feedback airtime rises with them — giving
|
||||
a genuine interior throughput optimum in feedback resolution.
|
||||
5. **A compliance audit** (`compliance.rs`): the rotation is orthogonal ⇒
|
||||
energy-preserving ⇒ adds no interfering energy ⇒ **not jamming**, turned into a
|
||||
checked `ComplianceReport` (energy ratio ≈ 1.0).
|
||||
6. **The experiment** (`experiment.rs`): runs the attacker against unprotected and
|
||||
protected traffic and reports both accuracies vs. chance, plus throughput and
|
||||
compliance, with a single `passed()` verdict.
|
||||
7. **The hyper-optimizer** (`optimize.rs`): derives the shipped shield config
|
||||
rather than hand-picking it — the throughput-optimal feedback resolution and
|
||||
the minimum rotation-mixing budget that collapses re-ID robustly (across both
|
||||
attacker metrics and N∈{16,32}), plus a Pareto frontier.
|
||||
8. **A deterministic proof** (`proof.rs`): a pinned FNV-1a witness over the
|
||||
reference experiment (the `nvsim`/`verify.py` discipline).
|
||||
|
||||
### 2.1 Why the keyed Givens rotation
|
||||
|
||||
It is simultaneously **orthogonal** (energy-preserving ⇒ compliant),
|
||||
**key-reversible** (the associated AP shares the session key and recovers the true
|
||||
precoder ⇒ throughput preserved), and **fresh per session** (a sniffer sees a new
|
||||
random rotation of the signature each session and cannot average it back ⇒ the
|
||||
enrollment attack collapses; over unknown rotations the signature carries no
|
||||
stable discriminative information ⇒ re-ID → chance). It is the shared-secret
|
||||
precoding idea (cf. MIMOCrypt) specialized to the identity-bearing subspace.
|
||||
|
||||
### 2.2 Measured behavior (SYNTHETIC / L0)
|
||||
|
||||
Reference experiment at the hyper-optimized operating point (§opt), default
|
||||
scene, N=16 identities, `cargo test`:
|
||||
|
||||
| Metric | Shield off | Shield on |
|
||||
|---|---|---|
|
||||
| Passive re-ID accuracy | 100.0% | **4.7%** (chance 6.25%) |
|
||||
| Link throughput ratio | 100% | **97.6%** |
|
||||
| Emission energy ratio | — | **1.000000** (compliant) |
|
||||
|
||||
All 35 unit/proof tests + doctest pass; the crate builds for
|
||||
`wasm32-unknown-unknown` and is clippy-clean.
|
||||
|
||||
### opt. Hyper-optimization (`optimize.rs`)
|
||||
|
||||
The shipped shield config is the optimizer's output, not a guess, and
|
||||
`ShieldConfig::default()` is asserted equal to it:
|
||||
|
||||
- **Feedback resolution = 5 bits.** Throughput has an interior optimum in
|
||||
feedback bits (residual falls, feedback airtime rises); the unconstrained
|
||||
optimum is 3 bits (matching DySPAN-2026), and 5 is the throughput-best value in
|
||||
the spec-allowed 802.11 {5,7,9} set.
|
||||
- **Givens passes = 96.** The proven minimum for robust collapse — across both
|
||||
attacker metrics *and* N∈{16,32} — is **48**; the shipped 96 is a free 2×
|
||||
privacy margin, since the keyed rotation is derived from the shared secret and
|
||||
never signaled (extra passes cost compute, not airtime). The original
|
||||
hand-picked 112 was 2.3× over-provisioned.
|
||||
|
||||
Net vs. the original hand-picked (112 passes / 7 bits): the optimum is strictly
|
||||
better on **both** privacy (re-ID 0.047 vs 0.078) and throughput (0.976 vs 0.974),
|
||||
and is now verified rather than assumed. See
|
||||
`docs/research/privacy-shield/08-optimization.md`.
|
||||
|
||||
### harness. Native terminal harness + TUI (`src/bin/veil.rs`)
|
||||
|
||||
A custom, dependency-free binary (`veil`) ships with the crate — the in-repo,
|
||||
native counterpart to the npm metaharness (ADR-289). It drives the same public
|
||||
API the tests use, as an interactive ANSI dashboard plus scriptable subcommands
|
||||
(`report`, `sweep`, `optimize`, `adaptive <N>`, `proof`, `doctor`, `tui`).
|
||||
Std-only (no `crossterm`/`ratatui`): the TUI is a command-driven redraw loop, so
|
||||
it runs in any terminal, pipe, or CI and keeps the crate a pure leaf. It reports
|
||||
only SYNTHETIC/L0 numbers and never relabels them. The wasm leaf story is
|
||||
unchanged (validated with `--lib`; the bin is native-only).
|
||||
|
||||
### sota. 2025–2026 evidence update (verified)
|
||||
|
||||
A cited, adversarially-verified SOTA sweep
|
||||
(`docs/research/privacy-shield/09-sota-update-2026.md`) refines the threat and
|
||||
positioning. Load-bearing points for this ADR:
|
||||
|
||||
- **Threat is broader and cheaper than §1.1 stated.** A passive, keyless,
|
||||
single-antenna sniffer at ~20 m and *through walls* can identify people
|
||||
(BFId, 99.5%/N=197, `MEASURED`), read **breathing** from stationary occupants
|
||||
and **keystrokes/PINs** (LeakyBeam / WiKI-Eve / SThief, `MEASURED`), and —
|
||||
decisively — **reconstruct full CSI from the sniffed BFI** (BFIAttack,
|
||||
≥93% single-antenna, `MEASURED`). VEIL's obfuscation must therefore degrade
|
||||
*reconstructed-CSI* utility, not merely raw-BFI feature noise; because VEIL's
|
||||
rotation is a **secret orthogonal** transform, the attacker has no key and no
|
||||
closed-form to invert — this is now a claim to **test**, not assume.
|
||||
- **VEIL's family is independently validated.** AP-side per-packet random
|
||||
unitary on the LTF (LeakyBeam defense, 89.7%→~51%, `MEASURED`) and RIS
|
||||
obfuscation (PrivISAC, 93%→~30%, robust to a retrained multi-location
|
||||
attacker, `MEASURED`) confirm standard-permitted beamforming-surface
|
||||
obfuscation works; DP-Givens quantization (`SYNTHETIC`) offers a formal ε knob.
|
||||
- **Compliance precedent.** BeamDancer (IEEE TWC 2024, `MEASURED`) argues
|
||||
native-beamforming obfuscation is 802.11-compliant while jamming/geofencing
|
||||
are not — cite it as precedent. (Its ">96% PDR" figure was **refuted** in
|
||||
verification; do not cite it.)
|
||||
- **Security honesty.** Obfuscation shields have published counter-attacks
|
||||
("Defeating CSI obfuscation", SnoopFi), so VEIL's own shield security is
|
||||
`CLAIMED`, not proven-secure, until it withstands learned de-obfuscation.
|
||||
- **Governance gap.** No claim on 802.11bf-2025 privacy provisions survived
|
||||
verification; that pillar remains an open question, not an asserted fact.
|
||||
|
||||
The derived, prioritized improvement backlog lives in the SOTA-update file (§4).
|
||||
|
||||
## 3. What this explicitly is NOT
|
||||
|
||||
- **Not a radio driver.** No RF frontend, no transmit path, no
|
||||
`wifi-densepose-hardware` coupling. VEIL cannot emit and cannot jam.
|
||||
- **Not a defense against the associated AP.** That party holds the session key by
|
||||
construction (threat class A3); protecting against a malicious AP is BFLD's
|
||||
detection/privacy-class problem (ADR-118/141), not this shield's.
|
||||
- **Not a full motion-obfuscation claim.** A fixed per-session rotation does not
|
||||
hide coarse within-session motion; identity *re-ID* is the guaranteed target,
|
||||
motion is partial/future work.
|
||||
- **Not a real-hardware performance claim.** All defense numbers are SYNTHETIC/L0
|
||||
until a two-node capture with a boot/runtime-log witness exists (CLAUDE.md
|
||||
hardware rule; roadmap P5).
|
||||
- **Not RF denial or camera-grade anything.**
|
||||
|
||||
## 4. Simplifications (honesty boundary)
|
||||
|
||||
- The two-subspace split is an abstraction; on real radios comm and identity
|
||||
information are only *approximately* separable, so the real throughput cost of
|
||||
fully hiding identity may exceed the model's ~2%. DySPAN-2026's MEASURED curve
|
||||
bounds it as *small* at fine resolution, not zero.
|
||||
- The attacker is nearest-centroid. The collapse argument is classifier-independent
|
||||
(it is about the marginalized signal), but P2/P5 must confirm a learned attacker
|
||||
also collapses.
|
||||
- The crate's PRNG is SplitMix64 — deterministic and WASM-safe but **not
|
||||
cryptographic**; a deployment derives the rotation key from the negotiated link
|
||||
secret, never from this PRNG.
|
||||
|
||||
## 5. Consequences
|
||||
|
||||
- RuView gains the *countermeasure* half of its RF-privacy story: BFLD detects
|
||||
leakage, VEIL acts on it — a defensible, standards-anchored, gap-filling
|
||||
position (see `docs/research/privacy-shield/06-market-and-buyers.md`).
|
||||
- The compliance audit gives regulators/auditors a machine-checkable "not jamming"
|
||||
artifact that composes with ADR-141 attestation.
|
||||
- Future integration (BFLD `identity_risk` → `SensingDetector`, ADR-280 governed
|
||||
actuation, firmware feedback shaping, two-node hardware measurement) is staged in
|
||||
the research bundle roadmap and deliberately deferred so the model validates in
|
||||
isolation first.
|
||||
|
||||
## 6. Validation
|
||||
|
||||
```bash
|
||||
cargo test -p wifi-densepose-privshield --no-default-features
|
||||
cargo build -p wifi-densepose-privshield --target wasm32-unknown-unknown
|
||||
cargo clippy -p wifi-densepose-privshield --all-targets
|
||||
```
|
||||
@@ -0,0 +1,95 @@
|
||||
# ADR-289: `wifi-densepose-privshield-harness` — a MetaHarness for the VEIL privacy shield
|
||||
|
||||
| Field | Value |
|
||||
|-------|-------|
|
||||
| **Status** | Proposed — implemented (P1) |
|
||||
| **Date** | 2026-08-09 |
|
||||
| **Parent** | ADR-288 (`wifi-densepose-privshield` / VEIL, the crate this harness assists development on) |
|
||||
| **Relates to** | ADR-286 (`wifi-densepose-sar-harness`, the per-crate harness scaffold this one mirrors), ADR-285 (`harness/homecore/`, the WASM-first `@metaharness/kernel` pattern), ADR-182 (`harness/ruview/`, the first minted harness), ADR-282 (L0–L5 evidence ladder) |
|
||||
| **Location** | `harness/wifi-densepose-privshield/` |
|
||||
|
||||
## 0. PROOF discipline
|
||||
|
||||
Every claim below about what is "real" versus "illustrative"/"SYNTHETIC" is
|
||||
checked by a test in this harness's own suite (router + flywheel + install-smoke
|
||||
+ guidance). The dependency-free `guidance` surface is covered by
|
||||
`__tests__/guidance.test.ts`, which runs even before `npm install`. Nothing here
|
||||
asserts a MEASURED defense result — the harness surfaces the VEIL crate's
|
||||
SYNTHETIC/L0 numbers with that label intact.
|
||||
|
||||
## 1. Context
|
||||
|
||||
`wifi-densepose-privshield` (ADR-288) is the VEIL privacy shield — a new,
|
||||
narrowly-scoped crate. Following the pattern ADR-286 set for
|
||||
`wifi-densepose-sar`, it gets a dedicated per-crate MetaHarness rather than a
|
||||
bespoke setup: the `vertical:coding` scaffold (architect/implementer/reviewer/
|
||||
test-writer, `doctor`) with `@metaharness/router`, `@metaharness/flywheel`, and
|
||||
Darwin Mode wired in, plus a VEIL-specific, dependency-free `guidance` surface.
|
||||
|
||||
## 2. Decision
|
||||
|
||||
Land the harness at `harness/wifi-densepose-privshield/`, mirroring
|
||||
`wifi-densepose-sar-harness`, with two deliberate improvements:
|
||||
|
||||
1. **Dynamic dependency imports.** `bin/cli.js` imports the `@metaharness/*`
|
||||
packages *inside* the commands that need them, not at module top. So
|
||||
`guidance`, `--help`, and the guidance test run with **zero dependencies
|
||||
installed** — useful for offline/air-gapped review and for this repo's CI
|
||||
before `npm install`. Only `init`/`doctor`/`route`/`flywheel` touch the
|
||||
kernel/host/router/flywheel packages.
|
||||
2. **A VEIL `guidance` command.** A self-contained, source-cited, read-only
|
||||
capability map (topics: `overview`, `threat`, `countermeasure`,
|
||||
`compliance`, `optimization`, `experiment`), each entry carrying a summary,
|
||||
repo-relative source citations, focused validation commands, and explicit
|
||||
limitations — the `ruview_guidance` shape, specialized to VEIL. It labels all
|
||||
defense evidence `SYNTHETIC/L0` and states plainly that guidance is
|
||||
navigation, not authority.
|
||||
|
||||
The standard three self-improvement/cost pieces are wired as real npm
|
||||
dependencies (not stubs):
|
||||
|
||||
- **`@metaharness/darwin`** (devDependency) — `npm run evolve` / `evolve:dry`
|
||||
mutates the harness's own operating config, keeping only measurable gains.
|
||||
- **`@metaharness/router`** — `src/router.ts` wires a real cost-optimal `Router`
|
||||
(`qualityBar: 0.8`, k=1) over two model tiers, with four VEIL-shaped task axes
|
||||
(threatModeling / complianceReview / optimizerTuning / docWriting). Labelled
|
||||
examples are illustrative seed data (honesty note in-file).
|
||||
- **`@metaharness/flywheel`** — `src/flywheel.ts` wires the real
|
||||
`runFlywheelGenerations` promotion loop (propose → evaluate → gate → promote,
|
||||
Ed25519-signed, independently replayable) with a SYNTHETIC proposer/evaluator
|
||||
(`dataSource: 'SYNTHETIC'`, no model call), over VEIL policy levers
|
||||
(`complianceReview`, `threatTriage`).
|
||||
|
||||
## 3. What this explicitly is NOT
|
||||
|
||||
- **Not a VEIL runtime.** The harness does not run a radio, emit RF, or jam. It
|
||||
assists *development* on the crate; it cannot execute the shield on hardware.
|
||||
- **Not evolving the crate.** Darwin/Flywheel mutate the harness's own policy
|
||||
(agent prompts, review-checklist depth), not VEIL's Rust code. The crate's
|
||||
actual hyper-optimization (ADR-288 §opt) was done directly, in the crate.
|
||||
- **Not a live routing/promotion system.** The router's examples are seed data;
|
||||
the flywheel's proposer/evaluator are deterministic stand-ins — both honestly
|
||||
labelled in-source and in `CLAUDE.md`.
|
||||
- **Not a replacement for the crate's gates.** The authoritative check for a
|
||||
VEIL change remains `cargo test -p wifi-densepose-privshield`.
|
||||
- **Not a re-labeller.** The harness must never present VEIL's SYNTHETIC results
|
||||
as MEASURED, and never scaffold interference-based ("jamming") defenses — both
|
||||
are hard rules in the harness `CLAUDE.md`.
|
||||
|
||||
## 4. Consequences
|
||||
|
||||
- The harness ships `guidance`/`doctor`/`init`/`route`/`flywheel`; `guidance`
|
||||
and `--help` work offline (validated here via `node bin/cli.js`), the rest
|
||||
after `npm install` + `npm run build` (CI).
|
||||
- `.harness/manifest.json` + `manifest.sha256` are generated with real per-file
|
||||
hashes at creation (unlike ADR-286's scaffold, whose manifest was historical).
|
||||
- Scoped to its own name: its plugin, permissions, and (future) MCP surface only
|
||||
read/assist on `wifi-densepose-privshield`. No risk to other harnesses/crates.
|
||||
|
||||
## 5. Validation
|
||||
|
||||
```bash
|
||||
cd harness/wifi-densepose-privshield
|
||||
node bin/cli.js guidance --topic overview # dependency-free
|
||||
npm ci && npm run build && npm test # full suite (CI; needs registry access)
|
||||
```
|
||||
@@ -0,0 +1,94 @@
|
||||
# ADR-290: VEIL end-to-end hardware implementation program (multi-provider firmware)
|
||||
|
||||
| Field | Value |
|
||||
|-------|-------|
|
||||
| **Status** | Proposed — P4 scaffolding (build-only); portable core validated on host |
|
||||
| **Date** | 2026-08-09 |
|
||||
| **Parent** | ADR-288 (VEIL shield), ADR-289 (harness), ADR-282 (L0–L5 evidence ladder) |
|
||||
| **Location** | `firmware/privshield/` |
|
||||
| **Relates to** | `firmware/esp32-csi-node/` (the CSI sensor/attacker node), ADR-280 (governed actuation), ADR-141 (attestation) |
|
||||
|
||||
## 0. PROOF discipline
|
||||
|
||||
The **only** artifact validated here is the portable C core
|
||||
(`firmware/privshield/core/`): a host test (`make test`) checks energy
|
||||
conservation, reversibility, wrong-key failure, and — pinned — that its
|
||||
SplitMix64 key schedule is **byte-identical to the Rust crate's** PRNG. That is
|
||||
`build`/host-level evidence, not silicon. Every per-provider adapter is a
|
||||
**build-only scaffold** with `TODO(hw)` markers: `SYNTHETIC / L0`, no captured
|
||||
log, no `MEASURED` claim. Nothing in this ADR asserts VEIL works on real
|
||||
hardware; it asserts a *plan and a shared core* to get there (P5).
|
||||
|
||||
## 1. Context
|
||||
|
||||
ADR-288 shipped VEIL as a deterministic, no-radio Rust model, and the 2025–2026
|
||||
SOTA sweep (ADR-288 §sota) confirmed the mechanism's family is real and
|
||||
standard-permitted. The open question left was **"does this run on real WiFi
|
||||
hardware, and on which?"** — including the user asks: *can OpenWRT / open WiFi
|
||||
software implement it, and can ESP32 help scramble signals?* Answering requires
|
||||
committing to the platform reality rather than assuming a uniform "firmware"
|
||||
target.
|
||||
|
||||
## 2. Decision
|
||||
|
||||
Stand up `firmware/privshield/` as a **multi-provider E2E program** around one
|
||||
shared, validated core:
|
||||
|
||||
1. **A portable C shield core** (`core/veil_shield.{h,c}`) — the keyed
|
||||
Givens-rotation obfuscation, `no_std`-friendly C99 (no malloc/libc I/O), with
|
||||
a SplitMix64 key schedule matching the Rust crate so on-air behavior is
|
||||
identical everywhere and every adapter links the *same* math. Host-tested.
|
||||
2. **Per-provider adapters**, each built and graded by a hardware research
|
||||
agent, honest about what its stack can actually touch:
|
||||
- **`openwifi/`** (open PHY/MAC on SDR/FPGA) — the highest-capability path and
|
||||
the one that can host the **keyed-reversible** design end-to-end
|
||||
(protector + AP-side compensation). Carries the **P5 measurement protocol**
|
||||
(`MEASUREMENT.md`) that yields the first `MEASURED` result with a witness.
|
||||
- **`openwrt/`** (Linux `mac80211`, mt76/ath9k…) — the commodity path.
|
||||
Sounding-cadence randomization, MU-group and stream-mapping control are
|
||||
feasible from the driver/hostapd; the per-packet unitary on the LTF spatial
|
||||
mapping is firmware-deep on most parts. Partial.
|
||||
- **`nexmon/`** (Broadcom/Cypress C firmware patches) — the commodity
|
||||
C-firmware route; the read path is proven (Wi-BFI/nexmon_csi), the transmit
|
||||
report-shaping path is research-grade/partial.
|
||||
- **`esp32/`** (ESP-IDF) — **not** a feedback protector (the beamforming path
|
||||
is a closed blob): ESP32 shapes CSI *read*, not transmitted feedback. Its
|
||||
legitimate roles are a **sensing detector** (trigger the AP-side shield) and
|
||||
an **RIS controller** (drive an external reconfigurable surface to scramble
|
||||
the sensing direction — the honest way ESP32 "helps scramble", via an
|
||||
external surface, not its own PHY).
|
||||
3. **Compliance stance carried into hardware:** every control shapes the node's
|
||||
own standards-conformant emission and preserves energy; the ESP32
|
||||
decoy/cover-traffic idea is documented as *legally sensitive / not
|
||||
recommended* precisely because it edges toward the interference line.
|
||||
|
||||
Per-provider feasibility grades live in each subdir README and the top-level
|
||||
feasibility matrix; they are the answer to the "which hardware" question.
|
||||
|
||||
## 3. What this explicitly is NOT
|
||||
|
||||
- **Not validated firmware.** No adapter has run on silicon; there is no witness.
|
||||
The scaffolds compile-*shaped*, not compile-*guaranteed* on their toolchains
|
||||
(which are absent in this environment).
|
||||
- **Not a claim that ESP32 can shield beamforming feedback** — it cannot; it is a
|
||||
detector/RIS-controller only.
|
||||
- **Not jamming, on any platform.** Compliant waveform shaping only.
|
||||
- **Not a MEASURED result.** That is P5, gated on a captured log.
|
||||
|
||||
## 4. Consequences
|
||||
|
||||
- One validated core, four honest provider scaffolds, and a concrete P5
|
||||
measurement plan — a real path from model to silicon, with the effort/blocker
|
||||
reality made explicit per platform.
|
||||
- The shared core keeps every future hardware result consistent with the crate
|
||||
and with each other.
|
||||
- Scope stays inside `firmware/privshield/`; no other crate/firmware is touched
|
||||
(the existing `esp32-csi-node` remains the sensor/attacker node).
|
||||
|
||||
## 5. Validation
|
||||
|
||||
```bash
|
||||
cd firmware/privshield/core && make test # host: energy/reversibility/PRNG parity
|
||||
# per-provider builds require their toolchains (ESP-IDF, OpenWRT SDK, Nexmon,
|
||||
# Vivado) and real hardware — see each subdir's BUILD/INTEGRATION notes.
|
||||
```
|
||||
+1
-1
@@ -1,4 +1,4 @@
|
||||
# ADR-288: Public-benchmark evaluation harness — Widar3.0 ingest, standard split protocols, leakage guards
|
||||
# ADR-291: Public-benchmark evaluation harness — Widar3.0 ingest, standard split protocols, leakage guards
|
||||
|
||||
- **Status**: Accepted — initial implementation (this PR)
|
||||
- **Date**: 2026-08-10
|
||||
+1
-1
@@ -1,4 +1,4 @@
|
||||
# ADR-289: Wideband 802.11ax CSI ingest — FeitCSI/AX210 adapter and subcarrier-agnostic plumbing
|
||||
# ADR-292: Wideband 802.11ax CSI ingest — FeitCSI/AX210 adapter and subcarrier-agnostic plumbing
|
||||
|
||||
- **Status**: Accepted — initial implementation (this PR)
|
||||
- **Date**: 2026-08-10
|
||||
+2
-2
@@ -1,4 +1,4 @@
|
||||
# ADR-290: Vitals ground-truth rig — reference ingest, time alignment, and agreement metrics
|
||||
# ADR-293: Vitals ground-truth rig — reference ingest, time alignment, and agreement metrics
|
||||
|
||||
- **Status**: Accepted — initial implementation (this PR)
|
||||
- **Date**: 2026-08-10
|
||||
@@ -69,7 +69,7 @@ Add a `groundtruth` module to `v2/crates/wifi-densepose-vitals`:
|
||||
reference device, non-zero paired samples, minimum coverage, and a
|
||||
reproducer command string; otherwise the report grades as `Claimed` (real
|
||||
data, no reference) or `Synthetic` (generated input). This mirrors
|
||||
ADR-288's enforcement-in-types approach and the CLAUDE.md tagging rule.
|
||||
ADR-291's enforcement-in-types approach and the CLAUDE.md tagging rule.
|
||||
|
||||
## Consequences
|
||||
|
||||
+1
-1
@@ -1,4 +1,4 @@
|
||||
# ADR-291: WiFi Veil integration — emission-shaping countermeasure as an advisory BFLD dependency
|
||||
# ADR-294: WiFi Veil integration — emission-shaping countermeasure as an advisory BFLD dependency
|
||||
|
||||
- **Status**: Accepted — initial implementation (this PR)
|
||||
- **Date**: 2026-08-10
|
||||
+1
-1
@@ -1,4 +1,4 @@
|
||||
# ADR-292: Source provenance state machine — synthetic can never present as live
|
||||
# ADR-295: Source provenance state machine — synthetic can never present as live
|
||||
|
||||
- **Status**: Accepted — initial implementation (this PR)
|
||||
- **Date**: 2026-08-11
|
||||
+1
-1
@@ -1,4 +1,4 @@
|
||||
# ADR-293: Sensor data-plane hardening — UDP bind control and source allowlist (step one)
|
||||
# ADR-296: Sensor data-plane hardening — UDP bind control and source allowlist (step one)
|
||||
|
||||
- **Status**: Accepted — initial implementation (this PR)
|
||||
- **Date**: 2026-08-11
|
||||
+2
-2
@@ -1,4 +1,4 @@
|
||||
# ADR-294: Multi-node semantic correctness — per-node inference, node-keyed rate limiting, stale state
|
||||
# ADR-297: Multi-node semantic correctness — per-node inference, node-keyed rate limiting, stale state
|
||||
|
||||
- **Status**: Accepted — initial implementation (this PR)
|
||||
- **Date**: 2026-08-11
|
||||
@@ -46,7 +46,7 @@ mechanism RuView uses to reduce blind spots and room dependence:
|
||||
- Schema change to `NodeInfo`/the MQTT contract; existing single-node
|
||||
deployments keep working (one node = one inference). Consumers reading the
|
||||
old aggregate-only shape need the migration accessor.
|
||||
- Aligns with ADR-292 (freshness) and the review's call for one canonical
|
||||
- Aligns with ADR-295 (freshness) and the review's call for one canonical
|
||||
`NodeInference`/`RoomInference` contract.
|
||||
|
||||
## Validation
|
||||
+2
-2
@@ -1,4 +1,4 @@
|
||||
# ADR-295: Model release sanity gates — block degenerate and mislabeled model artifacts
|
||||
# ADR-298: Model release sanity gates — block degenerate and mislabeled model artifacts
|
||||
|
||||
- **Status**: Accepted — initial implementation (this PR)
|
||||
- **Date**: 2026-08-11
|
||||
@@ -31,7 +31,7 @@ for any classifier artifact proposed for release, fails on:
|
||||
- **Degenerate class balance** — predicted-positive rate at/above a ceiling
|
||||
(e.g. > 99%) on a balanced probe set.
|
||||
- **Missing/blank baseline** — a report without a paired mean-pose/majority
|
||||
baseline (ties into ADR-288 `EvaluationReport`).
|
||||
baseline (ties into ADR-291 `EvaluationReport`).
|
||||
- **Metric-name provenance** — a metric may not be surfaced under a task name
|
||||
that does not match its computed kind (temporal-triplet ≠ presence);
|
||||
enforced by making the metric carry its kind and the label derive from it.
|
||||
+1
-1
@@ -1,4 +1,4 @@
|
||||
# ADR-296: Repository CSI data-incident controls — ignore rules and a pre-commit/CI policy check
|
||||
# ADR-299: Repository CSI data-incident controls — ignore rules and a pre-commit/CI policy check
|
||||
|
||||
- **Status**: Accepted — controls implemented; tree remediation gated on owner sign-off
|
||||
- **Date**: 2026-08-11
|
||||
+48
-48
@@ -1,4 +1,4 @@
|
||||
# ADR-297: RuView perception substrate — a phased program for the calibration, evidence, trust, and deployment layer
|
||||
# ADR-300: RuView perception substrate — a phased program for the calibration, evidence, trust, and deployment layer
|
||||
|
||||
- **Status**: Accepted — program framing; child ADRs carry their own status
|
||||
- **Date**: 2026-08-11
|
||||
@@ -25,8 +25,8 @@ Several of these primitives already have foundations in the tree and should be
|
||||
- RuField provenance/signature types (ADR-260/262/277/279) and BFLD
|
||||
attestation (ADR-141).
|
||||
- `worldgraph` crate; `wifi-densepose-mat/tracking` (tracker, fingerprint).
|
||||
- The in-flight ADR-292 (provenance state machine), ADR-293 (authenticated
|
||||
data plane, step one), ADR-295 (model sanity gates) — the first bricks.
|
||||
- The in-flight ADR-295 (provenance state machine), ADR-296 (authenticated
|
||||
data plane, step one), ADR-298 (model sanity gates) — the first bricks.
|
||||
|
||||
## What RuView is optimizing for
|
||||
|
||||
@@ -51,20 +51,20 @@ Every child ADR and implementation is bound by these:
|
||||
confident class, or silently hold a stale value.
|
||||
2. **Capability certificates bind cryptographically.** Hardware, environment,
|
||||
model, calibration, metrics, expiry, and evidence level are bound under one
|
||||
signature (ADR-315/ADR-302). An unsigned or partially-bound certificate is
|
||||
signature (ADR-318/ADR-305). An unsigned or partially-bound certificate is
|
||||
not a certificate.
|
||||
3. **One canonical semantics downstream.** Every surface (MQTT, REST, WebSocket,
|
||||
RuField, Matter, agents, UI) consumes the same Observation → Inference →
|
||||
GovernedEvent types (ADR-303). No transport- or UI-specific reinterpretation.
|
||||
GovernedEvent types (ADR-306). No transport- or UI-specific reinterpretation.
|
||||
4. **Benchmarks expose worst-domain performance and confidence intervals.**
|
||||
Pooled accuracy is never sufficient for promotion (ADR-314).
|
||||
Pooled accuracy is never sufficient for promotion (ADR-317).
|
||||
|
||||
### Certificate conditionality (the staleness guard)
|
||||
|
||||
The central architectural risk is **certificate staleness**: a room can remain
|
||||
syntactically calibrated while its RF distribution has drifted enough to
|
||||
invalidate the certificate. Therefore a capability certificate is **conditional
|
||||
on a continuously evaluated domain signature** (ADR-299), not a one-time stamp.
|
||||
on a continuously evaluated domain signature** (ADR-302), not a one-time stamp.
|
||||
Crossing the OOD threshold automatically degrades state and triggers
|
||||
recalibration rather than silently continuing:
|
||||
|
||||
@@ -72,8 +72,8 @@ recalibration rather than silently continuing:
|
||||
VALID → DEGRADED → UNKNOWN (auto-degrade on domain drift; triggers recalibration)
|
||||
```
|
||||
|
||||
This binds ADR-298 (calibration), ADR-299 (OOD), ADR-315 (certificate), and
|
||||
ADR-318 (policy): a degraded/unknown domain must invalidate the affected
|
||||
This binds ADR-301 (calibration), ADR-302 (OOD), ADR-318 (certificate), and
|
||||
ADR-321 (policy): a degraded/unknown domain must invalidate the affected
|
||||
capability *before* a false confident inference reaches an actuator.
|
||||
|
||||
### Commercial framing — three primitives, not one product
|
||||
@@ -82,7 +82,7 @@ capability *before* a false confident inference reaches an actuator.
|
||||
- **RuView Certify** — establishes what a deployment can legitimately claim
|
||||
(calibration + evidence + capability certificate + policy).
|
||||
- **RuView Trust / Fleet** — keeps that claim valid across hardware, firmware,
|
||||
models, and environmental drift (ADR-313).
|
||||
models, and environmental drift (ADR-316).
|
||||
|
||||
Certify and Trust are the parts that are hard to commoditize; presence
|
||||
detection alone is not.
|
||||
@@ -90,48 +90,48 @@ detection alone is not.
|
||||
## Decision
|
||||
|
||||
Adopt a **21-primitive phased program**. Each primitive gets a child ADR
|
||||
(ADR-298…ADR-318) that owns its detailed decision, status, and validation.
|
||||
(ADR-301…ADR-321) that owns its detailed decision, status, and validation.
|
||||
This ADR owns the framing, the dependency order, and the phase assignment.
|
||||
|
||||
### Primitive → ADR map
|
||||
|
||||
| # | Primitive | ADR | Phase |
|
||||
|---|---|---|---|
|
||||
| 1 | Automatic domain calibration | ADR-298 | 1 |
|
||||
| 2 | Out-of-distribution detection | ADR-299 | 1 |
|
||||
| 3 | Ground-truth synchronization | ADR-300 | 2 |
|
||||
| 4 | Evidence engine | ADR-301 | 1 |
|
||||
| 5 | Authenticated sensor identity | ADR-302 | 1 |
|
||||
| 6 | Canonical spatial ontology | ADR-303 | 1 |
|
||||
| 7 | Persistent identity & tracking | ADR-304 | 2 |
|
||||
| 8 | Sensor placement optimizer | ADR-305 | 3 |
|
||||
| 9 | Active sensing | ADR-306 | 3 |
|
||||
| 10 | 802.11bf-native architecture | ADR-307 | 2 |
|
||||
| 11 | Real sensor fusion | ADR-308 | 2 |
|
||||
| 12 | Long-term spatial memory | ADR-309 | 3 |
|
||||
| 13 | Counterfactual inference | ADR-310 | 3 |
|
||||
| 14 | Information-gain scheduler | ADR-311 | 3 |
|
||||
| 15 | Digital RF twin | ADR-312 | 3 |
|
||||
| 16 | Fleet control plane | ADR-313 | 2 |
|
||||
| 17 | Real benchmark service (multi-domain scorecard) | ADR-314 | 1 |
|
||||
| 18 | Capability certificates | ADR-315 | 1 |
|
||||
| 19 | Witness chain | ADR-316 | 1 |
|
||||
| 20 | RuView sensor HAL | ADR-317 | 2 |
|
||||
| 21 | Decision policy — action authorization | ADR-318 | 1 |
|
||||
| 1 | Automatic domain calibration | ADR-301 | 1 |
|
||||
| 2 | Out-of-distribution detection | ADR-302 | 1 |
|
||||
| 3 | Ground-truth synchronization | ADR-303 | 2 |
|
||||
| 4 | Evidence engine | ADR-304 | 1 |
|
||||
| 5 | Authenticated sensor identity | ADR-305 | 1 |
|
||||
| 6 | Canonical spatial ontology | ADR-306 | 1 |
|
||||
| 7 | Persistent identity & tracking | ADR-307 | 2 |
|
||||
| 8 | Sensor placement optimizer | ADR-308 | 3 |
|
||||
| 9 | Active sensing | ADR-309 | 3 |
|
||||
| 10 | 802.11bf-native architecture | ADR-310 | 2 |
|
||||
| 11 | Real sensor fusion | ADR-311 | 2 |
|
||||
| 12 | Long-term spatial memory | ADR-312 | 3 |
|
||||
| 13 | Counterfactual inference | ADR-313 | 3 |
|
||||
| 14 | Information-gain scheduler | ADR-314 | 3 |
|
||||
| 15 | Digital RF twin | ADR-315 | 3 |
|
||||
| 16 | Fleet control plane | ADR-316 | 2 |
|
||||
| 17 | Real benchmark service (multi-domain scorecard) | ADR-317 | 1 |
|
||||
| 18 | Capability certificates | ADR-318 | 1 |
|
||||
| 19 | Witness chain | ADR-319 | 1 |
|
||||
| 20 | RuView sensor HAL | ADR-320 | 2 |
|
||||
| 21 | Decision policy — action authorization | ADR-321 | 1 |
|
||||
|
||||
### Dependency order (why phase, not score, drives sequencing)
|
||||
|
||||
```
|
||||
ADR-303 spatial ontology ──┐
|
||||
ADR-302 auth identity ─────┼──► ADR-298 calibration cert ──► ADR-299 OOD gating
|
||||
ADR-306 spatial ontology ──┐
|
||||
ADR-305 auth identity ─────┼──► ADR-301 calibration cert ──► ADR-302 OOD gating
|
||||
│ │ │
|
||||
└──► ADR-316 witness chain │ (VALID→DEGRADED→UNKNOWN)
|
||||
└──► ADR-319 witness chain │ (VALID→DEGRADED→UNKNOWN)
|
||||
│ ▼
|
||||
ADR-301 evidence engine ──► ADR-315 capability certificate
|
||||
ADR-304 evidence engine ──► ADR-318 capability certificate
|
||||
│ │ (conditional on domain signature)
|
||||
│ ▼
|
||||
│ ADR-318 decision policy ──► governed action
|
||||
└──► ADR-314 benchmark scorecard (per-PR gate)
|
||||
│ ADR-321 decision policy ──► governed action
|
||||
└──► ADR-317 benchmark scorecard (per-PR gate)
|
||||
```
|
||||
|
||||
- **Phase 1 (the certificate spine, built now):** foundational roots 303, 302,
|
||||
@@ -152,20 +152,20 @@ validation plan) and are not implemented by the phase-1 swarm.
|
||||
### Acceptance test A — onboarding (from the strategic assessment)
|
||||
|
||||
> Connect a new sensor type in an unseen room. Within 30 minutes RuView should
|
||||
> identify the hardware (HAL, ADR-317), calibrate the environment (ADR-298),
|
||||
> quantify whether it can reliably sense the requested phenomenon (ADR-299),
|
||||
> generate a signed capability certificate (ADR-315), expose governed spatial
|
||||
> events (ADR-303), and return UNKNOWN whenever evidence falls outside that
|
||||
> certificate (ADR-299).
|
||||
> identify the hardware (HAL, ADR-320), calibrate the environment (ADR-301),
|
||||
> quantify whether it can reliably sense the requested phenomenon (ADR-302),
|
||||
> generate a signed capability certificate (ADR-318), expose governed spatial
|
||||
> events (ADR-306), and return UNKNOWN whenever evidence falls outside that
|
||||
> certificate (ADR-302).
|
||||
|
||||
### Acceptance test B — drift invalidation (the staleness guard)
|
||||
|
||||
> Deliberately change the room after certification — move furniture, change the
|
||||
> AP channel, or substitute hardware. RuView should detect distribution drift
|
||||
> (ADR-299), invalidate the affected capability (ADR-315) **before** a false
|
||||
> confident inference reaches an actuator (ADR-318 denies with the specific
|
||||
> (ADR-302), invalidate the affected capability (ADR-318) **before** a false
|
||||
> confident inference reaches an actuator (ADR-321 denies with the specific
|
||||
> failed condition), emit UNKNOWN, preserve the complete witness chain
|
||||
> (ADR-316), and explain exactly which certificate condition failed.
|
||||
> (ADR-319), and explain exactly which certificate condition failed.
|
||||
|
||||
Test B is the load-bearing one: it proves the substrate fails safe, not just
|
||||
that it perceives well. Phase 1 makes every clause except HAL testable in
|
||||
@@ -176,7 +176,7 @@ closes the "identify the hardware" clause.
|
||||
|
||||
- One coherent substrate replaces overlapping ad-hoc schemas; every surface
|
||||
(MQTT, REST, WebSocket, RuField, Matter, agents) eventually consumes the
|
||||
ADR-303 ontology and the ADR-315 certificate.
|
||||
ADR-306 ontology and the ADR-318 certificate.
|
||||
- Headline applications (pose/vitals/pointcloud models) are explicitly **not**
|
||||
the investment focus during this program, per the strategic direction.
|
||||
- Later ADRs may be revised as the spine lands; that is expected for a phased
|
||||
@@ -186,4 +186,4 @@ closes the "identify the hardware" clause.
|
||||
|
||||
- Each child ADR defines its own tests. The program-level exit is the
|
||||
acceptance test above, run end-to-end once phase 1 lands, and encoded as an
|
||||
AetherArena scenario (ADR-314).
|
||||
AetherArena scenario (ADR-317).
|
||||
+18
-18
@@ -1,19 +1,19 @@
|
||||
# ADR-298: Automatic domain calibration — signed, versioned, invalidatable room fingerprint
|
||||
# ADR-301: Automatic domain calibration — signed, versioned, invalidatable room fingerprint
|
||||
|
||||
- **Status**: Accepted — initial implementation planned (ADR-297 phase 1)
|
||||
- **Status**: Accepted — initial implementation planned (ADR-300 phase 1)
|
||||
- **Date**: 2026-08-11
|
||||
- **Deciders**: ruv
|
||||
- **Tags**: calibration, provenance, drift, evidence, honesty, substrate
|
||||
|
||||
## Context
|
||||
|
||||
This ADR is primitive 1 of the perception-substrate program (ADR-297) and the
|
||||
first brick of that program's "certificate spine" (ADR-297 phase 1). It depends
|
||||
on the canonical spatial ontology (ADR-303) to name *which space* it
|
||||
characterizes, on authenticated sensor identity (ADR-302) to bind a fingerprint
|
||||
to *which signed device* produced it, and on the witness chain (ADR-316) to
|
||||
This ADR is primitive 1 of the perception-substrate program (ADR-300) and the
|
||||
first brick of that program's "certificate spine" (ADR-300 phase 1). It depends
|
||||
on the canonical spatial ontology (ADR-306) to name *which space* it
|
||||
characterizes, on authenticated sensor identity (ADR-305) to bind a fingerprint
|
||||
to *which signed device* produced it, and on the witness chain (ADR-319) to
|
||||
anchor the resulting artifact. Its output is consumed directly by
|
||||
out-of-distribution detection (ADR-299).
|
||||
out-of-distribution detection (ADR-302).
|
||||
|
||||
WiFi sensing is only reproducible inside the environment it was tuned for.
|
||||
Multipath, furniture geometry, transceiver placement, and AP channel all shape
|
||||
@@ -43,7 +43,7 @@ than a soft `STALE` flag buried in the runtime.
|
||||
|
||||
1. **Keep calibration internal to the runtime (status quo).** Rejected: the
|
||||
room characterization exists only as in-process state; it cannot be signed,
|
||||
shipped, compared across time, or presented as evidence to ADR-299/ADR-315.
|
||||
shipped, compared across time, or presented as evidence to ADR-302/ADR-318.
|
||||
2. **Build a new calibration crate.** Rejected: `wifi-densepose-calibration`
|
||||
already owns enrollment, the specialist bank, geometry embedding, and the
|
||||
baseline-drift concept. A parallel crate would fork the room model.
|
||||
@@ -68,7 +68,7 @@ phase and a `certificate` artifact module. The target UX is:
|
||||
the room's CSI distribution (subcarrier amplitude/phase moments, multipath
|
||||
structure, occupancy-band energy), plus the `geometry_embedding` when a
|
||||
geometry record is present. The fingerprint is the distance-comparable object
|
||||
ADR-299 measures against; its schema is versioned.
|
||||
ADR-302 measures against; its schema is versioned.
|
||||
|
||||
### 2. Empty / occupied baseline pair
|
||||
|
||||
@@ -82,17 +82,17 @@ phase and a `certificate` artifact module. The target UX is:
|
||||
### 3. `CalibrationCertificate` artifact
|
||||
|
||||
- A serializable `CalibrationCertificate` binding: the `RoomFingerprint`; a
|
||||
space identifier from the ADR-303 ontology; the signing sensor identity from
|
||||
ADR-302; `captured_at_unix_s`; a monotonic `version`; a schema version; the
|
||||
space identifier from the ADR-306 ontology; the signing sensor identity from
|
||||
ADR-305; `captured_at_unix_s`; a monotonic `version`; a schema version; the
|
||||
calibration `tier`; and an `EvidenceLevel` (L0–L5, ADR-282) — an automatic
|
||||
characterization on real captured CSI is at most L1/L2 and is labelled as
|
||||
such, never L3+.
|
||||
- The certificate is **signed** using RuField provenance/signature types
|
||||
(ADR-260/262/277/279) and anchored in the witness chain (ADR-316). Signature
|
||||
(ADR-260/262/277/279) and anchored in the witness chain (ADR-319). Signature
|
||||
and witness anchoring are mandatory: an unsigned certificate is not a valid
|
||||
certificate.
|
||||
- Two certificates for the same space are **comparable**: `distance(a, b)`
|
||||
returns a bounded fingerprint distance, which is the primitive ADR-299 uses
|
||||
returns a bounded fingerprint distance, which is the primitive ADR-302 uses
|
||||
to gate KNOWN → DEGRADED → UNKNOWN.
|
||||
|
||||
### 4. Invalidation and continuous drift compensation
|
||||
@@ -101,7 +101,7 @@ phase and a `certificate` artifact module. The target UX is:
|
||||
fingerprint distance against live traffic exceeds a threshold, when the AP
|
||||
channel or transceiver geometry changes, when the signing device identity
|
||||
changes, or on age expiry. Invalidation is an explicit state transition that
|
||||
emits a witness record (ADR-316), not a silent `STALE` flag.
|
||||
emits a witness record (ADR-319), not a silent `STALE` flag.
|
||||
- Continuous drift compensation runs as a bounded online update of the
|
||||
fingerprint within a **compatibility envelope**: small drift is absorbed and
|
||||
logged; drift beyond the envelope invalidates the certificate and forces
|
||||
@@ -121,14 +121,14 @@ phase and a `certificate` artifact module. The target UX is:
|
||||
## Consequences
|
||||
|
||||
- Room characterization becomes a portable, signed, versioned artifact that
|
||||
ADR-299 (OOD), ADR-315 (capability certificates), and ADR-314 (benchmark)
|
||||
ADR-302 (OOD), ADR-318 (capability certificates), and ADR-317 (benchmark)
|
||||
can consume without re-deriving room state.
|
||||
- The automatic observe-only path lowers deployment friction (no mandatory
|
||||
enrollment ritual) but yields a weaker evidence level than guided enrollment;
|
||||
the certificate states which path produced it so consumers can weight it.
|
||||
- Explicit invalidation means RuView will sometimes refuse to sense a changed
|
||||
room until re-characterization. That refusal is the intended honest behavior,
|
||||
surfaced by ADR-299, not a regression.
|
||||
surfaced by ADR-302, not a regression.
|
||||
- The existing enrollment/bank/runtime path is preserved; `autocal` is an
|
||||
additional entry point that produces the same `RoomFingerprint` object the
|
||||
guided path can also emit.
|
||||
@@ -142,7 +142,7 @@ phase and a `certificate` artifact module. The target UX is:
|
||||
transitions (channel change, geometry change, age, drift-envelope breach)
|
||||
each emit the expected witness record; constructor rejects synthetic→measured
|
||||
mislabeling.
|
||||
- Cross-ADR: an ADR-299 test consumes a certificate and asserts the gating
|
||||
- Cross-ADR: an ADR-302 test consumes a certificate and asserts the gating
|
||||
state transitions on a drifted fingerprint.
|
||||
- Real-silicon characterization (ESP32 capture over a real 10-minute window)
|
||||
remains a follow-up requiring hardware evidence per CLAUDE.md; a successful
|
||||
+17
-17
@@ -1,33 +1,33 @@
|
||||
# ADR-299: Out-of-distribution detection — KNOWN / DEGRADED / UNKNOWN gating
|
||||
# ADR-302: Out-of-distribution detection — KNOWN / DEGRADED / UNKNOWN gating
|
||||
|
||||
- **Status**: Accepted — initial implementation planned (ADR-297 phase 1)
|
||||
- **Status**: Accepted — initial implementation planned (ADR-300 phase 1)
|
||||
- **Date**: 2026-08-11
|
||||
- **Deciders**: ruv
|
||||
- **Tags**: ood, calibration, uncertainty, quality, evidence, honesty, substrate
|
||||
|
||||
## Context
|
||||
|
||||
This ADR is primitive 2 of the perception-substrate program (ADR-297) and part
|
||||
This ADR is primitive 2 of the perception-substrate program (ADR-300) and part
|
||||
of the phase-1 certificate spine. It sits directly downstream of automatic
|
||||
domain calibration (ADR-298): the `CalibrationCertificate` and its
|
||||
domain calibration (ADR-301): the `CalibrationCertificate` and its
|
||||
`RoomFingerprint` are the reference distribution this ADR measures against. It
|
||||
reuses fusion-layer quality scoring (ADR-137) as one of its inputs and feeds
|
||||
its state into the evidence engine (ADR-301) and capability certificates
|
||||
(ADR-315).
|
||||
its state into the evidence engine (ADR-304) and capability certificates
|
||||
(ADR-318).
|
||||
|
||||
The central unsolved problem of WiFi sensing is cross-domain generalization: a
|
||||
model trained (or calibrated) in one room degrades unpredictably in another, or
|
||||
in the same room after furniture moves, the AP changes channel, or the radio
|
||||
hardware is swapped. A model that keeps returning confident classifications
|
||||
under these conditions is the single most misleading failure mode in the field,
|
||||
and it is the failure the strategic assessment (ADR-297) named explicitly.
|
||||
and it is the failure the strategic assessment (ADR-300) named explicitly.
|
||||
Confidence alone is insufficient: a softmax head is perfectly capable of being
|
||||
confidently wrong on out-of-distribution input. RuView must be able to say
|
||||
"I do not recognize this situation" instead of guessing.
|
||||
|
||||
Today RuView has partial signals but no unified gate:
|
||||
|
||||
- ADR-298 produces a comparable `RoomFingerprint` and a `distance()` metric.
|
||||
- ADR-301 produces a comparable `RoomFingerprint` and a `distance()` metric.
|
||||
- ADR-137 `QualityScore` carries fusion coherence, evidence references, and
|
||||
contradiction flags per fused frame.
|
||||
- Model heads emit confidence/uncertainty, but nothing combines domain
|
||||
@@ -44,7 +44,7 @@ Today RuView has partial signals but no unified gate:
|
||||
duplicates logic, cannot be audited uniformly, and does not compose with the
|
||||
calibration certificate or the evidence engine.
|
||||
3. **A shared OOD gate that every inference passes through, fusing four signals
|
||||
against the ADR-298 certificate.** Chosen.
|
||||
against the ADR-301 certificate.** Chosen.
|
||||
|
||||
## Decision
|
||||
|
||||
@@ -56,14 +56,14 @@ path) — that attaches a `DomainState` to **every** inference.
|
||||
|
||||
Each inference carries four measured quantities:
|
||||
|
||||
1. **Domain distance** — fingerprint distance (ADR-298 `distance()`) between
|
||||
1. **Domain distance** — fingerprint distance (ADR-301 `distance()`) between
|
||||
live traffic and the active `CalibrationCertificate`, split into the
|
||||
empty-baseline and occupied-baseline components so geometry drift and
|
||||
occupancy-statistics drift are distinguishable.
|
||||
2. **Signal quality** — reuse the ADR-137 quality scoring signals (fusion
|
||||
coherence, contradiction flags) plus per-frame SNR/validity.
|
||||
3. **Calibration compatibility** — is a valid, non-invalidated certificate
|
||||
present for this space (ADR-303) and this signed device (ADR-302)? An
|
||||
present for this space (ADR-306) and this signed device (ADR-305)? An
|
||||
expired, invalidated, or device-mismatched certificate is itself a
|
||||
compatibility failure.
|
||||
4. **Uncertainty** — the model head's own predictive uncertainty.
|
||||
@@ -90,11 +90,11 @@ cause are all reported — never a bare label.
|
||||
|
||||
### 3. Certificate-bound, honest by construction
|
||||
|
||||
- The gate is meaningless without a certificate: with no valid ADR-298
|
||||
- The gate is meaningless without a certificate: with no valid ADR-301
|
||||
certificate for the current space/device, the default state is UNKNOWN, not
|
||||
KNOWN. Absence of evidence is treated as absence of capability.
|
||||
- The `DomainState` and its inputs are emitted to the evidence engine
|
||||
(ADR-301) as part of every inference record, and are an input to the ADR-315
|
||||
(ADR-304) as part of every inference record, and are an input to the ADR-318
|
||||
capability certificate (a model's capability is bounded by the domain it can
|
||||
hold KNOWN in).
|
||||
- No accuracy number is claimed here; the ADR delivers the gating machinery.
|
||||
@@ -111,10 +111,10 @@ cause are all reported — never a bare label.
|
||||
is the product working: it is the difference between honest RF perception and
|
||||
confidently-wrong output.
|
||||
- Every task head that opts into the substrate must route through the gate;
|
||||
heads that bypass it cannot claim a KNOWN state or earn an ADR-315
|
||||
heads that bypass it cannot claim a KNOWN state or earn an ADR-318
|
||||
certificate.
|
||||
- The gate couples model serving to the presence of a live calibration
|
||||
certificate, making ADR-298 a hard dependency of confident inference — the
|
||||
certificate, making ADR-301 a hard dependency of confident inference — the
|
||||
intended coupling.
|
||||
|
||||
## Validation
|
||||
@@ -125,9 +125,9 @@ cause are all reported — never a bare label.
|
||||
device mismatch, and invalidated/absent certificate each → UNKNOWN;
|
||||
hysteresis prevents flapping under injected noise; missing certificate
|
||||
defaults to UNKNOWN.
|
||||
- Cross-ADR: consumes an ADR-298 certificate and asserts a drifted fingerprint
|
||||
- Cross-ADR: consumes an ADR-301 certificate and asserts a drifted fingerprint
|
||||
drives the expected transition; asserts the `DomainState` is present on every
|
||||
emitted inference record consumed by ADR-301.
|
||||
emitted inference record consumed by ADR-304.
|
||||
- No confident classification is emitted in the UNKNOWN state in any test —
|
||||
enforced as an assertion, not a convention.
|
||||
- Real-silicon OOD behavior (moving furniture / changing AP channel on a live
|
||||
+19
-19
@@ -1,21 +1,21 @@
|
||||
# ADR-300: Ground-truth synchronization — reference sensors as a formal validation plane
|
||||
# ADR-303: Ground-truth synchronization — reference sensors as a formal validation plane
|
||||
|
||||
- **Status**: Accepted — initial implementation (ADR-297 phase 2)
|
||||
- **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-297), authored
|
||||
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-301) and the real benchmark service
|
||||
(ADR-314). It generalizes the vitals ground-truth rig (ADR-290) from a single
|
||||
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-290 built exactly
|
||||
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
|
||||
@@ -39,7 +39,7 @@ inputs.
|
||||
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-290 ad hoc each time).** Rejected:
|
||||
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
|
||||
@@ -52,38 +52,38 @@ compares RF inference against independent observation and never feeds it.
|
||||
|
||||
### 1. Modality-agnostic reference ingest
|
||||
|
||||
- A `ReferenceObservation` generalizing ADR-290's `ReferenceSeries`: a
|
||||
- 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-290's ingest
|
||||
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-290's time alignment (bounded-lag normalized cross-correlation
|
||||
- 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-303 spatial ontology so an RF localization/pose result and a
|
||||
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-290's MAE/RMSE/bias/Bland–Altman/within-tolerance;
|
||||
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-288).
|
||||
(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-290.
|
||||
as in ADR-293.
|
||||
|
||||
### 4. Evidence and isolation guarantees
|
||||
|
||||
@@ -92,8 +92,8 @@ compares RF inference against independent observation and never feeds it.
|
||||
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-290 rule). Reports feed the ADR-301 evidence
|
||||
engine and are the substrate ADR-314 scores against.
|
||||
coverage, and a reproducer (ADR-293 rule). Reports feed the ADR-304 evidence
|
||||
engine and are the substrate ADR-317 scores against.
|
||||
|
||||
## Consequences
|
||||
|
||||
@@ -106,7 +106,7 @@ compares RF inference against independent observation and never feeds it.
|
||||
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-298/299/301/303) lands and the benchmark (ADR-314)
|
||||
phase-1 spine (ADR-301/299/301/303) lands and the benchmark (ADR-317)
|
||||
exercises it.
|
||||
|
||||
## Validation
|
||||
@@ -117,8 +117,8 @@ compares RF inference against independent observation and never feeds it.
|
||||
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-314 benchmark scenario consumes `GroundTruth` reports as
|
||||
its scored reference; ADR-301 ingests the agreement reports as evidence
|
||||
- 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
|
||||
@@ -1,21 +1,21 @@
|
||||
# ADR-301: Evidence engine — MLflow for physical sensing
|
||||
# ADR-304: Evidence engine — MLflow for physical sensing
|
||||
|
||||
- **Status**: Accepted — initial implementation planned (ADR-297 phase 1)
|
||||
- **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-297) and a
|
||||
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-299) and the calibration age from the
|
||||
calibration certificate (ADR-298), it is the store that capability certificates
|
||||
(ADR-315) are minted from, and it is the accuracy source the real benchmark
|
||||
service (ADR-314) reads. In phase 2 it ingests agreement reports from the
|
||||
ground-truth plane (ADR-300).
|
||||
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-297) judged this primitive **more commercially
|
||||
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.
|
||||
@@ -32,7 +32,7 @@ that unifies them per deployment context:
|
||||
witness-anchored ledger of scored results, the structural template here.
|
||||
- `frame::EvidenceLevel` L0–L5 (ADR-282) — the mandatory evidence tag every
|
||||
record carries.
|
||||
- ADR-299 `DomainState`, ADR-137 `QualityScore`, ADR-298 certificate version
|
||||
- ADR-302 `DomainState`, ADR-137 `QualityScore`, ADR-301 certificate version
|
||||
and age — the per-inference signals to accumulate.
|
||||
|
||||
## Options considered
|
||||
@@ -54,24 +54,24 @@ accuracy ledger that every model automatically writes to.
|
||||
|
||||
### 1. The evidence record
|
||||
|
||||
- An `EvidenceRecord` keyed by context — space id (ADR-303), signed device id
|
||||
(ADR-302), and subject id where consented and available — carrying: model
|
||||
version; calibration certificate version and **age** (ADR-298); the ADR-299
|
||||
- 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-300), the agreement result (accuracy, false-positive rate). Each record
|
||||
(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-316),
|
||||
(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-300 reference backs it — otherwise the record is
|
||||
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-298), the fraction of inferences in
|
||||
(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
|
||||
@@ -81,11 +81,11 @@ accuracy ledger that every model automatically writes to.
|
||||
|
||||
- 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-288/
|
||||
ADR-290 constructor discipline. A benchmark or certificate reading the ledger
|
||||
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-315)
|
||||
accounting. Empty contexts report "no evidence," which downstream (ADR-318)
|
||||
must treat as no capability.
|
||||
|
||||
## Consequences
|
||||
@@ -93,8 +93,8 @@ accuracy ledger that every model automatically writes to.
|
||||
- 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-315 capability certificates become derivable (a certificate is a signed
|
||||
attestation over a slice of the ledger) and ADR-314 gains a real accuracy
|
||||
- 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
|
||||
@@ -109,9 +109,9 @@ accuracy ledger that every model automatically writes to.
|
||||
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-299 `DomainState` and (phase 2) ADR-300 agreement
|
||||
reports; an ADR-315 test mints a certificate from a ledger slice and an
|
||||
ADR-314 test reads accuracy from the ledger.
|
||||
- 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-300 references) is the maturity milestone and requires hardware evidence
|
||||
ADR-303 references) is the maturity milestone and requires hardware evidence
|
||||
per CLAUDE.md; a synthetic ledger is L0 by construction.
|
||||
+25
-25
@@ -1,24 +1,24 @@
|
||||
# ADR-302: Authenticated sensor identity — RF chain of custody
|
||||
# ADR-305: Authenticated sensor identity — RF chain of custody
|
||||
|
||||
- **Status**: Accepted — initial implementation planned (ADR-297 phase 1)
|
||||
- **Status**: Accepted — initial implementation planned (ADR-300 phase 1)
|
||||
- **Date**: 2026-08-11
|
||||
- **Deciders**: ruv
|
||||
- **Tags**: security, identity, provenance, sensor-ingest, attestation, phase-1
|
||||
|
||||
## Context
|
||||
|
||||
This ADR is a child of **ADR-297** (perception substrate program) and owns
|
||||
primitive #5, *authenticated sensor identity*. In the ADR-297 dependency DAG it
|
||||
is a spine root that, together with **ADR-303** (canonical spatial ontology),
|
||||
feeds **ADR-298** (calibration certificate) and **ADR-316** (witness chain).
|
||||
This ADR is a child of **ADR-300** (perception substrate program) and owns
|
||||
primitive #5, *authenticated sensor identity*. In the ADR-300 dependency DAG it
|
||||
is a spine root that, together with **ADR-306** (canonical spatial ontology),
|
||||
feeds **ADR-301** (calibration certificate) and **ADR-319** (witness chain).
|
||||
|
||||
RuView's inference outputs are only as trustworthy as the measurements that
|
||||
produced them, yet today a measurement's origin is essentially assertional. The
|
||||
UDP data plane accepts frames from any reachable host: **ADR-293** shipped step
|
||||
UDP data plane accepts frames from any reachable host: **ADR-296** shipped step
|
||||
one — a loopback-default bind (`--udp-bind`) and an optional source
|
||||
IP/CIDR allowlist — and explicitly deferred to a follow-up ADR "per-device
|
||||
provisioned keys, MAC/AEAD, device identifiers, monotonic sequence numbers,
|
||||
freshness window, and replay rejection." **This ADR is that step two.** ADR-293
|
||||
freshness window, and replay rejection." **This ADR is that step two.** ADR-296
|
||||
correctly documented that an IP allowlist does not stop LAN spoofing; a
|
||||
cryptographic device identity is what closes that gap.
|
||||
|
||||
@@ -30,7 +30,7 @@ Foundations already exist in the tree and must be reused rather than rebuilt:
|
||||
- `wifi-densepose-bfld` provides `CapabilityAttestation` and
|
||||
`PrivacyAttestationProof` (BFLD attestation, ADR-141) — the device-side
|
||||
attestation surface.
|
||||
- **ADR-292** defines the source-provenance state machine and freshness
|
||||
- **ADR-295** defines the source-provenance state machine and freshness
|
||||
(`SpatialStateFreshness`); a monotonic sequence and freshness window slot
|
||||
into that machine rather than duplicating it.
|
||||
|
||||
@@ -42,7 +42,7 @@ hardware, and FFI boundary; default to least authority").
|
||||
|
||||
## Options considered
|
||||
|
||||
1. **Stop at ADR-293 (bind + IP allowlist).** Rejected: ADR-293 itself names
|
||||
1. **Stop at ADR-296 (bind + IP allowlist).** Rejected: ADR-296 itself names
|
||||
this insufficient on a trusted LAN; any on-subnet host can still spoof a
|
||||
device.
|
||||
2. **TLS/DTLS transport authentication only.** Rejected: authenticates the
|
||||
@@ -67,7 +67,7 @@ server, built from existing RuField/BFLD types.
|
||||
`firmware/esp32-csi-node` key-handling notes.
|
||||
- The enrollment record binds `DeviceId → public key → capabilities`
|
||||
(via `CapabilityAttestation`, ADR-141), so a device can only assert
|
||||
measurements for phenomena it is attested to sense. This is what **ADR-315**
|
||||
measurements for phenomena it is attested to sense. This is what **ADR-318**
|
||||
(capability certificate) later consumes.
|
||||
|
||||
### 2. Signed measurement envelope
|
||||
@@ -78,7 +78,7 @@ server, built from existing RuField/BFLD types.
|
||||
detectable without embedding the whole payload twice.
|
||||
- Verification uses `Signature`/`SignatureVerifyError` from
|
||||
`wifi-densepose-rufield`. A frame that fails signature verification is
|
||||
dropped and counted, exactly as ADR-293 drops disallowed sources — an `Err`
|
||||
dropped and counted, exactly as ADR-296 drops disallowed sources — an `Err`
|
||||
at the boundary, never a warning that proceeds.
|
||||
|
||||
### 3. Monotonic sequence + freshness (replay defense)
|
||||
@@ -87,44 +87,44 @@ server, built from existing RuField/BFLD types.
|
||||
server tracks the last accepted sequence per `DeviceId`; a non-increasing
|
||||
sequence is rejected as a replay.
|
||||
- A freshness window bounds `timestamp` against the server clock skew budget;
|
||||
stale frames are rejected. This reuses ADR-292's `SpatialStateFreshness`
|
||||
stale frames are rejected. This reuses ADR-295's `SpatialStateFreshness`
|
||||
rather than inventing a parallel notion of staleness, and composes with
|
||||
ADR-294's stale-node handling.
|
||||
ADR-297's stale-node handling.
|
||||
|
||||
### 4. Chain of custody into the event
|
||||
|
||||
- On successful verification the frame's `FrameProvenance` records the verified
|
||||
`DeviceId`, sequence, and timestamp. Calibration (ADR-298) and inference
|
||||
annotate their transforms, and the emitted spatial event (ADR-303 ontology)
|
||||
`DeviceId`, sequence, and timestamp. Calibration (ADR-301) and inference
|
||||
annotate their transforms, and the emitted spatial event (ADR-306 ontology)
|
||||
carries a signed provenance lineage. `ProvenanceClass` still enforces the
|
||||
synthetic/measured invariant from ADR-282/ADR-279 (invariant 6): a measured
|
||||
chain of custody can never be aliased to synthetic and vice-versa.
|
||||
- This end-to-end signed lineage is the substrate the **ADR-316** witness chain
|
||||
serializes and the **ADR-315** capability certificate points at as evidence.
|
||||
- This end-to-end signed lineage is the substrate the **ADR-319** witness chain
|
||||
serializes and the **ADR-318** capability certificate points at as evidence.
|
||||
|
||||
### Compatibility
|
||||
|
||||
- The envelope is **opt-in per deployment** and negotiated at enrollment. An
|
||||
un-enrolled single-node desktop deployment keeps working unauthenticated
|
||||
behind ADR-293's loopback default; a routable, multi-node, or fleet
|
||||
deployment (ADR-313) requires enrolled identities. The startup security log
|
||||
(ADR-293) is extended to state whether frame authentication is active.
|
||||
behind ADR-296's loopback default; a routable, multi-node, or fleet
|
||||
deployment (ADR-316) requires enrolled identities. The startup security log
|
||||
(ADR-296) is extended to state whether frame authentication is active.
|
||||
|
||||
## Consequences
|
||||
|
||||
- LAN spoofing and replay — the residual risks ADR-293 named plainly — are
|
||||
- LAN spoofing and replay — the residual risks ADR-296 named plainly — are
|
||||
closed for enrolled deployments. The measurement, not merely the channel, is
|
||||
authenticated, so the guarantee survives store-and-forward into the witness
|
||||
chain.
|
||||
- Enrollment/key-management is now an operational responsibility (provisioning,
|
||||
rotation, revocation). This is documented as a deployment step; key rotation
|
||||
and revocation lists are specified here but their fleet distribution is
|
||||
owned by ADR-313.
|
||||
owned by ADR-316.
|
||||
- Signature verification adds per-frame CPU cost at ingest; bounded and
|
||||
measured in validation below. It is a deliberate cost for a verifiable chain
|
||||
of custody.
|
||||
- A schema addition to the frame contract; un-enrolled deployments are
|
||||
unaffected, and the migration accessor mirrors ADR-294's approach.
|
||||
unaffected, and the migration accessor mirrors ADR-297's approach.
|
||||
- **No spoof-resistance claim is MEASURED until validated on real silicon**
|
||||
(CLAUDE.md hardware rule): a passing unit/integration suite demonstrates the
|
||||
logic, not the fielded device path.
|
||||
@@ -137,7 +137,7 @@ server, built from existing RuField/BFLD types.
|
||||
window timestamp rejected; un-enrolled `DeviceId` rejected; measured/synthetic
|
||||
provenance aliasing rejected (ADR-279 invariant 6).
|
||||
- Integration test: a captured/synthesized multi-frame stream produces a
|
||||
verifiable `device → … → signed event` lineage that ADR-316 can serialize and
|
||||
verifiable `device → … → signed event` lineage that ADR-319 can serialize and
|
||||
re-verify offline.
|
||||
- Benchmark (`cargo bench`): per-frame verification cost, to bound ingest
|
||||
overhead.
|
||||
+20
-20
@@ -1,28 +1,28 @@
|
||||
# ADR-303: Canonical spatial ontology — one Site→…→Event model for every surface
|
||||
# ADR-306: Canonical spatial ontology — one Site→…→Event model for every surface
|
||||
|
||||
- **Status**: Accepted — initial implementation planned (ADR-297 phase 1)
|
||||
- **Status**: Accepted — initial implementation planned (ADR-300 phase 1)
|
||||
- **Date**: 2026-08-11
|
||||
- **Deciders**: ruv
|
||||
- **Tags**: ontology, worldgraph, schema, mqtt, matter, rufield, phase-1
|
||||
|
||||
## Context
|
||||
|
||||
This ADR is a child of **ADR-297** and owns primitive #6, *canonical spatial
|
||||
ontology*. In the ADR-297 DAG it is a spine root alongside **ADR-302**
|
||||
This ADR is a child of **ADR-300** and owns primitive #6, *canonical spatial
|
||||
ontology*. In the ADR-300 DAG it is a spine root alongside **ADR-305**
|
||||
(authenticated identity) and feeds every downstream primitive that must speak
|
||||
about *where* and *what*: **ADR-298** (calibration), **ADR-304** (tracking,
|
||||
consumes `Track`/`Person`), **ADR-316** (witness chain), and every external
|
||||
surface named in the ADR-297 consequences (MQTT, REST, WebSocket, RuField,
|
||||
about *where* and *what*: **ADR-301** (calibration), **ADR-307** (tracking,
|
||||
consumes `Track`/`Person`), **ADR-319** (witness chain), and every external
|
||||
surface named in the ADR-300 consequences (MQTT, REST, WebSocket, RuField,
|
||||
Matter, agents).
|
||||
|
||||
RuView currently expresses "where something is" in several overlapping,
|
||||
per-surface schemas: the MQTT/Home-Assistant mapper has its own node/room
|
||||
shapes (**ADR-294** just introduced `NodeInference`/`RoomInference` to
|
||||
shapes (**ADR-297** just introduced `NodeInference`/`RoomInference` to
|
||||
disambiguate node vs. room state); the `worldgraph` crate models a spatial
|
||||
graph; RuField carries `SemanticProvenance`; Matter/HomeKit has its own area
|
||||
model. The same physical fact — "a person is in the kitchen" — is re-encoded
|
||||
differently on each surface, and the review called for "one canonical
|
||||
`NodeInference`/`RoomInference` contract" (ADR-294 consequences). Without a
|
||||
`NodeInference`/`RoomInference` contract" (ADR-297 consequences). Without a
|
||||
single semantic model, every new surface multiplies the translation matrix and
|
||||
each translation is a place where provenance and evidence level (ADR-282) can
|
||||
be silently dropped.
|
||||
@@ -75,14 +75,14 @@ Site ▸ Building ▸ Floor ▸ Space ▸ Zone
|
||||
elements. Containment reuses the existing `LocatedIn`/`AdjacentTo` edge
|
||||
vocabulary; a new `PartOf` edge expresses the pure hierarchy
|
||||
(Zone `PartOf` Space `PartOf` Floor …).
|
||||
- `Sensor` is the entity **ADR-302** authenticates (`DeviceId` as its stable
|
||||
identity) and **ADR-317** (HAL, phase 2) describes the hardware of. `Person`,
|
||||
- `Sensor` is the entity **ADR-305** authenticates (`DeviceId` as its stable
|
||||
identity) and **ADR-320** (HAL, phase 2) describes the hardware of. `Person`,
|
||||
`Object`, `Observation`, `Track`, and `Event` are first-class nodes.
|
||||
`Observes`/`LocatedIn` edges already carry quality and dwell timestamps.
|
||||
- `Track` and `Person` are defined **here** as the ontology contract that
|
||||
**ADR-304** (persistent tracking) produces and updates. `Observation` is what
|
||||
an authenticated frame (ADR-302) becomes after calibration (ADR-298), and
|
||||
`Event` is the governed output that ADR-315 certifies and ADR-316 witnesses.
|
||||
**ADR-307** (persistent tracking) produces and updates. `Observation` is what
|
||||
an authenticated frame (ADR-305) becomes after calibration (ADR-301), and
|
||||
`Event` is the governed output that ADR-318 certifies and ADR-319 witnesses.
|
||||
|
||||
### 2. Canonical serialization
|
||||
|
||||
@@ -90,8 +90,8 @@ Site ▸ Building ▸ Floor ▸ Space ▸ Zone
|
||||
one wire/at-rest representation. Every surface — MQTT/Home-Assistant, REST,
|
||||
WebSocket, RuField observations, Matter/HomeKit, agent queries — is a
|
||||
**projection** of this model, not an independent schema. `NodeInference` and
|
||||
`RoomInference` (ADR-294) become projections of `Sensor→Observes` and the
|
||||
`Space`-level fused inference respectively, so ADR-294's node/room separation
|
||||
`RoomInference` (ADR-297) become projections of `Sensor→Observes` and the
|
||||
`Space`-level fused inference respectively, so ADR-297's node/room separation
|
||||
is preserved by construction rather than re-encoded per surface.
|
||||
- Every node and edge carries `SemanticProvenance` and exactly one
|
||||
`EvidenceLevel` (L0–L5, ADR-282 policy): the evidence ladder travels *with*
|
||||
@@ -102,7 +102,7 @@ Site ▸ Building ▸ Floor ▸ Space ▸ Zone
|
||||
|
||||
- Each existing per-surface schema gets a documented, tested bidirectional
|
||||
mapping to/from the canonical model, plus a migration accessor for consumers
|
||||
reading the old shape (mirroring ADR-294's migration accessor). Surfaces are
|
||||
reading the old shape (mirroring ADR-297's migration accessor). Surfaces are
|
||||
cut over one at a time; a surface is "canonical" once its projection is the
|
||||
only encoder it uses. Until cutover, the mapping layer is authoritative and
|
||||
round-trip-tested so no fact is lost in translation.
|
||||
@@ -120,8 +120,8 @@ Site ▸ Building ▸ Floor ▸ Space ▸ Zone
|
||||
serialization and per-surface migration accessors. Single-node deployments
|
||||
keep working (one `Sensor`, one `Space`).
|
||||
- The ontology is a *representation*, not an inference engine: it says nothing
|
||||
about *how* a `Track` or `Event` is produced — that is owned by ADR-304,
|
||||
ADR-298, ADR-299, and the model layer. This ADR does not itself make any
|
||||
about *how* a `Track` or `Event` is produced — that is owned by ADR-307,
|
||||
ADR-301, ADR-302, and the model layer. This ADR does not itself make any
|
||||
accuracy claim to grade.
|
||||
- Extending `worldgraph` grows one crate's surface rather than forking a second
|
||||
world model; the geo/worldmodel sub-crates continue to build on the same node
|
||||
@@ -135,7 +135,7 @@ Site ▸ Building ▸ Floor ▸ Space ▸ Zone
|
||||
and edge type; every node/edge carries exactly one `EvidenceLevel`.
|
||||
- Migration tests: each per-surface schema maps to the canonical model and back
|
||||
with no loss of provenance or evidence level; `NodeInference`/`RoomInference`
|
||||
(ADR-294) project and re-project identically.
|
||||
(ADR-297) project and re-project identically.
|
||||
- Contract test: a single canonical `Event` renders correctly through the MQTT,
|
||||
REST, and WebSocket projections from one source of truth.
|
||||
- No accuracy numbers are claimed; this ADR delivers the shared representation
|
||||
+15
-15
@@ -1,18 +1,18 @@
|
||||
# ADR-304: Persistent identity & tracking — privacy-preserving probabilistic tracks
|
||||
# ADR-307: Persistent identity & tracking — privacy-preserving probabilistic tracks
|
||||
|
||||
- **Status**: Accepted — initial implementation (ADR-297 phase 2)
|
||||
- **Status**: Accepted — initial implementation (ADR-300 phase 2)
|
||||
- **Date**: 2026-08-11
|
||||
- **Deciders**: ruv
|
||||
- **Tags**: tracking, identity, privacy, fusion, worldgraph, phase-2
|
||||
|
||||
## Context
|
||||
|
||||
This ADR is a child of **ADR-297** and owns primitive #7, *persistent identity
|
||||
& tracking*. In the ADR-297 DAG it is a phase-2 primitive sitting on the
|
||||
phase-1 spine: it **consumes the ADR-303 ontology** (producing and updating the
|
||||
`Track` and `Person` node types defined there), it relies on **ADR-302**
|
||||
This ADR is a child of **ADR-300** and owns primitive #7, *persistent identity
|
||||
& tracking*. In the ADR-300 DAG it is a phase-2 primitive sitting on the
|
||||
phase-1 spine: it **consumes the ADR-306 ontology** (producing and updating the
|
||||
`Track` and `Person` node types defined there), it relies on **ADR-305**
|
||||
authenticated identity so that the observations it associates have a verified
|
||||
origin, and its outputs are governed `Event`s that ADR-315/ADR-316 can certify
|
||||
origin, and its outputs are governed `Event`s that ADR-318/ADR-319 can certify
|
||||
and witness.
|
||||
|
||||
The product need is to reason about *persistent entities* — "person_7 entered
|
||||
@@ -58,11 +58,11 @@ that survives track loss and hand-off between spaces, and (c) an explicit
|
||||
## Decision
|
||||
|
||||
Extend `wifi-densepose-mat/tracking` into a **cross-domain persistent track
|
||||
layer** that produces ADR-303 `Track`/`Person` nodes.
|
||||
layer** that produces ADR-306 `Track`/`Person` nodes.
|
||||
|
||||
### 1. Persistent probabilistic entity
|
||||
|
||||
- A persistent entity is a pseudonymous `Person` node (ADR-303) with a stable
|
||||
- A persistent entity is a pseudonymous `Person` node (ADR-306) with a stable
|
||||
synthetic id (e.g. `person_7`) backed by the existing `TrackId`/UUID. It
|
||||
aggregates one or more `SurvivorTracker` tracks over time and space and holds
|
||||
a **probabilistic** continuity belief — association is never asserted as
|
||||
@@ -76,14 +76,14 @@ layer** that produces ADR-303 `Track`/`Person` nodes.
|
||||
|
||||
### 2. Cross-radio / cross-modality / cross-room continuity
|
||||
|
||||
- Association operates over the ADR-303 ontology graph: `Observes` edges from
|
||||
- Association operates over the ADR-306 ontology graph: `Observes` edges from
|
||||
multiple `Sensor`s and `AdjacentTo`/`Doorway` topology constrain plausible
|
||||
hand-offs (a person can only move between adjacent spaces). The existing
|
||||
`mahalanobis_distance_sq` gating extends to a fused observation across
|
||||
modalities rather than a single node's detections.
|
||||
- Fusion here is track-level association; the underlying multi-modality fusion
|
||||
(radar/mmWave per ADR-063, multistatic per ADR-029, and real sensor fusion
|
||||
per ADR-308) supplies the observations. This ADR depends on those for the raw
|
||||
per ADR-311) supplies the observations. This ADR depends on those for the raw
|
||||
cross-modality evidence and does not re-implement sensor fusion.
|
||||
|
||||
### 3. Privacy boundary (by construction)
|
||||
@@ -113,10 +113,10 @@ layer** that produces ADR-303 `Track`/`Person` nodes.
|
||||
wrong civil-identity join is not.
|
||||
- Extends an existing tracker rather than forking one; single-room single-radio
|
||||
deployments keep the current behavior (one entity = one track).
|
||||
- Cross-modality quality depends on ADR-308/ADR-063/ADR-029 landing; until then
|
||||
- Cross-modality quality depends on ADR-311/ADR-063/ADR-029 landing; until then
|
||||
continuity is WiFi-primary and its limits are stated, not hidden.
|
||||
- Being phase 2, this ADR is design intent; it will be revised as the ADR-303
|
||||
ontology and ADR-302 identity spine finalize.
|
||||
- Being phase 2, this ADR is design intent; it will be revised as the ADR-306
|
||||
ontology and ADR-305 identity spine finalize.
|
||||
|
||||
## Validation
|
||||
|
||||
@@ -129,7 +129,7 @@ layer** that produces ADR-303 `Track`/`Person` nodes.
|
||||
with per-hand-off confidence, and a deliberately ambiguous crossing produces
|
||||
two pseudonyms rather than a false join.
|
||||
- Evidence discipline: any tracking-continuity accuracy is reported only with
|
||||
the ADR-288 leakage-free protocol and an evidence tag; no number is asserted
|
||||
the ADR-291 leakage-free protocol and an evidence tag; no number is asserted
|
||||
here.
|
||||
- Privacy review: confirm no persisted long-term biometric template and no
|
||||
civil-identity join path, as an explicit checklist item before any pilot.
|
||||
+27
-27
@@ -1,19 +1,19 @@
|
||||
# ADR-305: Sensor placement optimizer — floorplan + inventory → recommended positions
|
||||
# ADR-308: Sensor placement optimizer — floorplan + inventory → recommended positions
|
||||
|
||||
- **Status**: Accepted — initial implementation (ADR-297 phase 3)
|
||||
- **Status**: Accepted — initial implementation (ADR-300 phase 3)
|
||||
- **Date**: 2026-08-11
|
||||
- **Deciders**: ruv
|
||||
- **Tags**: placement, planning, rf-twin, coverage, worldgraph, phase-3
|
||||
|
||||
## Context
|
||||
|
||||
This ADR is a child of **ADR-297** and owns primitive #8, *sensor placement
|
||||
optimizer*. In the ADR-297 DAG it is a phase-3, research-forward primitive that
|
||||
sits on top of the fused world state and is tightly coupled to **ADR-312**
|
||||
This ADR is a child of **ADR-300** and owns primitive #8, *sensor placement
|
||||
optimizer*. In the ADR-300 DAG it is a phase-3, research-forward primitive that
|
||||
sits on top of the fused world state and is tightly coupled to **ADR-315**
|
||||
(digital RF twin): the twin provides the propagation simulation this optimizer
|
||||
plans against. It reads the **ADR-303** canonical ontology for the physical
|
||||
scene and, after install, compares its predictions against ADR-299 observability
|
||||
and the ADR-315 capability certificate.
|
||||
plans against. It reads the **ADR-306** canonical ontology for the physical
|
||||
scene and, after install, compares its predictions against ADR-302 observability
|
||||
and the ADR-318 capability certificate.
|
||||
|
||||
The problem it solves is the single most common cause of a bad RuView
|
||||
deployment: sensors placed by guesswork. Whether a room can be reliably sensed
|
||||
@@ -30,11 +30,11 @@ Relevant existing assets to build on rather than duplicate:
|
||||
- The `worldgraph` crate models the physical scene the optimizer plans over:
|
||||
`Room`/`Space` with `bounds_enu`, `Wall { rf_attenuation_db }` (drywall ≈ 3
|
||||
dB, brick ≈ 12 dB), `Doorway`, and `Zone` — enough geometry and coarse RF
|
||||
attenuation to seed a coverage model, plus `Sensor` nodes (ADR-303) for
|
||||
attenuation to seed a coverage model, plus `Sensor` nodes (ADR-306) for
|
||||
candidate positions.
|
||||
- **ADR-312** (RF twin, phase 3) is the propagation/multipath simulator; this
|
||||
- **ADR-315** (RF twin, phase 3) is the propagation/multipath simulator; this
|
||||
optimizer is a *consumer* of the twin, not a second simulator.
|
||||
- **ADR-299** (OOD/observability) and **ADR-315** (capability certificate)
|
||||
- **ADR-302** (OOD/observability) and **ADR-318** (capability certificate)
|
||||
define what "reliably sense the requested phenomenon" means, so the optimizer
|
||||
can optimize against the same observability metric the runtime later gates on.
|
||||
- **ADR-029** (multistatic) and **ADR-063** (mmWave fusion) inform which link
|
||||
@@ -49,36 +49,36 @@ Relevant existing assets to build on rather than duplicate:
|
||||
2. **Full electromagnetic solver per site.** Rejected for the default path:
|
||||
too heavy for an installer workflow and overkill relative to the coarse
|
||||
`rf_attenuation_db` scene RuView actually has; reserved as an optional
|
||||
high-fidelity backend inside ADR-312.
|
||||
3. **A coverage optimizer that consumes the ADR-312 RF twin over the ADR-303
|
||||
high-fidelity backend inside ADR-315.
|
||||
3. **A coverage optimizer that consumes the ADR-315 RF twin over the ADR-306
|
||||
scene, then validates predicted vs. measured observability after install.**
|
||||
Chosen.
|
||||
|
||||
## Decision
|
||||
|
||||
Define a **placement optimizer** that takes a floor plan (ADR-303 scene) and a
|
||||
Define a **placement optimizer** that takes a floor plan (ADR-306 scene) and a
|
||||
hardware inventory and recommends sensor positions, then closes the loop after
|
||||
install.
|
||||
|
||||
### 1. Inputs
|
||||
|
||||
- The ADR-303 canonical scene: `Space`/`Zone` bounds, `Wall` segments with
|
||||
- The ADR-306 canonical scene: `Space`/`Zone` bounds, `Wall` segments with
|
||||
`rf_attenuation_db`, `Doorway` topology, and any already-placed `Sensor`
|
||||
nodes.
|
||||
- A hardware inventory: the count and type of available radios (ESP32-S3/C6
|
||||
nodes, mmWave, adapters) with their capability envelopes (what each can
|
||||
sense, per ADR-315 / ADR-317 HAL descriptors).
|
||||
sense, per ADR-318 / ADR-320 HAL descriptors).
|
||||
- A sensing objective: which phenomenon must be observable in which
|
||||
`Space`/`Zone` (presence, vitals, pose), expressed against the ADR-299
|
||||
`Space`/`Zone` (presence, vitals, pose), expressed against the ADR-302
|
||||
observability metric.
|
||||
|
||||
### 2. Prediction
|
||||
|
||||
- For a candidate placement, query the **ADR-312 RF twin** for simulated RF
|
||||
- For a candidate placement, query the **ADR-315 RF twin** for simulated RF
|
||||
coverage: path loss through `Wall` attenuation, **Fresnel-zone clearance**
|
||||
between link endpoints, and coarse **multipath** structure. From that derive
|
||||
an **expected observability** and an **uncertainty** for each objective in
|
||||
each space — reusing the same observability definition ADR-299 gates on so the
|
||||
each space — reusing the same observability definition ADR-302 gates on so the
|
||||
plan and the runtime speak one language.
|
||||
- Search over candidate positions (the inventory bounds the count; the scene
|
||||
bounds the geometry) to recommend the placement that maximizes objective
|
||||
@@ -88,10 +88,10 @@ install.
|
||||
### 3. Post-install loop
|
||||
|
||||
- After install, compare **predicted vs. measured** observability using the
|
||||
ADR-299 runtime observability signal from the freshly enrolled (ADR-302),
|
||||
calibrated (ADR-298) sensors. Where measurement disagrees with prediction,
|
||||
ADR-302 runtime observability signal from the freshly enrolled (ADR-305),
|
||||
calibrated (ADR-301) sensors. Where measurement disagrees with prediction,
|
||||
recommend adjustments (move, re-aim, add a node) and feed the residual back
|
||||
to improve the ADR-312 twin's scene parameters (e.g. a wall's effective
|
||||
to improve the ADR-315 twin's scene parameters (e.g. a wall's effective
|
||||
attenuation).
|
||||
|
||||
### Evidence discipline
|
||||
@@ -108,15 +108,15 @@ install.
|
||||
- Installers get a principled, floorplan-specific placement plan and, crucially,
|
||||
a post-install check that says whether reality matched the plan — a
|
||||
differentiating capability over guess-and-check deployment.
|
||||
- Quality is bounded by the fidelity of the ADR-312 RF twin and the coarseness
|
||||
- Quality is bounded by the fidelity of the ADR-315 RF twin and the coarseness
|
||||
of the `worldgraph` scene (2D walls, coarse attenuation). The optimizer
|
||||
reports uncertainty rather than overstating a coarse model; higher fidelity
|
||||
is an ADR-312 concern.
|
||||
- Hard dependency on ADR-312 (twin), ADR-299 (observability metric), and
|
||||
ADR-303 (scene); this ADR does not build a simulator or an observability
|
||||
is an ADR-315 concern.
|
||||
- Hard dependency on ADR-315 (twin), ADR-302 (observability metric), and
|
||||
ADR-306 (scene); this ADR does not build a simulator or an observability
|
||||
metric of its own.
|
||||
- Being phase 3, this is design intent sitting on the fused world state; it is
|
||||
expected to be revised as ADR-312 and the phase-1 spine land.
|
||||
expected to be revised as ADR-315 and the phase-1 spine land.
|
||||
- No claim that recommended placement *guarantees* sensing — it maximizes
|
||||
modelled observability subject to inventory and geometry, with explicit
|
||||
uncertainty.
|
||||
@@ -1,22 +1,22 @@
|
||||
# ADR-306: Active sensing — closed-loop RF experiment control
|
||||
# ADR-309: Active sensing — closed-loop RF experiment control
|
||||
|
||||
- **Status**: Accepted — initial implementation (ADR-297 phase 3)
|
||||
- **Status**: Accepted — initial implementation (ADR-300 phase 3)
|
||||
- **Date**: 2026-08-11
|
||||
- **Deciders**: ruv
|
||||
- **Tags**: active-sensing, control-plane, closed-loop, information-gain, actuation, phase-3
|
||||
|
||||
## Context
|
||||
|
||||
This ADR is a child of **ADR-297** and owns primitive #9, *active sensing*. In
|
||||
the ADR-297 phasing it is a phase-3 primitive that sits on top of the fused
|
||||
world state produced by **ADR-308** (real sensor fusion) and is driven by the
|
||||
information budget of **ADR-311** (information-gain scheduler). It is authored
|
||||
This ADR is a child of **ADR-300** and owns primitive #9, *active sensing*. In
|
||||
the ADR-300 phasing it is a phase-3 primitive that sits on top of the fused
|
||||
world state produced by **ADR-311** (real sensor fusion) and is driven by the
|
||||
information budget of **ADR-314** (information-gain scheduler). It is authored
|
||||
as **Proposed**: design intent and validation plan, not a phase-1 build.
|
||||
|
||||
The default posture of every current RuView path is **passive**: RF traffic
|
||||
happens for its own reasons (a device transmits, a beacon fires), RuView
|
||||
observes whatever CSI/CIR arrives, and the pipeline extracts what it can from
|
||||
that incidental signal. The strategic assessment behind ADR-297 named the next
|
||||
that incidental signal. The strategic assessment behind ADR-300 named the next
|
||||
step: move from *RF-happens → observe* to **RuView-controls-RF → observe the
|
||||
response → optimize the next measurement**. That turns sensing into a
|
||||
closed-loop experiment — the system chooses what to measure to resolve the
|
||||
@@ -37,8 +37,8 @@ Substantial control-plane scaffolding already exists and must be
|
||||
- ADR-280 explicitly recorded that **information-gain *estimation* is not
|
||||
implemented** — "the planner uses staleness heuristics, not mutual
|
||||
information; RIS drivers, actual multi-AP coherence measurement, and OTFS
|
||||
waveform control are hardware-dependent roadmap items." ADR-306 is the ADR
|
||||
that closes exactly those gaps, in coordination with ADR-311.
|
||||
waveform control are hardware-dependent roadmap items." ADR-309 is the ADR
|
||||
that closes exactly those gaps, in coordination with ADR-314.
|
||||
|
||||
The missing piece is not the actuation surface — ADR-280 built that and made it
|
||||
fail closed — but the **loop**: a controller that reads the current fused-state
|
||||
@@ -73,11 +73,11 @@ observed response.
|
||||
|
||||
Define an `ExperimentControl` vocabulary over the configuration axes RuView can
|
||||
influence on hardware that exposes them (each axis is optional and
|
||||
capability-gated by ADR-317's HAL, so an ESP32-only deployment simply has an
|
||||
capability-gated by ADR-320's HAL, so an ESP32-only deployment simply has an
|
||||
empty controllable set and degrades to the passive planner):
|
||||
|
||||
- **Channel / band** and **bandwidth** (which spectrum to probe; reuses the
|
||||
ADR-289 wideband subcarrier-agnostic metadata).
|
||||
ADR-292 wideband subcarrier-agnostic metadata).
|
||||
- **Packet timing / cadence** (when to solicit a sounding, and at what rate).
|
||||
- **Antenna / chain selection** (which subset of a distributed aperture to
|
||||
activate — bounded by the ADR-280 `CoherentSensorGroup` compatibility proof).
|
||||
@@ -85,28 +85,28 @@ empty controllable set and degrades to the passive planner):
|
||||
governed exactly as ADR-280 §6 requires, via `request_actuation` and an
|
||||
`ActuationReceipt`).
|
||||
- **802.11bf measurement parameters** (TB/non-TB, reporting config) once
|
||||
ADR-307 exposes standardized sensing as a native measurement type.
|
||||
ADR-310 exposes standardized sensing as a native measurement type.
|
||||
|
||||
### 2. The loop
|
||||
|
||||
```
|
||||
fused-state uncertainty (ADR-308)
|
||||
fused-state uncertainty (ADR-311)
|
||||
│
|
||||
▼
|
||||
info-gain ranking of ExperimentControl options (ADR-311)
|
||||
info-gain ranking of ExperimentControl options (ADR-314)
|
||||
│ select argmax E[ΔI] / (cost, energy, privacy ceiling)
|
||||
▼
|
||||
governed request (ADR-280 admit_task / request_actuation, fail-closed)
|
||||
│
|
||||
▼
|
||||
observe response → update belief (ADR-308) → repeat
|
||||
observe response → update belief (ADR-311) → repeat
|
||||
```
|
||||
|
||||
The controller never bypasses the ADR-280 admission and actuation gates: every
|
||||
solicited measurement is a `SensingTask`/`SensingAction`, every environment
|
||||
change is an `ActuationReceipt`, and every step composes with the ADR-277
|
||||
policy engine. Information gain is what **ADR-311** supplies (the mutual-
|
||||
information estimate ADR-280 deferred); ADR-306 owns the *control loop* that
|
||||
policy engine. Information gain is what **ADR-314** supplies (the mutual-
|
||||
information estimate ADR-280 deferred); ADR-309 owns the *control loop* that
|
||||
consumes that estimate and drives the hardware.
|
||||
|
||||
### 3. Governance and honesty boundary
|
||||
@@ -127,13 +127,13 @@ consumes that estimate and drives the hardware.
|
||||
- Sensing becomes an experiment: RuView spends its RF/energy/privacy budget on
|
||||
the measurements that most reduce current uncertainty, instead of processing
|
||||
whatever incidental traffic arrives.
|
||||
- The loop is only as strong as its two dependencies: ADR-308 must expose a
|
||||
usable uncertainty surface and ADR-311 must produce trustworthy information-
|
||||
- The loop is only as strong as its two dependencies: ADR-311 must expose a
|
||||
usable uncertainty surface and ADR-314 must produce trustworthy information-
|
||||
gain estimates. Where either is absent, the controller degrades to the
|
||||
ADR-280 staleness planner rather than acting on a fabricated gain estimate.
|
||||
- Controllability is hardware-bounded. On commodity ESP32 sensors the
|
||||
controllable set may be limited to cadence; the full loop (bandwidth, antenna,
|
||||
beam) needs NICs/RIS that expose those axes, surfaced through ADR-317.
|
||||
beam) needs NICs/RIS that expose those axes, surfaced through ADR-320.
|
||||
- This ADR adds a controller; it does not re-open ADR-280's raw-export or
|
||||
actuation-governance decisions, which remain authoritative and fail-closed.
|
||||
|
||||
+20
-20
@@ -1,16 +1,16 @@
|
||||
# ADR-307: 802.11bf-native architecture — standardized WLAN sensing as native measurement types
|
||||
# ADR-310: 802.11bf-native architecture — standardized WLAN sensing as native measurement types
|
||||
|
||||
- **Status**: Proposed (ADR-297 phase 2)
|
||||
- **Status**: Proposed (ADR-300 phase 2)
|
||||
- **Date**: 2026-08-11
|
||||
- **Deciders**: ruv
|
||||
- **Tags**: 80211bf, wlan-sensing, standards, measurement-types, hal, phase-2
|
||||
|
||||
## Context
|
||||
|
||||
This ADR is a child of **ADR-297** and owns primitive #10, *802.11bf-native
|
||||
architecture*. In the ADR-297 phasing it is a phase-2 integration primitive: it
|
||||
sits on the phase-1 spine (authenticated identity ADR-302, spatial ontology
|
||||
ADR-303, evidence engine ADR-301) and **feeds ADR-317** (the RuView sensor HAL),
|
||||
This ADR is a child of **ADR-300** and owns primitive #10, *802.11bf-native
|
||||
architecture*. In the ADR-300 phasing it is a phase-2 integration primitive: it
|
||||
sits on the phase-1 spine (authenticated identity ADR-305, spatial ontology
|
||||
ADR-306, evidence engine ADR-304) and **feeds ADR-320** (the RuView sensor HAL),
|
||||
which is the clause of the acceptance test that "identifies the hardware." It is
|
||||
authored as **Proposed**.
|
||||
|
||||
@@ -44,7 +44,7 @@ the standardized procedure surface as forward-compatible types (ADR-152/153):
|
||||
The module's own honesty note is authoritative and carried forward here: it is
|
||||
**not a certified 802.11bf implementation**, and **no commodity silicon — ESP32
|
||||
included — implements the standard yet**; the OTA frame binding lands when a
|
||||
chipset exposes it. Wideband ingest plumbing is already in place too: **ADR-289**
|
||||
chipset exposes it. Wideband ingest plumbing is already in place too: **ADR-292**
|
||||
(FeitCSI/AX210) carries native subcarrier dimensionality end-to-end and records
|
||||
the native→pipeline mapping, and noted that "truncated CIR is a natural
|
||||
extension of the same plumbing."
|
||||
@@ -53,7 +53,7 @@ What is missing is architectural, not protocol scaffolding: normalized CSI is
|
||||
still treated as *the* WiFi input. The standardized sensing measurements
|
||||
(TB/non-TB soundings, truncated CIR / PDP reports) are modeled as protocol
|
||||
messages but are **not yet first-class native measurement types** that flow
|
||||
through calibration (ADR-298), fusion (ADR-308), and the ontology (ADR-303) on
|
||||
through calibration (ADR-301), fusion (ADR-311), and the ontology (ADR-306) on
|
||||
equal footing with normalized CSI.
|
||||
|
||||
## Options considered
|
||||
@@ -64,7 +64,7 @@ equal footing with normalized CSI.
|
||||
the standard's native report semantics.
|
||||
2. **Fork a parallel "bf pipeline" alongside the CSI pipeline.** Rejected:
|
||||
duplicates calibration, fusion, ontology, and evidence plumbing, and re-opens
|
||||
the O(surfaces²) translation problem ADR-303 exists to close.
|
||||
the O(surfaces²) translation problem ADR-306 exists to close.
|
||||
3. **Promote standardized sensing measurements to native measurement types
|
||||
inside the existing pipeline**, with normalized CSI as one measurement type
|
||||
among several. Chosen.
|
||||
@@ -83,7 +83,7 @@ replacing — normalized CSI.
|
||||
with its `SpecProfile` and band. Normalized CSI remains one such type; the
|
||||
`OpportunisticCsiBridge` remains the path for silicon that only offers
|
||||
incidental CSI.
|
||||
- Truncated CIR/PDP reuse the **ADR-289** subcarrier-agnostic / native-
|
||||
- Truncated CIR/PDP reuse the **ADR-292** subcarrier-agnostic / native-
|
||||
dimensionality plumbing (truncated CIR is the stated natural extension); the
|
||||
native→pipeline mapping is recorded in frame metadata so downstream stages
|
||||
know the true range/spectral resolution of a bf report vs. an interpolated CSI
|
||||
@@ -91,8 +91,8 @@ replacing — normalized CSI.
|
||||
|
||||
### 2. Ontology and governance binding
|
||||
|
||||
- Each standardized measurement becomes an ADR-303 `Observation` node from an
|
||||
ADR-302-authenticated `Sensor`, carrying `SemanticProvenance` and exactly one
|
||||
- Each standardized measurement becomes an ADR-306 `Observation` node from an
|
||||
ADR-305-authenticated `Sensor`, carrying `SemanticProvenance` and exactly one
|
||||
`EvidenceLevel` (L0–L5, ADR-282). The `ieee80211bf` `ConsentMode` metadata —
|
||||
required on every setup — composes with the ADR-277 policy engine, so a
|
||||
standardized session is admitted under the same governance as any other
|
||||
@@ -100,12 +100,12 @@ replacing — normalized CSI.
|
||||
- SBP (sensing-by-proxy) sessions attribute the report to the proxying and the
|
||||
sensing entities distinctly, so provenance is not laundered through the proxy.
|
||||
|
||||
### 3. HAL feed (ADR-317)
|
||||
### 3. HAL feed (ADR-320)
|
||||
|
||||
- The capability set a device advertises — which `MeasurementType`s, bands,
|
||||
bandwidths, roles, and `SpecProfile` it supports — is exactly the descriptor
|
||||
**ADR-317** (HAL) needs to "identify the hardware." ADR-307 defines that
|
||||
capability descriptor as the projection of `SensingCapabilities`; ADR-317
|
||||
**ADR-320** (HAL) needs to "identify the hardware." ADR-310 defines that
|
||||
capability descriptor as the projection of `SensingCapabilities`; ADR-320
|
||||
consumes it. A device that implements no bf profile advertises only the
|
||||
opportunistic-CSI capability.
|
||||
|
||||
@@ -122,7 +122,7 @@ replacing — normalized CSI.
|
||||
802.11bf yet; this ADR wires the *types and flow*, tested in simulation. Any
|
||||
OTA/native-report accuracy claim requires real silicon evidence (a captured
|
||||
log) per CLAUDE.md, and any wideband number must be tagged with the capture
|
||||
hardware (ADR-289). No benchmark number is invented here.
|
||||
hardware (ADR-292). No benchmark number is invented here.
|
||||
- This ADR does not re-open ADR-152/153's decision to avoid OTA frame binding
|
||||
until silicon exists; it consumes that surface and adds the pipeline
|
||||
integration.
|
||||
@@ -133,14 +133,14 @@ replacing — normalized CSI.
|
||||
table, and transport tests continue to pass; new tests assert that a
|
||||
`SensingMeasurementReport` (TB and non-TB) and a truncated-CIR/PDP report
|
||||
round-trip through the pipeline as native `MeasurementType`s.
|
||||
- `cargo test -p wifi-densepose-mat` — truncated CIR ingest reuses the ADR-289
|
||||
- `cargo test -p wifi-densepose-mat` — truncated CIR ingest reuses the ADR-292
|
||||
subcarrier-agnostic path and records the native→pipeline mapping; dimension/
|
||||
version validation on standardized reports mirrors the FeitCSI parser gates.
|
||||
- Ontology/governance tests: each standardized measurement becomes an ADR-303
|
||||
`Observation` from an ADR-302-authenticated `Sensor` with one `EvidenceLevel`;
|
||||
- Ontology/governance tests: each standardized measurement becomes an ADR-306
|
||||
`Observation` from an ADR-305-authenticated `Sensor` with one `EvidenceLevel`;
|
||||
`ConsentMode` composes with ADR-277 admission; SBP attributes proxy vs. sensor
|
||||
provenance distinctly.
|
||||
- HAL contract test: the ADR-317 capability descriptor is derivable from
|
||||
- HAL contract test: the ADR-320 capability descriptor is derivable from
|
||||
`SensingCapabilities`; a bf-less device advertises only opportunistic CSI.
|
||||
- All measurement-type flows are simulation-tested (`SimTransport`, synthetic
|
||||
fixtures); OTA binding and any hardware accuracy claim remain out of scope
|
||||
@@ -1,17 +1,17 @@
|
||||
# ADR-308: Real sensor fusion — uncertainty-aware, multiple observations → one world state
|
||||
# ADR-311: Real sensor fusion — uncertainty-aware, multiple observations → one world state
|
||||
|
||||
- **Status**: Accepted — initial implementation (ADR-297 phase 2)
|
||||
- **Status**: Accepted — initial implementation (ADR-300 phase 2)
|
||||
- **Date**: 2026-08-11
|
||||
- **Deciders**: ruv
|
||||
- **Tags**: fusion, uncertainty, multimodal, world-state, ontology, phase-2
|
||||
|
||||
## Context
|
||||
|
||||
This ADR is a child of **ADR-297** and owns primitive #11, *real sensor fusion*.
|
||||
In the ADR-297 DAG it is a phase-2 integration primitive: it **consumes ADR-303**
|
||||
This ADR is a child of **ADR-300** and owns primitive #11, *real sensor fusion*.
|
||||
In the ADR-300 DAG it is a phase-2 integration primitive: it **consumes ADR-306**
|
||||
(canonical spatial ontology) and **produces the single fused world state** that
|
||||
the phase-3 primitives build on — **ADR-309** (long-term spatial memory),
|
||||
**ADR-310** (counterfactual inference), and **ADR-312** (digital RF twin). It is
|
||||
the phase-3 primitives build on — **ADR-312** (long-term spatial memory),
|
||||
**ADR-313** (counterfactual inference), and **ADR-315** (digital RF twin). It is
|
||||
authored as **Proposed**.
|
||||
|
||||
The defining invariant is not "support more modalities" but the *shape of the
|
||||
@@ -28,7 +28,7 @@ rebuilt**:
|
||||
- **ADR-063** (60 GHz mmWave ↔ WiFi CSI fusion, *Proposed*) established the
|
||||
first cross-modal fusion case: pairing noisy CSI-derived vitals with clinical-
|
||||
grade mmWave FMCW radar (Seeed MR60BHA2 over UART, with a **live hardware
|
||||
capture** logged on 2026-03-15). ADR-308 generalizes that pairwise case into
|
||||
capture** logged on 2026-03-15). ADR-311 generalizes that pairwise case into
|
||||
an N-modality, uncertainty-aware fusion.
|
||||
- **ADR-137** (fusion-engine quality scoring, *Accepted — partial*) already
|
||||
built the auditable-quality building block: it identified that the multistatic
|
||||
@@ -36,10 +36,10 @@ rebuilt**:
|
||||
`wifi-densepose-ruvector/src/viewpoint/fusion.rs`) discarded the evidence they
|
||||
used, and specified a single auditable record — "this fused output is
|
||||
trustworthy because X, Y, Z, but be aware of contradiction C" — with evidence
|
||||
references and contradiction flags. ADR-308 reuses that record as the
|
||||
references and contradiction flags. ADR-311 reuses that record as the
|
||||
provenance/quality carrier of the fused state.
|
||||
- **ADR-280** `CoherentSensorGroup` (fail-closed coherent fusion) and
|
||||
**ADR-303** `Observation`/`Track`/`Event` node types are the input and output
|
||||
**ADR-306** `Observation`/`Track`/`Event` node types are the input and output
|
||||
vocabulary respectively.
|
||||
|
||||
What is missing is the **uncertainty-aware combiner across heterogeneous
|
||||
@@ -68,20 +68,20 @@ probabilistic world state.
|
||||
|
||||
### 1. Inputs: authenticated, ontology-typed observations
|
||||
|
||||
- Inputs are ADR-303 `Observation` nodes from **ADR-302-authenticated** sensors.
|
||||
Supported modalities: WiFi (CSI / 802.11bf native reports via ADR-307), BLE,
|
||||
- Inputs are ADR-306 `Observation` nodes from **ADR-305-authenticated** sensors.
|
||||
Supported modalities: WiFi (CSI / 802.11bf native reports via ADR-310), BLE,
|
||||
UWB, mmWave (ADR-063), acoustic, IMU, lidar, and cameras. Cameras and any
|
||||
higher privacy-class modality enter fusion **only where the ADR-277 policy
|
||||
engine permits** — camera-free coverage is a RuView invariant (ADR-282), so
|
||||
cameras are an opt-in, policy-gated input, never assumed present.
|
||||
- Each observation carries its own uncertainty and exactly one `EvidenceLevel`
|
||||
(ADR-282). An observation flagged out-of-distribution by **ADR-299** is
|
||||
(ADR-282). An observation flagged out-of-distribution by **ADR-302** is
|
||||
down-weighted or excluded per its OOD verdict rather than silently averaged in.
|
||||
|
||||
### 2. Combiner: uncertainty-weighted, contradiction-aware
|
||||
|
||||
- Observations are combined by their uncertainty into one probabilistic
|
||||
`WorldState` over the ADR-303 entities (`Person`, `Object`, `Track`, and the
|
||||
`WorldState` over the ADR-306 entities (`Person`, `Object`, `Track`, and the
|
||||
per-`Space` inference). The combiner does **not** collapse disagreement: when
|
||||
modalities conflict beyond their stated uncertainty, the fused output carries
|
||||
ADR-137 **contradiction flags** and the evidence references that produced
|
||||
@@ -93,9 +93,9 @@ probabilistic world state.
|
||||
|
||||
### 3. Output: one world state, provenance preserved
|
||||
|
||||
- The output is a single `WorldState` written into the ADR-303 ontology, with
|
||||
- The output is a single `WorldState` written into the ADR-306 ontology, with
|
||||
every fused value retaining recoverable per-observation provenance and the
|
||||
ADR-137 quality record. This is the state ADR-309/310/312 consume; they read
|
||||
ADR-137 quality record. This is the state ADR-312/310/312 consume; they read
|
||||
one probabilistic world, not a modality stack.
|
||||
- The fused state carries an aggregate uncertainty and an evidence level derived
|
||||
from its inputs (never upgraded above the weakest contributing L-level for a
|
||||
@@ -108,7 +108,7 @@ probabilistic world state.
|
||||
re-implementing reconciliation per consumer.
|
||||
- Contradictions become first-class signal, not noise: ADR-137's record means a
|
||||
disagreement between mmWave and CSI is surfaced and auditable, which is also
|
||||
what lets ADR-299 and the evidence engine (ADR-301) reason about reliability.
|
||||
what lets ADR-302 and the evidence engine (ADR-304) reason about reliability.
|
||||
- Fusion is uncertainty-honest: an OOD or low-evidence observation is
|
||||
down-weighted, not averaged in as if trustworthy; a fused claim never presents
|
||||
a stronger evidence level than its weakest necessary input.
|
||||
@@ -127,9 +127,9 @@ probabilistic world state.
|
||||
the ADR-280 `CoherentSensorGroup` gate still fails closed under
|
||||
clock/phase/geometry violation.
|
||||
- Fusion invariant test: N modality observations over one scene resolve to a
|
||||
single `WorldState` node in the ADR-303 ontology (not N feeds), with
|
||||
single `WorldState` node in the ADR-306 ontology (not N feeds), with
|
||||
per-observation provenance recoverable and one aggregate evidence level.
|
||||
- Uncertainty tests: a high-uncertainty or ADR-299-flagged-OOD observation is
|
||||
- Uncertainty tests: a high-uncertainty or ADR-302-flagged-OOD observation is
|
||||
down-weighted/excluded; conflicting modalities produce a contradiction flag
|
||||
rather than a silently averaged value; the fused evidence level never exceeds
|
||||
the weakest necessary input.
|
||||
+14
-14
@@ -1,15 +1,15 @@
|
||||
# ADR-309: Long-term spatial memory — learn the normal physics of a location
|
||||
# ADR-312: Long-term spatial memory — learn the normal physics of a location
|
||||
|
||||
- **Status**: Accepted — initial implementation (ADR-297 phase 3)
|
||||
- **Status**: Accepted — initial implementation (ADR-300 phase 3)
|
||||
- **Date**: 2026-08-11
|
||||
- **Deciders**: ruv
|
||||
- **Tags**: spatial-memory, ruvector, anomaly-detection, temporal, world-state, phase-3
|
||||
|
||||
## Context
|
||||
|
||||
This ADR is a child of **ADR-297** and owns primitive #12, *long-term spatial
|
||||
memory*. In the ADR-297 phasing it is a phase-3 primitive that sits on the fused
|
||||
world state produced by **ADR-308** (real sensor fusion) and **ties to ADR-312**
|
||||
This ADR is a child of **ADR-300** and owns primitive #12, *long-term spatial
|
||||
memory*. In the ADR-300 phasing it is a phase-3 primitive that sits on the fused
|
||||
world state produced by **ADR-311** (real sensor fusion) and **ties to ADR-315**
|
||||
(digital RF twin): spatial memory is the *learned normal* that a twin can
|
||||
simulate against and that anomaly detection compares against. It is authored as
|
||||
**Proposed**.
|
||||
@@ -34,12 +34,12 @@ rebuilt**:
|
||||
(`event_log.rs`), coverage and estimator surfaces, and the `crv`/`mat`
|
||||
temporal sub-modules — so long-term spatial memory is a *consumer and
|
||||
organizer* of RuVector primitives, not a new store.
|
||||
- **ADR-303** supplies the entity vocabulary the memory is indexed by (`Space`,
|
||||
`Object`, `Sensor`, `Track`, `Event`); **ADR-308** supplies the fused,
|
||||
- **ADR-306** supplies the entity vocabulary the memory is indexed by (`Space`,
|
||||
`Object`, `Sensor`, `Track`, `Event`); **ADR-311** supplies the fused,
|
||||
uncertainty-carrying `WorldState` snapshots that memory accumulates over time.
|
||||
- **ADR-135** (empty-room baseline calibration) and **ADR-298** (automatic
|
||||
- **ADR-135** (empty-room baseline calibration) and **ADR-301** (automatic
|
||||
domain calibration) already establish a *calibration-time* baseline of a
|
||||
space; ADR-309 extends that from a one-shot baseline to a **continuously
|
||||
space; ADR-312 extends that from a one-shot baseline to a **continuously
|
||||
learned, time-of-day-aware** model of normal.
|
||||
|
||||
What is missing is the **temporal normality model**: a per-`Space` learned
|
||||
@@ -67,7 +67,7 @@ on the RuVector substrate and scores live fused state against it.
|
||||
|
||||
### 1. What "normal" is learned over
|
||||
|
||||
Per ADR-303 `Space` (and the entities within it), accumulate the ADR-308 fused
|
||||
Per ADR-306 `Space` (and the entities within it), accumulate the ADR-311 fused
|
||||
`WorldState` over time into a learned normality model covering:
|
||||
|
||||
- **Occupancy / activity periodicity** — the distribution of presence and
|
||||
@@ -92,7 +92,7 @@ never presented above the evidence of the observations it was learned from.
|
||||
compression). Long-horizon history is temporally compressed — recent detail
|
||||
retained, older history summarized — so memory cost is bounded rather than
|
||||
growing linearly forever.
|
||||
- The memory is *keyed by* the ADR-303 ontology, so "normal for this `Space` at
|
||||
- The memory is *keyed by* the ADR-306 ontology, so "normal for this `Space` at
|
||||
this hour" is a first-class query, and slow legitimate drift updates the
|
||||
baseline (with provenance) instead of accumulating as permanent anomaly.
|
||||
|
||||
@@ -100,11 +100,11 @@ never presented above the evidence of the observations it was learned from.
|
||||
|
||||
- A live fused `WorldState` is scored against the applicable learned baseline
|
||||
(matched by space and time context). A deviation beyond the baseline's
|
||||
uncertainty is surfaced as an ADR-303 `Event` — *without* a per-anomaly
|
||||
uncertainty is surfaced as an ADR-306 `Event` — *without* a per-anomaly
|
||||
detector — carrying the baseline it deviated from, the deviation magnitude,
|
||||
and its evidence level. Whether that event is actionable is a policy/consumer
|
||||
decision (ADR-277), not this layer's.
|
||||
- The learned normal is exactly what **ADR-312** (RF twin) can simulate against:
|
||||
- The learned normal is exactly what **ADR-315** (RF twin) can simulate against:
|
||||
the twin proposes an expected state, spatial memory supplies the learned
|
||||
actual-normal, and their divergence is a physically grounded anomaly signal.
|
||||
|
||||
@@ -142,5 +142,5 @@ never presented above the evidence of the observations it was learned from.
|
||||
rather than emitting a persistent anomaly; an abrupt change does emit one.
|
||||
- Evidence test: a learned baseline carries the evidence level of its source
|
||||
observations and is never presented above it; retention honors ADR-277.
|
||||
- Twin-linkage design check (with ADR-312): divergence between a twin-simulated
|
||||
- Twin-linkage design check (with ADR-315): divergence between a twin-simulated
|
||||
expected state and the learned normal is expressible as a deviation signal.
|
||||
+27
-27
@@ -1,17 +1,17 @@
|
||||
# ADR-310: Counterfactual inference — generative spatial reasoning
|
||||
# ADR-313: Counterfactual inference — generative spatial reasoning
|
||||
|
||||
- **Status**: Accepted — initial implementation (ADR-297 phase 3)
|
||||
- **Status**: Accepted — initial implementation (ADR-300 phase 3)
|
||||
- **Date**: 2026-08-11
|
||||
- **Deciders**: ruv
|
||||
- **Tags**: inference, generative, counterfactual, rf-twin, fusion, uncertainty, phase-3
|
||||
|
||||
## Context
|
||||
|
||||
This ADR is a child of **ADR-297** (perception substrate program) and owns
|
||||
primitive #13, *counterfactual inference*. In the ADR-297 DAG it is a phase-3,
|
||||
This ADR is a child of **ADR-300** (perception substrate program) and owns
|
||||
primitive #13, *counterfactual inference*. In the ADR-300 DAG it is a phase-3,
|
||||
research-forward primitive that sits on top of the fused world state: it
|
||||
**consumes ADR-308** (real sensor fusion) for the current fused estimate and
|
||||
**ADR-312** (digital RF twin) for the twin's expected measurement
|
||||
**consumes ADR-311** (real sensor fusion) for the current fused estimate and
|
||||
**ADR-315** (digital RF twin) for the twin's expected measurement
|
||||
distributions. It is design intent, authored as Proposed, and is expected to be
|
||||
revised as the phase-1 spine and the phase-2 fusion layer land.
|
||||
|
||||
@@ -26,7 +26,7 @@ best-effort label; it cannot say "the observation is better explained by
|
||||
absence."
|
||||
|
||||
The step this ADR proposes is toward a **generative spatial model**: given a
|
||||
hypothesized scene state (occupancy, count, coarse positions) and the ADR-312
|
||||
hypothesized scene state (occupancy, count, coarse positions) and the ADR-315
|
||||
twin's propagation model for the deployment, predict the *expected* measurement
|
||||
distribution, then score how well each hypothesis explains the observed
|
||||
measurement. The best-explaining hypothesis — including the *nobody-present*
|
||||
@@ -35,17 +35,17 @@ first-class uncertainty signal.
|
||||
|
||||
Relevant existing assets to build on rather than duplicate:
|
||||
|
||||
- **ADR-308** (fusion) already produces the fused world estimate and its
|
||||
- **ADR-311** (fusion) already produces the fused world estimate and its
|
||||
covariance; the counterfactual layer scores hypotheses *relative to* that
|
||||
estimate rather than re-fusing raw measurements.
|
||||
- **ADR-312** (RF twin) is the generative forward model — per-deployment
|
||||
- **ADR-315** (RF twin) is the generative forward model — per-deployment
|
||||
geometry, radio locations, and expected measurement distributions. This ADR
|
||||
is a *consumer* of the twin's forward simulator, not a second simulator.
|
||||
- **ADR-299** (OOD/observability) already owns the `UNKNOWN` verdict; the
|
||||
- **ADR-302** (OOD/observability) already owns the `UNKNOWN` verdict; the
|
||||
null-hypothesis ("nobody present better explains this than any occupancy
|
||||
hypothesis") and the "no hypothesis explains this" case route through ADR-299,
|
||||
hypothesis") and the "no hypothesis explains this" case route through ADR-302,
|
||||
not a parallel gate.
|
||||
- `frame::EvidenceLevel` L0–L5 (ADR-282) and the ADR-301 evidence engine
|
||||
- `frame::EvidenceLevel` L0–L5 (ADR-282) and the ADR-304 evidence engine
|
||||
account for the resulting confidence.
|
||||
|
||||
## Options considered
|
||||
@@ -54,13 +54,13 @@ Relevant existing assets to build on rather than duplicate:
|
||||
cannot compare "one person vs. two" as competing explanations, and gives a
|
||||
confident label even when no world state explains the data.
|
||||
2. **A second, independently trained generative network with its own forward
|
||||
model.** Rejected for the default path: duplicates the ADR-312 twin's
|
||||
model.** Rejected for the default path: duplicates the ADR-315 twin's
|
||||
propagation model, invites the two models to disagree, and multiplies the
|
||||
surface that must be validated. Reserved only if the twin's analytic forward
|
||||
model proves insufficient for a phenomenon.
|
||||
3. **A hypothesis-scoring layer that uses the ADR-312 twin as the forward model
|
||||
and the ADR-308 fused state as the hypothesis prior, routing low-margin and
|
||||
null-dominant cases to the ADR-299 UNKNOWN verdict.** Chosen.
|
||||
3. **A hypothesis-scoring layer that uses the ADR-315 twin as the forward model
|
||||
and the ADR-311 fused state as the hypothesis prior, routing low-margin and
|
||||
null-dominant cases to the ADR-302 UNKNOWN verdict.** Chosen.
|
||||
|
||||
## Decision
|
||||
|
||||
@@ -70,31 +70,31 @@ generative forward model.
|
||||
|
||||
### 1. Hypothesis set
|
||||
|
||||
- Hypotheses are drawn from the ADR-308 fused state and its neighbourhood: the
|
||||
- Hypotheses are drawn from the ADR-311 fused state and its neighbourhood: the
|
||||
current estimate, the **null hypothesis** (nobody present), and a bounded set
|
||||
of nearby alternatives (±1 occupant, shifted position). The fused estimate
|
||||
supplies the prior so the search stays small and grounded rather than
|
||||
enumerating an open world.
|
||||
- The hypothesis space is expressed over the **ADR-303** canonical ontology
|
||||
- The hypothesis space is expressed over the **ADR-306** canonical ontology
|
||||
(`Space`/`Zone`, occupant count, coarse position), so a counterfactual result
|
||||
is a governed spatial statement, not an opaque score.
|
||||
|
||||
### 2. Forward model and scoring
|
||||
|
||||
- For each hypothesis, query the **ADR-312 twin** for the expected measurement
|
||||
- For each hypothesis, query the **ADR-315 twin** for the expected measurement
|
||||
distribution given that scene state and the deployment's propagation model.
|
||||
Score the observed measurement's likelihood under each hypothesis's expected
|
||||
distribution.
|
||||
- The answer is the maximum-likelihood hypothesis; the **margin** between the
|
||||
top hypotheses (and between the top hypothesis and the null) is the
|
||||
confidence signal, carried into the ADR-301 evidence engine.
|
||||
confidence signal, carried into the ADR-304 evidence engine.
|
||||
|
||||
### 3. Routing to UNKNOWN
|
||||
|
||||
- When the null hypothesis dominates, the layer reports *absence*, not a
|
||||
low-confidence occupancy label.
|
||||
- When **no** hypothesis explains the observation well (all likelihoods low, or
|
||||
the winning margin below threshold), the result routes to the **ADR-299**
|
||||
the winning margin below threshold), the result routes to the **ADR-302**
|
||||
`UNKNOWN` verdict — the observation is outside what the twin can explain, and
|
||||
the honest output is "I cannot account for this," never a forced label.
|
||||
|
||||
@@ -115,14 +115,14 @@ generative forward model.
|
||||
questions that discriminative heads structurally cannot — a step toward
|
||||
generative spatial reasoning and a differentiator for security and
|
||||
facility-monitoring applications where *absence* is the valuable signal.
|
||||
- Quality is bounded by the fidelity of the ADR-312 twin's forward model and the
|
||||
ADR-308 fused prior; the layer reports margins and defers to ADR-299 UNKNOWN
|
||||
- Quality is bounded by the fidelity of the ADR-315 twin's forward model and the
|
||||
ADR-311 fused prior; the layer reports margins and defers to ADR-302 UNKNOWN
|
||||
rather than overstating a coarse model.
|
||||
- Hard dependency on ADR-308 (fused state and covariance) and ADR-312 (forward
|
||||
- Hard dependency on ADR-311 (fused state and covariance) and ADR-315 (forward
|
||||
model); this ADR builds neither a fusion engine nor a propagation simulator of
|
||||
its own.
|
||||
- Being phase 3, this is design intent sitting on the fused world state; it is
|
||||
expected to be revised as ADR-308 and ADR-312 land, and it is not implemented
|
||||
expected to be revised as ADR-311 and ADR-315 land, and it is not implemented
|
||||
by the phase-1 swarm.
|
||||
|
||||
## Validation
|
||||
@@ -133,8 +133,8 @@ generative forward model.
|
||||
two-occupant hypothesis above the one-occupant hypothesis on a controlled
|
||||
synthetic case.
|
||||
- Integration test: measurements the twin cannot explain (out-of-model
|
||||
scattering) drive the layer to the ADR-299 UNKNOWN verdict rather than a
|
||||
forced occupancy label; margins propagate into the ADR-301 evidence engine.
|
||||
scattering) drive the layer to the ADR-302 UNKNOWN verdict rather than a
|
||||
forced occupancy label; margins propagate into the ADR-304 evidence engine.
|
||||
- Held-out discrimination (deferred, real-silicon): one-vs-two and
|
||||
presence-vs-absence discrimination on a leakage-free held-out split with a
|
||||
mean-pose baseline, reported as `MEASURED` with a reproducer. Until then all
|
||||
+27
-27
@@ -1,16 +1,16 @@
|
||||
# ADR-311: Information-gain scheduler — sample the most informative radios
|
||||
# ADR-314: Information-gain scheduler — sample the most informative radios
|
||||
|
||||
- **Status**: Accepted — initial implementation (ADR-297 phase 3)
|
||||
- **Status**: Accepted — initial implementation (ADR-300 phase 3)
|
||||
- **Date**: 2026-08-11
|
||||
- **Deciders**: ruv
|
||||
- **Tags**: scheduling, active-sensing, information-gain, edge, energy, fusion, phase-3
|
||||
|
||||
## Context
|
||||
|
||||
This ADR is a child of **ADR-297** (perception substrate program) and owns
|
||||
primitive #14, *information-gain scheduler*. In the ADR-297 DAG it is a phase-3,
|
||||
This ADR is a child of **ADR-300** (perception substrate program) and owns
|
||||
primitive #14, *information-gain scheduler*. In the ADR-300 DAG it is a phase-3,
|
||||
research-forward primitive that sits on top of the fused world state and
|
||||
**pairs with ADR-306** (active sensing): ADR-306 decides *what to probe*
|
||||
**pairs with ADR-309** (active sensing): ADR-309 decides *what to probe*
|
||||
(waveform, sensing task); this ADR decides *which radios/modalities to spend
|
||||
budget on next*. It is authored as Proposed and is not implemented by the
|
||||
phase-1 swarm.
|
||||
@@ -36,17 +36,17 @@ not by actually sampling.
|
||||
|
||||
Relevant existing assets to build on rather than duplicate:
|
||||
|
||||
- **ADR-308** (fusion) maintains the fused state and its covariance — the
|
||||
- **ADR-311** (fusion) maintains the fused state and its covariance — the
|
||||
current uncertainty the scheduler is trying to reduce. Expected uncertainty
|
||||
reduction is computed against that covariance, not a private one.
|
||||
- **ADR-312** (RF twin) provides the per-sensor forward model used to predict a
|
||||
- **ADR-315** (RF twin) provides the per-sensor forward model used to predict a
|
||||
candidate measurement's expected informativeness before sampling.
|
||||
- **ADR-317** (RuView sensor HAL, phase 2) exposes each radio's real
|
||||
- **ADR-320** (RuView sensor HAL, phase 2) exposes each radio's real
|
||||
compute/energy/bandwidth cost descriptors; the denominator is read from the
|
||||
HAL, not guessed per platform.
|
||||
- **ADR-306** (active sensing) is the paired actuator: the scheduler ranks
|
||||
sensors, ADR-306 chooses the probe on the chosen sensor.
|
||||
- **ADR-299** (observability) defines the phenomenon the estimate is *for*, so
|
||||
- **ADR-309** (active sensing) is the paired actuator: the scheduler ranks
|
||||
sensors, ADR-309 chooses the probe on the chosen sensor.
|
||||
- **ADR-302** (observability) defines the phenomenon the estimate is *for*, so
|
||||
the scheduler prioritizes uncertainty reduction on the objective that matters,
|
||||
not on nuisance dimensions.
|
||||
|
||||
@@ -61,8 +61,8 @@ Relevant existing assets to build on rather than duplicate:
|
||||
the present uncertainty — a well-placed WiFi link can dominate an occluded
|
||||
mmWave node in a given moment.
|
||||
3. **A value-of-information scheduler that ranks sensors by expected uncertainty
|
||||
reduction per unit cost, using the ADR-308 covariance and ADR-312 forward
|
||||
model, with costs from the ADR-317 HAL.** Chosen.
|
||||
reduction per unit cost, using the ADR-311 covariance and ADR-315 forward
|
||||
model, with costs from the ADR-320 HAL.** Chosen.
|
||||
|
||||
## Decision
|
||||
|
||||
@@ -72,12 +72,12 @@ sampling/processing budget across available radios by value of information.
|
||||
### 1. Value function
|
||||
|
||||
- For each candidate sensor/modality, estimate **expected uncertainty
|
||||
reduction** on the ADR-299 objective by evaluating how much a predicted
|
||||
measurement (via the **ADR-312** forward model) would shrink the **ADR-308**
|
||||
reduction** on the ADR-302 objective by evaluating how much a predicted
|
||||
measurement (via the **ADR-315** forward model) would shrink the **ADR-311**
|
||||
fused-state covariance — a value-of-information estimate made *before* paying
|
||||
for the measurement.
|
||||
- Divide by the sensor's **cost** — compute + energy + bandwidth — read from the
|
||||
**ADR-317** HAL descriptors. The exact weighting of the three cost terms is a
|
||||
**ADR-320** HAL descriptors. The exact weighting of the three cost terms is a
|
||||
deployment policy (a battery node weights energy heavily; a wired gateway
|
||||
weights bandwidth), configured, not hardcoded.
|
||||
|
||||
@@ -87,22 +87,22 @@ sampling/processing budget across available radios by value of information.
|
||||
configurable floor that guarantees each sensor is sampled at least
|
||||
occasionally (so a sensor whose value is currently low is not starved into
|
||||
permanent blindness and can be re-evaluated as the scene changes).
|
||||
- The scheduler emits an allocation, not a measurement; **ADR-306** active
|
||||
- The scheduler emits an allocation, not a measurement; **ADR-309** active
|
||||
sensing chooses the probe/waveform on each selected sensor, and the fusion
|
||||
layer (ADR-308) incorporates the result.
|
||||
layer (ADR-311) incorporates the result.
|
||||
|
||||
### 3. Governance and honesty
|
||||
|
||||
- Skipping a sensor for a cycle is a *deliberate* reduction in coverage; the
|
||||
scheduler records which sensors were sampled so downstream evidence (ADR-301)
|
||||
reflects the actual sensing that occurred, and observability (ADR-299) can
|
||||
scheduler records which sensors were sampled so downstream evidence (ADR-304)
|
||||
reflects the actual sensing that occurred, and observability (ADR-302) can
|
||||
raise `UNKNOWN` for a zone that went under-sampled rather than reporting a
|
||||
stale estimate as current.
|
||||
|
||||
### Evidence discipline
|
||||
|
||||
- Expected-uncertainty-reduction estimates are model predictions from the
|
||||
ADR-312 twin (simulation, L0 per ADR-282, `SYNTHETIC`); a scheduling decision
|
||||
ADR-315 twin (simulation, L0 per ADR-282, `SYNTHETIC`); a scheduling decision
|
||||
is a resource choice, never a sensing claim.
|
||||
- Any energy/latency/throughput improvement figure requires real-silicon
|
||||
measurement with a reproducer before it is tagged `MEASURED` (CLAUDE.md
|
||||
@@ -113,14 +113,14 @@ sampling/processing budget across available radios by value of information.
|
||||
- Edge deployments spend scarce compute, energy, and bandwidth where they buy
|
||||
the most certainty, making "hundreds of sensors" operationally tractable — a
|
||||
capability the reviews flagged as critical for edge deployment.
|
||||
- Quality is bounded by the accuracy of the ADR-312 forward model (informativeness
|
||||
prediction) and ADR-317 cost descriptors; a poor forward model degrades to
|
||||
- Quality is bounded by the accuracy of the ADR-315 forward model (informativeness
|
||||
prediction) and ADR-320 cost descriptors; a poor forward model degrades to
|
||||
near-round-robin, which is safe but not optimal. The sampling floor bounds the
|
||||
worst case.
|
||||
- Hard dependency on ADR-308 (covariance), ADR-312 (forward model), and ADR-317
|
||||
(cost descriptors), and paired with ADR-306; this ADR builds none of those.
|
||||
- Hard dependency on ADR-311 (covariance), ADR-315 (forward model), and ADR-320
|
||||
(cost descriptors), and paired with ADR-309; this ADR builds none of those.
|
||||
- Being phase 3, this is design intent sitting on the fused world state and is
|
||||
expected to be revised as ADR-306, ADR-308, ADR-312, and the ADR-317 HAL land.
|
||||
expected to be revised as ADR-309, ADR-311, ADR-315, and the ADR-320 HAL land.
|
||||
|
||||
## Validation
|
||||
|
||||
@@ -130,7 +130,7 @@ sampling/processing budget across available radios by value of information.
|
||||
sampling floor guarantees eventual re-evaluation of a low-value sensor.
|
||||
- Integration test: on a synthetic multi-sensor scene, the scheduler reduces
|
||||
objective uncertainty faster per unit modelled cost than round-robin, and
|
||||
raises ADR-299 UNKNOWN for a deliberately starved zone rather than reporting a
|
||||
raises ADR-302 UNKNOWN for a deliberately starved zone rather than reporting a
|
||||
stale estimate.
|
||||
- Field validation (deferred, real-silicon): energy/latency/throughput on an
|
||||
instrumented multi-node deployment, reported as `MEASURED` with a reproducer.
|
||||
@@ -1,20 +1,20 @@
|
||||
# ADR-312: Digital RF twin — persistent per-deployment RF model
|
||||
# ADR-315: Digital RF twin — persistent per-deployment RF model
|
||||
|
||||
- **Status**: Accepted — initial implementation (ADR-297 phase 3)
|
||||
- **Status**: Accepted — initial implementation (ADR-300 phase 3)
|
||||
- **Date**: 2026-08-11
|
||||
- **Deciders**: ruv
|
||||
- **Tags**: rf-twin, digital-twin, propagation, calibration, spatial-memory, worldgraph, phase-3
|
||||
|
||||
## Context
|
||||
|
||||
This ADR is a child of **ADR-297** (perception substrate program) and owns
|
||||
primitive #15, *digital RF twin*. In the ADR-297 DAG it is a phase-3,
|
||||
This ADR is a child of **ADR-300** (perception substrate program) and owns
|
||||
primitive #15, *digital RF twin*. In the ADR-300 DAG it is a phase-3,
|
||||
research-forward primitive that underpins several other phase-3 primitives:
|
||||
**ADR-305** (placement optimizer) plans against the twin's propagation model,
|
||||
**ADR-310** (counterfactual inference) uses it as the generative forward model,
|
||||
and **ADR-311** (information-gain scheduler) uses it to predict per-sensor
|
||||
informativeness. It ties directly to **ADR-298** (calibration), **ADR-305**
|
||||
(placement), and **ADR-309** (long-term spatial memory). It is authored as
|
||||
**ADR-308** (placement optimizer) plans against the twin's propagation model,
|
||||
**ADR-313** (counterfactual inference) uses it as the generative forward model,
|
||||
and **ADR-314** (information-gain scheduler) uses it to predict per-sensor
|
||||
informativeness. It ties directly to **ADR-301** (calibration), **ADR-308**
|
||||
(placement), and **ADR-312** (long-term spatial memory). It is authored as
|
||||
Proposed and is not implemented by the phase-1 swarm.
|
||||
|
||||
RuView today has no persistent, per-deployment model of the RF environment.
|
||||
@@ -29,9 +29,9 @@ noise or drift.
|
||||
The **digital RF twin** is that persistent baseline: a per-deployment model
|
||||
holding
|
||||
|
||||
- **geometry and radio locations** (from the ADR-303 scene / worldgraph),
|
||||
- **geometry and radio locations** (from the ADR-306 scene / worldgraph),
|
||||
- **propagation history** and **observed multipath** structure,
|
||||
- **calibration state** (from ADR-298),
|
||||
- **calibration state** (from ADR-301),
|
||||
- **expected measurement distributions** for each link and phenomenon.
|
||||
|
||||
Once the twin exists, a physical change becomes a **measurable delta against the
|
||||
@@ -45,15 +45,15 @@ Relevant existing assets to build on rather than duplicate:
|
||||
|
||||
- The `worldgraph` crate already models the physical scene — `Room`/`Space`
|
||||
with `bounds_enu`, `Wall { rf_attenuation_db }`, `Doorway`, `Zone`, and
|
||||
`Sensor` nodes (ADR-303). The twin *annotates and persists* this scene with RF
|
||||
`Sensor` nodes (ADR-306). The twin *annotates and persists* this scene with RF
|
||||
state; it does not invent a second geometry.
|
||||
- `wifi-densepose-calibration` (enrollment, bank, anchor, runtime, specialist)
|
||||
holds the calibration state the twin persists; the twin references and
|
||||
versions calibration records, it does not reimplement calibration.
|
||||
- **ADR-309** (long-term spatial memory, phase 3) is the persistence and
|
||||
- **ADR-312** (long-term spatial memory, phase 3) is the persistence and
|
||||
temporal-history substrate; the twin is a *structured occupant* of that
|
||||
memory, not a separate database.
|
||||
- **ADR-302** (authenticated identity) and **ADR-292** (provenance) mean the
|
||||
- **ADR-305** (authenticated identity) and **ADR-295** (provenance) mean the
|
||||
measurements that update the twin carry verified lineage, so a delta is
|
||||
attributable rather than anonymous.
|
||||
|
||||
@@ -67,8 +67,8 @@ Relevant existing assets to build on rather than duplicate:
|
||||
coarse `rf_attenuation_db` scene RuView actually has and impractical on edge
|
||||
hardware. A high-fidelity solver is retained as an *optional backend* the
|
||||
twin can call, not the baseline.
|
||||
3. **A persistent, per-deployment RF model layered over the ADR-303 scene and
|
||||
ADR-309 memory: geometry + radio locations + calibration state + observed
|
||||
3. **A persistent, per-deployment RF model layered over the ADR-306 scene and
|
||||
ADR-312 memory: geometry + radio locations + calibration state + observed
|
||||
multipath + expected measurement distributions, updated by verified
|
||||
measurements, exposing changes as deltas.** Chosen.
|
||||
|
||||
@@ -80,20 +80,20 @@ assets.
|
||||
|
||||
### 1. State the twin holds
|
||||
|
||||
- **Geometry and radio locations** referenced from the ADR-303 / worldgraph
|
||||
- **Geometry and radio locations** referenced from the ADR-306 / worldgraph
|
||||
scene (not copied).
|
||||
- **Calibration state** referenced and versioned from
|
||||
`wifi-densepose-calibration` (ADR-298), so the twin knows *which* calibration
|
||||
`wifi-densepose-calibration` (ADR-301), so the twin knows *which* calibration
|
||||
a stored distribution was captured under.
|
||||
- **Observed multipath and propagation history** — a bounded temporal summary
|
||||
of per-link channel structure, stored in ADR-309 spatial memory.
|
||||
of per-link channel structure, stored in ADR-312 spatial memory.
|
||||
- **Expected measurement distributions** per link and phenomenon — the forward
|
||||
model ADR-305, ADR-310, and ADR-311 consume.
|
||||
model ADR-308, ADR-313, and ADR-314 consume.
|
||||
|
||||
### 2. Update and delta
|
||||
|
||||
- Verified measurements (ADR-302 identity, ADR-292 provenance) update the twin's
|
||||
distributions online, bounded by ADR-298 calibration validity. A new
|
||||
- Verified measurements (ADR-305 identity, ADR-295 provenance) update the twin's
|
||||
distributions online, bounded by ADR-301 calibration validity. A new
|
||||
observation is compared to the twin's expected distribution; the **delta** —
|
||||
and its statistical significance against the twin's own variance — is the
|
||||
primary output. A change large relative to the twin's modelled variance is a
|
||||
@@ -104,12 +104,12 @@ assets.
|
||||
|
||||
### 3. Consumers
|
||||
|
||||
- **ADR-305** queries the twin's propagation model to plan placements.
|
||||
- **ADR-310** uses the twin's expected distributions as the generative forward
|
||||
- **ADR-308** queries the twin's propagation model to plan placements.
|
||||
- **ADR-313** uses the twin's expected distributions as the generative forward
|
||||
model for hypothesis scoring.
|
||||
- **ADR-311** uses per-sensor expected informativeness from the twin.
|
||||
- **ADR-314** uses per-sensor expected informativeness from the twin.
|
||||
- Facility/security/robotics/industrial integrations read the twin's change
|
||||
deltas as governed ADR-303 spatial events.
|
||||
deltas as governed ADR-306 spatial events.
|
||||
|
||||
### Evidence discipline
|
||||
|
||||
@@ -129,18 +129,18 @@ assets.
|
||||
measurement" into "a measurable, attributable, versioned change" — the bridge
|
||||
from a sensing runtime to facility management, security, robotics, and
|
||||
industrial monitoring.
|
||||
- The twin is the shared forward model for ADR-305/310/311, so those primitives
|
||||
- The twin is the shared forward model for ADR-308/310/311, so those primitives
|
||||
speak one propagation model rather than three inconsistent ones — a
|
||||
deliberate reason to build the twin before its consumers mature.
|
||||
- Quality is bounded by the coarseness of the worldgraph scene and the fidelity
|
||||
of the forward model; the twin reports deltas *with significance against its
|
||||
own variance* rather than asserting confident change detection on a coarse
|
||||
model. The optional high-fidelity backend is where higher accuracy lives.
|
||||
- Hard dependency on ADR-303 (scene), ADR-298 (calibration state), and ADR-309
|
||||
- Hard dependency on ADR-306 (scene), ADR-301 (calibration state), and ADR-312
|
||||
(persistence); it reuses `worldgraph` and `wifi-densepose-calibration` rather
|
||||
than rebuilding geometry or calibration.
|
||||
- Being phase 3, this is design intent; it is expected to be revised as the
|
||||
phase-1 spine, ADR-308 fusion, and ADR-309 memory land.
|
||||
phase-1 spine, ADR-311 fusion, and ADR-312 memory land.
|
||||
|
||||
## Validation
|
||||
|
||||
@@ -151,8 +151,8 @@ assets.
|
||||
is retained.
|
||||
- Integration test: on a synthetic deployment, an injected physical change (a
|
||||
wall attenuation shift) produces a significant delta against the twin while
|
||||
ordinary noise does not; the delta surfaces as a governed ADR-303 event with
|
||||
provenance (ADR-302/292).
|
||||
ordinary noise does not; the delta surfaces as a governed ADR-306 event with
|
||||
provenance (ADR-305/292).
|
||||
- Field validation (deferred, real-silicon): change detection on an instrumented
|
||||
real deployment with a controlled physical-change protocol, reported as
|
||||
`MEASURED` with a reproducer. Until then all twin distributions and deltas are
|
||||
@@ -1,17 +1,17 @@
|
||||
# ADR-313: Fleet control plane — provisioning to audit trails
|
||||
# ADR-316: Fleet control plane — provisioning to audit trails
|
||||
|
||||
- **Status**: Proposed (ADR-297 phase 2)
|
||||
- **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-297** (perception substrate program) and owns
|
||||
primitive #16, *fleet control plane*. In the ADR-297 DAG it is a phase-2
|
||||
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-302** (authenticated sensor identity) for per-device identity and
|
||||
enrollment, and **ADR-315** (capability certificate) for the signed models,
|
||||
**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.
|
||||
|
||||
@@ -27,26 +27,26 @@ 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-293** (bind + allowlist) plus **ADR-302**
|
||||
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-302** already defines per-device keypairs, the `DeviceId → public key →
|
||||
- **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-302 identity, not a new
|
||||
plane is the distribution and lifecycle layer over ADR-305 identity, not a new
|
||||
identity scheme.
|
||||
- **ADR-315** (capability certificate) defines the signed, expiring artifact a
|
||||
- **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-298** (calibration) owns calibration validity/expiry; the fleet plane
|
||||
- **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-316** (witness chain) provides the append-only, re-verifiable record;
|
||||
- **ADR-319** (witness chain) provides the append-only, re-verifiable record;
|
||||
fleet audit trails are witness-chain entries, not a parallel log format.
|
||||
- **ADR-317** (RuView sensor HAL, phase 2) provides hardware/firmware capability
|
||||
- **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.
|
||||
@@ -61,8 +61,8 @@ Relevant existing assets to build on rather than duplicate:
|
||||
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-302 identity, ADR-315
|
||||
certificates, ADR-298 calibration lifecycle, and ADR-316 audit — covering
|
||||
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
|
||||
@@ -73,22 +73,22 @@ spine.
|
||||
|
||||
### 1. Release identity and bill of materials
|
||||
|
||||
- Each fielded device has a **BOM record** binding `DeviceId` (ADR-302) → exact
|
||||
firmware version → signed model set → active capability certificate (ADR-315)
|
||||
→ current calibration record (ADR-298) → HAL/hardware descriptor (ADR-317).
|
||||
- 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-302 enrollment step at fleet scale:
|
||||
- **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-315 certificate. A device is untrusted until provisioned.
|
||||
- **Certificate lifecycle**: issue, rotate, expire, and **revoke** ADR-315
|
||||
certificates and the ADR-302 keys behind them; revocation lists are
|
||||
distributed here (the distribution ADR-302 deferred).
|
||||
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-317 HAL descriptor and ADR-141 capability attestation so an
|
||||
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.
|
||||
|
||||
@@ -102,13 +102,13 @@ spine.
|
||||
### 4. Health telemetry, remote diagnostics, retention, audit
|
||||
|
||||
- **Health telemetry** and **remote diagnostics** report device liveness,
|
||||
calibration staleness (ADR-298), certificate expiry (ADR-315), and error
|
||||
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-316 witness-chain** entry, giving a re-verifiable **audit
|
||||
written as an **ADR-319 witness-chain** entry, giving a re-verifiable **audit
|
||||
trail** rather than a mutable log.
|
||||
|
||||
### Authority and least privilege
|
||||
@@ -127,12 +127,12 @@ spine.
|
||||
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-302 (identity), ADR-315 (certificate), ADR-298
|
||||
(calibration lifecycle), ADR-316 (audit), and ADR-317 (firmware/HAL
|
||||
- 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-315, ADR-316, and ADR-317 land.
|
||||
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.
|
||||
@@ -142,7 +142,7 @@ spine.
|
||||
- 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-316 witness entry.
|
||||
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
|
||||
+17
-17
@@ -1,25 +1,25 @@
|
||||
# ADR-314: Multi-domain benchmark scorecard — regressions cannot hide behind pooled accuracy
|
||||
# ADR-317: Multi-domain benchmark scorecard — regressions cannot hide behind pooled accuracy
|
||||
|
||||
- **Status**: Accepted — initial implementation planned (ADR-297 phase 1)
|
||||
- **Status**: Accepted — initial implementation planned (ADR-300 phase 1)
|
||||
- **Date**: 2026-08-11
|
||||
- **Deciders**: ruv
|
||||
- **Tags**: benchmark, aetherarena, ci-gate, evidence, honesty, domain-generalization, substrate
|
||||
|
||||
## Context
|
||||
|
||||
This ADR is primitive 17 of the perception-substrate program (ADR-297) and the
|
||||
per-PR enforcement edge of the phase-1 certificate spine. In the ADR-297
|
||||
dependency DAG it reads accuracy from the evidence engine (ADR-301), consumes
|
||||
the domain state produced by out-of-distribution detection (ADR-299), scores
|
||||
against calibration certificates (ADR-298), and is anchored in the witness chain
|
||||
(ADR-316). It is the surface that makes the rest of the spine testable on every
|
||||
This ADR is primitive 17 of the perception-substrate program (ADR-300) and the
|
||||
per-PR enforcement edge of the phase-1 certificate spine. In the ADR-300
|
||||
dependency DAG it reads accuracy from the evidence engine (ADR-304), consumes
|
||||
the domain state produced by out-of-distribution detection (ADR-302), scores
|
||||
against calibration certificates (ADR-301), and is anchored in the witness chain
|
||||
(ADR-319). It is the surface that makes the rest of the spine testable on every
|
||||
change to sensing code.
|
||||
|
||||
A single pooled accuracy number is the classic way a domain-generalization
|
||||
regression hides. A model can raise mean PCK or mean presence accuracy while
|
||||
quietly collapsing on unseen rooms, unseen devices, or stationary subjects —
|
||||
exactly the conditions WiFi sensing fails in and exactly the conditions a
|
||||
pooled average washes out. The strategic assessment (ADR-297) named this: what
|
||||
pooled average washes out. The strategic assessment (ADR-300) named this: what
|
||||
distinguishes infrastructure from a demo is that a regression on *any* operating
|
||||
domain is caught before merge, not discovered in the field.
|
||||
|
||||
@@ -62,11 +62,11 @@ pooled into one figure. The v0 domain axes:
|
||||
(a stationary subject at range — the canonical WiFi failure case).
|
||||
- **Pose**: `matched`, `subject-unseen`, `room-unseen`.
|
||||
- **OOD rejection**: the rate at which genuinely out-of-distribution input is
|
||||
correctly returned as UNKNOWN by ADR-299 (a capability, not a failure) and
|
||||
correctly returned as UNKNOWN by ADR-302 (a capability, not a failure) and
|
||||
the false-UNKNOWN rate on in-distribution input.
|
||||
- **Calibration drift**: fingerprint-distance trajectory against the ADR-298
|
||||
- **Calibration drift**: fingerprint-distance trajectory against the ADR-301
|
||||
certificate over the scored window, and the fraction of inferences in each
|
||||
ADR-299 `DomainState` (KNOWN / DEGRADED / UNKNOWN).
|
||||
ADR-302 `DomainState` (KNOWN / DEGRADED / UNKNOWN).
|
||||
|
||||
Each cell carries exactly one `EvidenceLevel` (L0–L5, ADR-282). A slice scored
|
||||
on synthetic input is L0/`Synthetic` by construction; a slice on a leakage-free
|
||||
@@ -86,7 +86,7 @@ accuracy at all.
|
||||
domains carry the strictest budgets because they are the ones a pooled score
|
||||
hides. The baseline is append-only and witness-anchored — a new baseline is a
|
||||
new signed ledger entry, never an in-place overwrite (ADR-149 ledger pattern,
|
||||
ADR-316 anchoring).
|
||||
ADR-319 anchoring).
|
||||
|
||||
### 3. Sensing-crate CI wiring
|
||||
|
||||
@@ -102,7 +102,7 @@ accuracy at all.
|
||||
|
||||
- No benchmark numbers are invented by this ADR. It delivers the scorecard
|
||||
format, the per-domain gate, and the CI wiring; the numbers come from the
|
||||
ADR-301 evidence ledger and the AetherArena scorer on real data, labelled at
|
||||
ADR-304 evidence ledger and the AetherArena scorer on real data, labelled at
|
||||
the honest evidence level. Empty domains report "no evidence," which the gate
|
||||
treats as no coverage — never as a pass.
|
||||
|
||||
@@ -120,7 +120,7 @@ accuracy at all.
|
||||
- Some domains will show weak or absent coverage. Surfacing that per-domain is
|
||||
the point; the scorecard must never paper over a thin domain with a pooled
|
||||
number.
|
||||
- The program-level acceptance test (ADR-297) is encoded here as an AetherArena
|
||||
- The program-level acceptance test (ADR-300) is encoded here as an AetherArena
|
||||
scenario, closing the loop once the phase-1 spine lands.
|
||||
|
||||
## Validation
|
||||
@@ -132,9 +132,9 @@ accuracy at all.
|
||||
`EvidenceLevel`; synthetic slices are L0 by construction.
|
||||
- Determinism: a scored run reproduces its SHA-256 hash under `PROOF_SEED=42`
|
||||
(ADR-011/ADR-149 binding); the baseline scorecard is append-only and
|
||||
witness-anchored (ADR-316), never mutated in place.
|
||||
witness-anchored (ADR-319), never mutated in place.
|
||||
- CI: the sensing-crate gate runs on a PR touching a sensing crate and blocks a
|
||||
planted single-domain regression.
|
||||
- Real-data scorecards (a leakage-free held-out split with ADR-300 references)
|
||||
- Real-data scorecards (a leakage-free held-out split with ADR-303 references)
|
||||
are the maturity milestone; a synthetic scorecard is L0 and no per-domain
|
||||
number is MEASURED without a reproducer per CLAUDE.md.
|
||||
+36
-36
@@ -1,21 +1,21 @@
|
||||
# ADR-315: Capability certificates — validated-for-this-environment claims
|
||||
# ADR-318: Capability certificates — validated-for-this-environment claims
|
||||
|
||||
- **Status**: Accepted — initial implementation planned (ADR-297 phase 1)
|
||||
- **Status**: Accepted — initial implementation planned (ADR-300 phase 1)
|
||||
- **Date**: 2026-08-11
|
||||
- **Deciders**: ruv
|
||||
- **Tags**: capability, certificate, evidence, provenance, signature, honesty, substrate
|
||||
|
||||
## Context
|
||||
|
||||
This ADR is primitive 18 of the perception-substrate program (ADR-297) and,
|
||||
This ADR is primitive 18 of the perception-substrate program (ADR-300) and,
|
||||
per the strategic assessment, among the strongest ideas in the program: it is
|
||||
where the whole certificate spine becomes a consumable contract. In the ADR-297
|
||||
dependency DAG it **consumes the evidence engine (ADR-301)** — a capability
|
||||
where the whole certificate spine becomes a consumable contract. In the ADR-300
|
||||
dependency DAG it **consumes the evidence engine (ADR-304)** — a capability
|
||||
certificate is a signed attestation minted over a slice of that ledger — the
|
||||
**calibration certificate (ADR-298)** for the environment it is validated
|
||||
against, and the **RuField signature types (ADR-302 / ADR-260/262/277/279)** to
|
||||
sign it. It reports domain state via ADR-299 and is anchored in the witness
|
||||
chain (ADR-316).
|
||||
**calibration certificate (ADR-301)** for the environment it is validated
|
||||
against, and the **RuField signature types (ADR-305 / ADR-260/262/277/279)** to
|
||||
sign it. It reports domain state via ADR-302 and is anchored in the witness
|
||||
chain (ADR-319).
|
||||
|
||||
RuView must stop making unconditional capability claims. "Supports presence" is
|
||||
not a true statement — presence detection works in some rooms, on some hardware,
|
||||
@@ -24,10 +24,10 @@ uncalibrated room. A capability is only ever *validated for a specific
|
||||
environment*, and the honest unit of that claim is a signed, expiring
|
||||
certificate, not a feature flag in a README.
|
||||
|
||||
The ingredients now exist across the phase-1 spine: ADR-301 accumulates
|
||||
The ingredients now exist across the phase-1 spine: ADR-304 accumulates
|
||||
per-`(room, device, subject)` accuracy, false-positive rate, drift, and domain
|
||||
state; ADR-298 produces the signed room fingerprint the environment is keyed to;
|
||||
ADR-302 provides the authenticated device identity and `CapabilityAttestation`
|
||||
state; ADR-301 produces the signed room fingerprint the environment is keyed to;
|
||||
ADR-305 provides the authenticated device identity and `CapabilityAttestation`
|
||||
(BFLD, ADR-141) that bounds *what a device is even attested to sense*; ADR-282
|
||||
provides the mandatory `EvidenceLevel`. What is missing is the artifact that
|
||||
binds them into a single, verifiable "validated here, until then" claim and the
|
||||
@@ -39,10 +39,10 @@ consumer-side rule that refuses capabilities lacking one.
|
||||
the exact dishonest claim — environment-independent, unsigned, non-expiring,
|
||||
and false the moment the room, device, or subject dynamics differ.
|
||||
2. **Report raw ledger accuracy to consumers directly.** Rejected: the ledger
|
||||
(ADR-301) is the source of truth but not a portable, signed, bounded contract;
|
||||
(ADR-304) is the source of truth but not a portable, signed, bounded contract;
|
||||
handing consumers raw records pushes evidence-weighting and expiry logic into
|
||||
every consumer and drops the single verifiable object.
|
||||
3. **Mint a signed, expiring `CapabilityCertificate` over an ADR-301 ledger
|
||||
3. **Mint a signed, expiring `CapabilityCertificate` over an ADR-304 ledger
|
||||
slice, and make consumers refuse capabilities without a valid one.** Chosen.
|
||||
|
||||
## Decision
|
||||
@@ -56,38 +56,38 @@ time.
|
||||
A serializable `CapabilityCertificate` binding:
|
||||
|
||||
- `capability` — the phenomenon (e.g. `presence`, `pose`), which must be within
|
||||
the device's ADR-302/ADR-141 `CapabilityAttestation` (a device cannot be
|
||||
the device's ADR-305/ADR-141 `CapabilityAttestation` (a device cannot be
|
||||
certified for something it is not even attested to sense).
|
||||
- `room` — the ADR-303 space identifier, tied to the ADR-298 calibration
|
||||
- `room` — the ADR-306 space identifier, tied to the ADR-301 calibration
|
||||
certificate version the validation was performed against.
|
||||
- `hardware` — the ADR-302 authenticated `DeviceId` (and, in phase 2, the
|
||||
ADR-317 HAL descriptor of the sensor).
|
||||
- `hardware` — the ADR-305 authenticated `DeviceId` (and, in phase 2, the
|
||||
ADR-320 HAL descriptor of the sensor).
|
||||
- `model` — the model version scored.
|
||||
- `calibrated_date` — the calibration certificate age at validation time.
|
||||
- `moving_recall`, `stationary_recall`, `false_presence_per_24h` — the measured
|
||||
operating metrics, sliced from the ADR-301 ledger for this exact context (not
|
||||
operating metrics, sliced from the ADR-304 ledger for this exact context (not
|
||||
a global average), each honestly labelled. These are per-capability; a pose
|
||||
certificate carries pose metrics with the mean-pose baseline and a
|
||||
leakage-free split (CLAUDE.md) or it is not issued.
|
||||
- `valid_until` — an explicit expiry; a certificate is never open-ended.
|
||||
- `evidence_level` — exactly one L0–L5 (ADR-282). A certificate minted from a
|
||||
synthetic ledger slice is L0/`Synthetic`; a MEASURED metric requires an
|
||||
ADR-300 reference and a reproducer. The certificate cannot upgrade the level
|
||||
of the ledger it is minted from (ADR-301 honesty rule).
|
||||
- `signature` — a RuField `SignatureBlock` (ADR-302 / ADR-260/262/277/279) over
|
||||
ADR-303 reference and a reproducer. The certificate cannot upgrade the level
|
||||
of the ledger it is minted from (ADR-304 honesty rule).
|
||||
- `signature` — a RuField `SignatureBlock` (ADR-305 / ADR-260/262/277/279) over
|
||||
the canonical serialization; an unsigned certificate is not a valid
|
||||
certificate. The certificate is anchored in the witness chain (ADR-316).
|
||||
certificate. The certificate is anchored in the witness chain (ADR-319).
|
||||
|
||||
### 2. Minting
|
||||
|
||||
- A certificate is minted from a slice of the ADR-301 evidence ledger for one
|
||||
- A certificate is minted from a slice of the ADR-304 evidence ledger for one
|
||||
`(room, device, subject-class, model)` context. If the ledger reports "no
|
||||
evidence" for that context, **no certificate is issued** — absence of evidence
|
||||
is never a capability. Minting is a pure function over the append-only ledger
|
||||
at mint time; the metrics are frozen into the signed object.
|
||||
- Expiry (`valid_until`) is derived from calibration validity (ADR-298) and an
|
||||
- Expiry (`valid_until`) is derived from calibration validity (ADR-301) and an
|
||||
evidence-freshness policy: a certificate cannot outlive the calibration it was
|
||||
validated against, and drift beyond the ADR-298 envelope invalidates both.
|
||||
validated against, and drift beyond the ADR-301 envelope invalidates both.
|
||||
|
||||
### 3. Consumer refusal rule
|
||||
|
||||
@@ -95,9 +95,9 @@ A serializable `CapabilityCertificate` binding:
|
||||
certificate for the current environment**. "Valid" means: signature verifies,
|
||||
`room`/`hardware`/`model` match the running context, `valid_until` is in the
|
||||
future, and the referenced calibration certificate is itself still valid
|
||||
(ADR-298 not invalidated). A failed check yields UNKNOWN via ADR-299, not a
|
||||
(ADR-301 not invalidated). A failed check yields UNKNOWN via ADR-302, not a
|
||||
best-effort guess.
|
||||
- This makes the ADR-297 acceptance clause "quantify whether it can reliably
|
||||
- This makes the ADR-300 acceptance clause "quantify whether it can reliably
|
||||
sense the requested phenomenon → generate a signed capability certificate"
|
||||
a hard gate rather than a hope.
|
||||
|
||||
@@ -114,10 +114,10 @@ A serializable `CapabilityCertificate` binding:
|
||||
certificate and therefore no capability until validated. That refusal is the
|
||||
intended honest behavior, not a regression.
|
||||
- Key management and expiry policy are operational responsibilities, reusing the
|
||||
ADR-302 enrollment/rotation and ADR-298 validity machinery rather than new
|
||||
infrastructure; fleet distribution of certificates is owned by ADR-313.
|
||||
ADR-305 enrollment/rotation and ADR-301 validity machinery rather than new
|
||||
infrastructure; fleet distribution of certificates is owned by ADR-316.
|
||||
- No capability number is invented here; every metric on a certificate is sliced
|
||||
from the ADR-301 ledger at its honest evidence level.
|
||||
from the ADR-304 ledger at its honest evidence level.
|
||||
|
||||
## Validation
|
||||
|
||||
@@ -125,14 +125,14 @@ A serializable `CapabilityCertificate` binding:
|
||||
frozen metrics; "no evidence" context yields no certificate; signature
|
||||
round-trip and tamper rejection; `valid_until` and calibration-linked expiry
|
||||
enforced; consumer refusal on room/hardware/model mismatch, expiry, or
|
||||
invalidated calibration resolves to UNKNOWN (ADR-299), not a guess; evidence
|
||||
invalidated calibration resolves to UNKNOWN (ADR-302), not a guess; evidence
|
||||
level is inherited from the ledger and cannot be upgraded; a certificate
|
||||
cannot be issued for a capability outside the device's ADR-302/ADR-141
|
||||
cannot be issued for a capability outside the device's ADR-305/ADR-141
|
||||
attestation.
|
||||
- Cross-ADR: an ADR-301 ledger fixture mints a certificate; an ADR-299 test
|
||||
asserts an expired/mismatched certificate gates to UNKNOWN; the ADR-297
|
||||
- Cross-ADR: an ADR-304 ledger fixture mints a certificate; an ADR-302 test
|
||||
asserts an expired/mismatched certificate gates to UNKNOWN; the ADR-300
|
||||
acceptance test consumes a minted certificate end-to-end.
|
||||
- Real-deployment certificates (minted from a populated ledger with ADR-300
|
||||
- Real-deployment certificates (minted from a populated ledger with ADR-303
|
||||
references on live ESP32 captures) are the maturity milestone and require
|
||||
hardware evidence per CLAUDE.md; a certificate minted from a synthetic ledger
|
||||
is L0 by construction.
|
||||
@@ -1,22 +1,22 @@
|
||||
# ADR-316: Witness chain — epistemic infrastructure for physical AI
|
||||
# ADR-319: Witness chain — epistemic infrastructure for physical AI
|
||||
|
||||
- **Status**: Accepted — initial implementation planned (ADR-297 phase 1)
|
||||
- **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-297) and a
|
||||
spine root of its phase-1 certificate stack. In the ADR-297 dependency DAG it
|
||||
**extends the source-provenance state machine (ADR-292)** and the RuField
|
||||
provenance types, **ties to the signature machinery (ADR-302 /
|
||||
ADR-260/262/277/279)**, and anchors the artifacts produced by ADR-298
|
||||
(calibration certificates), ADR-301 (evidence records), ADR-314 (benchmark
|
||||
scorecards), and ADR-315 (capability certificates). In phase 2 it carries the
|
||||
independent-corroboration link from ADR-300.
|
||||
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-297) framed RuView's real product as **epistemic
|
||||
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
|
||||
@@ -24,10 +24,10 @@ 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-292
|
||||
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-302 defines the signed
|
||||
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,
|
||||
@@ -43,7 +43,7 @@ provenance of that stage.
|
||||
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-301)
|
||||
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.
|
||||
@@ -63,23 +63,23 @@ RF observation ▸ DSP evidence ▸ model inference ▸ independent corroboratio
|
||||
|
||||
- Each stage is a signed record carrying its **confidence** and its
|
||||
**provenance**:
|
||||
- **RF observation** — the ADR-302 authenticated frame envelope
|
||||
(`DeviceId`, sequence, timestamp, measurement hash) and its ADR-292
|
||||
- **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-292 invariant).
|
||||
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-299 `DomainState` (KNOWN / DEGRADED / UNKNOWN) gate
|
||||
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-300 agreement link
|
||||
- **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-303 ontology `Observation`/`Track`/`Event` the
|
||||
- **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-315) it relied on.
|
||||
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
|
||||
@@ -87,23 +87,23 @@ RF observation ▸ DSP evidence ▸ model inference ▸ independent corroboratio
|
||||
|
||||
### 2. Signing and anchoring
|
||||
|
||||
- Each stage is signed with RuField signature types (ADR-302 /
|
||||
- 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-298/ADR-301/ADR-314/ADR-315 write into.
|
||||
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-301 and CLAUDE.md's "source
|
||||
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-302) can re-verify a chain
|
||||
- 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-302) cannot provide.
|
||||
channel authentication (rejected in ADR-305) cannot provide.
|
||||
|
||||
### Provenance and honesty discipline
|
||||
|
||||
@@ -119,7 +119,7 @@ RF observation ▸ DSP evidence ▸ model inference ▸ independent corroboratio
|
||||
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-298/301/314/315) gains a single anchoring substrate;
|
||||
- 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;
|
||||
@@ -135,12 +135,12 @@ RF observation ▸ DSP evidence ▸ model inference ▸ independent corroboratio
|
||||
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-292 invariant); an UNKNOWN gate (ADR-299) and a "no corroboration" stage
|
||||
(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-302 signed frame lineage serializes into a chain that
|
||||
re-verifies offline with only the enrolled public keys; ADR-298/301/314/315
|
||||
- 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-300 corroboration)
|
||||
- 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.
|
||||
@@ -1,18 +1,18 @@
|
||||
# ADR-317: RuView sensor HAL — abstract all sensing hardware to one Observation type
|
||||
# ADR-320: RuView sensor HAL — abstract all sensing hardware to one Observation type
|
||||
|
||||
- **Status**: Accepted — initial implementation (ADR-297 phase 2)
|
||||
- **Status**: Accepted — initial implementation (ADR-300 phase 2)
|
||||
- **Date**: 2026-08-11
|
||||
- **Deciders**: ruv
|
||||
- **Tags**: hal, sensor-abstraction, ontology, fusion, adapters, category, phase-2
|
||||
|
||||
## Context
|
||||
|
||||
This ADR is primitive 20 of the perception-substrate program (ADR-297) and a
|
||||
phase-2 integration primitive; it is authored as **Proposed**. In the ADR-297
|
||||
DAG it **consumes the canonical spatial ontology (ADR-303)** — its output is an
|
||||
This ADR is primitive 20 of the perception-substrate program (ADR-300) and a
|
||||
phase-2 integration primitive; it is authored as **Proposed**. In the ADR-300
|
||||
DAG it **consumes the canonical spatial ontology (ADR-306)** — its output is an
|
||||
ontology `Observation` bound to a `Sensor` entity — and **feeds real sensor
|
||||
fusion (ADR-308)**, which resolves many observations into one world state. It
|
||||
closes the "identify the hardware" clause of the ADR-297 acceptance test that
|
||||
fusion (ADR-311)**, which resolves many observations into one world state. It
|
||||
closes the "identify the hardware" clause of the ADR-300 acceptance test that
|
||||
phase 1 leaves open.
|
||||
|
||||
RuView's strategic ceiling is set by how tightly it is coupled to WiFi CSI.
|
||||
@@ -35,7 +35,7 @@ must be reused, not rebuilt:
|
||||
- Existing CSI adapters (ESP32/Nexmon/FeitCSI paths), the mmWave fusion path
|
||||
(ADR-063), and the multistatic WiFi path (ADR-029) are concrete producers to
|
||||
bring under one trait.
|
||||
- ADR-302 already authenticates a `Sensor`/`DeviceId`; ADR-303 already defines
|
||||
- ADR-305 already authenticates a `Sensor`/`DeviceId`; ADR-306 already defines
|
||||
`Sensor`, `Observation`, `Track`, and `Event` as first-class node types. The
|
||||
HAL is the trait that turns a heterogeneous device into that authenticated
|
||||
`Sensor` emitting those `Observation`s.
|
||||
@@ -55,7 +55,7 @@ only a provenance-bearing, evidence-labelled `Observation`.
|
||||
has no meaningful `RfFrameV2` projection; forcing one is the same mistake at a
|
||||
larger scale.
|
||||
3. **Define a `SensorHal` trait producing one `Observation` type, with existing
|
||||
adapters as implementations feeding a shared latent and the ADR-303
|
||||
adapters as implementations feeding a shared latent and the ADR-306
|
||||
ontology.** Chosen.
|
||||
|
||||
## Decision
|
||||
@@ -67,39 +67,39 @@ only `Observation`s.
|
||||
### 1. The `SensorHal` trait
|
||||
|
||||
- A `SensorHal` describes a device's **capabilities** (which phenomena it can
|
||||
sense — reusing the ADR-302/ADR-141 `CapabilityAttestation`), its **native
|
||||
sense — reusing the ADR-305/ADR-141 `CapabilityAttestation`), its **native
|
||||
frame** (kept native, not canonicalized, per the ADR-279 shared-latent
|
||||
lesson), and a method that lifts a native frame into an `Observation`.
|
||||
- Implementations wrap the existing producers: CSI (ESP32/Nexmon/FeitCSI via the
|
||||
ADR-279 `RfFrameV2` path), 802.11bf (ADR-307, phase 2), BLE, UWB, mmWave
|
||||
ADR-279 `RfFrameV2` path), 802.11bf (ADR-310, phase 2), BLE, UWB, mmWave
|
||||
(ADR-063), acoustic, camera, lidar, IMU, and `custom`. RF modalities reuse the
|
||||
ADR-279 per-device latent adapters wholesale; the HAL adds the non-RF and
|
||||
ranging modalities under the same trait.
|
||||
- The trait is the boundary where untrusted hardware input is validated
|
||||
(CLAUDE.md: validate at every hardware/FFI boundary; default to least
|
||||
authority). A device is authenticated as an ADR-302 `Sensor` before its
|
||||
authority). A device is authenticated as an ADR-305 `Sensor` before its
|
||||
observations are trusted.
|
||||
|
||||
### 2. The `Observation` type
|
||||
|
||||
- One provenance-bearing `Observation`: a measurement plus its `SensorHal`
|
||||
source descriptor, its ADR-302 authenticated `DeviceId`, its ADR-292
|
||||
source descriptor, its ADR-305 authenticated `DeviceId`, its ADR-295
|
||||
`SourceState`, its native-frame reference (not a lossy projection), and
|
||||
exactly one `EvidenceLevel` (L0–L5, ADR-282). A camera-derived `Observation`
|
||||
and a CSI-derived `Observation` are the same type with different provenance —
|
||||
and a camera observation never lifts WiFi output to camera-grade; each carries
|
||||
its own honest evidence level (CLAUDE.md: never present WiFi sensing as
|
||||
camera-grade).
|
||||
- The `Observation` maps directly onto the ADR-303 ontology `Observation` node
|
||||
- The `Observation` maps directly onto the ADR-306 ontology `Observation` node
|
||||
attached to its `Sensor`, so the ontology is the one representation and the
|
||||
HAL is its ingest funnel.
|
||||
|
||||
### 3. Feeding fusion
|
||||
|
||||
- Observations from any set of modalities flow into ADR-308 fusion, which
|
||||
- Observations from any set of modalities flow into ADR-311 fusion, which
|
||||
resolves them into one probabilistic world state. The HAL guarantees fusion
|
||||
never sees a modality-specific frame — only `Observation`s with uniform
|
||||
provenance and evidence — which is what makes ADR-308's "many observations →
|
||||
provenance and evidence — which is what makes ADR-311's "many observations →
|
||||
one world state" invariant implementable across heterogeneous hardware.
|
||||
|
||||
### Category and honesty discipline
|
||||
@@ -107,7 +107,7 @@ only `Observation`s.
|
||||
- This ADR changes RuView's category from a WiFi-DensePose pipeline to an open
|
||||
spatial-intelligence operating layer, but it makes **no accuracy claim**: the
|
||||
HAL delivers a uniform ingest boundary, not a detector. Any capability of a
|
||||
newly-connected sensor is still gated by ADR-299 and certified by ADR-315 for
|
||||
newly-connected sensor is still gated by ADR-302 and certified by ADR-318 for
|
||||
its specific environment — connecting a camera does not grant a validated
|
||||
capability by itself.
|
||||
- Hardware support for a given modality is CLAIMED until demonstrated on real
|
||||
@@ -118,10 +118,10 @@ only `Observation`s.
|
||||
|
||||
- New sensing hardware lands as one `SensorHal` implementation instead of a
|
||||
bespoke pipeline; the translation matrix stays O(modalities), mirroring how
|
||||
ADR-303 collapsed the surface matrix.
|
||||
- The ADR-297 acceptance clause "identify the hardware" becomes implementable:
|
||||
a new sensor type is described by its HAL, authenticated as an ADR-302
|
||||
`Sensor`, calibrated (ADR-298), gated (ADR-299), and certified (ADR-315)
|
||||
ADR-306 collapsed the surface matrix.
|
||||
- The ADR-300 acceptance clause "identify the hardware" becomes implementable:
|
||||
a new sensor type is described by its HAL, authenticated as an ADR-305
|
||||
`Sensor`, calibrated (ADR-301), gated (ADR-302), and certified (ADR-318)
|
||||
through the same phase-1 spine, closing the last open clause.
|
||||
- A trait boundary and an `Observation` type are added; existing RF adapters
|
||||
are re-expressed as implementations rather than rewritten, preserving the
|
||||
@@ -129,8 +129,8 @@ only `Observation`s.
|
||||
- Non-RF modalities (camera, lidar, acoustic) enter the governed plane with the
|
||||
same provenance and privacy discipline as RF; a camera is not a privacy-free
|
||||
shortcut — it inherits the ADR-277 governance and its own evidence level.
|
||||
- As a phase-2 Proposed ADR, the trait shape may be revised as ADR-308 fusion
|
||||
and ADR-307 802.11bf land; that revision is expected for a phased program.
|
||||
- As a phase-2 Proposed ADR, the trait shape may be revised as ADR-311 fusion
|
||||
and ADR-310 802.11bf land; that revision is expected for a phased program.
|
||||
|
||||
## Validation
|
||||
|
||||
@@ -140,10 +140,10 @@ only `Observation`s.
|
||||
`SourceState`, native-frame reference, and exactly one `EvidenceLevel`; a
|
||||
synthetic source yields L0/`Synthetic` and cannot alias to measured
|
||||
(ADR-279 invariant 6); an unauthenticated device's observations are rejected
|
||||
at the trait boundary (ADR-302).
|
||||
- Cross-ADR: an `Observation` maps round-trip to an ADR-303 ontology
|
||||
at the trait boundary (ADR-305).
|
||||
- Cross-ADR: an `Observation` maps round-trip to an ADR-306 ontology
|
||||
`Observation` node with no provenance loss, and a set of `Observation`s from
|
||||
distinct modalities is accepted by an ADR-308 fusion fixture.
|
||||
distinct modalities is accepted by an ADR-311 fusion fixture.
|
||||
- Real-silicon evidence is required before any modality's hardware support is
|
||||
claimed beyond CLAIMED: a captured boot/runtime log from the real device
|
||||
emitting `Observation`s. A successful build or simulator run is not hardware
|
||||
+15
-15
@@ -1,14 +1,14 @@
|
||||
# ADR-318: Decision policy — action authorization conditioned on certificate class, freshness, uncertainty, and evidence
|
||||
# ADR-321: Decision policy — action authorization conditioned on certificate class, freshness, uncertainty, and evidence
|
||||
|
||||
- **Status**: Accepted — initial implementation planned (ADR-297 phase 1)
|
||||
- **Status**: Accepted — initial implementation planned (ADR-300 phase 1)
|
||||
- **Date**: 2026-08-11
|
||||
- **Deciders**: ruv
|
||||
- **Tags**: policy, authorization, safety, certificates, governed-action, phase-1
|
||||
|
||||
## Context
|
||||
|
||||
The perception substrate (ADR-297) makes RuView state *what it knows* and
|
||||
*how well* — the capability certificate (ADR-315) binds hardware, environment,
|
||||
The perception substrate (ADR-300) makes RuView state *what it knows* and
|
||||
*how well* — the capability certificate (ADR-318) binds hardware, environment,
|
||||
model, calibration, metrics, expiry, and evidence level. But a certificate is a
|
||||
statement of knowledge, not a grant of action. The same certificate that is
|
||||
adequate to dim a light is wholly inadequate to release a door lock or clear an
|
||||
@@ -34,13 +34,13 @@ that sits between governed spatial state and any actuator.
|
||||
|
||||
An `ActionClass` declares the assurance an action demands:
|
||||
|
||||
- `min_certificate_class` — the required `CapabilityCertificate` class (ADR-315).
|
||||
- `min_certificate_class` — the required `CapabilityCertificate` class (ADR-318).
|
||||
- `max_certificate_age` / `min_domain_freshness` — the certificate must be
|
||||
currently valid **and** the live domain signature (ADR-299) must not be in a
|
||||
currently valid **and** the live domain signature (ADR-302) must not be in a
|
||||
DEGRADED/UNKNOWN state (this is the staleness guard, program invariant on
|
||||
certificate conditionality — see ADR-297).
|
||||
certificate conditionality — see ADR-300).
|
||||
- `max_uncertainty` — inference uncertainty ceiling.
|
||||
- `min_evidence_level` — the L0–L5 floor (ADR-282/ADR-301); e.g. a safety
|
||||
- `min_evidence_level` — the L0–L5 floor (ADR-282/ADR-304); e.g. a safety
|
||||
action may require ≥ L3 (held-out room+subject validation).
|
||||
|
||||
Reference action classes (illustrative, configurable):
|
||||
@@ -54,20 +54,20 @@ Reference action classes (illustrative, configurable):
|
||||
### 2. The authorization decision
|
||||
|
||||
`authorize(action, capability_certificate, live_state) -> Authorization` where
|
||||
`live_state` carries the current `SourceState` (ADR-292), OOD/domain state
|
||||
(ADR-299), and inference uncertainty. Rules:
|
||||
`live_state` carries the current `SourceState` (ADR-295), OOD/domain state
|
||||
(ADR-302), and inference uncertainty. Rules:
|
||||
|
||||
- **Fail-closed.** Any unmet condition → `Deny { failed_condition }`. The denial
|
||||
names the *specific* condition (expired cert, domain DEGRADED, uncertainty
|
||||
over ceiling, evidence below floor, certificate class too low).
|
||||
- **UNKNOWN denies high-assurance actions.** A domain in UNKNOWN (ADR-299)
|
||||
- **UNKNOWN denies high-assurance actions.** A domain in UNKNOWN (ADR-302)
|
||||
cannot authorize `Security`/`SafetyCritical` actions; it may still authorize
|
||||
`Convenience` if that class's policy permits, but the authorization records
|
||||
that it proceeded under UNKNOWN.
|
||||
- The decision is a **pure function** of (action class, certificate, live
|
||||
state) — deterministic and unit-testable without a clock or actuator.
|
||||
- Every authorization (allow or deny) is emitted as the terminal stage of the
|
||||
witness chain (ADR-316), so "why was this actuator allowed/denied" is
|
||||
witness chain (ADR-319), so "why was this actuator allowed/denied" is
|
||||
auditable end-to-end.
|
||||
|
||||
### 3. No silent optimism
|
||||
@@ -83,8 +83,8 @@ all deny by default. Absence of a policy is not permission.
|
||||
- A behavior change for existing automations that acted directly on presence:
|
||||
they now pass through the gate. Convenience-class defaults keep low-stakes
|
||||
automations working; high-stakes actions must opt into stricter classes.
|
||||
- Depends on ADR-315 (certificate), ADR-299 (domain/OOD state), ADR-292
|
||||
(source state), ADR-301 (evidence). Built in the phase-1 dependent wave after
|
||||
- Depends on ADR-318 (certificate), ADR-302 (domain/OOD state), ADR-295
|
||||
(source state), ADR-304 (evidence). Built in the phase-1 dependent wave after
|
||||
those types land.
|
||||
|
||||
## Validation
|
||||
@@ -94,7 +94,7 @@ all deny by default. Absence of a policy is not permission.
|
||||
above/below ceiling × evidence above/below floor); UNKNOWN denies
|
||||
safety-critical; every deny names its failed condition; absence-of-policy
|
||||
denies; determinism.
|
||||
- Integration: the acceptance-test scenario (ADR-297) — post-certification room
|
||||
- Integration: the acceptance-test scenario (ADR-300) — post-certification room
|
||||
change drives domain to DEGRADED→UNKNOWN, and a `SafetyCritical` authorization
|
||||
is denied with `failed_condition = domain_not_known` *before* the inference
|
||||
reaches the actuator, witness chain preserved.
|
||||
+34
-31
@@ -145,37 +145,40 @@ Statuses: **Proposed** (under discussion), **Accepted** (approved and/or impleme
|
||||
| [ADR-287](ADR-287-coherent-wideband-rf-tomography-crate.md) | `wifi-densepose-sar` — coherent wideband RF tomography research crate | Accepted (implemented, published) |
|
||||
| [ADR-285](ADR-285-homecore-wasm-first-metaharness.md) | WASM-first Homecore developer metaharness via `npx homecore` | Accepted (implemented and validated) |
|
||||
| [ADR-286](ADR-286-wifi-densepose-sar-harness-via-metaharness.md) | `wifi-densepose-sar-harness` — MetaHarness with darwin/router/flywheel | Accepted (implemented, published) |
|
||||
| [ADR-288](ADR-288-public-benchmark-evaluation-harness.md) | Public-benchmark evaluation harness — Widar3.0 ingest, split protocols, leakage guards | Accepted (initial implementation) |
|
||||
| [ADR-289](ADR-289-wideband-80211ax-csi-ingest.md) | Wideband 802.11ax CSI ingest — FeitCSI/AX210 adapter, subcarrier-agnostic plumbing | Accepted (initial implementation) |
|
||||
| [ADR-290](ADR-290-vitals-ground-truth-rig.md) | Vitals ground-truth rig — reference ingest, alignment, agreement metrics | Accepted (initial implementation) |
|
||||
| [ADR-291](ADR-291-wifi-veil-integration.md) | WiFi Veil integration — emission-shaping countermeasure as advisory BFLD dependency | Accepted (initial implementation) |
|
||||
| [ADR-292](ADR-292-source-provenance-state-machine.md) | Source provenance state machine — synthetic can never present as live | Accepted (initial implementation) |
|
||||
| [ADR-293](ADR-293-sensor-data-plane-bind-hardening.md) | Sensor data-plane hardening — UDP bind control and source allowlist (step one) | Accepted (initial implementation) |
|
||||
| [ADR-294](ADR-294-multi-node-semantic-correctness.md) | Multi-node semantic correctness — per-node inference, node-keyed rate limiting, stale state | Accepted (initial implementation) |
|
||||
| [ADR-295](ADR-295-model-release-sanity-gates.md) | Model release sanity gates — block degenerate and mislabeled model artifacts | Accepted (initial implementation) |
|
||||
| [ADR-296](ADR-296-csi-data-incident-repo-controls.md) | Repository CSI data-incident controls — ignore rules and pre-commit/CI policy check | Accepted (controls implemented; tree remediation gated) |
|
||||
| [ADR-297](ADR-297-perception-substrate-program.md) | RuView perception substrate — phased 21-primitive program (calibration, evidence, trust, deployment) | Accepted (program; children ADR-298..317) |
|
||||
| [ADR-298](ADR-298-automatic-domain-calibration.md) | Automatic domain calibration — signed, versioned, invalidatable room fingerprint | Accepted (phase 1) |
|
||||
| [ADR-299](ADR-299-out-of-distribution-detection.md) | Out-of-distribution detection — KNOWN / DEGRADED / UNKNOWN gating | Accepted (phase 1) |
|
||||
| [ADR-300](ADR-300-ground-truth-synchronization.md) | Ground-truth synchronization — reference sensors as a formal validation plane | Proposed (phase 2) |
|
||||
| [ADR-301](ADR-301-evidence-engine.md) | Evidence engine — per-(room,device,subject) accuracy ledger | Accepted (phase 1) |
|
||||
| [ADR-302](ADR-302-authenticated-sensor-identity.md) | Authenticated sensor identity — RF chain of custody | Accepted (phase 1) |
|
||||
| [ADR-303](ADR-303-canonical-spatial-ontology.md) | Canonical spatial ontology — one Site→…→Event model for every surface | Accepted (phase 1) |
|
||||
| [ADR-304](ADR-304-persistent-identity-tracking.md) | Persistent identity & tracking — privacy-preserving probabilistic tracks | Proposed (phase 2) |
|
||||
| [ADR-305](ADR-305-sensor-placement-optimizer.md) | Sensor placement optimizer — floorplan + inventory → recommended positions | Proposed (phase 3) |
|
||||
| [ADR-306](ADR-306-active-sensing.md) | Active sensing — closed-loop RF experiment control | Proposed (phase 3) |
|
||||
| [ADR-307](ADR-307-80211bf-native-architecture.md) | 802.11bf-native architecture — standardized WLAN sensing as native measurement types | Proposed (phase 2) |
|
||||
| [ADR-308](ADR-308-real-sensor-fusion.md) | Real sensor fusion — uncertainty-aware, multiple observations → one world state | Proposed (phase 2) |
|
||||
| [ADR-309](ADR-309-long-term-spatial-memory.md) | Long-term spatial memory — learn the normal physics of a location | Proposed (phase 3) |
|
||||
| [ADR-310](ADR-310-counterfactual-inference.md) | Counterfactual inference — generative spatial reasoning | Proposed (phase 3) |
|
||||
| [ADR-311](ADR-311-information-gain-scheduler.md) | Information-gain scheduler — sample the most informative radios | Proposed (phase 3) |
|
||||
| [ADR-312](ADR-312-digital-rf-twin.md) | Digital RF twin — persistent per-deployment RF model | Proposed (phase 3) |
|
||||
| [ADR-313](ADR-313-fleet-control-plane.md) | Fleet control plane — provisioning to audit trails | Proposed (phase 2) |
|
||||
| [ADR-314](ADR-314-benchmark-multi-domain-scorecard.md) | Multi-domain benchmark scorecard — regressions cannot hide behind pooled accuracy | Accepted (phase 1) |
|
||||
| [ADR-315](ADR-315-capability-certificates.md) | Capability certificates — validated-for-this-environment claims | Accepted (phase 1) |
|
||||
| [ADR-316](ADR-316-witness-chain.md) | Witness chain — staged, signed epistemic envelope | Accepted (phase 1) |
|
||||
| [ADR-317](ADR-317-sensor-hal.md) | RuView sensor HAL — abstract all sensing hardware to one Observation type | Proposed (phase 2) |
|
||||
| [ADR-318](ADR-318-decision-policy-action-authorization.md) | Decision policy — action authorization conditioned on certificate class, freshness, uncertainty, evidence | Accepted (phase 1) |
|
||||
| [ADR-288](ADR-288-veil-privacy-shield-compliant-waveform.md) | VEIL — compliant-waveform privacy shield against unauthorized WiFi sensing (`wifi-densepose-privshield`) | Proposed (implemented, P1 reference) |
|
||||
| [ADR-289](ADR-289-wifi-densepose-privshield-harness-via-metaharness.md) | `wifi-densepose-privshield-harness` — npm MetaHarness for the VEIL crate (guidance/router/flywheel) | Proposed (implemented, P1) |
|
||||
| [ADR-290](ADR-290-veil-e2e-hardware-implementation-program.md) | VEIL end-to-end hardware implementation program — portable C core + multi-provider firmware scaffolds (openwifi/openwrt/nexmon/esp32) | Proposed (P4 scaffolding; C core host-validated) |
|
||||
| [ADR-291](ADR-291-public-benchmark-evaluation-harness.md) | Public-benchmark evaluation harness — Widar3.0 ingest, split protocols, leakage guards | Accepted (initial implementation) |
|
||||
| [ADR-292](ADR-292-wideband-80211ax-csi-ingest.md) | Wideband 802.11ax CSI ingest — FeitCSI/AX210 adapter, subcarrier-agnostic plumbing | Accepted (initial implementation) |
|
||||
| [ADR-293](ADR-293-vitals-ground-truth-rig.md) | Vitals ground-truth rig — reference ingest, alignment, agreement metrics | Accepted (initial implementation) |
|
||||
| [ADR-294](ADR-294-wifi-veil-integration.md) | WiFi Veil integration — emission-shaping countermeasure as advisory BFLD dependency | Accepted (initial implementation) |
|
||||
| [ADR-295](ADR-295-source-provenance-state-machine.md) | Source provenance state machine — synthetic can never present as live | Accepted (initial implementation) |
|
||||
| [ADR-296](ADR-296-sensor-data-plane-bind-hardening.md) | Sensor data-plane hardening — UDP bind control and source allowlist (step one) | Accepted (initial implementation) |
|
||||
| [ADR-297](ADR-297-multi-node-semantic-correctness.md) | Multi-node semantic correctness — per-node inference, node-keyed rate limiting, stale state | Accepted (initial implementation) |
|
||||
| [ADR-298](ADR-298-model-release-sanity-gates.md) | Model release sanity gates — block degenerate and mislabeled model artifacts | Accepted (initial implementation) |
|
||||
| [ADR-299](ADR-299-csi-data-incident-repo-controls.md) | Repository CSI data-incident controls — ignore rules and pre-commit/CI policy check | Accepted (controls implemented; tree remediation gated) |
|
||||
| [ADR-300](ADR-300-perception-substrate-program.md) | RuView perception substrate — phased 21-primitive program (calibration, evidence, trust, deployment) | Accepted (program; children ADR-301..317) |
|
||||
| [ADR-301](ADR-301-automatic-domain-calibration.md) | Automatic domain calibration — signed, versioned, invalidatable room fingerprint | Accepted (phase 1) |
|
||||
| [ADR-302](ADR-302-out-of-distribution-detection.md) | Out-of-distribution detection — KNOWN / DEGRADED / UNKNOWN gating | Accepted (phase 1) |
|
||||
| [ADR-303](ADR-303-ground-truth-synchronization.md) | Ground-truth synchronization — reference sensors as a formal validation plane | Proposed (phase 2) |
|
||||
| [ADR-304](ADR-304-evidence-engine.md) | Evidence engine — per-(room,device,subject) accuracy ledger | Accepted (phase 1) |
|
||||
| [ADR-305](ADR-305-authenticated-sensor-identity.md) | Authenticated sensor identity — RF chain of custody | Accepted (phase 1) |
|
||||
| [ADR-306](ADR-306-canonical-spatial-ontology.md) | Canonical spatial ontology — one Site→…→Event model for every surface | Accepted (phase 1) |
|
||||
| [ADR-307](ADR-307-persistent-identity-tracking.md) | Persistent identity & tracking — privacy-preserving probabilistic tracks | Proposed (phase 2) |
|
||||
| [ADR-308](ADR-308-sensor-placement-optimizer.md) | Sensor placement optimizer — floorplan + inventory → recommended positions | Proposed (phase 3) |
|
||||
| [ADR-309](ADR-309-active-sensing.md) | Active sensing — closed-loop RF experiment control | Proposed (phase 3) |
|
||||
| [ADR-310](ADR-310-80211bf-native-architecture.md) | 802.11bf-native architecture — standardized WLAN sensing as native measurement types | Proposed (phase 2) |
|
||||
| [ADR-311](ADR-311-real-sensor-fusion.md) | Real sensor fusion — uncertainty-aware, multiple observations → one world state | Proposed (phase 2) |
|
||||
| [ADR-312](ADR-312-long-term-spatial-memory.md) | Long-term spatial memory — learn the normal physics of a location | Proposed (phase 3) |
|
||||
| [ADR-313](ADR-313-counterfactual-inference.md) | Counterfactual inference — generative spatial reasoning | Proposed (phase 3) |
|
||||
| [ADR-314](ADR-314-information-gain-scheduler.md) | Information-gain scheduler — sample the most informative radios | Proposed (phase 3) |
|
||||
| [ADR-315](ADR-315-digital-rf-twin.md) | Digital RF twin — persistent per-deployment RF model | Proposed (phase 3) |
|
||||
| [ADR-316](ADR-316-fleet-control-plane.md) | Fleet control plane — provisioning to audit trails | Proposed (phase 2) |
|
||||
| [ADR-317](ADR-317-benchmark-multi-domain-scorecard.md) | Multi-domain benchmark scorecard — regressions cannot hide behind pooled accuracy | Accepted (phase 1) |
|
||||
| [ADR-318](ADR-318-capability-certificates.md) | Capability certificates — validated-for-this-environment claims | Accepted (phase 1) |
|
||||
| [ADR-319](ADR-319-witness-chain.md) | Witness chain — staged, signed epistemic envelope | Accepted (phase 1) |
|
||||
| [ADR-320](ADR-320-sensor-hal.md) | RuView sensor HAL — abstract all sensing hardware to one Observation type | Proposed (phase 2) |
|
||||
| [ADR-321](ADR-321-decision-policy-action-authorization.md) | Decision policy — action authorization conditioned on certificate class, freshness, uncertainty, evidence | Accepted (phase 1) |
|
||||
|
||||
---
|
||||
|
||||
|
||||
Reference in New Issue
Block a user