ruvnet--RuView/api-docs/adr/ADR-294-wifi-veil-integration.md

ADR-294: WiFi Veil integration — emission-shaping countermeasure as an advisory BFLD dependency

• Status: Accepted — initial implementation (this PR)
• Date: 2026-08-10
• Deciders: ruv
• Tags: privacy, bfld, bfi, wifi-veil, countermeasure, dependency

Context

RuView's BFLD layer (ADR-118, ADR-141) senses via beamforming feedback while enforcing structural privacy invariants on data entering the node. The 2026 research sweep identified the complementary, unaddressed surface: a node's own outgoing BFI is unencrypted and enables passive third-party re-identification (BFId, ACM CCS 2025); IEEE 802.11bf-2025 shipped with no privacy mechanism; and no commercial product occupies the countermeasure category.

wifi-veil (codename VEIL, extracted from this monorepo as a standalone crate) models a compliant emission-shaping defense: keyed Givens rotations over the fine subspace of compressed beamforming reports, energy-preserving (never jamming), reversible by a keyed legitimate receiver. The crate is dependency-free, deterministic, std-only, WASM-ready, dual MIT/Apache-2.0, and explicitly SYNTHETIC/L0: it models waveform controls and never drives a radio.

RuView should consume this capability rather than re-implement it, giving the sensing stack a defensive counterpart under one evidence regime.

Options considered

1. Vendor the veil sources into a RuView crate. Rejected: forks the witness-pinned upstream and duplicates maintenance.
2. crates.io dependency. Not yet available (v0.1.0 unpublished at decision time); revisit when released.
3. Git dependency pinned to an exact rev, feature-gated in wifi-densepose-bfld. Chosen.

Decision

• Add wifi-veil to v2/Cargo.toml [workspace.dependencies] as a git dependency pinned to rev 018468b5d2bf41f35c552910f35659830af0eb91 (v0.1.0). Exact-rev pinning preserves provenance and reproducibility for a pre-release upstream; bumping the rev is an explicit, reviewable change.
• Gate it in wifi-densepose-bfld behind a new veil feature (veil = ["std", "dep:wifi-veil"]), off by default — the default build remains dependency-light and unchanged.
• New bfld::veil module (advisory-only):
  • ShieldAssessment: stable projection of wifi-veil's deterministic attacker-vs-protector ExperimentReport (re-ID accuracy shield-off/on, chance level, throughput ratio, energy-conservation audit), always carrying the SYNTHETIC/L0 evidence label.
  • assess / assess_default: run the deterministic experiment.
  • optimized_shield: wrap hyper_optimize to derive the optimizer-shipped shield config plus its verifying assessment.
• Boundaries, stated structurally and in docs:
  • Advisory only. Nothing in the integration emits RF, alters frames, or relaxes any BFLD gate/invariant (I1–I3 untouched).
  • Evidence honesty. Every veil-derived figure is labeled SYNTHETIC/L0; no MEASURED claim is possible from this path (hardware validation lives in wifi-veil's own P5 roadmap).
  • ESP32 nodes cannot shield their own feedback (per wifi-veil's platform matrix); the integration therefore informs posture and reporting, not on-node emission control.

Consequences

• RuView gains a sense-and-defend posture no commercial offering has, under a single claim taxonomy.
• First git dependency in the workspace: builds now fetch one pinned external rev. Acceptable: the crate is dependency-free, small, witness- pinned upstream, and license-compatible (MIT OR Apache-2.0 into MIT).
• Feature-gated consumers (e.g. sensing-server privacy reporting, the desktop UI) can surface shield assessments later without new deps.
• When wifi-veil publishes to crates.io, switch the workspace entry to a version requirement in a follow-up ADR amendment.

Validation

• cargo test -p wifi-densepose-bfld --features veil — determinism, shield-reduces-re-ID, compliance (energy conservation), chance-band attainment, evidence labeling, optimizer wrapper.
• cargo test -p wifi-densepose-bfld (default features) — unchanged behavior with the feature off.