Add per-deployment adaptive optimization + VEIL npm metaharness (ADR-289)

Two additions on top of the hyper-optimized VEIL shield. 1) Adaptive optimization (v2/crates/wifi-densepose-privshield/src/optimize.rs): - optimal_bits_across_snr / model_optimal_bits_for_snr: the throughput- optimal feedback resolution shifts with SNR (unconstrained optimum 4 bits at 5-10 dB, 3 bits at 20-40 dB); within the spec {5,7,9} set it stays 5, which is why the shipped shield is SNR-stable. - adaptive_shield / min_passes_for_n: derive a shield for a specific deployment. Finding: the collapse budget is N-independent in this model (48 passes collapses N in {8,64} alike) — it is set by the fine-subspace dimension, not the candidate count. Defaults unchanged, so the proof witness is untouched. 38 tests + doctest pass; clippy -D warnings clean. 2) npm metaharness harness/wifi-densepose-privshield/ (ADR-289), mirroring wifi-densepose-sar-harness (ADR-286) with two improvements: - @metaharness/* imported dynamically inside the commands that need them, so `guidance` and `--help` run with ZERO dependencies installed (offline / pre `npm install`). - a dependency-free VEIL `guidance` command: a source-cited, evidence- labelled, read-only capability map (topics: overview, threat, countermeasure, compliance, optimization, experiment). Standard router + flywheel (SYNTHETIC) + Darwin wiring, tailored to VEIL task axes and policy levers. Tests: smoke + router + flywheel (need install) and guidance (offline). .harness manifest generated with real per-file hashes. Validated offline: cli syntax, --help, guidance topics, exit codes, graceful degradation when deps are absent. Docs: research bundle 08 gains a per-deployment adaptivity section; 07 and the crate README point at the harness; ADR-289 added and indexed. Co-Authored-By: claude-flow <ruv@ruv.net> Claude-Session: https://claude.ai/code/session_01WEXNqzs7UsfNFBcP5yW21p
2026-08-11 20:41:44 +00:00 · 2026-08-09 14:23:12 +00:00
parent 006a66ca20
commit 18060b9c77
26 changed files with 1217 additions and 3 deletions
@@ -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)
+```
@@ -146,6 +146,7 @@ Statuses: **Proposed** (under discussion), **Accepted** (approved and/or impleme
 | [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-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) |

 ---