From cbb365729f5abd4cc549f217ffc25ae38f50d3a8 Mon Sep 17 00:00:00 2001 From: ruv Date: Sun, 24 May 2026 20:03:01 -0400 Subject: [PATCH] docs(adr-118): CHANGELOG [Unreleased] BFLD entry + validation test (332/332 GREEN) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Iter 50. PR-readiness pivot iter #1. Lands the BFLD entry under CHANGELOG.md's [Unreleased] section per the project's pre-merge checklist (CLAUDE.md). Plus a validation test that catches drift if someone edits the entry and breaks the operator-facing summary. Added (in CHANGELOG.md): - New top-of-[Unreleased]-Added bullet for BFLD spanning: * ADR-118 umbrella + invariants I1/I2/I3 + their enforcement mechanism (Sink traits / Drop+no-Serialize / per-site BLAKE3) * ADR-119 frame format (86-byte header, payload sections, CRC32) * ADR-120 privacy classes + PrivacyGate::demote + apply_privacy_gating * ADR-121 multiplicative risk score + CoherenceGate + SoulMatchOracle * ADR-122 MQTT topic router + HA discovery + availability + LWT * ADR-123 capture path (reference; production capture is Pi5/Nexmon hardware-gated and remains skipped) * BfldPipelineHandle worker + spawn_with_oracle for Soul Signature * 3 operator HA blueprints (presence-lighting / motion-HVAC / identity-risk-anomaly) * Two runnable examples (bfld_minimal, bfld_handle) * eclipse-mosquitto:2 CI service container workflow * Performance measurements: 320k frames/sec, p95 0.9µs, 9.96 Hz * 327 default-feature tests, 101 no_std-compatible, 220+ with mqtt * Companion research dossier docs/research/BFLD/ (11 files, 13,544 words) * try-it command: cargo run -p wifi-densepose-bfld --example bfld_handle Added (in tests/changelog_entry.rs, 5 tests): - changelog_documents_bfld_entry_under_unreleased Slices CHANGELOG from `## [Unreleased]` to the first numbered version header and asserts the block contains BFLD, wifi-densepose-bfld, and the #787 tracking link. - changelog_bfld_entry_cites_companion_adrs Substring asserts ADR-118..123 each appear at least once. - changelog_bfld_entry_names_three_structural_invariants **I1**, **I2**, **I3** must be called out by name. - changelog_bfld_entry_documents_a_runnable_example Operators get a copy-pasteable cargo command. - changelog_bfld_entry_references_research_bundle Caught + fixed during iter: - First draft used "ADR-118 through ADR-123" shorthand; the per-ADR substring test fired for ADR-120 (not literally present). Re-wrote the parenthetical to "ADR-118 umbrella + ADR-119 frame format + ADR-120 privacy class + ADR-121 identity risk scoring + ADR-122 RuView HA/Matter exposure + ADR-123 capture path" so each ADR number is its own grep-discoverable token. ADR-124 status (iter step 0 sibling check): - docs/adr/ADR-124-rvagent-mcp-ruvector-npm-integration.md unchanged at 431 lines. SENSE-BRIDGE scope remains orthogonal. ACs progressed: - Pre-merge checklist item #5 (CLAUDE.md) — CHANGELOG `[Unreleased]` entry shipped. PR description can now link to the line + commit range as evidence. Test config: - cargo test --no-default-features → 101 passed (changelog_entry cfg-out) - cargo test → 332 passed (327 + 5) Out of scope (next iter target): - Pre-merge checklist remaining: README.md update (#3 — points at the new crate from the workspace level), user-guide.md (#6), witness bundle regeneration (#8). External-resource-gated work (KIT BFId, Pi5/Nexmon) still skipped. Co-Authored-By: claude-flow --- CHANGELOG.md | 1 + .../tests/changelog_entry.rs | 63 +++++++++++++++++++ 2 files changed, 64 insertions(+) create mode 100644 v2/crates/wifi-densepose-bfld/tests/changelog_entry.rs diff --git a/CHANGELOG.md b/CHANGELOG.md index e32a5fb1..78968f9b 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -62,6 +62,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 they can be reintroduced with a real implementation. ### Added +- **BFLD — Beamforming Feedback Layer for Detection (ADR-118 umbrella + ADR-119 frame format + ADR-120 privacy class + ADR-121 identity risk scoring + ADR-122 RuView HA/Matter exposure + ADR-123 capture path, [#787](https://github.com/ruvnet/RuView/issues/787)).** New crate `wifi-densepose-bfld` (`v2/crates/wifi-densepose-bfld/`) — the privacy-gated WiFi sensing layer that detects when RF data crosses from "ambient sensing" into "identity record" and **structurally prevents** identity-correlated data from leaving the node. Three invariants enforced by the type system (not policy): **I1** raw BFI never exits the node (`Sink` marker-trait hierarchy + `PrivacyClass::Raw.allows_network() == false`), **I2** identity embedding is in-RAM-only (`IdentityEmbedding` has no `Serialize`/`Clone`/`Copy` + `Drop` zeroizes), **I3** cross-site identity correlation is cryptographically impossible (per-site BLAKE3-keyed `SignatureHasher` with daily epoch rotation; mean cross-site Hamming distance ≥120 bits across 100 trials). Ships the complete operator surface: `BfldPipeline` + `BfldPipelineHandle` (worker-thread variant + `spawn_with_oracle` for Soul Signature deployments), `BfldEvent` with JSON publishing (`"blake3:"` `rf_signature_hash` format per spec), 4 `privacy_class` levels (Raw/Derived/Anonymous/Restricted) with `PrivacyGate::demote` monotonic transformer + irreversible `apply_privacy_gating`, `CoherenceGate` with ±0.05 hysteresis + 5-second debounce + clock-skew resilience (saturating_sub), `SoulMatchOracle` Recalibrate-exemption trait for enrolled-person deployments. **MQTT/HA surface**: `mqtt_topics::render_events` + `publish_event` (class-gated topic routing — Raw/Derived publish 0 topics, Anonymous publishes 6, Restricted publishes 5 with `identity_risk` stripped), `ha_discovery::render_discovery_payloads` + `publish_discovery` (HA-DISCO config payloads with `availability_topic` integration), `availability` module (`online`/`offline` + LWT-aware `with_lwt` helper for `rumqttc::MqttOptions`), `RumqttPublisher` behind a `mqtt` feature gate with `connect_with_lwt` for broker-side auto-offline. **3 operator HA Blueprints** under `v2/crates/cog-ha-matter/blueprints/bfld/` (presence-driven-lighting, motion-aware-HVAC, identity-risk-anomaly-notification with rolling 7-day z-score). **Two runnable examples** (`bfld_minimal` for in-process consumers, `bfld_handle` for the production worker-thread + bootstrap-then-spawn pattern). **GitHub Actions CI workflow** (`.github/workflows/bfld-mqtt-integration.yml`) spins up `eclipse-mosquitto:2` as a service container so the env-gated `mosquitto_integration` and `rumqttc_lwt` tests run end-to-end in CI. **Performance**: `BfldFrame::to_bytes()` measured at **320,255 frames/sec** debug (6.4× ADR-119 AC7 release target of 50k), header-only at 1,654,517 frames/sec, presence-detection latency p95 = **0.9µs** (~1,000,000× under ADR-119 AC2's 1s target), 9.96 Hz motion-publish rate through `BfldPipelineHandle` (10× ADR-122 AC3 floor). **Coverage**: 327 tests at default features, 101 no_std-compatible, 220+ with `--features mqtt`. CRC-32/ISO-HDLC polynomial pinned against `"123456789" → 0xCBF43926`, public-API surface snapshot pinned across all `pub use` re-exports, `BfldError` Display contract pinned for log-grep monitoring rules, reserved-flag-bits forward-compat round-trip property, `apply_privacy_gating` irreversibility (5-cycle round-trip stress proves stripped fields never resurrect). Companion research dossier in `docs/research/BFLD/` (11 files, 13,544 words). 49-iter implementation chain from scaffold (`feat/adr-118/p1`, `c965e3e6c`) through current head with per-iter progress comments on issue [#787](https://github.com/ruvnet/RuView/issues/787). Try it: `cargo run -p wifi-densepose-bfld --example bfld_handle`. - **Home Assistant + Matter integration (ADR-115).** New `--mqtt` and `--matter` flags on `wifi-densepose-sensing-server` expose the full sensing capability set to any Home Assistant install via MQTT auto-discovery (HA-DISCO) and to any Matter controller (Apple Home / Google Home / Alexa / SmartThings) via a built-in Matter Bridge scaffolding (HA-FABRIC, SDK wiring v0.7.1). Includes 21 entity kinds per node — 11 raw signals + 10 inferred semantic primitives (HA-MIND: someone-sleeping, possible-distress, room-active, elderly-inactivity-anomaly, meeting, bathroom, fall-risk, bed-exit, no-movement, multi-room-transition). The semantic primitives run server-side so `--privacy-mode` strips HR/BR/pose values from the wire while still publishing the inferred *states* — the architectural win for healthcare and AAL deployments. Ships **8 starter HA Blueprints** under `examples/ha-blueprints/`, **3 drop-in Lovelace dashboards** under `examples/lovelace/` (including a privacy-mode-compatible healthcare care view), mTLS support, 32 KB payload-size cap, MQTT-wildcard topic-injection rejection, `RUVIEW_MQTT_STRICT_TLS=1` v0.8.0 upgrade path. **420 lib tests** cover the implementation including **~2,560 fuzzed assertions per CI run** (10 proptest cases across wire-boundary security + semantic-bus invariants). Plus mosquitto-backed integration tests in `.github/workflows/mqtt-integration.yml`, criterion benchmarks beating every ADR target by 1.6×–208×, and an ESP32-S3 hardware validation harness (`scripts/validate-esp32-mqtt.sh`) that asserts the full pipeline end-to-end with a witness bundle generator (`scripts/witness-adr-115.sh`) that self-verifies. See [`docs/releases/v0.7.0-mqtt-matter.md`](docs/releases/v0.7.0-mqtt-matter.md), [`docs/integrations/home-assistant.md`](docs/integrations/home-assistant.md), [`docs/integrations/semantic-primitives-metrics.md`](docs/integrations/semantic-primitives-metrics.md), [`docs/integrations/benchmarks.md`](docs/integrations/benchmarks.md), [`docs/adr/ADR-115-home-assistant-integration.md`](docs/adr/ADR-115-home-assistant-integration.md), tracking issue [#776](https://github.com/ruvnet/RuView/issues/776), PR [#778](https://github.com/ruvnet/RuView/pull/778). Matter SDK wiring (P8b) and CSA-certification path (P10) deferred to v0.7.1+ per ADR §9.10. Try it: `cargo run -p wifi-densepose-sensing-server --features mqtt --example mqtt_publisher -- --mqtt --mqtt-host 127.0.0.1`. - **ESP32-C6 firmware target with Wi-Fi 6 / 802.15.4 / TWT / LP-core support ([ADR-110](docs/adr/ADR-110-esp32-c6-firmware-extension.md), #762).** `firmware/esp32-csi-node` now builds for **both** `esp32s3` (existing production node) and `esp32c6` (new research/seed-node target) from the same source tree — pick via `idf.py set-target esp32c6` and ESP-IDF auto-applies the new `sdkconfig.defaults.esp32c6` overlay. Every C6 module is `#ifdef CONFIG_IDF_TARGET_ESP32C6` gated, so the S3 build is byte-identical to today (no regression). - **Wi-Fi 6 HE-LTF subcarrier tagging** — `csi_collector.c` now reads `rx_ctrl.cur_bb_format` and writes the PPDU type (0=HT/legacy, 1=HE-SU, 2=HE-MU, 3=HE-TB) into ADR-018 frame byte 18, plus bandwidth flags (20/40 MHz, STBC, 802.15.4-sync-valid) into byte 19. Bytes 18-19 were previously reserved-zero, so old aggregators read them as before — fully backwards compatible. Magic stays `0xC5110001`. Default on via `CONFIG_CSI_FRAME_HE_TAGGING`. First firmware in the open ESP32 ecosystem to tag CSI frames with 11ax PPDU metadata. diff --git a/v2/crates/wifi-densepose-bfld/tests/changelog_entry.rs b/v2/crates/wifi-densepose-bfld/tests/changelog_entry.rs new file mode 100644 index 00000000..92673895 --- /dev/null +++ b/v2/crates/wifi-densepose-bfld/tests/changelog_entry.rs @@ -0,0 +1,63 @@ +//! Validate the BFLD entry exists in the workspace-root CHANGELOG.md. +//! `cog-ha-matter`, `wifi-densepose-sensing-server`, and the pip wheel +//! ship under their own release cadence; the workspace CHANGELOG is the +//! one canonical record an operator scans when upgrading a Cognitum Seed. + +#![cfg(feature = "std")] + +const CHANGELOG: &str = include_str!("../../../../CHANGELOG.md"); + +#[test] +fn changelog_documents_bfld_entry_under_unreleased() { + // Find the position of the [Unreleased] header. + let unreleased = CHANGELOG + .find("## [Unreleased]") + .expect("CHANGELOG must have an [Unreleased] section"); + // The first numbered version header marks the end of [Unreleased]. + let after_unreleased = CHANGELOG[unreleased..] + .find("\n## [0") + .or_else(|| CHANGELOG[unreleased..].find("\n## [1")) + .map(|off| unreleased + off) + .unwrap_or(CHANGELOG.len()); + let unreleased_block = &CHANGELOG[unreleased..after_unreleased]; + assert!( + unreleased_block.contains("BFLD"), + "[Unreleased] must mention BFLD", + ); + assert!(unreleased_block.contains("wifi-densepose-bfld")); + assert!( + unreleased_block.contains("#787"), + "[Unreleased] BFLD entry must link tracking issue #787", + ); +} + +#[test] +fn changelog_bfld_entry_cites_companion_adrs() { + for adr in ["ADR-118", "ADR-119", "ADR-120", "ADR-121", "ADR-122", "ADR-123"] { + assert!( + CHANGELOG.contains(adr), + "CHANGELOG BFLD entry must cite {adr}", + ); + } +} + +#[test] +fn changelog_bfld_entry_names_three_structural_invariants() { + let needles = ["**I1**", "**I2**", "**I3**"]; + for n in needles { + assert!(CHANGELOG.contains(n), "CHANGELOG must call out invariant {n}"); + } +} + +#[test] +fn changelog_bfld_entry_documents_a_runnable_example() { + assert!( + CHANGELOG.contains("cargo run -p wifi-densepose-bfld --example"), + "CHANGELOG entry should give operators a copy-pasteable try-it command", + ); +} + +#[test] +fn changelog_bfld_entry_references_research_bundle() { + assert!(CHANGELOG.contains("docs/research/BFLD/")); +}