deploy: f783df2

Author: romeo1250-crypto

api-docs/adr/ADR-021-vital-sign-detection-rvdna-pipeline.md

@@ -1081,6 +1081,23 @@ The `wifi-densepose-vitals` crate (ESP32 CSI-grade vital signs) has not yet been
 - SONA-based environment adaptation
 - VitalSignStore with tiered temporal compression
 
+## Implementation Notes
+
+### 2026-06 — ESP32 edge vitals: person-count over-count + presence flicker (#998, #996)
+
+Two robustness bugs were fixed in the on-device edge path (`firmware/esp32-csi-node/main/edge_processing.c`, the ADR-039 packet `0xC5110002`). These touch the *boolean/count emission logic*, not the underlying CSI signal-processing math, and do **not** constitute a validated-accuracy claim — true occupancy-count and presence accuracy vs labelled ground truth remain hardware/data-gated (COM9 ESP32-S3 + labelled capture).
+
+- **#998 `n_persons` over-count (reported 4 for one person).** `update_multi_person_vitals()` divided the top-K subcarriers into `top_k_count/2` groups and marked *every* group `active`, so one body's multipath always read the full `EDGE_MAX_PERSONS`. Added an energy gate (`EDGE_PERSON_MIN_ENERGY_RATIO`), spatial dedup (`EDGE_PERSON_MIN_SC_SEP`), and a persistence debounce (`EDGE_PERSON_PERSIST_FRAMES`) via two pure functions `count_distinct_persons()` / `person_count_debounce()`.
+- **#996 presence flag flicker at ~50 cm.** Single-threshold compare on a noisy `presence_score` chattered at the boundary. Replaced with a Schmitt trigger + clear-debounce (`presence_flag_update()`, constants `EDGE_PRESENCE_HYST_RATIO` / `EDGE_PRESENCE_CLEAR_FRAMES`); `presence_score` is unchanged and still emitted for consumer-side thresholding.
+
+Both are pinned by host-buildable C99 tests in `firmware/esp32-csi-node/test/test_vitals_count_presence.c` (`make run_vitals`). The exact thresholds are documented constants pending on-device calibration against ground truth.
+
+### 2026-06 — Rust `wifi-densepose-vitals`: IIR filter NaN/inf self-heal (ADR-158 §A1)
+
+A correctness/safety review of the Rust extraction crate found a real bug parallel to the firmware robustness class above. The 2nd-order resonator `bandpass_filter` in both `breathing.rs` and `heartrate.rs` latches each output `y[n]` into its filter state (`y1`/`y2`). A single non-finite amplitude residual from a corrupt CSI frame produced a NaN `output` that was written into the state; the existing `extract()` `is_finite()` guard dropped that one sample from the history buffer **but never sanitized the poisoned filter state**, so every later output stayed NaN, was rejected too, and the sliding-window history never refilled — breathing **and** heart-rate extraction went silently dead (returning `None` forever) until `reset()`. On the alert path this is a safety-relevant denial of service (one bad frame stops vitals monitoring with no error surfaced).
+
+Fix: when `bandpass_filter` computes a non-finite `output`, it resets the IIR state to default and returns `0.0`, so the resonator self-heals on the next clean frame (the `0.0` is still dropped by the caller's finite-check, so no spurious sample enters history). Same shape as the calibration NaN bug (ADR-154 §3) — the prior hardening guarded the *history boundary* but not the *filter-state boundary*. Pinned by `breathing::tests::nan_frame_does_not_permanently_poison_filter`, `breathing::tests::inf_mid_stream_does_not_freeze_history`, and `heartrate::tests::nan_frame_does_not_permanently_poison_filter` (all FAIL pre-fix, verified by reverting). The review also de-magicked the HR physiological plausibility band into named `HR_PLAUSIBLE_MIN_BPM`/`HR_PLAUSIBLE_MAX_BPM` consts (value-identical 40/180 BPM) and added a fabricated-vital negative (`pure_noise_is_never_reported_valid` — broadband noise never yields a clinically `Valid` HR; the extractor honestly returns low-confidence `Unreliable`). Clean dimensions confirmed with evidence: flat/silent input → `None`; pure noise → low-confidence `Unreliable`, never `Valid`; harmonic-rich breathing with no cardiac component → low-confidence, not a confident false HR; out-of-band BPM rejected by the plausibility clamp.
+
 ## References
 
 - Ramsauer et al. (2020). "Hopfield Networks is All You Need." ICLR 2021. (ModernHopfield formulation)

api-docs/adr/ADR-046-android-tv-box-armbian-deployment.md

@@ -83,7 +83,7 @@ This ADR covers Phase 1 (TV box as aggregator) and Phase 2 (custom WiFi firmware
    |---------|--------|-------------|--------------|--------|
    | Broadcom BCM43455 | brcmfmac | **Proven** (Nexmon CSI) | Yes | Low — patches exist |
    | Realtek RTL8822CS | rtw88 | **Moderate** — driver is open-source, CSI hooks need adding | Yes (patched) | Medium |
-   | MediaTek MT7661 | mt76 | **Unknown** — MediaTek has released CSI tools for some chips | Yes | Medium-High |
+   | MediaTek MT7661 | mt76 | **Unverified** — no supported public CSI capture API was found in upstream `mt76` or public MediaTek SDK material | Yes | Research only |
 
 2. **CSI extraction architecture** (Linux kernel driver modification):
 

api-docs/adr/ADR-084-rabitq-similarity-sensor.md

@@ -259,14 +259,75 @@ Validation runs against:
 - **ADR-083** (Proposed) — Per-cluster Pi compute hop. Defines the
   device class that hosts the sketch bank.
 
+## Pass 2 — randomized rotation + multi-bit (ADR-156 §8, landed 2026-06)
+
+The "Open question" below ("does `BinaryQuantized` need a randomized
+rotation pre-pass?") is now **answered with measured numbers** via
+ADR-156 §10. Summary:
+
+- **Pass 2 (randomized rotation) is implemented** —
+  `crates/wifi-densepose-ruvector/src/rotation.rs`: a deterministic
+  `R = H·D` (Fast Hadamard Transform + seeded ±1 sign flips), `O(d log d)`
+  / `O(d)`, norm-preserving, reproducible from a stored `u64` seed. Opt-in
+  via `Sketch::from_embedding_rotated` / `SketchBank::with_rotation`;
+  Pass-1 API and wire format unchanged.
+- **Measured top-K coverage** (anisotropic planted-cluster fixture,
+  cosine ground truth, dim=128 N=2048 K=8): rotation lifts coverage
+  **36.13% → 46.39%** at the strict `candidate_k = K` bar, and Pass-2
+  reaches the **≥90% acceptance bar at candidate_k = 24 (~3× over-fetch)**.
+  Multi-bit (≤4-bit) reaches 74% at the strict bar. **Honest verdict:
+  neither rotation nor ≤4-bit multi-bit clears the strict-K 90% bar on
+  this distribution; the bar is met via the over-fetch "candidate set"
+  pattern this ADR specifies** (Decision §"the canonical pattern" — sketch
+  picks the candidate set, full precision refines). Full numbers and
+  reproduce commands in ADR-156 §10.
+- **Pre-existing `SketchBank::topk` bug fixed** — the `n > k` heap path
+  returned the k *farthest* sketches (min-heap mistaken for max-heap);
+  only the `n ≤ k` fast path had test coverage. Fixed + regression-pinned
+  (`topk_heap_path_returns_nearest`,
+  `tight_clusters_give_high_coverage_with_overfetch`). This makes every
+  prior top-K acceptance number in this ADR depend on the fixed path; the
+  ≥90% coverage criterion is only meaningful post-fix.
+
+## Pass 2b — RaBitQ unbiased distance estimator (ADR-156 §11, landed 2026-06)
+
+The **real** RaBitQ contribution (Gao & Long, SIGMOD 2024) — an
+**unbiased estimator of the inner product / distance** from the 1-bit
+code + per-vector side info, not just sign bits — is now implemented and
+**MEASURED against this ADR's ≥90% strict-K bar**:
+
+- **Implemented** — `crates/wifi-densepose-ruvector/src/estimator.rs`:
+  `EstimatorSketch` (Pass-2 sign code + 8 B/vec side info:
+  `residual_norm` + `x_dot_o = ⟨x̄, o'⟩`), `DistanceEstimator`
+  (`⟨o',q'⟩ ≈ ⟨x̄,q'⟩ / x_dot_o`, the paper's unbiased rescale), and
+  `EstimatorBank` reranking candidates by the estimate instead of raw
+  Hamming. **Zero-centroid simplification** (`c = 0`) documented;
+  paper-faithful centroid path also built (`with_centroid`). Additive —
+  Pass-1/Pass-2 and the wire format are unchanged.
+- **MEASURED strict-K coverage** (same fixture as §"Pass 2", cosine
+  ground truth): the estimator lifts the strict `candidate_k = K` bar
+  **46.39% (Pass-2 sign) → 49.71% (estimator, cosine rerank)** — a real
+  **+3.3 pp** lift, but **still ~40 pp short of the ≥90% strict bar.**
+  At over-fetch the estimator does better than sign (95.12% vs 91.60% at
+  candidate_k = 24). **Honest verdict: the unbiased estimator does NOT
+  clear the strict-K 90% bar on this distribution** — the binding
+  constraint is the 1-bit code's information ceiling, not estimator
+  variance. The ≥90% acceptance bar is still met only via the over-fetch
+  "candidate set" pattern this ADR's Decision specifies; the estimator
+  **reduces the over-fetch factor** needed but does not remove it. This
+  is a **published negative**, reported as such. Full numbers + reproduce
+  commands in ADR-156 §11.
+
 ## Open questions
 
 - **Does `BinaryQuantized` need a randomized rotation pre-pass for
-  RuView's embedding distributions?** Pure sign quantization assumes
-  zero-centered, isotropic embeddings. If AETHER / spectrogram
-  distributions are skewed (likely for spectrogram), add a
-  `randomized_rotation` pre-pass following the original RaBitQ paper
-  (Gao & Long, SIGMOD 2024). Decided after pass-1 benchmark.
+  RuView's embedding distributions?** **ANSWERED (ADR-156 §10):** rotation
+  is built and measured — it helps (+10pp at strict K) but is not
+  sufficient alone for strict-K 90% on the tested anisotropic
+  distribution; the over-fetch candidate-set pattern meets the bar.
+  Pure sign quantization assumes zero-centered, isotropic embeddings; the
+  rotation decorrelates anisotropic coords as the RaBitQ paper
+  (Gao & Long, SIGMOD 2024) prescribes.
 - **Sketch dimension target.** Default to the embedding's native
   dimension (128 for AETHER, 256 for spectrogram). Higher-dimensional
   sketches (Johnson-Lindenstrauss-projected to 512) trade compute for

api-docs/adr/ADR-116-cog-ha-matter-seed.md

@@ -104,6 +104,57 @@ Ranked by build cost × user impact:
 | **P9** | HACS integration repo (`hass-wifi-densepose`) for HA-side install path | pending |
 | **P10** | Witness bundle + CSA-style spec compliance check | pending |
 
+## 4.1 Crypto/security review notes (§2.2 witness chain — ADR-262 P2 prerequisite)
+
+Beyond-SOTA crypto+security review of the SHA-256 + Ed25519 witness chain
+(`witness.rs` / `witness_signing.rs`) and the manifest signature surface
+(`manifest.rs`), because ADR-262 P2 proposes to **reuse this exact signing
+chain**. Top priority was the sibling `wifi-densepose-engine` bug class —
+unframed boundary-to-boundary concatenation of operator-influenceable strings
+into a signed/hashed digest.
+
+- **Engine bug class ABSENT (good result, reported with byte evidence).**
+  `canonical_bytes` is `DOMAIN_TAG ‖ prev_hash[32] ‖ seq:u64-be ‖ ts:u64-be ‖
+  kind_len:u32-be ‖ kind ‖ payload_len:u32-be ‖ payload`. The two
+  variable-length operator-influenceable fields (`kind`, `payload`) are
+  **length-prefixed**; the fixed-width fields are self-delimiting → the
+  encoding is injective (no two distinct event tuples share a preimage). The
+  Ed25519 signature signs the **identical** bytes the SHA-256 chain commits to.
+  No separate unframed concatenation exists; the manifest `binary_signature`
+  is signed at build time (Makefile) over a single fixed-length `binary_sha256`
+  hex value, not in-crate.
+
+- **CHM-WIT-01 (FIXED) — domain-separation tag added.** The engine fix
+  prescribed *domain-tag + length-prefix*; length-prefix was present, the
+  domain tag was not. Added a versioned, NUL-terminated
+  `WITNESS_DOMAIN_TAG = b"cog-ha-matter/witness-event/v1\x00"` prefix so the
+  witness message can never be replayed as a message for another Ed25519
+  context that shares key infrastructure (notably the manifest signature).
+  **Witness bytes change by design** (prior on-disk hashes/signatures
+  invalidated, as with the engine fix); verified safe because no in-repo crate
+  consumes cog-ha-matter witness bytes programmatically (doc-mentions only).
+
+- **CHM-WIT-02 (HARDENED) — `verify_signature` now uses `verify_strict`.** For
+  an audit chain the signature is the attestation, so non-canonical encodings
+  and small-order keys are rejected (RFC 8032 strict), giving the "one
+  canonical signature per event" property. Not a forgery fix — the verifying
+  key is caller-pinned, never read from the event.
+
+- **Confirmed clean (with evidence):** verify-before-trust + key-pinning
+  (`verify_signature` takes the verifying key as a parameter; `read_jsonl`
+  re-derives every hash and chain-verifies); key handling (the crate never
+  generates/stores/logs/serializes a signing key — only a documented test-only
+  fixed seed; production keys come from the Seed secure store, out of scope);
+  determinism (positional bytes, deterministic Ed25519, alphabetically-locked
+  JSONL field order, sorted TXT records — no HashMap/float nondeterminism feeds
+  any digest); fail-closed parsing (structured errors, no panics; `main.rs`
+  reads no untrusted files/paths).
+
+Tests: `cog-ha-matter --no-default-features` 64 → **68**, 0 failed (CHM-WIT-01
+pinned by 4 fails-on-old tests across `witness.rs`/`witness_signing.rs`;
+CHM-WIT-02 guarded by a key-pinning test). Python deterministic proof
+unchanged (cog-ha-matter is off the signal proof path).
+
 ## 5. References
 
 - ADR-101 — `cog-pose-estimation` packaging precedent (signed binaries on GCS, .cog manifest)

api-docs/adr/ADR-127-homecore-state-machine-rust.md

@@ -190,4 +190,78 @@ The entity registry is a `RwLock<HashMap<EntityId, EntityEntry>>` backed by an a
 
 - `v2/crates/wifi-densepose-sensing-server/src/main.rs` — Axum + Tokio architecture pattern used throughout the existing server stack
 - `docs/adr/ADR-126-ruview-native-ha-port-master.md` — HOMECORE master; §5.5 crate naming; §6 compatibility contract; §5.1 RUVIEW-POLICY
+
+---
+
+## 9. Security & concurrency review (P1 core, beyond-SOTA sweep)
+
+Foundational review of the `homecore` crate — the state store + event bus +
+service/entity registries every other HOMECORE module trusts. Same rigor as
+the ADR-129/130/132/133/161 sibling reviews. **Three real fixes (one
+concurrency, two hardening), each pinned by a fails-on-old test; the bus-lag
+and lock-discipline dimensions confirmed clean with evidence.**
+
+- **HC-RACE-01 (state-set TOCTOU — lost / reordered `state_changed`, the
+  crux). FIXED.** `StateMachine::set` did `get()` (releasing the DashMap
+  shard lock) → compute the next snapshot + the no-op / `last_changed`
+  decision → `insert()` (re-acquiring the lock) → `send()`. The
+  read-modify-write was **not atomic** w.r.t. a concurrent writer on the
+  same entity, contradicting §2.1's promise that "the writer atomically
+  replaces the map entry." A writer that read a stale `old` could
+  mis-classify a genuine transition as a no-op and **drop its
+  `state_changed` event** (a missed automation trigger) or fire an event
+  whose `new_state` duplicated the previously delivered one (a spurious
+  trigger for any automation keyed on `old_state != new_state`). **Fix:**
+  hold the shard write-lock across the entire read→decide→insert→fire
+  sequence via `entry()`/`insert_entry()`; `tx.send` is non-blocking,
+  non-async, and never re-enters the map, so firing under the shard lock
+  cannot deadlock and keeps global event order in lock-step with global
+  commit order. Pinned by `concurrent_set_fires_no_duplicate_adjacent_events`
+  (4 writers toggling one entity A/B; asserts no two consecutive fired
+  events carry an identical `new_state` — impossible under correct
+  serialisation; a probe observed ~93k such duplicate-adjacent events across
+  200 trials on the racy code, zero on the fix).
+- **HC-EID-LEN-01 (unbounded `entity_id` — memory-DoS at the REST boundary).
+  FIXED.** `homecore-api/src/rest.rs` parses untrusted path segments
+  straight through `EntityId::parse`; with no length cap, an
+  otherwise-valid id (`a.` + many MB of `[a-z0-9_]`) was accepted and a
+  `POST /api/states/<giant>` would persist it into the DashMap state store
+  (permanent growth across distinct ids). **Fix:** reject ids longer than
+  `MAX_ENTITY_ID_LEN` (255, HA-compatible) up front in `parse()`, before any
+  per-char scan, with a new `EntityIdError::TooLong`; fail-closed at the
+  boundary type protects every caller. Pinned by `entity_id_length_boundary`
+  (exactly-MAX accepted, MAX+1 and a 4 MiB id rejected — fails on old code).
+- **HC-SVC-PANIC-01 (service-handler panic not isolated). HARDENED.**
+  `ServiceRegistry::call` already ran handlers outside the registry lock (no
+  `RwLock` poisoning, no blocking of other callers — clean), but a
+  panicking handler unwound through `call()` into the caller's task. **Fix:**
+  wrap the handler future in `AssertUnwindSafe` + `catch_unwind`, converting
+  a panic to `ServiceError::HandlerPanicked`; the registry stays fully
+  usable. Pinned by `panicking_handler_is_isolated_and_registry_survives`.
+
+**Dimensions confirmed clean (with evidence):**
+
+- **Event-bus bounds / lag (same class as the homecore-api WS lag-DoS).**
+  Both `StateMachine` and `EventBus` use bounded `tokio::sync::broadcast`
+  (capacity 4,096). A slow subscriber gets a recoverable `Lagged(n)`
+  (drop-oldest + re-sync); `fire_*` is non-blocking and **never waits on
+  slow receivers**, so a lagging subscriber cannot block the publisher, grow
+  the channel without bound, or take down a fast subscriber. Evidenced by
+  `slow_subscriber_does_not_block_publisher_or_kill_the_bus` (fire 3×
+  capacity at an idle subscriber; publisher unblocked, bus stays live).
+- **Lock ordering / lock-across-await (deadlock).** No code path holds two
+  of `{state DashMap, registry RwLock, service RwLock}` simultaneously, so
+  no inconsistent-ordering deadlock can exist. Every `tokio::sync::RwLock`
+  guard in `registry.rs`/`service.rs` is used in a single synchronous
+  statement and dropped before any `.await`; `call` explicitly scopes the
+  read guard out before awaiting the handler. The only guard held across a
+  send is the DashMap shard lock in `set`, across a synchronous
+  (non-await) broadcast send — safe.
+- **Panic-on-input.** No reachable `unwrap`/`expect`/index in non-test code
+  beyond the safe `send().unwrap_or(0)` and the dead-but-harmless
+  `split_once(...).unwrap_or(...)` fallbacks on already-validated ids.
+
+`cargo test -p homecore --no-default-features`: **20 → 24 passed, 0 failed**
+(+4 pins). Workspace green; Python deterministic proof unchanged
+(`f8e76f21…46f7a`, bit-exact — `homecore` is off the signal proof path).
 - `docs/adr/ADR-028-esp32-capability-audit.md` — witness chain pattern (Ed25519 per state transition)