feat(privshield): E2E hardware program — validated C core + multi-provider firmware scaffolds

Take VEIL from the synthetic Rust reference model toward real WiFi silicon
across multiple hardware providers, around one shared, host-validated core.
Answers the questions "can OpenWRT / open WiFi software implement this?" and
"can ESP32 help scramble signals?" with an honest per-platform feasibility map.

Portable C shield core (firmware/privshield/core/) — VALIDATED (host test):
- veil_shield.{h,c}: keyed Givens-rotation obfuscation of the identity-bearing
  "fine" subspace, C99, no malloc / no libc I/O, only <math.h>. SplitMix64 key
  schedule byte-identical to the Rust crate, so on-air behavior is consistent
  everywhere and every adapter links the same math.
- make test passes: energy conservation (orthogonal => "not jamming"),
  reversibility (recover inverts apply), wrong-key-fails, and PRNG stream parity
  with the Rust crate. This is build/host evidence, NOT silicon.

Per-provider adapters (all SYNTHETIC / L0, build-only, TODO(hw) markers):
- openwifi/  grade B (ceiling A, effort D): only open PHY/MAC (FPGA) that can
  host the full keyed rotation + inverse; needs new HDL + 2nd TX chain. Carries
  the P5 measurement protocol (MEASUREMENT.md) for the first MEASURED result.
- openwrt/   grade C: per-packet keyed unitary is blob-blocked on commodity APs;
  coarse compliant knobs (TX antenna map, sounding-cadence jitter) reachable
  from userspace/hostapd; ath9k is the one credible driver-patch route.
- nexmon/    grade C: reading the compressed-BF angles is solved (nexmon_csi /
  Wi-BFI); shaping the transmitted report is research-grade (D11 ucode-adjacent).
- esp32/     grade F (self) / B (supporting): cannot shape its own BF feedback
  (closed esp-phy-lib blob); legitimate as a sensing detector and external-RIS
  controller — the honest way ESP32 "helps scramble", via an external surface.

Docs:
- firmware/privshield/README.md: architecture, layout, and the feasibility matrix.
- ADR-290: the E2E hardware program, PROOF discipline, and per-provider decision;
  added to docs/adr/README.md index.

Compliant waveform controls only, never jamming. No adapter has run on silicon;
no MEASURED claim is made (that is roadmap P5, gated on a captured log).

Co-Authored-By: claude-flow <ruv@ruv.net>
Claude-Session: https://claude.ai/code/session_01WEXNqzs7UsfNFBcP5yW21p

firmware/privshield/esp32/veil_sensing_detector/include/veil_sensing_detector.h

@@ -0,0 +1,88 @@
+/* SPDX-License-Identifier: MIT OR Apache-2.0
+ *
+ * veil_sensing_detector — detect 802.11 sensing solicitation and raise a
+ * trigger that engages the AP-side VEIL shield.
+ *
+ * STATUS: SYNTHETIC / L0. Build-only ESP-IDF component skeleton. Never flashed,
+ * never captured on silicon. Do NOT claim runtime behavior without a captured
+ * hardware log (CLAUDE.md hardware-evidence rule).
+ *
+ * ROLE (honest): the ESP32 is a passive CSI *observer* here. It watches how
+ * often it is being sounded / probed (NDP announcements, action frames, and the
+ * cadence of incoming CSI-bearing frames) and, when that rate crosses a
+ * threshold, tells a *separate* protector (the AP running the veil_shield core)
+ * that a sensing burst is in progress. The ESP32 does NOT modify any waveform
+ * and does NOT protect its own beamforming feedback (see README.md). This is
+ * the strongest, clearly-compliant supporting role for the ESP32.
+ */
+#ifndef VEIL_SENSING_DETECTOR_H
+#define VEIL_SENSING_DETECTOR_H
+
+#include <stdbool.h>
+#include <stdint.h>
+#include "esp_err.h"
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+/* How the detector announces "sensing burst detected" to the protector. */
+typedef enum {
+    VEIL_TRIGGER_GPIO = 0, /* drive a GPIO line to a co-located AP / relay   */
+    VEIL_TRIGGER_MQTT,     /* publish to a broker the AP subscribes to        */
+    VEIL_TRIGGER_ESPNOW,   /* connectionless ESP-NOW unicast to the AP node   */
+} veil_trigger_backend_t;
+
+typedef struct {
+    /* Sliding-window length for the solicitation-rate estimate, milliseconds. */
+    uint32_t window_ms;
+    /* Solicitations/second above which the shield should be engaged. */
+    float    trigger_rate_hz;
+    /* Hysteresis: rate must fall below this to clear the trigger. */
+    float    release_rate_hz;
+
+    veil_trigger_backend_t backend;
+
+    /* GPIO backend. */
+    int      gpio_num;            /* output line; active-high engage          */
+
+    /* MQTT backend. broker_uri/topic are borrowed, must outlive the detector. */
+    const char *mqtt_broker_uri;  /* e.g. "mqtts://ap.local:8883"             */
+    const char *mqtt_topic;       /* e.g. "veil/engage"                       */
+
+    /* ESP-NOW backend. */
+    uint8_t  espnow_peer[6];      /* AP node MAC                              */
+} veil_sensing_detector_cfg_t;
+
+/* Sensible SYNTHETIC defaults (not silicon-validated). */
+#define VEIL_SENSING_DETECTOR_DEFAULT_CFG() \
+    (veil_sensing_detector_cfg_t){          \
+        .window_ms        = 1000,           \
+        .trigger_rate_hz  = 20.0f,          \
+        .release_rate_hz  = 5.0f,           \
+        .backend          = VEIL_TRIGGER_GPIO, \
+        .gpio_num         = -1,             \
+        .mqtt_broker_uri  = NULL,           \
+        .mqtt_topic       = "veil/engage",  \
+        .espnow_peer      = {0},            \
+    }
+
+/* Install the CSI callback + configured trigger backend. Enables promiscuous
+ * CSI capture. Returns ESP_OK on successful *registration* only — this says
+ * nothing about on-air behavior. */
+esp_err_t veil_sensing_detector_start(const veil_sensing_detector_cfg_t *cfg);
+
+/* Tear down callback + backend. */
+esp_err_t veil_sensing_detector_stop(void);
+
+/* Last estimated solicitation rate (Hz), for telemetry/tests. */
+float veil_sensing_detector_rate_hz(void);
+
+/* True while the engage trigger is asserted. */
+bool veil_sensing_detector_engaged(void);
+
+#ifdef __cplusplus
+}
+#endif
+
+#endif /* VEIL_SENSING_DETECTOR_H */