fix: ESP32 vitals over-count + presence flicker (#998/#996) + Observatory per-person position/motion (#1050) (#1060)

* fix(firmware): gate phantom persons + add presence hysteresis (#998, #996)

Two ESP32 edge-vitals logic bugs in edge_processing.c. Both are
robustness/logic fixes — NOT validated-accuracy claims. True count/PCK
vs labelled ground truth remains hardware/data-gated (COM9 ESP32-S3).

#998 — n_persons over-counted (reported 4 for one person):
update_multi_person_vitals() split 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 two pure, host-testable helpers:
  - count_distinct_persons(): per-group energy gate
    (EDGE_PERSON_MIN_ENERGY_RATIO) + spatial dedup
    (EDGE_PERSON_MIN_SC_SEP) so weak/adjacent multipath groups don't
    count as separate bodies. Strongest group always counts (>=1).
  - person_count_debounce(): a gated count must hold
    EDGE_PERSON_PERSIST_FRAMES consecutive frames before it's emitted,
    so a single noisy frame can't promote a phantom.
The active flags now mark only the strongest stable_count groups.

#996 — presence flag flickered at ~50cm despite high presence_score:
the bare `score > threshold` compare chattered on a noisy score
(field-observed 2.6-26.7 frame-to-frame). Replaced with a Schmitt
trigger + clear-debounce (presence_flag_update): assert above
threshold, hold in the dead band down to threshold *
EDGE_PRESENCE_HYST_RATIO, clear only after EDGE_PRESENCE_CLEAR_FRAMES
consecutive sub-low frames. presence_score itself is unchanged and
still emitted for consumer-side thresholding.

All thresholds are named, documented constants in edge_processing.h.
Firmware builds clean for esp32s3 (idf.py build RC=0).

Co-Authored-By: claude-flow <ruv@ruv.net>

* test(firmware): host C99 tests for vitals count + presence logic (#998, #996)

test/test_vitals_count_presence.c pins the two fixes with deterministic
host-buildable tests (no ESP-IDF needed). 13 cases / 22 assertions, all
passing under gcc 13 -Wall -Wextra:

  #998 count gate: single strong signature + multipath -> count==1;
  two well-separated -> 2; two strong-but-adjacent -> 1 (dedup);
  no signal -> 0; three well-separated -> 3.
  #998 debounce: transient spike rejected; sustained change accepted;
  flapping count stays stable.
  #996 presence: dithering trace -> stable flag (no flicker); brief dips
  held by clear-debounce; genuine departure clears within hold window;
  dead-band holds state.

The named tuning constants are #include'd from the real
edge_processing.h so the test and firmware can never disagree on
thresholds. `make run_vitals` / `make host_tests` added; binaries
gitignored.

Hardware-gated caveat documented in the test header: these pin the
decision LOGIC; the exact energy/separation/hysteresis values that best
match a real room vs labelled occupancy remain on-device tuning.

Co-Authored-By: claude-flow <ruv@ruv.net>

* docs: record ESP32 vitals count/presence fixes (#998, #996)

CHANGELOG [Unreleased] Fixed: root cause + fix + named constants + test
+ explicit hardware/data-gated caveat for both bugs.

ADR-021 Implementation Notes: dated 2026-06 entry noting the edge-path
person-count + presence-flicker fixes are boolean/count emission-logic
fixes, not a validated-accuracy claim; thresholds pending on-device
calibration.

Co-Authored-By: claude-flow <ruv@ruv.net>

* fix(sensing-server): emit real field-derived person position/motion to /ws/sensing (#1050)

The Observatory 3D figure never animated because the sensing_update WS
frame carried no per-person position/motion_score/pose — only image-space
keypoints. The FigurePool/PoseSystem (and demo-data.js's own contract)
animate each figure from persons[i].position (room-world), .motion_score
(0..100), and .pose; none were on the live stream.

Honest scope (Case 2): the pipeline has no calibrated per-person room
localizer or per-person skeletal pose. New field_localize module extracts
the strongest peak(s) from the real signal_field grid (subcarrier
variances x motion-band power) and maps the peak cell to Observatory world
coords with the exact _buildSignalField transform. motion_score is the
measured motion_band_power passed through; pose is set only from a real
aggregate posture estimate, else None (never a fabricated skeleton).
Empty/below-threshold field -> persons: [] (no phantom); present person
with no resolvable peak keeps position [0,0,0], not invented coords.

attach_field_positions runs after the tracker step at all five broadcast
sites. New position/motion_score/pose fields added to both PersonDetection
structs. No UI change needed — the Observatory already reads these fields.

Tests: field_localize peak/coordinate/empty/separation units +
observatory_persons_field_position_tests (known-peak -> emitted position,
empty-room -> no phantom, pose real-or-None, below-threshold honesty).
sensing-server bin 441->451, 0 failed.

Co-Authored-By: claude-flow <ruv@ruv.net>

* docs(changelog): record #1050 Observatory persons position/motion fix

Co-Authored-By: claude-flow <ruv@ruv.net>

.gitignore

@@ -16,6 +16,15 @@ firmware/esp32-csi-node/sdkconfig.defaults.bak
 # ESP-IDF set-target backup (local only)
 firmware/esp32-hello-world/sdkconfig.old
 
+# Host-built firmware test binaries (compiled from test/*.c, not source)
+firmware/esp32-csi-node/test/test_adr110
+firmware/esp32-csi-node/test/test_vitals
+firmware/esp32-csi-node/test/fuzz_serialize
+firmware/esp32-csi-node/test/fuzz_edge
+firmware/esp32-csi-node/test/fuzz_nvs
+firmware/esp32-csi-node/test/*.exe
+firmware/esp32-csi-node/test/*.obj
+
 # Claude Flow swarm runtime state
 .swarm/
 

CHANGELOG.md

@@ -8,12 +8,18 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ## [Unreleased]
 
 ### Security
+- **ADR-157 Milestone-1 B4 - constant-time HMAC sync-beacon tag compare (`wifi-densepose-hardware`).** `AuthenticatedBeacon::verify` compared the 8-byte HMAC-SHA256 tag with `self.hmac_tag == expected`, which short-circuits on the first differing byte and leaks, through verification latency, how many leading bytes an attacker's forged tag matched - a byte-by-byte tag-recovery oracle (~256*N trials instead of 256^N). Replaced with a hand-rolled branch-free `constant_time_tag_eq` (XOR-accumulate every byte difference into a single `u8`, no early exit, `#[inline(never)]` + `core::hint::black_box` to stop the optimizer reintroducing a short-circuit or a non-constant-time `memcmp`). **No new dependency** - ADR-157 had deferred this only to avoid adding the `subtle` crate; a fixed 8-byte compare needs none. Grade MEASURED (constant-time *construction*; micro-timing on a noisy host is a smoke check only, gated `#[ignore]`). Pinned by `tag_compare_is_constant_time_shape` (equal/first-differ/last-differ/all-differ/length-mismatch + an end-to-end `verify()` last-byte tamper), proven to fail on a last-byte-skipping constant-time bug. ADR-157 §8 B4 -> RESOLVED.
 - **ADR-080 open HIGH findings closed on the Rust `wifi-densepose-sensing-server` boundary (ADR-164 G11).** The QE sweep's three HIGH findings — XFF-spoofing bypass, leaked stack traces, JWT-in-URL (CWE-598) — were logged against the Python v1 API and never re-verified against the shipped Rust sensing-server; the HOMECORE/M7 sweep (ADR-161) covered `homecore-server`, not this crate.
   - **#2 leaked internal errors (the one live exposure) — FIXED.** Six handlers in `main.rs` serialized the internal error `Display` straight into the JSON response body: `edge_registry_endpoint` returned a panicked `spawn_blocking` `JoinError` (`"task … panicked"`) in a `500`, plus the raw upstream error in a `503`; `delete_model`/`delete_recording`/`start_recording` returned `std::io::Error` strings (OS detail / path); `calibration_start`/`calibration_stop` returned the `FieldModel` error chain. New `error_response` module logs the full detail **server-side only** (with a correlation id) and returns a generic body (`{"error":"internal_error","correlation_id":…}`) — no `panicked`, no file paths, no Debug chain. 5 module tests (a leak-substring guard proven to fail on the reverted old body) + the existing handler suite.
   - **#1 XFF-spoofing bypass — VERIFIED ABSENT, regression-pinned.** The sensing-server has no XFF-trusting control to bypass: there is no IP-based rate-limiter or IP-allowlist, and neither `bearer_auth` (token-only) nor `host_validation` (Host-header only) reads `X-Forwarded-For`/`X-Forwarded-Host` (no `forwarded`/`peer_addr`/`client_ip` anywhere in the crate). Added regression tests proving a spoofed `X-Forwarded-For` never flips an auth decision and a spoofed `X-Forwarded-Host` never bypasses the Host allowlist.
   - **#3 JWT-in-URL (CWE-598) — VERIFIED ABSENT, regression-pinned.** `require_bearer` reads the token only from the `Authorization` header; the WebSocket handlers take no token query param and the sole `Query` extractor (`EdgeRegistryParams`) is a non-secret `refresh` flag. Added a regression proving `?token=`/`?access_token=` in the URL never authenticates while the header path still does.
 
 ### Fixed
+- **ESP32 vitals: `n_persons` over-counted (reported 4 for one person) + presence flag flickered at close range (#998, #996).** Two firmware logic bugs in `firmware/esp32-csi-node/main/edge_processing.c`, both robustness/logic fixes — **not** validated-accuracy claims (true count/PCK vs labelled ground truth stays hardware/data-gated on the COM9 ESP32-S3).
+  - **#998 over-count — root cause + fix.** `update_multi_person_vitals()` split the top-K subcarriers into `top_k_count/2` groups and marked **every** group `active` unconditionally, so one body's multipath always reported the full `EDGE_MAX_PERSONS` (=4). New pure, host-testable `count_distinct_persons()` gates each candidate group: (1) **energy gate** — a group's phase variance must be ≥ `EDGE_PERSON_MIN_ENERGY_RATIO` (0.35) × the strongest group's, so weak multipath echoes don't count; (2) **spatial dedup** — groups whose representative subcarriers sit within `EDGE_PERSON_MIN_SC_SEP` (4) of each other are the same body. A `person_count_debounce()` then requires the gated count to hold `EDGE_PERSON_PERSIST_FRAMES` (3) consecutive frames before it's emitted, so a single noisy frame can't promote a phantom. The strongest group always counts (a present body yields ≥1). All thresholds are named, documented constants in `edge_processing.h`.
+  - **#996 presence flicker — root cause + fix.** Presence was a bare `score > threshold` compare on a noisy `presence_score` (field-observed 2.6–26.7 frame-to-frame for one stationary person), so the boolean chattered at the boundary while the score clearly indicated a person. New pure `presence_flag_update()` is a Schmitt trigger + clear-debounce: assert above `threshold`, **hold** in the dead band down to `threshold × EDGE_PRESENCE_HYST_RATIO` (0.5), and only clear after the score stays below the low threshold for `EDGE_PRESENCE_CLEAR_FRAMES` (5) consecutive frames. The score itself is unchanged (and still emitted at packet offset 20 for consumer-side thresholding). Constants named/documented in `edge_processing.h`.
+  - **Tests:** `firmware/esp32-csi-node/test/test_vitals_count_presence.c` (host C99, `make run_vitals`) — 13 cases / 22 assertions, all passing under gcc 13 `-Wall -Wextra`. Pins: single-strong-signature + multipath → count==1; two well-separated → count==2; two strong-but-adjacent → 1 (dedup); transient count spike rejected; sustained change accepted; dithering presence trace → stable flag (no flicker); genuine departure → clears within hold window. The named tuning constants are `#include`d from the real header so the test and firmware can't disagree. **Hardware-gated caveat:** these pin the decision *logic*; the exact energy/separation/hysteresis values that best match a real room vs labelled occupancy remain on-device tuning (COM9 ESP32-S3 + ground truth).
+- **Observatory 3D figure never animated — `/ws/sensing` omitted per-person `position`/`motion_score`/`pose` (#1050).** The `sensing_update` frame shipped `nodes`/`features`/`classification`/`signal_field` and a `persons[]` carrying only image-space `keypoints`/`bbox`/`zone`; the Observatory's `FigurePool`/`PoseSystem` (and `demo-data.js`'s own contract) animate each figure from `persons[i].position` (room-world `[x,y,z]`), `persons[i].motion_score` (0..100), and `persons[i].pose`, none of which the live stream emitted — so the figure sat static while signal metrics updated. **Honest scope (Case 2 — no calibrated per-person localizer exists):** a single ESP32 link does not produce calibrated room-coordinate localization or per-person skeletal pose, so the fix emits only what is *truthfully derivable*. New `field_localize` module reads the **strongest peak(s)** out of the frame's real `signal_field` grid (already built from measured subcarrier variances × measured motion-band power) and maps the peak cell to Observatory world coordinates with the **exact** `_buildSignalField` transform (`x=(ix−nx/2)·0.6`, `z=(iz−nz/2)·0.5`, `y=0`), so the figure lands on the field hotspot it stands on. `motion_score` is the measured `motion_band_power` passed through (clamped 0..100); `pose` is set **only** from a real aggregate `posture` estimate when one exists, else `None` (never a fabricated skeleton — per-person pose keypoints in room coordinates stay gated on the pose model + ADR-079 paired data). An empty / below-threshold field yields `persons: []` (no phantom person); a present person on a field with no resolvable peak keeps `position=[0,0,0]` (not invented coords) while `motion_score` stays real. `attach_field_positions` runs after the tracker step at all five broadcast sites. **No UI change required** — the Observatory already reads these fields and defaults `pose`→`'standing'` when absent. New `PersonDetection.position`/`motion_score`/`pose` fields added to both the `main.rs`-local and `types.rs` structs. Pinned by 10 tests: `field_localize` peak-extraction/coordinate-mapping/empty-field/separation unit tests + `observatory_persons_field_position_tests` (`sensing_update_emits_persons_with_field_derived_position` feeds a synthetic field with a known peak at cell (15,4) and asserts the emitted `position` = `[3.0, 0, −3.0]` within tolerance; `empty_room_yields_no_phantom_person`; `pose_is_real_when_posture_present_and_absent_otherwise`; `present_but_below_threshold_field_keeps_position_at_origin_not_fabricated`). `wifi-densepose-sensing-server --no-default-features`: bin **441→451**, 0 failed; workspace green; Python proof unchanged (off the deterministic proof path).
 - **ADR-155 Milestone-1b — metric-definition unification, the §8 backlog subset (Goals A/B/C).** Closed the two §8 metric-integrity items; every change pinned by a test, graded MEASURED. The audit (Goal A) also surfaced findings the §1 table under-counted — recorded honestly in ADR-155 §8.1, not hidden. Workspace stays green; Python proof unchanged (metrics are not on the deterministic proof's signal path).
   - **Goal B — `test_metrics.rs` now validates the production metric, not a reimplementation.** The integration test previously asserted properties of its OWN local `compute_pck`/`compute_oks` (a test that can't catch a canonical-impl bug — both could be wrong the same way). Hoisted the canonical core (`pck_canonical`/`oks_canonical`/`canonical_torso_size`/sigmas/`bounding_box_diagonal`) into a new **un-gated** `metrics_core` module so the single definition is reachable under `cargo test --no-default-features` (the `metrics` module is `tch-backend`-gated); `metrics` re-exports it → still exactly ONE implementation. Rewrote the test to assert the production `pck_canonical`/`oks_canonical` equal **hand-computed** fixtures (`canonical_pck_matches_hand_computed_fixture` = 3/4 correct ⇒ 0.75; hip↔hip normalizer pin; zero-visible⇒0.0; OKS perfect⇒1.0; fake-Gold pin) plus a differential cross-check (`test_kernel_agrees_with_canonical`: an independent raw-threshold kernel must AGREE with canonical where torso==1.0). `wifi-densepose-train --no-default-features`: test_metrics **10→12**, 0 failed.
   - **Goal C — divergent live-server PCK/OKS relabelled so they're never conflated with canonical.** Goal C named `training_api.rs:804` (torso-HEIGHT PCK); the audit found that file is an **orphan (not `mod`-declared, does not compile)** and the **real** live `best_pck`/`best_oks` come from `trainer.rs` — a **raw, unnormalized** `pck_at_threshold` and an **`area=1.0` fake-Gold** `oks_map` (both MISSED by ADR-155 §1, both on the claim-inflating side, both serialized as bare "PCK@0.2"/"OKS"). Torso-height/raw math is load-bearing (pixel-space, different scale axis, no `ndarray`/train dep), so the honest fix is **relabel, not force-unify**: `training_api.rs` `compute_pck` → `compute_pck_torso_height` + field/log docs; `trainer.rs` kernels documented raw/fake-Gold; `main.rs` prints `pck_raw@0.2` / `oks_map(area=1.0 proxy)`. No wire-format field or `pub`-fn renames (no silent API break). Pinned by `torso_pck_is_labelled_distinctly_from_canonical` + `pck_at_threshold_is_raw_unnormalized_not_canonical`. `wifi-densepose-sensing-server --no-default-features`: lib **450→451**, 0 failed. True unification onto `pck_canonical`/`oks_canonical` remains a tracked ADR-155 §8 item.
@@ -26,9 +32,18 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - **Published HuggingFace model was unloadable — RVF format mismatch (#894).** The `ProgressiveLoader` rejected the published `ruvnet/wifi-densepose-pretrained` model with the opaque `invalid magic at offset 0: expected 0x52564653 (RVFS), got 0x77455735`, then silently fell back to signal heuristics (the "10 persons for 1" garbage reporters saw). The HF repo ships `model.safetensors`, `model-q{2,4,8}.bin` (magic `0x77455735` = "5WEw"), and `model.rvf.jsonl` — none carry the binary-RVF magic. New `model_format` module **auto-detects** RVFS / safetensors / HF-quant-bin / JSONL by magic+name, returns a **typed actionable** `ModelLoadError` (lists accepted formats + the one-command convert path — never the opaque magic), and **converts** `model.safetensors` / `model.rvf.jsonl` → RVF in-memory so the published full-precision model now loads via `--model`. A `--convert-model <in> --convert-out <out>` CLI subcommand gives a one-command offline path; the silent heuristics fallback is now a loud, actionable error. **Honest scope:** the converter wires the format/load path (safetensors F32 tensors → RVF weight segment, manifest written, Layer A/B/C all succeed, weights round-trip) — it does **not** claim end-to-end pose accuracy, since the HF pose-decoder architecture differs from this crate's inference head (still data-gated in #894). Quantized `.bin` blobs are rejected with a typed error pointing at the safetensors path. Pinned by `safetensors_converts_and_loads` + `hf_quant_classifies_to_actionable_error` (both fail on the old opaque-magic path).
 
 ### Changed
+- **ADR-157 Milestone-1 §5 #4 - native `wlanapi.dll` multi-BSSID throughput MEASURED on real hardware (`wifi-densepose-wifiscan`).** The ADR's prior status ("asserted but NOT implemented; live scanner is the ~2 Hz netsh shim") is now stale: `wlanapi_native.rs` already implements the real `WlanOpenHandle` -> `WlanEnumInterfaces` -> `WlanGetNetworkBssList` -> `WlanFreeMemory`/`WlanCloseHandle` FFI and `WlanApiScanner` already wires it native-first with a netsh fallback. This milestone **measured it on this box** (Intel Wi-Fi 7 BE201 320MHz, 2026-06-13): a new `benchmark_backend(backend, window)` drives each backend over the same fixed 10 s wall-clock window so netsh is timed independently (the prior `benchmark()` picked native-first and never measured netsh on a Windows box where native works). **MEASURED: native 21.42 Hz vs netsh 3.84 Hz = 5.57x** (mean 5.0 BSSIDs/scan, both paths); a separate native-only run measured 18.0 Hz. Native genuinely beats netsh - this is a real positive result, not a fabricated "10x". 50 back-to-back native scans completed 50/50 with no handle leak/degradation. Live-WLAN tests (`measure_native_vs_netsh_throughput`, `native_scans_dont_leak_handles`, `measure_native_scan_rate`) are `#[ignore]` for CI but were RUN here; `native_scan_runs_real_ffi_on_windows` is a non-ignored schema-valid pin. ADR-157 §5 #4 + §8 -> MEASURED (was ACCEPTED-FUTURE / CLAIMED-unmeasured).
 - **Mesh partition risk now demotes the privacy class and is witnessed (ADR-032).** The dynamic min-cut guard's `at_risk` signal was advisory-only (it fed the recalibration advisor). It now also contributes to the ADR-141 privacy demotion alongside fusion- and array-level contradictions: a mesh close to partitioning makes the fused belief less trustworthy, so the cycle emits at a more restricted class (monotonic — information only removed). Because `effective_class` feeds the BLAKE3 witness, a fragmenting array now shifts the witness — partition risk is auditable, not just logged. The mesh computation moved ahead of the demotion step in `process_cycle`; new `mesh_guard_mut()` exposes risk-threshold tuning. Test proves a forced-risk 3-node cycle demotes PrivateHome Anonymous→Restricted and shifts the witness vs a clean *same-topology* baseline (the only delta between the two cycles is the forced risk).
 
 ### Added
+- **ADR-155 Milestone-2 — cleared the host-verifiable subset of the §8 P3 backlog in `wifi-densepose-train` (+ the pure-Rust `rf_encoder.rs`/`densepose.rs` the §3/§4 items named).** Mirrors the ADR-154 M3 cleanup discipline. **Honest enumeration first (grep, not the ADR's "~40" estimate):** the actual non-tch train/nn surface is smaller — **7 de-magicked (const + `*_consts_unchanged_from_literals` pin == prior literal), 9 boundary/characterization tests, 1 added input guard (`rf_encoder::LinearHead::try_new`) + test, 2 doc-only fixes, 1 perf item bench-first → MEASURED-INCONCLUSIVE (not shipped)**. **This is cleanup — no operating value or behaviour changed:** each lifted literal is bit-identical to its prior value, each boundary test pins CURRENT behaviour. De-magicked: `metrics_core.rs` (`VISIBILITY_THRESHOLD`/`MIN_REFERENCE_EXTENT`/`OKS_FALLBACK_SIGMA`), `ruview_metrics.rs` (`NUM_KEYPOINTS`/`VISIBILITY_THRESHOLD`/`PCK_THRESHOLD`/`MIN_BBOX_DIAG`/`MIN_DURATION_MINUTES`), `subcarrier.rs` (6 `SPARSE_*` consts), `eval.rs` (`MIN_POSITIVE_MPJPE`), `domain.rs` (`LAYER_NORM_EPS`), `virtual_aug.rs` (`BOX_MULLER_U1_FLOOR`/`MIN_ROOM_SCALE`), `rf_encoder.rs` (`SOFTPLUS_LINEAR_THRESHOLD`). **§3 `rf_encoder.rs`:** added a pure-Rust fallible `LinearHead::try_new` → typed `RfHeadError` so untrusted/deserialized checkpoint weights can be shape-validated without the `new()` panic (`new` unchanged; additive). **§4 native-conv:** `densepose.rs::apply_conv_layer` (pure-Rust naive loop) was benched (committed `benches/native_conv_bench.rs`); a bit-identical range-clamped rewrite measured ~35% faster on padding-heavy small-channel maps but ~3% *slower* on channel-heavy maps, all inside a ±20% host-noise floor — **MEASURED-INCONCLUSIVE, so NOT shipped** (no fabricated number), characterized by `native_conv_matches_reference` and honestly deferred. **Skipped honestly (not-real / already-handled):** `ablation.rs` (NaN-sort + boundaries already fixed/tested in M1), `signal_features.rs` (consts already named, n=0 tested), `mae.rs` (no bare guard literals). `wifi-densepose-train --no-default-features`: **303 passed** (was 288, +15), 0 failed; `wifi-densepose-nn --no-default-features` lib: **38** (was 35, +3). Workspace `--no-default-features`: GREEN (single clean run). Python proof **VERDICT: PASS**, hash **`f8e76f21…46f7a` UNCHANGED, bit-exact** (asserted — the metrics path is off the deterministic signal proof path). **Remaining §8 backlog stays deferred-not-dropped:** GraphPose-Fi / ONNX-INT4 / CSI-JEPA (data/model-gated), ONNX read-lock (upstream `ort`-gated), tch-gated panic sites in `proof.rs`/`trainer.rs`/`model.rs` + `metrics.rs` `*_v2` dead-code (tch-gated — need a libtorch host). **The non-tch-verifiable subset of §8 is now cleared.**
+- **ADR-154 Milestone-3 — cleared the §7.4 row #21–45 P3 backlog in `wifi-densepose-signal` (the lumped "remaining clarity/doc/magic-constant/missing-boundary-test findings across `ruvsense/*`, `features.rs`, `motion.rs`").** Honest enumeration first (grep, not the ADR's estimate): the lumped row was **~25 findings → 22 real, de-magicked across 11 modules; 6 boundary/characterization tests added; ~4 doc-only; the rest were already-handled or not-real and are reported as such** (the "row #21–45" count was an estimate — there were not 25 *distinct* magic constants left after M0–M2). **This is cleanup — no operating value or behaviour changed:** every de-magicked literal becomes a named, documented EMPIRICAL-DEFAULT const that **equals the prior literal exactly** (each module ships a `*_consts_unchanged_from_literals` pin test), and every boundary test pins **current** behaviour so a future retune is a visible, tested change. Modules touched: `motion.rs` (#18, fusion weights/normalization/adaptive-threshold consts + 5 tests), `gesture.rs` (#12, `euclidean_distance` length-mismatch `debug_assert` documenting the silent-truncation contract + DTW n=0/m=0 boundary), `longitudinal.rs` (drift thresholds 7-day/2σ/3-day/7-day/EMA + day-6/7 + zero-vector cosine), `cross_room.rs`/`multiband.rs`/`intention.rs`/`hampel.rs` (division-guard epsilons + zero-norm/zero-variance/zero-MAD boundary + `half_window==0` error path), `rf_slam.rs` (`NS_PER_DAY` + fixed-map defaults + zero-span guard), `attractor_drift.rs` (buffer/recent-window consts + documented the implicit `recent.len()≥1` divide-safety + `min_observations` off-by-one boundary), `coherence.rs` (#9 completion — variance-floor + default-decay), `calibration.rs` (#2 — `DEFAULT_MIN_FRAMES` deduped across 4 tier constructors + motion/subtract thresholds), `fusion_quality.rs` (contradiction penalty/bounds + n=0 identity), `temporal_gesture.rs` (confidence epsilon + quantization scale). **A "magic" the agents flagged that was NOT real:** an `attractor_drift.rs:301` "divide-by-zero" is unreachable (the `count < min_observations` guard guarantees `recent.len()≥1`) — documented + boundary-tested rather than guarded, per the no-behaviour-change rule. Signal crate lib `--no-default-features`: **476 passed, 0 failed, 1 ignored**; `--no-default-features --features cir`: **476 passed, 0 failed** (plain `--features cir` is unbuildable on this Windows host — the default `eigenvalue` feature pulls `openblas-src`, the same BLAS gate documented in M2 #8). Workspace `--no-default-features`: **3,275 / 0 failed** (single clean run). Python proof **VERDICT: PASS**, hash **`f8e76f21…46f7a` UNCHANGED, bit-exact** (asserted explicitly — these modules are off the deterministic PSD/Doppler proof path, and the de-magicked consts are bit-identical regardless). **This clears ADR-154's §7.4 deferred backlog to zero across M0–M3.**
+- **ADR-154 Milestone-2 — bench-first P2 perf subset + missing boundary tests (`wifi-densepose-signal`, §7.4 #5/#6/#7/#8/#14/#16/#19/#20).** PROOF discipline (ADR-154 §0): every perf item was **benched before being touched** (new committed `benches/dsp_perf_bench.rs`, criterion, this Windows box); only the one item the bench proved hot was optimized, the rest are committed MEASURED-NULLs — a benched null is the proof the micro-opt was unnecessary, the §5.1 "already amortized" pattern. Every behaviour-changing edit is pinned bit-identical (or documented-tolerance). Signal crate lib `--no-default-features`: **447 passed, 0 failed, 1 ignored**; `--features cir`: **447 passed, 0 failed**.
+  - **#20 MEASURED-HOT, optimized (bit-identical).** `compute_multi_subcarrier_spectrogram` re-planned a fresh `FftPlanner` for *every* subcarrier (via `compute_spectrogram`). Hoisted the plan + window out of the per-subcarrier loop (new `compute_spectrogram_with_plan` core; `compute_spectrogram` delegates, unchanged). **56-subcarrier: 467.88 µs → 254.75 µs = 1.84×** (window 128); **627.27 µs → 448.39 µs = 1.40×** (window 256). Bit-identical via `multi_subcarrier_hoisted_plan_bit_identical` (`f64::to_bits` of every value across all 4 window functions × {power,magnitude}). The §7.4 intro's predicted "most likely real win" — confirmed.
+  - **#5 / #6 / #7 MEASURED-NULL, left as-is.** `node_attention_weights` 181 ns (2 nodes)…848 ns (8) — sub-µs, no hot-path alloc. `tomography reconstruct` (full 50-iter ISTA, 256 voxels) 47.5 µs (16 links) / 60.4 µs (32) — the 2 voxel buffers are already alloc-once + `.fill`-reused, negligible vs O(iters·links·voxels). `pose_tracker` Kalman cycle 150 ns (17 keypoints) / 2.82 µs (170) — the "gain matrices" are fixed-size **stack** arrays, zero heap to reuse. No rewrite shipped; the committed benches prove each is not hot.
+  - **#8 MEASUREMENT-ONLY, BLAS-gated (number deferred, not fabricated).** Correction to the finding: `extract_perturbation` does **not** recompute the SVD (it projects against cached `finalize_calibration` modes); the real per-call eigendecomposition is the `eigenvalue`-feature `estimate_occupancy` (`cov.eigh()` on a 56×56 covariance). The `eig` bench is committed but `openblas-src` won't build on this Windows host ("Non-vcpkg builds are not supported on Windows" — the exact reason the project gate runs `--no-default-features`), so its µs cost must come from a Linux/BLAS box. Recorded, not estimated. Incremental SVD stays a sized future item.
+  - **#14 / #16 / #19 RESOLVED — tests added (no behaviour change).** `fft_operator_within_tolerance_of_dense_canonical56` pins the full `Cir` output of the opt-in FFT path within a documented relative tolerance of the dense path on the production canonical-56 config (τ ∈ {20,50,90} ns) — it changes the witness hash, so it must be provably *close*, not silently divergent. `refinement_terminates_at_iteration_cap_when_not_converging` (+ convergent companion) proves the LO-offset refinement terminates at exactly `max_iterations` on a non-converging input (cap, not convergence, bounds the loop; internal `…_counted` refactor returns the identical offsets). `ratio_finite_at_and_below_1e_12_epsilon` pins that the conjugate-product CSI-ratio (no division → no `1e-12` divide-guard needed) is finite + bit-exact at/below the epsilon boundary and at exact zero (where a naive `H_i/H_j` ratio is ±inf/NaN).
+- **ADR-156 §11 Milestone-2: RaBitQ unbiased distance estimator — IMPLEMENTED & MEASURED (RESOLVED-NEGATIVE on the strict-K bar).** Closes the §10.5 / §8 backlog "full RaBitQ residual-distance estimator (not just a uniform scalar code)" item — the **real** Gao & Long (SIGMOD 2024) contribution, not just sign bits. New `wifi-densepose-ruvector/src/estimator.rs`: `EstimatorSketch` carries the Pass-2 sign code (over the padded FHT length `D = next_pow2(dim)`) **plus 8 B/vec side info** (`residual_norm` + `x_dot_o = ⟨x̄, o'⟩`, 2× f32); `DistanceEstimator` computes the **unbiased** estimate `⟨o',q'⟩ ≈ ⟨x̄,q'⟩ / x_dot_o` (the random rotation makes the 1-bit code's quantization error orthogonal-in-expectation to the query, paper `O(1/√D)` bound); `EstimatorBank::topk_estimated_cosine` reranks the candidate set by the estimate instead of raw Hamming. **Zero-centroid simplification (`c = 0`) stated honestly** — the paper-faithful per-cluster centroid path (`from_embedding_centred` / `EstimatorBank::with_centroid`) is also built so the simplification is a measured choice (no centroid coverage number is reported against the cosine ground truth, because cosine-of-residual ≠ cosine-of-raw would be a metric mismatch). **Purely additive + backward-compatible** — new types only; Pass-1 `Sketch` / Pass-2 `SketchBank` / `WireSketch` wire format unchanged; all external callers (`event_log.rs`, `signal/longitudinal.rs`, `sensing-server`) use Pass-1 and are unaffected. **MEASURED strict-K coverage** (same fixture/seeds as §10: dim=128 N=2048 K=8, 64 clusters, noise=0.35, 128 queries, 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, **still ~40 pp short of the ADR-084 ≥90% strict bar.** At over-fetch the estimator beats sign (candidate_k=24: **95.12%** vs 91.60%). **Honest verdict — RESOLVED-NEGATIVE: 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 bar is still met only via the over-fetch "candidate set" pattern ADR-084 specifies, though the estimator **reduces the over-fetch factor** needed. A published negative, reported as such — no benchmark tuned to manufacture a pass. Unbiasedness pinned by `estimator_unbiased_on_fixture` (Monte-Carlo mean over 4000 rotation seeds → true inner product within tolerance); not-worse-than-sign pinned by `estimator_rerank_not_worse_than_sign`; determinism by `estimator_is_deterministic`. +12 tests in the crate (119→131). Workspace **3,228 / 0 failed** (`cargo test --workspace --no-default-features`, 162 test binaries, single clean run), Python proof **VERDICT: PASS** (`f8e76f21…46f7a`, unchanged — estimator is not on the proof's signal path). Full numbers + reproduce commands in ADR-156 §11 / ADR-084 "Pass 2b".
 - **ADR-156 §8 Milestone-1: RaBitQ Pass-2 randomized rotation + multi-bit experiment — IMPLEMENTED & MEASURED (RESOLVED-PARTIAL).** Closes the §8 "Multi-bit / Extended RaBitQ" backlog item. New `wifi-densepose-ruvector/src/rotation.rs`: a deterministic randomized orthogonal rotation `R = H·D` — **Fast Hadamard Transform** (`O(d log d)`, in-place, `1/√m`-normalized so norm-preserving) + seeded ±1 sign flips (SplitMix64 from a stored `u64` seed; identical at index + query time). Chosen over a dense `d×d` matrix (`O(d²)`, infeasible at the 65,535-d the wire format provisions for); pads to `next_pow2(d)`. Additive, backward-compatible API (`Sketch::from_embedding_rotated`, `SketchBank::with_rotation` + `insert_embedding`/`topk_embedding`/`novelty_embedding`); Pass-1 and the wire format are byte-for-byte unchanged. New `coverage.rs` single-source-of-truth top-K coverage harness (anisotropic planted-cluster fixture, cosine ground truth) backs both a `#[test]` report and the `sketch_bench` coverage table. **MEASURED (dim=128 N=2048 K=8, 64 clusters, noise=0.35, 128 queries, seeded):** at the strict `candidate_k=K` bar, rotation lifts coverage **36.13% → 46.39%**; Pass-2 reaches the **ADR-084 ≥90% bar at candidate_k=24 (~3× over-fetch)**; multi-bit Pass-3 reaches 54%/67%/74% at 2/3/4-bit (strict bar). **Honest verdict: neither rotation nor ≤4-bit multi-bit clears the strict-K 90% bar on this distribution — the bar is met only via the over-fetch "candidate set" pattern ADR-084 specifies.** No benchmark was tuned to manufacture a pass; the strict-bar gap is documented (ADR-156 §10, ADR-084 "Pass 2" section). +19 tests in the crate (100→119), workspace **3,225 / 0 failed**, Python proof VERDICT: PASS (`f8e76f21…`, unchanged — sketch is not on the proof's signal path).
 - **Beyond-SOTA `v2/crates/` sweep (ADR-154–158) + full stub-implementation push — every claim MEASURED or graded.** A 5-milestone review/optimize/secure/benchmark/validate sweep, then a verified-audit-driven push to replace every production stub with real, tested logic (no labels, no placeholders). Each fix is pinned by a test that fails on the old code; every number ships with a reproduce command. Workspace: **3,122 tests / 0 failed** (`cargo test --workspace --no-default-features`), Python proof **VERDICT: PASS** (bit-exact).
   - **ADR-154 Signal/DSP** — revived a dead ADR-134 CIR coherence gate (canonical-56 vs ht20 mismatch meant it never ran in production: 8/8 Err → 8/8 Ok); NaN-bypass + window div0 guards; PSD FFT-planner cache (**2.0–3.1×**) + honored DTW band (**2.4–4.1×**).

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

@@ -1081,6 +1081,17 @@ 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.
+
 ## References
 
 - Ramsauer et al. (2020). "Hopfield Networks is All You Need." ICLR 2021. (ModernHopfield formulation)

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

@@ -289,6 +289,35 @@ ADR-156 §10. Summary:
   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

docs/adr/ADR-154-signal-dsp-beyond-sota.md

@@ -7,7 +7,7 @@
 | **Deciders** | ruv |
 | **Codebase target** | `wifi-densepose-signal` (`ruvsense/`, `features.rs`, `csi_processor.rs`, `spectrogram.rs`, `bvp.rs`), benches, docs |
 | **Relates to** | ADR-134 (CIR sparse recovery), ADR-135 (Empty-Room Baseline), ADR-029/030/032 (Multistatic mesh + security), ADR-152 (WiFi-Pose SOTA 2026 intake), ADR-153 (802.11bf forward-compat) |
-| **Scope** | Milestone 0 of the beyond-SOTA signal/DSP sweep: high-leverage **correctness/security fixes**, two **measured** perf wins, the per-module SOTA landscape with evidence grades, and a prioritized roadmap. **45 review findings are explicitly deferred** (§7 backlog) — nothing is silently dropped. |
+| **Scope** | Milestone 0 of the beyond-SOTA signal/DSP sweep: high-leverage **correctness/security fixes**, two **measured** perf wins, the per-module SOTA landscape with evidence grades, and a prioritized roadmap. **45 review findings were explicitly deferred** (§7 backlog) — **now all addressed across Milestones 0–3** (§7.4 backlog cleared 2026-06-13); nothing was silently dropped. |
 
 ---
 
@@ -199,33 +199,37 @@ The §2–§5 fixes are **ACCEPTED and committed**: dead CIR gate fixed, NaN byp
 
 Catalogued so nothing is silently dropped. Priority: **P1** correctness-adjacent, **P2** perf, **P3** clarity/style.
 
-**Milestone-1 update (2026-06-13):** the **four P1 backlog items** (#1, #9, #10, #13) are now cleared — #1 and #10 **RESOLVED (MEASURED)**, #9 and #13 **RESOLVED-PARTIAL (DATA-GATED:** de-magicked + boundary-tested, operating values unchanged**)**. ~41 P2/P3 items remain deferred. Each fix is pinned by a regression test that fails on the old behaviour (commits `fd32f094a`, `4a9f2bcf4`, `d672fa602`, `5193f6369`); workspace `--no-default-features` green, Python proof unchanged (bit-exact).
+**Milestone-1 update (2026-06-13):** the **four P1 backlog items** (#1, #9, #10, #13) are now cleared — #1 and #10 **RESOLVED (MEASURED)**, #9 and #13 **RESOLVED-PARTIAL (DATA-GATED:** de-magicked + boundary-tested, operating values unchanged**)**. Each fix is pinned by a regression test that fails on the old behaviour (commits `fd32f094a`, `4a9f2bcf4`, `d672fa602`, `5193f6369`); workspace `--no-default-features` green, Python proof unchanged (bit-exact).
+
+**Milestone-2 update (2026-06-13):** the **bench-first P2 perf subset** (#5, #6, #7, #8, #20) and the **three missing boundary tests** (#14, #16, #19) are now cleared — ~36 P2/P3 items remained deferred *(now cleared — see the Milestone-3 update)*. PROOF discipline (§0): every perf item was **benched before being touched** — committed in `benches/dsp_perf_bench.rs` (criterion, this Windows box). Only **#20** proved hot and was optimized; **#5/#6/#7** are committed **MEASURED-NULLs** (benched, not hot, left as-is for clarity — exactly the §5.1 "already amortized" pattern); **#8** is **MEASUREMENT-ONLY** but its `eigenvalue`/BLAS backend won't build on this Windows host, so its µs cost must come from a Linux/BLAS box (recorded, not fabricated). Commits `e839fa8f1` (#20 fix), `02e5dd13a` (#14/#16/#19 tests), `aad9464f0` (benches). Workspace `--no-default-features` green; Python proof unchanged (#20 is bit-identical, off the proof path).
+
+**Milestone-3 update (2026-06-13):** the lumped **row #21–45** P3 backlog — *"remaining clarity/doc/magic-constant/missing-boundary-test findings across `ruvsense/*`, `features.rs`, `motion.rs`"* — is now **cleared, and with it the residual P3 items #2/#12/#17/#18.** Honest enumeration first (`grep`, not the ADR's "21–45" estimate — that was a count, not 25 distinct findings): after M0–M2 the genuinely-bare in-function literals resolved to **22 de-magicked constants across 11 modules** (each → a named, documented **EMPIRICAL-DEFAULT** const that **equals the prior literal exactly**), **6 added boundary/characterization tests**, **~4 doc-only fixes** (no-behaviour-change), and **a handful of agent-flagged "findings" that were NOT real** and are reported as skipped (below). **No operating value or behaviour changed** — every module carries a `*_consts_unchanged_from_literals` pin test and every boundary test pins *current* behaviour, so a future retune is a visible, tested change. Resolution by module: `motion.rs` (**#18** — fusion weights / Doppler+variance+phase scales / confidence weights / adaptive-threshold clamp; 5 tests), `gesture.rs` (**#12** — `euclidean_distance` length-mismatch `debug_assert` documenting the silent-`zip`-truncation caller contract, behaviour-preserving in release; + confidence epsilon; + DTW n=0/m=0 boundary), `longitudinal.rs` (7-day/2σ/3-day/7-day drift thresholds + EMA-α + cosine epsilon; day-6/7 + zero-vector boundaries; the duplicated `>=7` deduped), `cross_room.rs`/`multiband.rs`/`intention.rs`/`hampel.rs` (**#17** — division-guard epsilons `1e-9`/`1e-12`/`1e-10`/`1e-15` + zero-norm/zero-variance/zero-MAD boundaries + the previously-untested `hampel half_window==0` error path + `# Errors` doc), `rf_slam.rs` (`NS_PER_DAY` + `MIGRATION_MIN_SPAN_DAYS` + fixed-map defaults; single-sighting zero-span guard), `attractor_drift.rs` (`METRIC_BUFFER_CAPACITY`/`STABLE_CENTER_WINDOW`; **documented** the implicit `recent.len()>=1` divide-safety; `min_observations` off-by-one boundary), `coherence.rs` (**#9 completion** — the residual bare `1e-6` variance-floor ×4 + default `0.95` decay; floor-effect test), `calibration.rs` (**#2 completion** — `DEFAULT_MIN_FRAMES` deduped across all 4 tier constructors + `AMP_STD_FLOOR`/`MOTION_AMP_Z_THRESHOLD`/`MOTION_PHASE_DRIFT_THRESHOLD`/`SUBTRACT_MIN_NORM`), `fusion_quality.rs` (`CONTRADICTION_PENALTY` 0.8 / bound-halfwidth 0.1; n=0 identity boundary), `temporal_gesture.rs` (confidence epsilon + L2-norm quantization scale). **NOT-REAL / skipped (reported honestly, no churn manufactured):** an agent-flagged `attractor_drift.rs:301` "divide-by-zero" is **unreachable** — the `count < min_observations` guard guarantees `recent.len()>=1` before the `PointAttractor` branch (documented + boundary-tested, **not** guarded, per the no-behaviour-change rule); agent-flagged `gesture.rs` `2.0`/`π·6` motion thresholds **do not exist** in that file (a confusion with `calibration.rs::deviation`); **`features.rs` was deliberately left untouched** (it is on the deterministic Python-proof PSD/Doppler path — its `1e-10` guards already exist and are already correct; doc-only-skipped to protect the bit-exact hash). Commits `c794d1a0c` (motion #18), `adf9ed8e4` (gesture #12), `19f5b6335` (longitudinal), `19e0373c8` (epsilon helpers #17), `c6a09b69a` (rf_slam + attractor_drift), `5a1839f33` (coherence #9 completion), `df25a303e` (calibration #2 completion), `0f931ff2f` (fusion_quality + temporal_gesture). Signal crate lib `--no-default-features` **476 passed / 0 failed / 1 ignored**; `--no-default-features --features cir` **476 / 0**; workspace `--no-default-features` **3,275 / 0 failed** (single clean run); Python proof **VERDICT: PASS**, hash `f8e76f21…46f7a` **UNCHANGED (bit-exact)**. **§7.4 backlog is now fully cleared — ADR-154's deferred findings are addressed across M0–M3 with nothing silently dropped.**
 
 | # | Module | Finding | Pri | Why deferred |
 |---|--------|---------|-----|--------------|
 | 1 | cir.rs ~937 | `phase_variance` uses **linear** variance on **wrapped** angles (doc says "variance of phase angles") — spuriously inflates near ±π | P1 | **RESOLVED (`fd32f094a`) — metric MEASURED, threshold DATA-GATED.** Replaced with Mardia's circular variance V = 1 − R̄ ∈ **[0,1]**, invariant to the cluster's position on the circle (branch-cut artefact gone). Guard re-derived against the bounded metric via named const `GHOST_TAP_CIRCULAR_VARIANCE_MAX = 0.99` (fires only when R̄ ≤ 0.01 — essentially uniform phase). The **threshold value is DATA-GATED**: a clean single-path ramp also sweeps the circle, so V alone can't separate clean from unsanitized without labelled frames — the default is deliberately conservative (strictly more permissive at the wrap boundary than the buggy linear guard). Fails-on-old: `phase_variance_circular_not_fooled_by_branch_cut` (old linear variance > TAU on wrap-straddling phases while circular V≈0, guard no longer trips), `phase_variance_circular_is_bounded_and_extremal`. |
-| 2 | calibration.rs ~311 | `subtract_in_place` had a vacuous `if active_input {ki} else {ki}` branch implying a full-FFT→bin remap that didn't exist | P3 | **Resolved here** (branch removed, sequential-convention documented to match the sibling `extract_first_stream`). Listed for visibility — behavior unchanged. |
+| 2 | calibration.rs ~311 | `subtract_in_place` had a vacuous `if active_input {ki} else {ki}` branch implying a full-FFT→bin remap that didn't exist | P3 | **Resolved (M0 + M3 `df25a303e`).** Branch removed in M0 (sequential-convention documented). M3 completed the de-magic: `DEFAULT_MIN_FRAMES=600` deduped across all four tier constructors, plus `AMP_STD_FLOOR`/`MOTION_AMP_Z_THRESHOLD`/`MOTION_PHASE_DRIFT_THRESHOLD`/`SUBTRACT_MIN_NORM` named + `calibration_consts_unchanged_from_literals`. Behaviour unchanged. |
 | 3 | spectrogram.rs / bvp.rs | FFT planner built once-per-call (already amortized across frames) | P2 | Marginal vs the per-frame PSD site; cache if these become hot. |
 | 4 | features.rs ~347 | Doppler FFT planner planned once per call, reused across subcarriers | P2 | Already amortized within the call. |
-| 5 | multistatic.rs | `node_attention_weights` recomputes consensus/softmax each call; no SIMD | P2 | Needs a bench before touching; not obviously hot. |
-| 6 | tomography.rs | ISTA L1 solver re-allocates voxel buffers per solve | P2 | Bench first. |
-| 7 | pose_tracker.rs | Kalman gain matrices reallocated per update | P2 | Bench first. |
-| 8 | field_model.rs | SVD recomputed on every perturbation extract | P2 | Incremental SVD is a real project, not a micro-fix. |
+| 5 | multistatic.rs | `node_attention_weights` recomputes consensus/softmax each call; no SIMD | P2 | **MEASURED-NULL (`aad9464f0`) — benched, not hot, left as-is.** `multistatic_attention/weights`: **181 ns** (2 nodes) … **848 ns** (8 nodes) @ 56 subcarriers — sub-µs, no hot-path allocation. A precompute/SIMD rewrite buys nothing measurable at the realistic 2–8 node fan-in; the cosine/softmax cost is dwarfed by the surrounding fusion + per-frame FFT. Bench `multistatic_attention` in `dsp_perf_bench.rs`. |
+| 6 | tomography.rs | ISTA L1 solver re-allocates voxel buffers per solve | P2 | **MEASURED-NULL (`aad9464f0`) — benched, not hot, left as-is.** A full 50-iteration `reconstruct` (256 voxels): **47.5 µs** (16 links) / **60.4 µs** (32 links). The two voxel buffers (`x`, `gradient`; ~4 KB) are already allocated *once* per `reconstruct()` and `.fill`-reused across iterations — the per-solve alloc is a negligible fraction of the O(iters·links·voxels) inner product. Reusing scratch across *calls* would force `reconstruct(&self)`→`&mut self` (API break) for no measurable gain. Bench `tomography_reconstruct`. |
+| 7 | pose_tracker.rs | Kalman gain matrices reallocated per update | P2 | **MEASURED-NULL (`aad9464f0`) — benched, not hot, left as-is.** A Kalman predict+update cycle: **150 ns** (17 keypoints) / **2.82 µs** (170). The "gain matrices" (`s:[f32;3]`, `k:[[f32;3];6]`) are fixed-size **stack** arrays, *not* heap — there is no per-update allocation to reuse; the compiler keeps them in registers/stack. Bench `pose_kalman_update`. |
+| 8 | field_model.rs | SVD recomputed on every perturbation extract | P2 | **MEASUREMENT-ONLY (`aad9464f0`) — BLAS-gated, not measurable on this host.** Correction: `extract_perturbation` does **not** recompute the SVD — it projects against the cached `modes` from `finalize_calibration`. The real per-call eigendecomposition is in the `eigenvalue`-feature `estimate_occupancy` (`cov.eigh()` on a 56×56 covariance, an O(n³)≈175k-flop symmetric eigensolve + O(n²·frames) covariance build, run per call). The bench (`dsp_perf_bench`'s `eig` module) is committed, but `openblas-src` **fails to build on this Windows box** ("Non-vcpkg builds are not supported on Windows" — the very reason the project gate runs `--no-default-features`), so a measured µs number must come from a Linux/BLAS host; **not estimated/fabricated here.** Incremental SVD remains a sized future project, not a micro-fix. |
 | 9 | coherence.rs / coherence_gate.rs | Z-score thresholds are magic constants, untested at boundaries | P1 | **RESOLVED-PARTIAL (`5193f6369`) — DATA-GATED.** De-magicked `classify_drift` (`DRIFT_STABLE_SCORE=0.85`, `DRIFT_STEP_CHANGE_MAX_STALE=10`) and the `coherence_gate.rs` defaults (`DEFAULT_ACCEPT_THRESHOLD`/`…REJECT…`/`…MAX_STALE_FRAMES`/`…PREDICT_ONLY_NOISE`) into named, documented consts marked EMPIRICAL DEFAULT; added at/just-below/just-above boundary tests (`classify_drift_*_boundary`) + `*_consts_unchanged_from_literals`. **Operating values explicitly NOT changed** — defensible values still need labelled stable/drifting traces. The gate already exposed these via `GatePolicyConfig` (config seam). |
 | 10 | longitudinal.rs | Welford update not numerically guarded for n=0 | P1 | **RESOLVED (`4a9f2bcf4`) — MEASURED.** The shared `WelfordStats` (`field_model.rs`, consumed by longitudinal.rs) `count < 2` guards already prevent the n=0 NaN / n=1 div0 / `(count−1)` underflow, but the boundary was untested. Added `welford_finite_at_n0_and_n1` (finite + documented 0.0 sentinel at n=0/n=1). Fails-on-old proof: removing the `sample_variance` guard makes the test panic with "attempt to subtract with overflow" at the `(count − 1)` underflow. |
 | 11 | cross_room.rs | Fingerprint hash collisions unhandled | P2 | Low collision prob; needs design. |
-| 12 | gesture.rs | `euclidean_distance` no length-mismatch guard | P3 | Caller-enforced; add `debug_assert`. |
+| 12 | gesture.rs | `euclidean_distance` no length-mismatch guard | P3 | **RESOLVED (M3 `adf9ed8e4`).** Added a `debug_assert_eq!` on the two slice lengths + a doc block stating the same-`feature_dim` caller contract and that `zip()` silently truncates on a mismatch. Behaviour-preserving (no-op in release, the operating path). Also de-magicked the confidence `1e-10` epsilon and pinned the DTW `n=0`/`m=0` boundary (`dtw_empty_sequence_is_infinite`). |
 | 13 | adversarial.rs | Gini/consistency thresholds are magic constants | P1 | **RESOLVED-PARTIAL (`d672fa602`) — DATA-GATED.** Lifted the bare literals in `check`/`check_consistency` (`FIELD_MODEL_GINI_VIOLATION=0.8`, `ENERGY_RATIO_HIGH_VIOLATION=2.0`, `ENERGY_RATIO_LOW_VIOLATION=0.1`, `CONSISTENCY_ACTIVE_FRACTION_OF_MEAN=0.1`, `SCORE_W_*`) into named, documented consts marked EMPIRICAL DEFAULT; added at/just-below/just-above boundary tests (`energy_ratio_high_boundary`, `energy_ratio_low_boundary`, `field_model_gini_boundary`, `consistency_active_fraction_boundary`) + `tuning_consts_unchanged_from_literals`. **Operating values explicitly NOT changed** — defensible values still need labelled spoofed/clean CSI (Wi-Spoof, §6.2/§7.3). Bumping a const fails a boundary test (verified). |
-| 14 | cir.rs | `fft_operator` path changes the witness hash (documented) — no test that it's *numerically close* to dense | P2 | Add a tolerance test. |
+| 14 | cir.rs | `fft_operator` path changes the witness hash (documented) — no test that it's *numerically close* to dense | P2 | **RESOLVED (`02e5dd13a`) — tolerance test added.** `fft_operator_within_tolerance_of_dense_canonical56` pins the **full `Cir` output** of the FFT path within a *documented* relative tolerance of the dense path on the production **canonical-56** config across τ ∈ {20,50,90} ns: every tap within `1e-2·|dominant|`, identical `dominant_tap_idx`, `active_tap_count`, `ranging_valid`, `dominant_tap_ratio` within `1e-2`, `rms_delay_spread` within `1e-2` rel. A regression that lets the FFT path drift (scaling/Φ-column bug) now fails here instead of silently corrupting a downstream witness. Extends the existing HT20/single-τ `fft_estimate_matches_dense_dominant_tap`. |
 | 15 | multistatic.rs | `cir_gate_coherence` only estimates the **first** node/channel; multi-node CIR consensus unused | P2 | Design item (which node's CIR is authoritative?). |
-| 16 | phase_align.rs | Iterative LO offset estimation has no convergence cap test | P2 | Add iteration-cap test. |
-| 17 | hampel.rs | Window edge handling at series boundaries | P3 | Cosmetic. |
-| 18 | motion.rs | Threshold constants undocumented | P3 | Doc-only. |
-| 19 | csi_ratio.rs | Division guard relies on `1e-12` epsilon; no test | P2 | Add boundary test. |
-| 20 | spectrogram.rs | `compute_multi_subcarrier_spectrogram` re-plans per subcarrier via `compute_spectrogram` | P2 | Hoist the planner (relates to #3). |
-| 21–45 | (assorted) | Remaining clarity/doc/magic-constant/missing-boundary-test findings across `ruvsense/*`, `features.rs`, `motion.rs` | P3 | Bulk-addressable in a dedicated "test-the-boundaries + de-magic-constant" follow-up; not high-leverage individually. |
+| 16 | phase_align.rs | Iterative LO offset estimation has no convergence cap test | P2 | **RESOLVED (`02e5dd13a`) — cap test added.** `refinement_terminates_at_iteration_cap_when_not_converging` forces non-convergence (`tolerance = 0.0`, unreachable since `max_update ≥ 0`) and asserts the loop runs **exactly `max_iterations`** then returns — proving the cap (not convergence) bounds the loop, so a non-converging input can never spin forever. Companion `refinement_converges_before_cap_on_easy_input` proves the cap is an upper bound, not the only exit. Internal-only refactor: `estimate_phase_offsets` still returns the identical offset vector; a `…_counted` core surfaces the iteration count for the test. |
+| 17 | hampel.rs | Window edge handling at series boundaries | P3 | **RESOLVED (M3 `19e0373c8`).** De-magicked the zero-MAD `1e-15` epsilon (`ZERO_MAD_EPSILON`), documented `hampel_filter`'s `# Errors`, and added the previously-untested `half_window == 0` error-path boundary (`test_zero_half_window_error`) + a zero-MAD constant-window characterization (`test_zero_mad_constant_window`). Window-edge handling itself is correct (`saturating_sub`/`.min(n)`); it is now pinned. |
+| 18 | motion.rs | Threshold constants undocumented | P3 | **RESOLVED (M3 `c794d1a0c`).** Lifted the fusion weights, Doppler/variance/phase full-scale divisors, confidence-indicator weights, and adaptive-threshold clamp into named, documented EMPIRICAL-DEFAULT consts (`motion_tuning_consts_unchanged_from_literals` pins them) + small-`n` boundary tests (correlation `n<2`, temporal-variance `len<2`, adaptive-threshold history 9-vs-10, Doppler full-scale saturation). Doc-only-plus: values unchanged. |
+| 19 | csi_ratio.rs | Division guard relies on `1e-12` epsilon; no test | P2 | **RESOLVED (`02e5dd13a`) — boundary test added.** Finding clarification: `csi_ratio.rs` implements the CSI *ratio model* as the **conjugate product** `H_i·conj(H_j)` (SpotFi/IndoTrack) — there is **no division**, hence no literal `1e-12` epsilon; the classic `H_i/H_j` ratio (which a `1e-12` guard protects) is deliberately avoided. `ratio_finite_at_and_below_1e_12_epsilon` pins the property the finding cares about: at and below the `1e-12` target magnitude (and at exact zero — where a division ratio is ±inf/NaN) the conjugate-product output is **finite**, exactly the conjugate product (bit-exact), collapses toward zero (the physically correct "no path" answer), and stays finite through `ratio_to_amplitude_phase`. |
+| 20 | spectrogram.rs | `compute_multi_subcarrier_spectrogram` re-plans per subcarrier via `compute_spectrogram` | P2 | **MEASURED-HOT (`e839fa8f1`) — optimized, bit-identical.** Hoisted the FFT plan + window out of the per-subcarrier loop (new `compute_spectrogram_with_plan` core). **56-subcarrier** multi-spectrogram: **467.88 µs → 254.75 µs = 1.84×** (window 128); **627.27 µs → 448.39 µs = 1.40×** (window 256). The removed cost is the per-subcarrier `FftPlanner` re-plan (~1.86 µs/plan @ w128 × 56). Bit-identical (`multi_subcarrier_hoisted_plan_bit_identical`, `f64::to_bits` across all 4 windows × {power,magnitude}). The most likely real win predicted by the §7.4 intro — confirmed. (Relates to #3, which stays deferred: `spectrogram.rs`/`bvp.rs` single-signal callers already plan once-per-call.) |
+| 21–45 | (assorted) | Remaining clarity/doc/magic-constant/missing-boundary-test findings across `ruvsense/*`, `features.rs`, `motion.rs` | P3 | **RESOLVED (Milestone-3, 2026-06-13).** Enumerated honestly (the "21–45" was an estimate, not 25 distinct findings): **22 bare in-function literals de-magicked → named EMPIRICAL-DEFAULT consts (each == prior literal, pinned)**, **6 boundary/characterization tests added**, **~4 doc-only fixes**, across 11 modules (`motion`, `gesture`, `longitudinal`, `cross_room`, `multiband`, `intention`, `hampel`, `rf_slam`, `attractor_drift`, `coherence`, `calibration`, `fusion_quality`, `temporal_gesture`). **No operating value changed.** **Skipped-as-not-real (reported, no churn):** `attractor_drift.rs:301` "divide-by-zero" is unreachable (guarded by `count < min_observations`) → documented + boundary-tested, not guarded; agent-flagged `gesture.rs` `2.0`/`π·6` motion thresholds don't exist there (confusion with `calibration::deviation`); **`features.rs` left untouched** (on the deterministic Python-proof path; its `1e-10` guards already exist & are correct — doc-only-skipped to keep the `f8e76f21…` hash bit-exact). See the Milestone-3 update note above and the per-row #2/#12/#17/#18 entries. |
 
-> **Horizon-ledger one-liner.** Milestone-0 DONE: dead CIR gate (FIXED+proved), NaN/inf adversarial bypass (FIXED+proved), divide-by-(n−1) window trio (FIXED+proved), calibration dead-branch (FIXED), PSD FFT-planner cache (MEASURED), DTW band (MEASURED). **Milestone-1 DONE (2026-06-13): all four P1 backlog items cleared — circular phase variance #1 (RESOLVED/MEASURED metric, DATA-GATED threshold), Welford n=0 guard #10 (RESOLVED/MEASURED), threshold magic-constants #9 & #13 (RESOLVED-PARTIAL/DATA-GATED — de-magicked + boundary-tested, values unchanged).** DEFERRED to follow-up: the ~41 remaining P2/P3 findings in §7.4 — none silently dropped.
+> **Horizon-ledger one-liner.** Milestone-0 DONE: dead CIR gate (FIXED+proved), NaN/inf adversarial bypass (FIXED+proved), divide-by-(n−1) window trio (FIXED+proved), calibration dead-branch (FIXED), PSD FFT-planner cache (MEASURED), DTW band (MEASURED). **Milestone-1 DONE (2026-06-13): all four P1 backlog items cleared — circular phase variance #1 (RESOLVED/MEASURED metric, DATA-GATED threshold), Welford n=0 guard #10 (RESOLVED/MEASURED), threshold magic-constants #9 & #13 (RESOLVED-PARTIAL/DATA-GATED — de-magicked + boundary-tested, values unchanged).** **Milestone-2 DONE (2026-06-13): bench-first P2 perf subset + missing boundary tests cleared — spectrogram per-subcarrier FFT re-plan #20 (MEASURED-HOT, 1.40–1.84×, bit-identical); attention/tomography/Kalman #5/#6/#7 (MEASURED-NULL — benched, not hot, left as-is); field_model eigendecompose #8 (MEASUREMENT-ONLY, BLAS un-buildable on this Windows host, number deferred to a BLAS box, NOT fabricated); fft_operator tolerance #14, phase-align convergence-cap #16, csi-ratio epsilon #19 (RESOLVED, tests added).** **Milestone-3 DONE (2026-06-13): the lumped §7.4 row #21–45 P3 backlog cleared, and with it residual P3 items #2/#12/#17/#18 — 22 magic constants de-magicked into named EMPIRICAL-DEFAULT consts (each pinned == prior literal) + 6 boundary/characterization tests across 11 modules; ~4 doc-only; not-real findings (unreachable attractor_drift div0, non-existent gesture thresholds, proof-path features.rs) reported + skipped, no churn; no operating value changed; workspace 3,275/0, Python proof bit-exact `f8e76f21…`.** **§7.4 deferred backlog is now FULLY CLEARED across M0–M3 — nothing silently dropped.**
 
 ---
 

docs/adr/ADR-155-nn-training-beyond-sota.md

@@ -187,13 +187,41 @@ The gap review surfaced ~60 findings; this milestone scoped to the provable inte
 - **GraphPose-Fi graph decoder** — build the §5 top candidate (ACCEPTED-future, not built).
 - **ONNX INT4** quantization; **CSI-JEPA vs MAE** A/B; the rest of the §5 roadmap.
 - **ONNX read-lock concurrency win** — blocked on an `ort` release exposing `&self` `Session::run` (§4.2); harness already committed.
-- **native-conv naive-loop** perf rewrite (§4).
-- **`rf_encoder.rs` `assert_eq!`-on-checkpoint** and any other **tch-gated** panic-on-input sites — require a libtorch host to compile/verify (`model.rs` `amp_fc1` unbounded alloc is *indirectly* guarded by the new `config.validate()` upper bounds, but a direct guard + test is deferred).
+- ~~**native-conv naive-loop** perf rewrite (§4).~~ — **RESOLVED in Milestone-2 (see §8.2): bench-first → MEASURED-INCONCLUSIVE, no perf change shipped.**
+- ~~**`rf_encoder.rs` `assert_eq!`-on-checkpoint**~~ — **RESOLVED in Milestone-2 (see §8.2): a pure-Rust fallible `LinearHead::try_new` guard was added.** Any genuine **tch-gated** panic-on-input sites remain deferred — they require a libtorch host to compile/verify (`model.rs` `amp_fc1` unbounded alloc is *indirectly* guarded by the new `config.validate()` upper bounds, but a direct guard + test is deferred).
 - ~~**`sensing-server/training_api.rs` PCK**~~ — **RESOLVED in Milestone-1b (see §8.1, Goal C).** Relabelled (not unified) — and the audit found the *real* live divergence is in `trainer.rs`, not the orphaned `training_api.rs`.
 - ~~**`test_metrics.rs` reference kernels**~~ — **RESOLVED in Milestone-1b (see §8.1, Goal B).** Canonical core hoisted to an un-gated module; the integration test now validates the production functions against hand-computed fixtures + a differential cross-check.
 - **`metrics.rs` `compute_pck_v2`/`compute_oks_v2`/`MetricsAccumulatorV2`/`evaluate_dataset_v2`/`hungarian_assignment_v2`** — confirmed to have **zero external callers** (only `evaluate_dataset_v2`→`MetricsAccumulatorV2` internally). They are already `#[deprecated]` and route through canonical, so they are not a *divergent-definition* risk, only dead weight. Left in place this pass (public API in a tch-gated module; deleting needs a deprecation-cycle + tch host to verify) — flagged here for a future cleanup, NOT deleted silently.
 - **`sensing-server/trainer.rs` `pck_at_threshold` (raw) + `oks_map(area=1.0)` and the `training_bench.rs` raw kernel** — relabelled in Milestone-1b (§8.1); true unification onto `pck_canonical`/`oks_canonical` (needs a torso scale + the train crate as a sensing-server dep) remains deferred.
-- The remaining ~40 lower-severity review findings (style, micro-opt, doc) from the NN/training gap review.
+- ~~The remaining ~40 lower-severity review findings (style, micro-opt, doc).~~ — **RESOLVED in Milestone-2 (§8.2): the host-verifiable subset is cleared.** The "~40" was an estimate; the actual host-verifiable (non-tch) train/nn surface is smaller. Enumerated resolution below.
+
+### 8.2 Milestone-2 — host-verifiable §8 P3 backlog clearance — RESOLVED
+
+Mirroring the ADR-154 M3 cleanup discipline, M2 closed the **host-verifiable (non-tch) subset** of the §8 backlog in `wifi-densepose-train` (+ the pure-Rust `rf_encoder.rs`/`densepose.rs` in `wifi-densepose-nn` that the §3/§4 items named). Everything behind `#[cfg(feature = "tch-backend")]` (`metrics.rs`, `model.rs`, `losses.rs`, `proof.rs`, `trainer.rs`, `wiflow_std/{layers,model}.rs`) is **out of host-verifiable scope** — it cannot be compiled/verified without libtorch and stays genuinely deferred (not dropped).
+
+**PROOF discipline held:** every de-magicked constant is pinned `== prior literal` by a `*_consts_unchanged_from_literals` test; every boundary test characterizes CURRENT behaviour; no operating-value or behaviour change; the Python proof stays bit-exact at `f8e76f21…46f7a` (the metrics path is off the signal proof path — asserted, not assumed). A smaller-but-true count was reported rather than inventing 40 fixes.
+
+**Enumerated finding → resolution (real counts):**
+
+| # | Finding (location) | Action | Pin/characterization test |
+|---|---|---|---|
+| 1 | `metrics_core.rs` — `0.5` vis / `1e-6` extent / `0.07` OKS-fallback sigma | de-magic → `VISIBILITY_THRESHOLD` / `MIN_REFERENCE_EXTENT` / `OKS_FALLBACK_SIGMA` | `metrics_core_consts_unchanged_from_literals`; `visibility_threshold_boundary_is_inclusive`; `degenerate_extent_below_floor_is_unscoreable` |
+| 2 | `ruview_metrics.rs` — `17` / `0.5` / `0.2` / `1e-3` / `1e-6` | de-magic → `NUM_KEYPOINTS` / `VISIBILITY_THRESHOLD` / `PCK_THRESHOLD` / `MIN_BBOX_DIAG` / `MIN_DURATION_MINUTES` | `ruview_metrics_consts_unchanged_from_literals`; `tracking_zero_duration_does_not_divide_by_zero`; `oks_short_array_is_bounded_at_keypoint_count` |
+| 3 | `subcarrier.rs` — sparse-interp `0.15`/`1e-4`/`0.1`/`1e-8`/`1e-5`/`500` | de-magic → 6 `SPARSE_*` consts | `sparse_interp_consts_unchanged_from_literals`; `compute_interp_weights_single_target_is_index_zero`; `sparse_interp_single_target_is_finite` |
+| 4 | `eval.rs` — `1e-10` division guard (×3) | de-magic → `MIN_POSITIVE_MPJPE` | `eval_min_positive_mpjpe_unchanged_from_literal`; `domain_gap_infinite_when_in_domain_perfect_but_cross_nonzero`; `domain_gap_unity_when_everything_perfect` |
+| 5 | `domain.rs` — `1e-5` LayerNorm eps | de-magic → `LAYER_NORM_EPS` | `layer_norm_eps_unchanged_from_literal` (n=0/zero-var boundary already covered) |
+| 6 | `virtual_aug.rs` — `1e-10` Box-Muller / room-scale guards | de-magic → `BOX_MULLER_U1_FLOOR` / `MIN_ROOM_SCALE` | `virtual_aug_guard_consts_unchanged_from_literals`; `augment_frame_zero_room_scale_passes_amplitude_finite` |
+| 7 | `rf_encoder.rs` — `20.0` softplus overflow threshold | de-magic → `SOFTPLUS_LINEAR_THRESHOLD` | `softplus_threshold_unchanged_from_literal` |
+| 8 | `rf_encoder.rs` — panic-only `LinearHead::new` for untrusted weights (§3) | add pure-Rust fallible `try_new` → typed `RfHeadError` (additive; `new` unchanged) | `try_new_accepts_valid_and_rejects_each_bad_shape` |
+| 9 | `densepose.rs::apply_conv_layer` naive-loop (§4) | **bench-first → MEASURED-INCONCLUSIVE**, no perf change shipped; committed bench + characterization anchor | `native_conv_matches_reference` + `benches/native_conv_bench.rs` |
+| 10 | `rapid_adapt.rs` module-doc "O(ε)" inconsistency | doc-only fix → "O(ε²)" (central differences) | n/a (doc) |
+| 11 | `geometry.rs` `DeepSets::encode` missing `# Panics` | doc-only fix (documents existing `assert!`) | n/a (doc) |
+
+**Tally:** **7 de-magicked (const + pin test)**, **9 new boundary/characterization tests**, **1 added input guard (`try_new`) + test**, **2 doc-only fixes**, **1 perf item bench-first MEASURED-INCONCLUSIVE (not shipped, deferred)**. New tests: train `--no-default-features` **303** (was 288, +15); nn `--no-default-features` lib **38** (was 35, +3).
+
+**Skipped honestly (flagged-but-not-real):** `ablation.rs` (NaN sort + boundary already fixed/tested in M1 — clean), `signal_features.rs` (consts already named, n=0 boundary already tested), `mae.rs` (no bare guard literals found), `metrics_core` already had thorough zero-visible/hip-normalizer coverage from M1. No churn was manufactured to hit a count.
+
+**Genuinely data-gated / tch-gated — remaining backlog (blocked, not dropped):** GraphPose-Fi graph decoder, ONNX INT4, CSI-JEPA vs MAE A/B (all **data/model-gated** — need a training run + datasets); ONNX read-lock concurrency win (**upstream-gated** on `ort`); the tch-gated panic-on-input sites in `proof.rs`/`trainer.rs`/`model.rs` and the `metrics.rs` `*_v2` dead-code deletion (**tch-gated** — need a libtorch host to compile/verify). **The non-tch-verifiable subset of §8 is now cleared.**
 
 ### 8.1 Milestone-1b — metric-definition unification (the §8 metric subset) — RESOLVED
 

docs/adr/ADR-156-ruvector-fusion-beyond-sota.md

@@ -103,7 +103,7 @@ The double-clone elimination is also correctness-neutral: all 100 `viewpoint`/`m
 | # | Candidate | What | Grade | Verdict |
 |---|-----------|------|-------|---------|
 | **1** | **SymphonyQG** (SIGMOD 2025, public code) | Unified quantization + graph ANN; source reports **3.5–17× QPS over HNSW at equal recall**, pure-CPU / edge-portable. | **CLAIMED** (author-measured; **not reproduced on our hardware** — reproduction is future work) | **Lead beyond-SOTA candidate for the ruvector ANN path.** Propose as ACCEPTED-future; cite honestly as "claimed by source, reproduction pending." Best fit because the ruvector retrieval path (AETHER re-ID, sketch prefilter) is exactly an ANN problem and SymphonyQG is CPU/edge-portable like our deployment. |
-| **2** | **Multi-bit / Extended RaBitQ** | Extends our existing **1-bit** `sketch.rs` (ADR-084) to multiple bits per dimension — precisely the "Pass 2" our own `sketch.rs` doc deferred (1-bit sign quantization ships first; rotation/more-bits "later if benchmark-measured top-K coverage drops below the ADR-084 90% threshold"). | **MEASURED-on-our-hardware** (was CLAIMED) — Pass-2 rotation + multi-bit Pass-3 implemented and benchmarked; see §10. Rotation lifts strict-bar coverage 36%→46% and clears 90% only with ~3× over-fetch; multi-bit (≤4-bit) reaches 74% at the strict bar — both **short of the strict 90% bar** on the tested distribution. | **DONE — RESOLVED-PARTIAL.** Built and MEASURED (§10). The honest negative (no strict-bar 90% from rotation or ≤4-bit) is recorded, not hidden. Over-fetch + Pass-2 is the path that meets the bar; that matches ADR-084's "candidate set" deployment pattern. |
+| **2** | **Multi-bit / Extended RaBitQ + unbiased estimator** | Extends our existing **1-bit** `sketch.rs` (ADR-084): Pass-2 rotation, multi-bit Pass-3, and the **real RaBitQ unbiased distance estimator** (Gao & Long SIGMOD 2024) reranking the candidate set from the 1-bit code + 8 B/vec side info (§11). | **MEASURED-on-our-hardware** (was CLAIMED) — rotation (§10), multi-bit (§10), and the estimator (§11) all implemented + benchmarked. Rotation lifts strict-K 36%→46%; multi-bit (≤4-bit) reaches 74% strict; **the estimator reaches 49.71% strict (cosine rerank), still short of 90%.** All clear 90% only with over-fetch (estimator improves the factor: 95% at candidate_k=24 vs sign 91.6%). | **DONE — RESOLVED-PARTIAL / NEGATIVE.** Rotation (§10) + estimator (§11) built and MEASURED. The honest negative (no strict-bar 90% from rotation, ≤4-bit, **or the unbiased estimator**) is recorded, not hidden. Over-fetch + Pass-2 is the path that meets the bar (ADR-084's "candidate set" pattern); the estimator lowers the over-fetch factor needed. |
 | **3** | **GraphPose-Fi-style learned antenna-attention + ChebGConv fusion head** | Would replace the current **untrained identity-projection + mean-pool** "attention" (the `CrossViewpointAttention` default is `ProjectionWeights::identity` — not a *learned* attention) with a learned graph fusion head. | **DATA-GATED** (per ADR-152 measurement (b): architecture is **NOT** the current bottleneck — **data is**) | **ACCEPTED-future, data-gated. Do NOT build now.** ADR-152's measured lesson was that swapping architecture without more/better paired data does not move PCK. Building a learned fusion head before the data exists would repeat the mistake ADR-155 §5 also flagged for GraphPose-Fi. |
 | — | **Cramér-Rao / sensor-placement** (`geometry.rs` CRB) | Investigated for a 2026 advance beating the textbook Fisher-information CRB already implemented. | **Investigated — NO ACTION** | **Cleared honestly.** No 2026 method beats the closed-form Fisher-information CRB for this 2-D bearing problem; our implementation is already correct SOTA. (Recording a negative result is a deliberate anti-slop signal.) The only CRB change this milestone is the §2.3 *GDOP* honesty fix, which is a labelling/quantity correction, not an algorithmic one. |
 
@@ -202,6 +202,64 @@ Test machine: Windows 11, `cargo bench --release` / `cargo test`. Fixture: **dim
 
 ### 10.5 Deferred sub-items (graded, not dropped)
 
-- **Strict-bar 90% from a richer code** — neither rotation nor uniform multi-bit closes it here. A learned/asymmetric quantizer or the full RaBitQ residual-distance estimator (not just a uniform scalar code) might, but is unbuilt and **unmeasured** — explicitly deferred, not claimed.
+- **Strict-bar 90% from a richer code** — neither rotation nor uniform multi-bit closes it here. A learned/asymmetric quantizer or the full RaBitQ residual-distance estimator (not just a uniform scalar code) might. **RESOLVED-NEGATIVE (§11): the estimator is now built and MEASURED — it lifts strict-K 46.39%→49.71% but does NOT clear the 90% strict bar.** The residual strict-bar gap is a published negative, not a deferral.
 - **Distribution sensitivity** — the result is for one synthetic anisotropic distribution; on real AETHER traces the strict-bar number may differ. Re-measuring on recorded embeddings is deferred to the ADR-084 post-merge soak.
 - **Promoting a `MultiBitSketch` type** — the multi-bit code lives in the measurement harness, not as a shipped sketch type. Building the production type is gated on a use site actually needing strict-K (vs over-fetch), which the measurement says is not required today.
+
+---
+
+## 11. RaBitQ unbiased distance estimator — IMPLEMENTED & MEASURED (Milestone-2, §8 backlog item #2 / §10.5 strict-bar item)
+
+Milestone-2 of the §8 backlog. Status: **RESOLVED-NEGATIVE** — the estimator is built, measured, and lifts strict-K coverage, but the honest result is that it does **not** clear the ADR-084 ≥90% strict-K bar on this distribution. The negative is reported as such, exactly like the Pass-2 rotation result.
+
+### 11.1 What landed
+
+- **`crates/wifi-densepose-ruvector/src/estimator.rs`** (new) — the real Gao & Long (SIGMOD 2024) contribution: an **unbiased estimator of the inner product / squared distance** recovered from the 1-bit code plus per-vector side info, on top of the Pass-2 rotation. Pass-1/Pass-2 ranked candidates by raw Hamming over sign bits — a coarse proxy. This module reranks by the unbiased estimate.
+  - `EstimatorSketch` — Pass-2 sign code (over the **padded** FHT length `D = next_pow2(dim)`, the frame `x̄` is unit in) **plus** the side info.
+  - `SideInfo` = `{ residual_norm: f32, x_dot_o: f32 }` = **8 bytes/vector** (2× f32).
+  - `EstimatorQuery` — query rotated once, reused across all candidates.
+  - `DistanceEstimator` — `estimate_inner_product`, `estimate_sq_distance`, `ranking_key` (euclidean), `cosine_ranking_key` (the correct key vs a cosine ground truth — needs only the code + `x_dot_o`).
+  - `EstimatorBank` — `topk_estimated` (euclidean) / `topk_estimated_cosine`; optional `with_centroid` (the paper's centroid path).
+- **`coverage.rs`** — `measure_estimator` (cosine rerank) + `measure_estimator_euclidean`, on the **bit-identical** fixture / cluster centres / query stream / cosine ground truth as `measure_pass1`/`measure_pass2`. Single source of truth for the §11.3 table; backs both `estimator_coverage_report` and the `sketch_bench` coverage table.
+- **Additive + backward-compatible.** New types only; Pass-1 `Sketch` / Pass-2 `SketchBank` / `WireSketch` wire format are untouched. All external callers (`event_log.rs`, `signal/longitudinal.rs`, `sensing-server`) use Pass-1 `from_embedding` and are unaffected.
+
+### 11.2 The estimator formula (and the zero-centroid simplification, stated honestly)
+
+Let `P` be the Pass-2 orthogonal rotation (`R = H·D`), `D = next_pow2(dim)`. For data `o_raw`, query `q_raw`, centroid `c`:
+
+1. **Centroid — SIMPLIFIED to zero/global `c = 0`.** The paper centres on a per-cluster centroid (`o_r = o_raw − c`); we use `c = 0` (`o_r = o_raw`), because the current sketch path has no IVF/k-means cluster structure. This costs accuracy when the data is far off-origin. **We document it, do not hide it,** and built the paper-faithful centroid path (`from_embedding_centred` / `EstimatorBank::with_centroid`) so the simplification is a measured choice, not an assumption. (We do **not** report a centroid coverage number against the *cosine* ground truth: centroid-subtraction changes the metric — cosine-of-residual ≠ cosine-of-raw — so a centroid number vs raw-cosine truth would be a metric mismatch, itself dishonest. Zero-centroid is the correct match for this raw-cosine harness.)
+2. **Unit residual + 1-bit code.** `o = o_r/‖o_r‖`, `o' = P·o`, code `x̄_i = sign(o'_i)·(1/√D)` — a unit vector at the nearest hypercube corner.
+3. **Side info:** `residual_norm = ‖o_r‖` and `x_dot_o = ⟨x̄, o'⟩ ∈ (0,1]` (the paper's `⟨x̄, o⟩`).
+4. **Unbiased estimator** (paper Eq.): `⟨o', q'⟩ ≈ ⟨x̄, q'⟩ / ⟨x̄, o'⟩ = ⟨x̄, q'⟩ / x_dot_o`. The random rotation makes the code's quantization error orthogonal **in expectation** to `q'`, so the rescale is unbiased (paper's `O(1/√D)` bound). Per candidate: one length-`D` signed sum (`x̄ ∈ {±1/√D}`), as cheap as Hamming + a multiply.
+5. **Distance / cosine.** `⟨o_r,q_r⟩ = ‖o_r‖·(⟨x̄,q'⟩/x_dot_o)`; `‖q_r−o_r‖² = ‖q_r‖²+‖o_r‖²−2⟨o_r,q_r⟩`. For a **cosine** ground truth (AETHER / this harness), rank by `−⟨o,q_r⟩ = −(⟨x̄,q'⟩/x_dot_o)` (needs only the code + `x_dot_o`).
+
+**Unbiasedness is pinned** (`estimator_unbiased_on_fixture`): averaging the estimate of `⟨o_r,q_r⟩` over 4000 random rotation seeds converges to the true inner product within ~6% of the `‖o‖‖q‖` envelope — a biased estimator (or sign-only proxy) would be systematically off.
+
+### 11.3 MEASURED strict-K coverage
+
+Same fixture/seeds as §10 (dim=128, N=2048, K=8, 64 clusters, noise=0.35, 128 queries, `master_seed=0xAD000084`, `rotation_seed=0x5EEDC0DE12345678`), cosine ground truth. Reproduce: `cargo test -p wifi-densepose-ruvector --no-default-features estimator_coverage_report -- --nocapture` or `cargo bench -p wifi-densepose-ruvector --bench sketch_bench -- pass2_coverage`.
+
+| candidate_k | Pass-1 (sign) | Pass-2 (sign) | **Pass-2 + estimator (cosine)** | Pass-2 + estimator (euclid) | vs 90% bar |
+|---|---|---|---|---|---|
+| **8 (= K, strict bar)** | 36.13% | 46.39% | **49.71%** | 49.02% | **all BELOW** |
+| 16 | 62.79% | 75.59% | 79.20% | 77.93% | below |
+| 24 | 83.89% | 91.60% | **95.12%** | 93.65% | estimator clears |
+| 32 | 100.00% | 100.00% | 100.00% | 100.00% | clears |
+| 64 | 100.00% | 100.00% | 100.00% | 100.00% | clears |
+
+Side-info memory overhead: **8 bytes/vector** (2× f32) on top of the 16 B/vec 1-bit sketch.
+
+### 11.4 Honest verdict
+
+- **The estimator helps, and the cosine key beats the euclidean key** (49.71% vs 49.02% at strict-K; cosine is the apples-to-apples match for the cosine ground truth — both it and sign-Hamming are angular). The unbiased rescale is a real, consistent lift at every over-fetch level (e.g. 24: 91.60%→95.12%).
+- **It does NOT clear the strict candidate_k==K 90% bar.** Strict-K goes 36.13% (Pass-1) → 46.39% (Pass-2-sign) → **49.71% (Pass-2 + estimator)** — a **+3.3 pp** improvement over sign-only, **still ~40 pp short of 90%**. This is a **published negative**, the same class of honest result as the Pass-2 rotation (§10).
+- **Why the strict-K gain is modest:** the binding constraint at strict K is the **1-bit code's information ceiling** (resolving 8-of-2048 from a single sign bit per coordinate), not the *estimator's variance* — the estimator sharpens the ranking but cannot add information the 1-bit code never captured. The estimator's larger wins are at over-fetch, where there is room to re-rank a wider candidate pool.
+- **The bar is still met the way ADR-084 deploys the sensor:** at candidate_k=24 (~3× over-fetch) the estimator reaches **95.12%** (vs Pass-2-sign 91.60%) — the "candidate set, then full refinement" pattern. The estimator **improves the over-fetch factor needed** but does not eliminate it.
+- **No benchmark was tuned to manufacture a pass.** The strict-bar gap is documented, not spun.
+
+### 11.5 Pinning tests
+
+- `estimator::estimator_is_deterministic` — fixed seed ⇒ identical estimate + identical bank top-K.
+- `estimator::estimator_unbiased_on_fixture` — Monte-Carlo mean over 4000 seeds converges to the true inner product within tolerance (the unbiasedness claim).
+- `coverage::estimator_rerank_not_worse_than_sign` — estimator-reranked coverage ≥ sign-only Pass-2 on a fixed fixture (must not regress).
+- Plus: `estimator_self_distance_is_small`, `x_dot_o_in_unit_range`, `zero_input_does_not_panic`, `bank_self_query_ranks_self_first`, `centroid_path_self_query_ranks_self_first`, `centroid_zero_matches_default`, `estimator_coverage_is_deterministic`.

docs/adr/ADR-157-hardware-sensing-beyond-sota.md

@@ -85,9 +85,11 @@ A new criterion bench (`harness = false`, registered in `Cargo.toml`) drives eac
 
 `OpportunisticCsiBridge::ingest` built `CsiReportPayload { n_subcarriers: self.amp_accum.len() as u16, … }`. The `as u16` would silently wrap a count above 65 535. **This is unreachable in practice**: `ingest` gates `frame.subcarrier_count() > MAX_REPORT_SUBCARRIERS` (484) at entry and returns `None`, and `report.validate()` independently rejects oversized counts downstream. We replaced the cast with `u16::try_from(self.amp_accum.len()).ok()?` (drop-instead-of-truncate) so the construction is **correct-by-construction** rather than relying on the upstream gate. We disclose this as **defense-in-depth on an unreachable path, not a live bug** — no behavior change, no new test (the gate already prevents the input that would exercise it).
 
-### 2.6 §B4 — constant-time HMAC tag compare: **DEFERRED, not landed** (disclosed)
+### 2.6 §B4 — constant-time HMAC tag compare: **RESOLVED — no-dependency hand-rolled constant-time compare (Milestone-1)**
 
-`secure_tdm.rs:284` compares the 8-byte HMAC tag with `self.hmac_tag == expected` (data-dependent, non-constant-time). The research authorized adding `subtle::ConstantTimeEq` **only if `subtle` were already a direct dependency** — it is not (only transitive, via a crypto crate). Per that guidance, and because this is an **8-byte tag on a LAN multistatic sync beacon** (not a remote attacker-controlled timing-oracle surface), we **do not add a direct dependency** for it. Tracked in §8 as a deferred item, not silently dropped.
+`secure_tdm.rs` compared the 8-byte HMAC tag with `self.hmac_tag == expected` (data-dependent, non-constant-time: short-circuits on the first differing byte, leaking through verification latency how many leading bytes a forged tag matched — a byte-by-byte tag-recovery oracle). Milestone-3 deferred this **only** to avoid adding the `subtle` crate as a direct dependency. Milestone-1 resolves it **without any dependency**: a hand-rolled `constant_time_tag_eq(a, b)` that XOR-accumulates every byte difference into a single `u8` with **no early exit**, then compares the accumulator to zero exactly once. `#[inline(never)]` + `core::hint::black_box(diff)` stop the optimizer from reintroducing a short-circuit or lowering the loop into a non-constant-time `memcmp`; a length mismatch returns `false` without inspecting contents. The former `==` verify site now calls this helper.
+
+**Test (fails on old code, the hard gate):** `tag_compare_is_constant_time_shape` — asserts correct accept/reject for equal, first-byte-differ, last-byte-differ, all-byte-differ, and length-mismatch tags, plus an end-to-end `verify()` last-byte-only tamper. Verified to **bite**: introducing a classic constant-time bug (loop `take(LEN-1)`, skipping the last byte) makes it fail on `last-byte-differ must reject`. A coarse timing-invariance smoke check `tag_compare_timing_invariance_smoke` exists but is `#[ignore]`d (noisy host — not a CI gate). **Grade MEASURED** (constant-time *construction*; micro-timing on a noisy host is only a smoke check, disclosed honestly). Tracked RESOLVED in §8.
 
 ---
 
@@ -143,7 +145,7 @@ Grades: **MEASURED** (source measured it, ideally public method/code), **CLAIMED
 | 1 | **CSI vital signs (HR/BR)** | Deep-CSI vital-sign models report **MAE ~2–3 BPM** vs our classical IIR-bandpass + autocorrelation/zero-crossing. | **DATA-GATED + CLAIMED** | **NO ACTION on method.** A deep model needs **paired PPG/ECG ground truth** we do not have, and no public ESP32 artifact reproduces the cited MAE on commodity CSI. Our classical method is the honest commodity baseline; the real wins this milestone are the A1/A3 robustness fixes, not a new model. |
 | 2 | **802.11bf-2025 conformance** | Adopt a conformance test-vector suite for the `ieee80211bf/` forward-compat model. | **CLAIMED (not public)** | **NO ACTION.** No commodity silicon ships a conformant 802.11bf interface as of 2026, and the conformance suites are **WBA / Wi-Fi Alliance pre-certification** material, **not public**. Our model's "no OTA encoding until silicon exists" posture (ADR-153) is the correct one. Tracked in §8: *add SBP conformance vectors when the WFA publishes a test plan* — we will **not invent vectors**. |
 | 3 | **Per-room calibration (ADR-151)** | Bank-of-specialists + drift-veto vs a 2026 calibration SOTA. | **CLAIMED on numbers, DATA-GATED on a head-to-head** | **NO ACTION on architecture.** The bank-of-specialists + drift-veto design is SOTA-shaped, but we have **no head-to-head PCK** against a published method (no paired multi-room data). The geometry-conditioned LoRA head is **built-but-unconsumed** and data-gated → **ACCEPTED-FUTURE** (§8), not built now. |
-| 4 | **Multi-BSSID throughput (wifiscan)** | The module docs assert a native `wlanapi.dll` FFI 10–20 Hz path; the current `WlanApiScanner` wraps `netsh` (~2 Hz). | **CLAIMED-unmeasured** | **NO ACTION + corrected expectation.** The native FFI fast path is **asserted but NOT implemented** — the live scanner is the ~2 Hz netsh shim. The "10×" is unmeasured. → **ACCEPTED-FUTURE** (§8). **We explicitly do NOT claim a speedup that does not exist.** |
+| 4 | **Multi-BSSID throughput (wifiscan)** | The module docs assert a native `wlanapi.dll` FFI 10–20 Hz path; the current `WlanApiScanner` wraps `netsh` (~2 Hz). | **MEASURED (Milestone-1)** | **IMPLEMENTED + MEASURED — real positive win.** Status corrected: the native FFI is **fully implemented and wired live** (`wlanapi_native::scan_native` calls `WlanOpenHandle`/`WlanEnumInterfaces`/`WlanGetNetworkBssList`/`WlanFreeMemory`/`WlanCloseHandle`; `WlanApiScanner::scan_instrumented` runs it native-first with a netsh fallback). Milestone-1 **measured both paths on this box** (Intel Wi-Fi 7 BE201 320MHz, 2026-06-13) over an identical 10 s wall-clock window via a new `benchmark_backend`: **native 21.42 Hz vs netsh 3.84 Hz = 5.57× MEASURED** (mean 5.0 BSSIDs/scan each; native-only run 18.0 Hz). Native genuinely beats netsh — a real measured multiple, **not** a fabricated 10×; the achieved 21.4 Hz lands in the asserted >2 Hz regime though below the asserted 10–20 Hz upper bound. 50 back-to-back native scans = 50/50 OK, no handle leak. → §8 MEASURED. |
 
 ---
 
@@ -176,10 +178,10 @@ Grades: **MEASURED** (source measured it, ideally public method/code), **CLAIMED
 
 ## 8. Deferred backlog (NOT silently dropped)
 
-- **§B4 constant-time HMAC compare** — `secure_tdm.rs:284` uses `==` on the 8-byte tag. Add `subtle::ConstantTimeEq` **if** `subtle` becomes a direct dependency for another reason; not worth a new dependency for an 8-byte LAN sync-beacon tag (out of the current threat model). Deferred, not dropped.
+- **§B4 constant-time HMAC compare** — **RESOLVED (Milestone-1).** Replaced the short-circuiting `==` on the 8-byte tag with a hand-rolled branch-free `constant_time_tag_eq` (XOR-accumulate, no early exit, `#[inline(never)]` + `black_box`). **No new dependency** — the `subtle` crate was the only reason this was deferred, and a fixed 8-byte compare needs none. Pinned by `tag_compare_is_constant_time_shape` (proven to fail on a last-byte-skipping bug). Grade MEASURED (constant-time construction). See §2.6.
 - **802.11bf SBP conformance vectors** (§5 #2) — add real conformance test vectors to the `ieee80211bf/` model **when the Wi-Fi Alliance / WBA publishes a public test plan**. Do not invent vectors before then.
 - **Geometry-conditioned LoRA calibration head** (§5 #3) — built-but-unconsumed and **data-gated** on paired multi-room PCK data (ADR-152 measurement (b): data, not architecture, is the bottleneck). ACCEPTED-FUTURE.
-- **Native `wlanapi.dll` FFI multi-BSSID fast path** (§5 #4) — the asserted 10–20 Hz path is **not implemented**; the live scanner is the ~2 Hz netsh shim. Implement and **measure** the real throughput before claiming any multiple. ACCEPTED-FUTURE, CLAIMED-unmeasured until then.
+- **Native `wlanapi.dll` FFI multi-BSSID fast path** (§5 #4) — **RESOLVED + MEASURED (Milestone-1).** The native FFI is implemented and wired live (native-first, netsh fallback). Measured on this box (Intel Wi-Fi 7 BE201 320MHz, 2026-06-13): **native 21.42 Hz vs netsh 3.84 Hz = 5.57×**, mean 5.0 BSSIDs/scan, 50/50 native scans with no handle leak. Real positive result — no fabricated 10×. See §5 #4. (Note: a prior sweep recorded 9.74 Hz on a different/older adapter; the per-adapter number varies, the ratio over netsh is the claim.)
 - **Deep-CSI vital-sign model** (§5 #1) — DATA-GATED on paired PPG/ECG ground truth. No public ESP32 artifact reproduces the cited ~2–3 BPM MAE. Not on the near-term path.
 
 ---

firmware/esp32-csi-node/main/edge_processing.c

@@ -367,6 +367,7 @@ static float    s_heartrate_bpm;
 static float    s_motion_energy;
 static float    s_presence_score;
 static bool     s_presence_detected;
+static uint8_t  s_presence_below_count;  /**< Consecutive frames below low thresh (issue #996). */
 static bool     s_fall_detected;
 static int8_t   s_latest_rssi;
 static uint32_t s_frame_count;
@@ -398,6 +399,11 @@ static uint16_t s_feature_seq;
 
 /** Multi-person vitals state. */
 static edge_person_vitals_t s_persons[EDGE_MAX_PERSONS];
+
+/** Person-count persistence debounce (issue #998). */
+static uint8_t s_person_count_candidate;  /**< Last raw (gated) candidate count. */
+static uint8_t s_person_count_streak;     /**< Consecutive frames at the candidate. */
+static uint8_t s_person_count_stable;     /**< Emitted (debounced) count. */
 static edge_biquad_t s_person_bq_br[EDGE_MAX_PERSONS];
 static edge_biquad_t s_person_bq_hr[EDGE_MAX_PERSONS];
 static float s_person_br_filt[EDGE_MAX_PERSONS][EDGE_PHASE_HISTORY_LEN];
@@ -446,6 +452,61 @@ static void update_top_k(uint16_t n_subcarriers)
     s_top_k_count = k;
 }
 
+/* ======================================================================
+ * Presence Flag Hysteresis + Debounce (issue #996)
+ * ====================================================================== */
+
+/**
+ * Schmitt-trigger presence decision with a clear-debounce.
+ *
+ * Pure function (no globals) so it is host-testable: feed a presence_score
+ * trace and assert the boolean flag is stable. Replaces the old single-
+ * threshold `score > threshold` compare that chattered when a noisy score
+ * dithered around the boundary (observed 2.6-26.7 for one stationary person).
+ *
+ *   - score  >  threshold              → assert presence (enter immediately)
+ *   - score  >= threshold * HYST_RATIO → hold current state (dead band)
+ *   - score  <  threshold * HYST_RATIO → count toward clearing; only clear
+ *                                        after CLEAR_FRAMES consecutive frames
+ *
+ * @param prev          Current presence flag (in/out via return + below_count).
+ * @param score         Latest presence score.
+ * @param threshold     High (enter) threshold.
+ * @param below_count   In/out: consecutive frames the score has been below the
+ *                      low threshold. Reset to 0 whenever the score recovers.
+ * @return New presence flag.
+ */
+static bool presence_flag_update(bool prev, float score, float threshold,
+                                 uint8_t *below_count)
+{
+    float low_thresh = threshold * EDGE_PRESENCE_HYST_RATIO;
+
+    if (score > threshold) {
+        /* Clearly present — assert and reset the clear debounce. */
+        *below_count = 0;
+        return true;
+    }
+
+    if (score >= low_thresh) {
+        /* Dead band: hold whatever we had, no flicker. Recovery above the low
+         * threshold also resets the clear debounce so a brief dip doesn't
+         * accumulate toward a false clear. */
+        *below_count = 0;
+        return prev;
+    }
+
+    /* Below the low threshold — candidate for clearing. */
+    if (*below_count < 0xFF) (*below_count)++;
+    if (!prev) {
+        return false;  /* Already cleared. */
+    }
+    if (*below_count >= EDGE_PRESENCE_CLEAR_FRAMES) {
+        *below_count = 0;
+        return false;  /* Sustained absence — clear. */
+    }
+    return true;  /* Still within the hold window — keep asserting. */
+}
+
 /* ======================================================================
  * Adaptive Presence Calibration
  * ====================================================================== */
@@ -581,6 +642,112 @@ store_prev:
  * Multi-Person Vitals
  * ====================================================================== */
 
+/**
+ * Count distinct persons from per-group energy + representative subcarrier (issue #998).
+ *
+ * Pure function (no globals) so it is host-testable. Each of the `n_groups`
+ * subcarrier groups is a *candidate* person. A candidate is counted only if:
+ *   1. Energy gate   — its energy >= EDGE_PERSON_MIN_ENERGY_RATIO * max energy.
+ *                      One body's multipath spreads energy unevenly across the
+ *                      groups; weak groups are reflections, not extra people.
+ *   2. Spatial dedup — its representative subcarrier is at least
+ *                      EDGE_PERSON_MIN_SC_SEP away from every already-counted
+ *                      person. Adjacent subcarriers see the same reflection, so
+ *                      a near-duplicate group is the same body.
+ *
+ * The strongest group is always counted (so a present body yields >= 1).
+ *
+ * @param energy   Per-group energy (e.g. phase variance), length n_groups.
+ * @param sc_idx   Per-group representative subcarrier index, length n_groups.
+ * @param n_groups Number of candidate groups (<= EDGE_MAX_PERSONS).
+ * @return Distinct person count in [0, n_groups].
+ */
+static uint8_t count_distinct_persons(const float *energy, const uint8_t *sc_idx,
+                                      uint8_t n_groups)
+{
+    if (n_groups == 0) return 0;
+
+    /* Strongest group sets the reference energy. */
+    float max_energy = 0.0f;
+    for (uint8_t g = 0; g < n_groups; g++) {
+        if (energy[g] > max_energy) max_energy = energy[g];
+    }
+    /* No real signal anywhere → no persons. */
+    if (max_energy <= 0.0f) return 0;
+
+    float min_energy = max_energy * EDGE_PERSON_MIN_ENERGY_RATIO;
+
+    uint8_t counted_sc[EDGE_MAX_PERSONS];
+    uint8_t count = 0;
+
+    /* Greedy by descending energy: take the strongest unclaimed group that is
+     * spatially separated from everything already counted. */
+    bool used[EDGE_MAX_PERSONS];
+    for (uint8_t g = 0; g < n_groups && g < EDGE_MAX_PERSONS; g++) used[g] = false;
+
+    for (uint8_t iter = 0; iter < n_groups && iter < EDGE_MAX_PERSONS; iter++) {
+        /* Find the strongest still-unused group above the energy gate. */
+        int best = -1;
+        float best_e = min_energy;  /* must beat the gate */
+        for (uint8_t g = 0; g < n_groups && g < EDGE_MAX_PERSONS; g++) {
+            if (used[g]) continue;
+            if (energy[g] >= best_e) { best_e = energy[g]; best = g; }
+        }
+        if (best < 0) break;  /* nothing left above the gate */
+        used[best] = true;
+
+        /* Spatial dedup against already-counted persons. */
+        bool duplicate = false;
+        for (uint8_t c = 0; c < count; c++) {
+            int sep = (int)sc_idx[best] - (int)counted_sc[c];
+            if (sep < 0) sep = -sep;
+            if (sep < EDGE_PERSON_MIN_SC_SEP) { duplicate = true; break; }
+        }
+        if (duplicate) continue;
+
+        counted_sc[count++] = sc_idx[best];
+    }
+
+    /* The strongest group always represents at least one body. */
+    if (count == 0) count = 1;
+    return count;
+}
+
+/**
+ * Debounce a raw person count so a single noisy frame can't change the emitted
+ * value (issue #998). A new candidate must hold for EDGE_PERSON_PERSIST_FRAMES
+ * consecutive frames before it replaces the stable count.
+ *
+ * Pure function (state passed by pointer) → host-testable.
+ *
+ * @param raw        Raw (gated) count this frame.
+ * @param candidate  In/out: the candidate being accumulated.
+ * @param streak     In/out: consecutive frames the candidate has held.
+ * @param stable     In/out: the currently emitted count.
+ * @return The (possibly updated) stable count.
+ */
+static uint8_t person_count_debounce(uint8_t raw, uint8_t *candidate,
+                                     uint8_t *streak, uint8_t *stable)
+{
+    if (raw == *stable) {
+        /* Agrees with what we emit — reset any pending change. */
+        *candidate = raw;
+        *streak = 0;
+        return *stable;
+    }
+    if (raw == *candidate) {
+        if (*streak < 0xFF) (*streak)++;
+    } else {
+        *candidate = raw;
+        *streak = 1;
+    }
+    if (*streak >= EDGE_PERSON_PERSIST_FRAMES) {
+        *stable = *candidate;
+        *streak = 0;
+    }
+    return *stable;
+}
+
 /**
  * Update multi-person vitals by assigning top-K subcarriers to person groups.
  *
@@ -600,10 +767,25 @@ static void update_multi_person_vitals(const uint8_t *iq_data, uint16_t n_sc,
 
     uint8_t subs_per_person = s_top_k_count / n_persons;
 
+    /* Per-group energy + representative subcarrier, for the #998 person gate. */
+    float   group_energy[EDGE_MAX_PERSONS] = {0};
+    uint8_t group_sc[EDGE_MAX_PERSONS]     = {0};
+
     for (uint8_t p = 0; p < n_persons; p++) {
         edge_person_vitals_t *pv = &s_persons[p];
-        pv->active = true;
         pv->subcarrier_idx = s_top_k[p * subs_per_person];
+        group_sc[p] = s_top_k[p * subs_per_person];
+
+        /* Group energy = max Welford variance over its subcarriers. This is the
+         * same variance used for top-K selection, so a multipath group (weak,
+         * adjacent to the strong one) registers low energy and gets gated out. */
+        float energy = 0.0f;
+        for (uint8_t s = 0; s < subs_per_person; s++) {
+            uint8_t sc = s_top_k[p * subs_per_person + s];
+            float v = (float)welford_variance(&s_subcarrier_var[sc]);
+            if (v > energy) energy = v;
+        }
+        group_energy[p] = energy;
 
         /* Average phase across this person's subcarrier group. */
         float avg_phase = 0.0f;
@@ -662,10 +844,32 @@ static void update_multi_person_vitals(const uint8_t *iq_data, uint16_t n_sc,
         }
     }
 
-    /* Mark remaining persons as inactive. */
-    for (uint8_t p = n_persons; p < EDGE_MAX_PERSONS; p++) {
+    /* --- Issue #998: gate phantom persons by energy + spatial dedup,
+     * then debounce so a single noisy frame can't change the count. --- */
+    uint8_t raw_count = count_distinct_persons(group_energy, group_sc, n_persons);
+    uint8_t stable_count = person_count_debounce(raw_count,
+                                                 &s_person_count_candidate,
+                                                 &s_person_count_streak,
+                                                 &s_person_count_stable);
+
+    /* Mark the strongest `stable_count` groups active (descending energy); the
+     * rest — including phantom multipath groups — are inactive. */
+    bool used[EDGE_MAX_PERSONS];
+    for (uint8_t p = 0; p < EDGE_MAX_PERSONS; p++) {
+        used[p] = false;
         s_persons[p].active = false;
     }
+    for (uint8_t n = 0; n < stable_count && n < n_persons; n++) {
+        int best = -1;
+        float best_e = -1.0f;
+        for (uint8_t p = 0; p < n_persons; p++) {
+            if (used[p]) continue;
+            if (group_energy[p] > best_e) { best_e = group_energy[p]; best = p; }
+        }
+        if (best < 0) break;
+        used[best] = true;
+        s_persons[best].active = true;
+    }
 }
 
 /* ======================================================================
@@ -960,7 +1164,12 @@ static void process_frame(const edge_ring_slot_t *slot)
     } else if (threshold == 0.0f) {
         threshold = 0.05f;  /* Default until calibrated. */
     }
-    s_presence_detected = (s_presence_score > threshold);
+    /* Issue #996: hysteresis + clear-debounce instead of a bare threshold
+     * compare, so a noisy score dithering around the boundary doesn't flicker
+     * the boolean flag. */
+    s_presence_detected = presence_flag_update(s_presence_detected,
+                                               s_presence_score, threshold,
+                                               &s_presence_below_count);
 
     /* --- Step 10: Fall detection (phase acceleration + debounce, issue #263) --- */
     if (s_history_len >= 3) {
@@ -1160,6 +1369,7 @@ esp_err_t edge_processing_init(const edge_config_t *cfg)
     s_motion_energy = 0.0f;
     s_presence_score = 0.0f;
     s_presence_detected = false;
+    s_presence_below_count = 0;
     s_fall_detected = false;
     s_latest_rssi = 0;
     s_frame_count = 0;
@@ -1183,6 +1393,9 @@ esp_err_t edge_processing_init(const edge_config_t *cfg)
     for (uint8_t p = 0; p < EDGE_MAX_PERSONS; p++) {
         s_persons[p].active = false;
     }
+    s_person_count_candidate = 0;
+    s_person_count_streak = 0;
+    s_person_count_stable = 0;
 
     /* Design biquad bandpass filters.
      * Sampling rate ~20 Hz (typical ESP32 CSI callback rate). */

firmware/esp32-csi-node/main/edge_processing.h

@@ -38,6 +38,30 @@
 /* ---- Multi-person ---- */
 #define EDGE_MAX_PERSONS      4     /**< Max simultaneous persons. */
 
+/* ---- Multi-person counting gates (issue #998) ----
+ *
+ * Over-counting root cause: the multi-person path used to split the top-K
+ * subcarriers into EDGE_MAX_PERSONS groups and mark EVERY group active,
+ * so one body's multipath always reported the full EDGE_MAX_PERSONS. These
+ * gates promote a subcarrier group to a real "person" only when it carries
+ * genuine, distinct, persistent energy:
+ *
+ *   1. Energy gate   — a group's phase variance must exceed a fraction of the
+ *                      strongest group's variance, else it is multipath/noise.
+ *   2. Spatial dedup — two groups whose representative subcarriers sit within
+ *                      EDGE_PERSON_MIN_SC_SEP of each other are the same body
+ *                      (adjacent subcarriers see correlated reflections), so
+ *                      the weaker one is merged away.
+ *   3. Persistence   — a candidate count must hold for EDGE_PERSON_PERSIST_FRAMES
+ *                      consecutive decisions before it is emitted, so a single
+ *                      noisy frame cannot promote a phantom person.
+ *
+ * These are robustness gates on the existing heuristic, not a calibrated
+ * occupancy model — true count accuracy vs ground truth remains data-gated. */
+#define EDGE_PERSON_MIN_ENERGY_RATIO 0.35f /**< Group var must be >= this * max group var to count. */
+#define EDGE_PERSON_MIN_SC_SEP       4     /**< Min subcarrier separation between distinct persons. */
+#define EDGE_PERSON_PERSIST_FRAMES   3     /**< Consecutive decisions a count must hold before emit. */
+
 /* ---- Calibration ---- */
 #define EDGE_CALIB_FRAMES     1200  /**< Frames for adaptive calibration (~60s at 20 Hz). */
 #define EDGE_CALIB_SIGMA_MULT 3.0f  /**< Threshold = mean + 3*sigma of ambient. */
@@ -46,6 +70,27 @@
 #define EDGE_FALL_COOLDOWN_MS 5000  /**< Minimum ms between fall alerts (debounce). */
 #define EDGE_FALL_CONSEC_MIN  3     /**< Consecutive frames above threshold to trigger. */
 
+/* ---- Presence flag hysteresis + debounce (issue #996) ----
+ *
+ * Flicker root cause: the presence flag was a single-threshold compare on a
+ * noisy presence_score (observed 2.6-26.7 frame-to-frame for one stationary
+ * person), so the boolean chattered at the boundary even while the score
+ * clearly indicated a person. Fix: Schmitt-trigger hysteresis plus a clear
+ * debounce.
+ *
+ *   - Assert  presence when score >  threshold              (enter immediately).
+ *   - Hold    presence while score >= threshold * HYST_RATIO (no flicker in the
+ *                                                            gap band).
+ *   - Clear   presence only after the score stays below the low threshold for
+ *             EDGE_PRESENCE_CLEAR_FRAMES consecutive frames (genuine departure).
+ *
+ * HYST_RATIO < 1.0 sets the low threshold below the high threshold; a wider gap
+ * (smaller ratio) is more flicker-immune but slower to clear on real exit. The
+ * exact ratio that best matches a given room's score scale remains an on-device
+ * tuning parameter — this removes the logic bug (no hysteresis at all). */
+#define EDGE_PRESENCE_HYST_RATIO  0.5f /**< Low thresh = HYST_RATIO * high thresh. */
+#define EDGE_PRESENCE_CLEAR_FRAMES 5   /**< Frames below low thresh before clearing. */
+
 /* ---- DSP task tuning ---- */
 #define EDGE_BATCH_LIMIT      4     /**< Max frames per batch before longer yield. */
 

firmware/esp32-csi-node/test/Makefile

@@ -43,9 +43,10 @@ MAIN_DIR  = ../main
 FUZZ_DURATION ?= 30
 FUZZ_JOBS     ?= 1
 
-.PHONY: all clean run_serialize run_edge run_nvs run_all test_adr110 run_adr110 host_tests
+.PHONY: all clean run_serialize run_edge run_nvs run_all test_adr110 run_adr110 \
+        test_vitals run_vitals host_tests
 
-all: fuzz_serialize fuzz_edge fuzz_nvs test_adr110
+all: fuzz_serialize fuzz_edge fuzz_nvs test_adr110 test_vitals
 
 # --- ADR-110 encoding unit tests ---
 # Host-side, no libFuzzer needed — plain C99 deterministic table tests
@@ -57,8 +58,19 @@ test_adr110: test_adr110_encoding.c
 run_adr110: test_adr110
 	./test_adr110
 
-host_tests: run_adr110
-	@echo "ADR-110 host tests passed"
+# --- Vitals count + presence logic unit tests (issue #998 / #996) ---
+# Host-side, no libFuzzer. Pins the person-count gate (no over-count for one
+# body) and the presence hysteresis (no flicker on a dithering score). Pulls
+# the named tuning constants from ../main/edge_processing.h so the test and the
+# firmware can never disagree on thresholds.
+test_vitals: test_vitals_count_presence.c $(MAIN_DIR)/edge_processing.h
+	cc -std=c99 -Wall -Wextra -Istubs -I$(MAIN_DIR) -o $@ $< -lm
+
+run_vitals: test_vitals
+	./test_vitals
+
+host_tests: run_adr110 run_vitals
+	@echo "Host tests passed (ADR-110 + vitals #998/#996)"
 
 # --- Serialize fuzzer ---
 # Tests csi_serialize_frame() with random wifi_csi_info_t inputs.
@@ -94,5 +106,5 @@ run_nvs: fuzz_nvs
 run_all: run_serialize run_edge run_nvs
 
 clean:
-	rm -f fuzz_serialize fuzz_edge fuzz_nvs test_adr110
+	rm -f fuzz_serialize fuzz_edge fuzz_nvs test_adr110 test_vitals
 	rm -rf corpus_serialize/ corpus_edge/ corpus_nvs/

firmware/esp32-csi-node/test/test_vitals_count_presence.c

@@ -0,0 +1,387 @@
+/**
+ * @file test_vitals_count_presence.c
+ * @brief Host-side unit tests for the issue #998 / #996 vitals logic fixes.
+ *
+ * Covers two pure decision functions extracted from edge_processing.c:
+ *   1. count_distinct_persons()  — issue #998 person over-count gate
+ *                                   (energy gate + spatial dedup).
+ *   2. person_count_debounce()   — issue #998 count persistence debounce.
+ *   3. presence_flag_update()    — issue #996 presence hysteresis + clear
+ *                                   debounce (Schmitt trigger).
+ *
+ * Build (Linux/macOS/Windows with any C99 compiler):
+ *   cc -std=c99 -Wall -I../main -o test_vitals \
+ *      test_vitals_count_presence.c && ./test_vitals
+ *
+ * Exits 0 on all-pass, prints which assertion failed otherwise.
+ *
+ * Why a separate host test file: these are deterministic logic checks for the
+ * exact boundary behaviour the issues describe; libFuzzer adds no signal here.
+ *
+ * IMPORTANT — these three functions are copied VERBATIM from
+ * firmware/esp32-csi-node/main/edge_processing.c. They are pure (no globals,
+ * no ESP-IDF). If the firmware copy changes, update the copy here and re-run
+ * this test before the firmware change merges. The named tuning constants are
+ * pulled from the real header so the test and firmware can never disagree on
+ * thresholds.
+ *
+ * HARDWARE-GATED CAVEAT: these tests pin the *logic* (no flicker / no
+ * over-count for the synthetic traces). True count accuracy and the exact
+ * energy/separation/hysteresis thresholds that best match a real room vs
+ * labelled ground truth remain hardware- and data-gated (COM9 ESP32-S3 +
+ * labelled occupancy). This is a robustness/logic fix, not a validated
+ * accuracy claim.
+ */
+
+#include <stdint.h>
+#include <stdbool.h>
+#include <stdio.h>
+
+/* Named tuning constants come from the real firmware header so the test can
+ * never silently diverge from the constants the firmware compiles with. */
+#include "edge_processing.h"
+
+/* ──────────────────────────────────────────────────────────────────────
+ *  System under test — copied VERBATIM from edge_processing.c.
+ * ────────────────────────────────────────────────────────────────────── */
+
+/* count_distinct_persons() — issue #998 energy gate + spatial dedup. */
+static uint8_t count_distinct_persons(const float *energy, const uint8_t *sc_idx,
+                                      uint8_t n_groups)
+{
+    if (n_groups == 0) return 0;
+
+    float max_energy = 0.0f;
+    for (uint8_t g = 0; g < n_groups; g++) {
+        if (energy[g] > max_energy) max_energy = energy[g];
+    }
+    if (max_energy <= 0.0f) return 0;
+
+    float min_energy = max_energy * EDGE_PERSON_MIN_ENERGY_RATIO;
+
+    uint8_t counted_sc[EDGE_MAX_PERSONS];
+    uint8_t count = 0;
+
+    bool used[EDGE_MAX_PERSONS];
+    for (uint8_t g = 0; g < n_groups && g < EDGE_MAX_PERSONS; g++) used[g] = false;
+
+    for (uint8_t iter = 0; iter < n_groups && iter < EDGE_MAX_PERSONS; iter++) {
+        int best = -1;
+        float best_e = min_energy;
+        for (uint8_t g = 0; g < n_groups && g < EDGE_MAX_PERSONS; g++) {
+            if (used[g]) continue;
+            if (energy[g] >= best_e) { best_e = energy[g]; best = g; }
+        }
+        if (best < 0) break;
+        used[best] = true;
+
+        bool duplicate = false;
+        for (uint8_t c = 0; c < count; c++) {
+            int sep = (int)sc_idx[best] - (int)counted_sc[c];
+            if (sep < 0) sep = -sep;
+            if (sep < EDGE_PERSON_MIN_SC_SEP) { duplicate = true; break; }
+        }
+        if (duplicate) continue;
+
+        counted_sc[count++] = sc_idx[best];
+    }
+
+    if (count == 0) count = 1;
+    return count;
+}
+
+/* person_count_debounce() — issue #998 count persistence. */
+static uint8_t person_count_debounce(uint8_t raw, uint8_t *candidate,
+                                     uint8_t *streak, uint8_t *stable)
+{
+    if (raw == *stable) {
+        *candidate = raw;
+        *streak = 0;
+        return *stable;
+    }
+    if (raw == *candidate) {
+        if (*streak < 0xFF) (*streak)++;
+    } else {
+        *candidate = raw;
+        *streak = 1;
+    }
+    if (*streak >= EDGE_PERSON_PERSIST_FRAMES) {
+        *stable = *candidate;
+        *streak = 0;
+    }
+    return *stable;
+}
+
+/* presence_flag_update() — issue #996 hysteresis + clear debounce. */
+static bool presence_flag_update(bool prev, float score, float threshold,
+                                 uint8_t *below_count)
+{
+    float low_thresh = threshold * EDGE_PRESENCE_HYST_RATIO;
+
+    if (score > threshold) {
+        *below_count = 0;
+        return true;
+    }
+
+    if (score >= low_thresh) {
+        *below_count = 0;
+        return prev;
+    }
+
+    if (*below_count < 0xFF) (*below_count)++;
+    if (!prev) {
+        return false;
+    }
+    if (*below_count >= EDGE_PRESENCE_CLEAR_FRAMES) {
+        *below_count = 0;
+        return false;
+    }
+    return true;
+}
+
+/* ──────────────────────────────────────────────────────────────────────
+ *  Test harness
+ * ────────────────────────────────────────────────────────────────────── */
+
+static int g_failed = 0;
+static int g_passed = 0;
+
+#define CHECK_EQ_U8(label, got, expected) do {                              \
+    if ((uint8_t)(got) == (uint8_t)(expected)) { g_passed++; }              \
+    else {                                                                  \
+        g_failed++;                                                         \
+        printf("FAIL: %s — got=%u expected=%u\n",                           \
+               (label), (unsigned)(uint8_t)(got),                           \
+               (unsigned)(uint8_t)(expected));                              \
+    }                                                                       \
+} while (0)
+
+#define CHECK_TRUE(label, cond) do {                                        \
+    if (cond) { g_passed++; }                                               \
+    else { g_failed++; printf("FAIL: %s — expected true\n", (label)); }     \
+} while (0)
+
+/* ──────────────────────────────────────────────────────────────────────
+ *  #998 — count_distinct_persons: single body must NOT report EDGE_MAX_PERSONS
+ * ────────────────────────────────────────────────────────────────────── */
+
+/* One strong signature + weak multipath echoes in adjacent subcarrier groups.
+ * This is exactly the field report: one person ~50 cm → persons=4. The energy
+ * gate + spatial dedup must collapse this to 1. */
+static void test_count_single_strong_signature(void)
+{
+    /* 4 groups: one dominant, three weak multipath (below the energy gate),
+     * representative subcarriers clustered (adjacent → one body). */
+    float   energy[EDGE_MAX_PERSONS] = {10.0f, 0.6f, 0.4f, 0.3f};
+    uint8_t sc[EDGE_MAX_PERSONS]     = {20, 21, 22, 23};
+    CHECK_EQ_U8("single strong signature → 1",
+                count_distinct_persons(energy, sc, EDGE_MAX_PERSONS), 1);
+}
+
+/* Even if the weak echoes are spatially spread, they're still below the energy
+ * gate, so they don't count. */
+static void test_count_single_spread_multipath(void)
+{
+    float   energy[EDGE_MAX_PERSONS] = {10.0f, 1.0f, 0.8f, 0.5f};
+    uint8_t sc[EDGE_MAX_PERSONS]     = {10, 40, 70, 100};
+    CHECK_EQ_U8("single body spread multipath → 1",
+                count_distinct_persons(energy, sc, EDGE_MAX_PERSONS), 1);
+}
+
+/* Two genuine, well-separated, comparably-strong signatures → 2. */
+static void test_count_two_well_separated(void)
+{
+    float   energy[EDGE_MAX_PERSONS] = {10.0f, 9.0f, 0.3f, 0.2f};
+    uint8_t sc[EDGE_MAX_PERSONS]     = {10, 90, 11, 12};
+    CHECK_EQ_U8("two well-separated strong → 2",
+                count_distinct_persons(energy, sc, EDGE_MAX_PERSONS), 2);
+}
+
+/* Two strong but spatially ADJACENT signatures collapse to 1 (same body):
+ * spatial dedup prevents double-counting one person's two strong subcarriers. */
+static void test_count_two_strong_adjacent_dedup(void)
+{
+    float   energy[EDGE_MAX_PERSONS] = {10.0f, 9.0f, 0.3f, 0.2f};
+    uint8_t sc[EDGE_MAX_PERSONS]     = {20, 21, 60, 61};  /* 20 & 21 adjacent */
+    CHECK_EQ_U8("two strong but adjacent → 1 (dedup)",
+                count_distinct_persons(energy, sc, EDGE_MAX_PERSONS), 1);
+}
+
+/* No signal at all → 0 persons (empty room). */
+static void test_count_no_signal(void)
+{
+    float   energy[EDGE_MAX_PERSONS] = {0.0f, 0.0f, 0.0f, 0.0f};
+    uint8_t sc[EDGE_MAX_PERSONS]     = {10, 30, 50, 70};
+    CHECK_EQ_U8("no signal → 0", count_distinct_persons(energy, sc, EDGE_MAX_PERSONS), 0);
+}
+
+/* Three genuine well-separated strong signatures → 3 (gate doesn't under-count). */
+static void test_count_three_well_separated(void)
+{
+    float   energy[EDGE_MAX_PERSONS] = {10.0f, 9.0f, 8.0f, 0.2f};
+    uint8_t sc[EDGE_MAX_PERSONS]     = {10, 50, 90, 11};
+    CHECK_EQ_U8("three well-separated strong → 3",
+                count_distinct_persons(energy, sc, EDGE_MAX_PERSONS), 3);
+}
+
+/* ──────────────────────────────────────────────────────────────────────
+ *  #998 — person_count_debounce: a single noisy frame can't change the count
+ * ────────────────────────────────────────────────────────────────────── */
+
+static void test_debounce_rejects_transient_spike(void)
+{
+    uint8_t candidate = 1, streak = 0, stable = 1;  /* settled on 1 person */
+
+    /* One spurious frame reports 4 — must NOT promote. */
+    uint8_t out = person_count_debounce(4, &candidate, &streak, &stable);
+    CHECK_EQ_U8("transient spike held at 1", out, 1);
+
+    /* Back to 1 — resets pending change. */
+    out = person_count_debounce(1, &candidate, &streak, &stable);
+    CHECK_EQ_U8("recovered to 1", out, 1);
+    CHECK_EQ_U8("streak reset", streak, 0);
+}
+
+static void test_debounce_accepts_sustained_change(void)
+{
+    uint8_t candidate = 1, streak = 0, stable = 1;
+
+    uint8_t out = 1;
+    /* A genuine 2-person arrival must hold EDGE_PERSON_PERSIST_FRAMES frames. */
+    for (int i = 0; i < EDGE_PERSON_PERSIST_FRAMES; i++) {
+        out = person_count_debounce(2, &candidate, &streak, &stable);
+    }
+    CHECK_EQ_U8("sustained 2 promoted", out, 2);
+    CHECK_EQ_U8("stable now 2", stable, 2);
+}
+
+/* A flapping count (2,1,2,1,...) never accumulates a streak → stays at stable. */
+static void test_debounce_flapping_stays_stable(void)
+{
+    uint8_t candidate = 1, streak = 0, stable = 1;
+    uint8_t out = 1;
+    for (int i = 0; i < 10; i++) {
+        out = person_count_debounce((i & 1) ? 1 : 2, &candidate, &streak, &stable);
+    }
+    CHECK_EQ_U8("flapping count stays at 1", out, 1);
+}
+
+/* ──────────────────────────────────────────────────────────────────────
+ *  #996 — presence_flag_update: dithering score must NOT flicker the flag
+ * ────────────────────────────────────────────────────────────────────── */
+
+/* Field trace dithers around the OLD single threshold while the person is
+ * clearly present. With T_high=10, T_low=5, a score sequence that crosses 10
+ * up and down must produce a STABLE flag (no per-frame flicker). */
+static void test_presence_no_flicker_on_dither(void)
+{
+    const float threshold = 10.0f;  /* high threshold */
+    /* Observed-style trace (issue evidence: 2.6-26.7), but here we model the
+     * realistic "person present" case where the score mostly sits in/above the
+     * dead band and only briefly dips. */
+    float trace[] = {5.6f, 23.0f, 6.8f, 12.0f, 8.0f, 26.7f, 7.0f, 11.0f, 9.0f, 24.0f};
+    int n = (int)(sizeof(trace) / sizeof(trace[0]));
+
+    bool flag = false;
+    uint8_t below = 0;
+    int flips = 0;
+    bool prev = flag;
+    for (int i = 0; i < n; i++) {
+        flag = presence_flag_update(flag, trace[i], threshold, &below);
+        if (i > 0 && flag != prev) flips++;
+        prev = flag;
+    }
+    /* First sample (5.6) is below T_low=5? No, 5.6 >= 5 → dead band, holds
+     * initial false until 23.0 asserts. After that, dips to 6.8/8.0/7.0/9.0 are
+     * all >= T_low (5), so they HOLD true. The only transition is the initial
+     * false→true. No flicker. */
+    CHECK_TRUE("presence asserted by end", flag);
+    CHECK_TRUE("at most one transition (no flicker)", flips <= 1);
+}
+
+/* Hard dither straddling T_low must still not flicker frame-to-frame because of
+ * the clear debounce: brief sub-T_low dips don't immediately clear. */
+static void test_presence_clear_debounce_holds(void)
+{
+    const float threshold = 10.0f;  /* T_low = 5.0 */
+    bool flag = false;
+    uint8_t below = 0;
+
+    /* Assert. */
+    flag = presence_flag_update(flag, 20.0f, threshold, &below);
+    CHECK_TRUE("asserted on strong score", flag);
+
+    /* A few brief dips below T_low (< CLEAR_FRAMES) must NOT clear. */
+    for (int i = 0; i < EDGE_PRESENCE_CLEAR_FRAMES - 1; i++) {
+        flag = presence_flag_update(flag, 1.0f, threshold, &below);
+    }
+    CHECK_TRUE("brief dips below T_low still present", flag);
+
+    /* Recovery resets the debounce. */
+    flag = presence_flag_update(flag, 20.0f, threshold, &below);
+    CHECK_TRUE("recovered", flag);
+    CHECK_EQ_U8("below_count reset on recovery", below, 0);
+}
+
+/* A genuine departure (score drops and STAYS low) clears within the hold window. */
+static void test_presence_genuine_departure_clears(void)
+{
+    const float threshold = 10.0f;
+    bool flag = false;
+    uint8_t below = 0;
+
+    flag = presence_flag_update(flag, 20.0f, threshold, &below);
+    CHECK_TRUE("asserted", flag);
+
+    /* Person leaves: score stays well below T_low for CLEAR_FRAMES frames. */
+    for (int i = 0; i < EDGE_PRESENCE_CLEAR_FRAMES; i++) {
+        flag = presence_flag_update(flag, 0.5f, threshold, &below);
+    }
+    CHECK_TRUE("cleared after sustained low", !flag);
+}
+
+/* Schmitt gap: a score in the dead band (between T_low and T_high) holds state,
+ * it neither asserts from false nor clears from true. */
+static void test_presence_dead_band_holds_state(void)
+{
+    const float threshold = 10.0f;  /* dead band 5..10 */
+    uint8_t below = 0;
+
+    /* From false, a dead-band score does not assert. */
+    bool flag = presence_flag_update(false, 7.0f, threshold, &below);
+    CHECK_TRUE("dead band does not assert from false", !flag);
+
+    /* From true, a dead-band score does not clear. */
+    below = 0;
+    flag = presence_flag_update(true, 7.0f, threshold, &below);
+    CHECK_TRUE("dead band does not clear from true", flag);
+}
+
+/* ──────────────────────────────────────────────────────────────────────
+ *  main
+ * ────────────────────────────────────────────────────────────────────── */
+
+int main(void)
+{
+    /* #998 person count gate */
+    test_count_single_strong_signature();
+    test_count_single_spread_multipath();
+    test_count_two_well_separated();
+    test_count_two_strong_adjacent_dedup();
+    test_count_no_signal();
+    test_count_three_well_separated();
+
+    /* #998 count debounce */
+    test_debounce_rejects_transient_spike();
+    test_debounce_accepts_sustained_change();
+    test_debounce_flapping_stays_stable();
+
+    /* #996 presence hysteresis */
+    test_presence_no_flicker_on_dither();
+    test_presence_clear_debounce_holds();
+    test_presence_genuine_departure_clears();
+    test_presence_dead_band_holds_state();
+
+    printf("\n%d passed, %d failed\n", g_passed, g_failed);
+    return g_failed == 0 ? 0 : 1;
+}

v2/Cargo.lock

@@ -10835,7 +10835,7 @@ dependencies = [
 
 [[package]]
 name = "wifi-densepose-cli"
-version = "0.3.0"
+version = "0.3.1"
 dependencies = [
  "anyhow",
  "assert_cmd",
@@ -11067,7 +11067,7 @@ dependencies = [
 
 [[package]]
 name = "wifi-densepose-sensing-server"
-version = "0.3.2"
+version = "0.3.3"
 dependencies = [
  "axum",
  "chrono",
@@ -11101,7 +11101,7 @@ dependencies = [
 
 [[package]]
 name = "wifi-densepose-signal"
-version = "0.3.3"
+version = "0.3.4"
 dependencies = [
  "chrono",
  "criterion",

v2/crates/wifi-densepose-hardware/src/esp32/secure_tdm.rs

@@ -47,6 +47,42 @@ type HmacSha256 = Hmac<Sha256>;
 /// Size of the HMAC-SHA256 truncated tag (manual crypto mode).
 const HMAC_TAG_SIZE: usize = 8;
 
+/// Constant-time comparison of two fixed-size HMAC/auth tags.
+///
+/// ADR-157 §B4: the previous `self.hmac_tag == expected` short-circuits on the
+/// first differing byte, leaking how many leading bytes matched through its
+/// execution time. For an authentication tag that is a timing oracle: an
+/// attacker who can submit forged beacons and measure verification latency can
+/// recover the correct tag byte-by-byte (~256·N trials instead of 256^N).
+///
+/// This hand-rolled compare avoids adding the `subtle` crate (ADR-157 deferred
+/// B4 only to dodge that dependency — a fixed 8-byte compare needs none). We
+/// XOR-accumulate every byte difference into a single `u8` with **no early
+/// exit**, so the work done is identical regardless of where (or whether) the
+/// tags differ. The accumulator is non-zero iff any byte differed; we compare
+/// it to zero exactly once at the end.
+///
+/// `#[inline(never)]` plus `black_box` on the accumulator stop the optimizer
+/// from reintroducing a short-circuit or hoisting the loop into a `memcmp`
+/// (which is itself non-constant-time). The two slices are required to be the
+/// same length by construction (both `[u8; HMAC_TAG_SIZE]`); a length mismatch
+/// returns `false` without inspecting contents.
+#[inline(never)]
+fn constant_time_tag_eq(a: &[u8], b: &[u8]) -> bool {
+    if a.len() != b.len() {
+        return false;
+    }
+    let mut diff: u8 = 0;
+    for (x, y) in a.iter().zip(b.iter()) {
+        // Branch-free: accumulate the bitwise difference of every byte.
+        diff |= x ^ y;
+    }
+    // black_box prevents the compiler from proving `diff == 0` early and
+    // short-circuiting the loop above. The single equality check is the only
+    // data-dependent branch, and it is on the fully-accumulated value.
+    core::hint::black_box(diff) == 0
+}
+
 /// Size of the nonce field (manual crypto mode).
 const NONCE_SIZE: usize = 4;
 
@@ -281,7 +317,10 @@ impl AuthenticatedBeacon {
         msg[..16].copy_from_slice(&self.beacon.to_bytes());
         msg[16..20].copy_from_slice(&self.nonce.to_le_bytes());
         let expected = Self::compute_tag(&msg, key);
-        if self.hmac_tag == expected {
+        // ADR-157 §B4: constant-time compare — `==` on the tag would leak,
+        // via short-circuit timing, how many leading bytes an attacker's
+        // forged tag matched, enabling byte-by-byte tag recovery.
+        if constant_time_tag_eq(&self.hmac_tag, &expected) {
             Ok(())
         } else {
             Err(SecureTdmError::BeaconAuthFailed)
@@ -752,6 +791,124 @@ mod tests {
         ));
     }
 
+    // ---- ADR-157 §B4: constant-time tag compare ----
+
+    /// Functional pin proving the new constant-time helper is wired and correct
+    /// for the four tag-shape cases. This is the *hard gate* for §B4 — it fails
+    /// on the old `==` path only if the helper is removed/unwired, and it
+    /// guarantees accept/reject semantics are byte-exact. Grade: MEASURED
+    /// (constant-time *construction*); micro-timing on a noisy host is only a
+    /// smoke check (see `tag_compare_timing_invariance_smoke`, #[ignore]).
+    #[test]
+    fn tag_compare_is_constant_time_shape() {
+        let base = [0xA5u8; HMAC_TAG_SIZE];
+
+        // Equal tags accept.
+        assert!(constant_time_tag_eq(&base, &base), "equal tags must accept");
+
+        // First byte differs → reject.
+        let mut first = base;
+        first[0] ^= 0xFF;
+        assert!(
+            !constant_time_tag_eq(&base, &first),
+            "first-byte-differ must reject"
+        );
+
+        // Last byte differs → reject.
+        let mut last = base;
+        last[HMAC_TAG_SIZE - 1] ^= 0x01;
+        assert!(
+            !constant_time_tag_eq(&base, &last),
+            "last-byte-differ must reject"
+        );
+
+        // Every byte differs → reject.
+        let all = [0x5Au8; HMAC_TAG_SIZE]; // bitwise-inverse of 0xA5
+        assert!(
+            !constant_time_tag_eq(&base, &all),
+            "all-bytes-differ must reject"
+        );
+
+        // Length mismatch → reject without inspecting contents.
+        assert!(
+            !constant_time_tag_eq(&base, &base[..HMAC_TAG_SIZE - 1]),
+            "length mismatch must reject"
+        );
+
+        // End-to-end through verify(): a tag whose only difference is the
+        // *last* byte must still be rejected exactly like a first-byte diff.
+        let beacon = SyncBeacon {
+            cycle_id: 7,
+            cycle_period: Duration::from_millis(50),
+            drift_correction_us: 0,
+            generated_at: std::time::Instant::now(),
+        };
+        let key = DEFAULT_TEST_KEY;
+        let nonce = 1u32;
+        let mut msg = [0u8; 20];
+        msg[..16].copy_from_slice(&beacon.to_bytes());
+        msg[16..20].copy_from_slice(&nonce.to_le_bytes());
+        let mut tag = AuthenticatedBeacon::compute_tag(&msg, &key);
+        tag[HMAC_TAG_SIZE - 1] ^= 0x01; // tamper the LAST byte only
+        let auth = AuthenticatedBeacon {
+            beacon,
+            nonce,
+            hmac_tag: tag,
+        };
+        assert!(
+            matches!(auth.verify(&key), Err(SecureTdmError::BeaconAuthFailed)),
+            "last-byte tamper must fail verify()"
+        );
+    }
+
+    /// Coarse timing-invariance smoke check. #[ignore]d so it never flakes CI —
+    /// the host is noisy and a hard timing bound is unreliable. Run manually
+    /// with `cargo test -p wifi-densepose-hardware -- --ignored
+    /// tag_compare_timing_invariance_smoke --nocapture`. The assertion is a
+    /// deliberately *generous* ratio bound (4×): a short-circuit `==` would show
+    /// last-byte-differ ≫ first-byte-differ; the constant-time helper should not.
+    #[test]
+    #[ignore = "timing smoke check — noisy host, run manually with --ignored"]
+    fn tag_compare_timing_invariance_smoke() {
+        use std::time::Instant;
+        const ITERS: u32 = 2_000_000;
+        let base = [0xA5u8; HMAC_TAG_SIZE];
+        let mut first = base;
+        first[0] ^= 0xFF;
+        let mut last = base;
+        last[HMAC_TAG_SIZE - 1] ^= 0x01;
+
+        // Warm up.
+        for _ in 0..ITERS / 10 {
+            core::hint::black_box(constant_time_tag_eq(&base, &first));
+        }
+
+        let t0 = Instant::now();
+        let mut acc = false;
+        for _ in 0..ITERS {
+            acc ^= constant_time_tag_eq(&base, &first);
+        }
+        core::hint::black_box(acc);
+        let dt_first = t0.elapsed().as_nanos() as f64;
+
+        let t1 = Instant::now();
+        let mut acc2 = false;
+        for _ in 0..ITERS {
+            acc2 ^= constant_time_tag_eq(&base, &last);
+        }
+        core::hint::black_box(acc2);
+        let dt_last = t1.elapsed().as_nanos() as f64;
+
+        let ratio = dt_last.max(dt_first) / dt_last.min(dt_first).max(1.0);
+        println!(
+            "first-differ {dt_first:.0}ns, last-differ {dt_last:.0}ns, ratio {ratio:.3}"
+        );
+        assert!(
+            ratio < 4.0,
+            "timing ratio {ratio:.3} too large — possible short-circuit leak"
+        );
+    }
+
     #[test]
     fn test_auth_beacon_too_short() {
         let result = AuthenticatedBeacon::from_bytes(&[0u8; 10]);

v2/crates/wifi-densepose-nn/Cargo.toml

@@ -63,3 +63,7 @@ harness = false
 name = "onnx_bench"
 harness = false
 required-features = ["onnx"]
+
+[[bench]]
+name = "native_conv_bench"
+harness = false

v2/crates/wifi-densepose-nn/benches/native_conv_bench.rs

@@ -0,0 +1,79 @@
+//! ADR-155 M2 §4 — native (pure-Rust) DensePose conv benchmark.
+//!
+//! `DensePoseHead::apply_conv_layer` is a pure-Rust naive 6-nested-loop
+//! convolution (the §8 "native-conv naive-loop" backlog item). This bench
+//! measures `forward()` (which runs the shared-conv + segmentation + UV conv
+//! stacks through that naive loop) on a representative single-layer config so a
+//! perf claim can be made (or refused) with a MEASURED before/after — never a
+//! fabricated number.
+//!
+//! Reproduce:
+//!   cargo bench -p wifi-densepose-nn --no-default-features --bench native_conv_bench
+//!
+//! The bench is `--no-default-features` (no `onnx`/`ort` download needed): the
+//! conv path is pure-Rust and benchable on any host.
+
+use criterion::{criterion_group, criterion_main, BenchmarkId, Criterion, Throughput};
+use ndarray::{Array1, Array4};
+use std::hint::black_box;
+use wifi_densepose_nn::densepose::{ConvLayerWeights, DensePoseWeights};
+use wifi_densepose_nn::{DensePoseConfig, DensePoseHead, Tensor};
+
+/// Build a single same-padding conv layer `in_ch -> out_ch`, kernel `k`, with a
+/// bias (no batch-norm) — deterministic, small, representative of one stage.
+fn conv_layer(in_ch: usize, out_ch: usize, k: usize) -> ConvLayerWeights {
+    let weight = Array4::from_shape_fn((out_ch, in_ch, k, k), |(o, i, kh, kw)| {
+        // Deterministic, bounded weights.
+        ((o + i + kh + kw) as f32 * 0.013).sin()
+    });
+    ConvLayerWeights {
+        weight,
+        bias: Some(Array1::from_shape_fn(out_ch, |o| o as f32 * 0.01)),
+        bn_gamma: None,
+        bn_beta: None,
+        bn_mean: None,
+        bn_var: None,
+    }
+}
+
+/// A head whose shared-conv stack is one `ch->ch` conv, with empty seg/uv heads,
+/// so the bench isolates a single conv-layer cost.
+fn single_conv_head(ch: usize, k: usize) -> DensePoseHead {
+    let mut config = DensePoseConfig::new(ch, 1, 2);
+    config.kernel_size = k;
+    config.padding = k / 2; // same padding
+    config.hidden_channels = vec![ch];
+    let weights = DensePoseWeights {
+        shared_conv: vec![conv_layer(ch, ch, k)],
+        segmentation_head: vec![],
+        uv_head: vec![],
+    };
+    DensePoseHead::with_weights(config, weights).expect("valid head")
+}
+
+fn bench_native_conv(c: &mut Criterion) {
+    let mut group = c.benchmark_group("native_conv");
+    // (channels, spatial, kernel) — a modest map and a larger one.
+    for &(ch, hw, k) in &[(16usize, 32usize, 3usize), (32, 32, 3)] {
+        let head = single_conv_head(ch, k);
+        let input = Tensor::Float4D(Array4::from_shape_fn((1, ch, hw, hw), |(_, c, y, x)| {
+            ((c + y + x) as f32 * 0.001).cos()
+        }));
+        // Throughput in output elements processed.
+        group.throughput(Throughput::Elements((ch * hw * hw) as u64));
+        group.bench_with_input(
+            BenchmarkId::from_parameter(format!("ch{ch}_hw{hw}_k{k}")),
+            &input,
+            |bencher, inp| {
+                bencher.iter(|| {
+                    let out = head.forward(black_box(inp)).expect("forward ok");
+                    black_box(out);
+                });
+            },
+        );
+    }
+    group.finish();
+}
+
+criterion_group!(benches, bench_native_conv);
+criterion_main!(benches);

v2/crates/wifi-densepose-nn/src/densepose.rs

@@ -338,7 +338,16 @@ impl DensePoseHead {
 
         let mut output = Array4::zeros((batch, out_channels, out_height, out_width));
 
-        // Simple convolution implementation (not optimized)
+        // Naive direct convolution (one MAC per tap). ADR-155 M2 §4: a
+        // range-clamped variant (hoisting the per-tap in-bounds branch out of the
+        // inner loops) was prototyped and proven bit-identical, but a committed
+        // criterion bench (`benches/native_conv_bench.rs`) showed the perf result
+        // is INCONCLUSIVE on this host: a ~35% win on padding-heavy small-channel
+        // maps but a small (~3%) *regression* on channel-heavy maps, all inside a
+        // ±20% run-to-run noise floor. Per the §0 PROOF discipline we do not ship
+        // a perf change whose benefit isn't robustly positive, nor fabricate a
+        // number — the naive loop is kept and the rewrite is honestly deferred
+        // (see ADR-155 §8). Behaviour pinned by `native_conv_matches_reference`.
         for b in 0..batch {
             for oc in 0..out_channels {
                 for oh in 0..out_height {
@@ -565,6 +574,61 @@ impl BodyPart {
 #[cfg(test)]
 mod tests {
     use super::*;
+    use ndarray::Array4;
+
+    /// ADR-155 M2 §4: characterize the native conv against **hand-computed**
+    /// values so the §8 native-conv perf rewrite (or any future change) has a
+    /// behaviour anchor — a 1×1 conv is just a per-pixel scalar multiply, and a
+    /// same-padded 3×3 corner has a known truncated-window sum. Pins CURRENT
+    /// behaviour (no behaviour change in this milestone — the rewrite was
+    /// reverted as perf-inconclusive; see `benches/native_conv_bench.rs`).
+    #[test]
+    fn native_conv_matches_reference() {
+        // --- Case 1: a 1×1 conv (no padding) is exactly `out = w·in + b`. ---
+        let w11 = ConvLayerWeights {
+            weight: Array4::from_shape_fn((1, 1, 1, 1), |_| 2.0_f32),
+            bias: Some(ndarray::Array1::from_elem(1, 0.5_f32)),
+            bn_gamma: None,
+            bn_beta: None,
+            bn_mean: None,
+            bn_var: None,
+        };
+        let input = Array4::from_shape_fn((1, 1, 2, 2), |(_, _, y, x)| (y * 2 + x) as f32);
+        let mut cfg = DensePoseConfig::new(1, 1, 2);
+        cfg.kernel_size = 1;
+        cfg.padding = 0;
+        cfg.hidden_channels = vec![1];
+        let head = DensePoseHead::new(cfg).unwrap();
+        let out = head.apply_conv_layer(&input, &w11).unwrap();
+        assert_eq!(out.dim(), (1, 1, 2, 2));
+        // out[y,x] = 2·in[y,x] + 0.5 ⇒ {0.5, 2.5, 4.5, 6.5}.
+        for (got, want) in out.iter().zip([0.5_f32, 2.5, 4.5, 6.5].iter()) {
+            assert!((got - want).abs() < 1e-6, "1x1 conv: got {got}, want {want}");
+        }
+
+        // --- Case 2: a same-padded 3×3 all-ones kernel sums the in-bounds
+        // window. Input is all 1.0 on a 3×3 map ⇒ the centre output = 9 (full
+        // window), each corner = 4 (2×2 truncated window). ---
+        let w33 = ConvLayerWeights {
+            weight: Array4::from_elem((1, 1, 3, 3), 1.0_f32),
+            bias: None,
+            bn_gamma: None,
+            bn_beta: None,
+            bn_mean: None,
+            bn_var: None,
+        };
+        let ones = Array4::from_elem((1, 1, 3, 3), 1.0_f32);
+        let mut cfg2 = DensePoseConfig::new(1, 1, 2);
+        cfg2.kernel_size = 3;
+        cfg2.padding = 1;
+        cfg2.hidden_channels = vec![1];
+        let head2 = DensePoseHead::new(cfg2).unwrap();
+        let out2 = head2.apply_conv_layer(&ones, &w33).unwrap();
+        assert_eq!(out2.dim(), (1, 1, 3, 3));
+        assert!((out2[[0, 0, 1, 1]] - 9.0).abs() < 1e-6, "centre full window = 9");
+        assert!((out2[[0, 0, 0, 0]] - 4.0).abs() < 1e-6, "corner 2x2 window = 4");
+        assert!((out2[[0, 0, 0, 1]] - 6.0).abs() < 1e-6, "edge 2x3 window = 6");
+    }
 
     #[test]
     fn test_config_validation() {

v2/crates/wifi-densepose-nn/src/rf_encoder.rs

@@ -98,8 +98,64 @@ pub struct LinearHead {
     var_b: f32,
 }
 
+/// A shape mismatch when building a [`LinearHead`] from supplied weights.
+///
+/// Returned by [`LinearHead::try_new`] so a caller loading weights from an
+/// **untrusted / deserialized** source can validate the tensor shapes without
+/// the panic that [`LinearHead::new`] raises on a programmer-supplied mismatch
+/// (ADR-155 M2 §3: a pure-Rust input guard ahead of the construction contract).
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub enum RfHeadError {
+    /// `w.len()` was not `out_dim * EMBEDDING_DIM`.
+    WeightShape {
+        /// Expected length (`out_dim * EMBEDDING_DIM`).
+        expected: usize,
+        /// Actual `w.len()`.
+        got: usize,
+    },
+    /// `b.len()` was not `out_dim`.
+    BiasShape {
+        /// Expected length (`out_dim`).
+        expected: usize,
+        /// Actual `b.len()`.
+        got: usize,
+    },
+    /// `var_w.len()` was not `EMBEDDING_DIM`.
+    VarWeightShape {
+        /// Expected length (`EMBEDDING_DIM`).
+        expected: usize,
+        /// Actual `var_w.len()`.
+        got: usize,
+    },
+}
+
+impl std::fmt::Display for RfHeadError {
+    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+        match self {
+            Self::WeightShape { expected, got } => {
+                write!(f, "weight shape mismatch: expected {expected}, got {got}")
+            }
+            Self::BiasShape { expected, got } => {
+                write!(f, "bias shape mismatch: expected {expected}, got {got}")
+            }
+            Self::VarWeightShape { expected, got } => {
+                write!(f, "var weight shape mismatch: expected {expected}, got {got}")
+            }
+        }
+    }
+}
+
+impl std::error::Error for RfHeadError {}
+
 impl LinearHead {
     /// Build a head with given weights. `w.len()` must be `out_dim * EMBEDDING_DIM`.
+    ///
+    /// # Panics
+    ///
+    /// Panics on a shape mismatch (`w`/`b`/`var_w`). This is a construction-time
+    /// API contract on *programmer-supplied* vectors. For weights from an
+    /// untrusted / deserialized source, prefer [`LinearHead::try_new`], which
+    /// returns a typed [`RfHeadError`] instead of panicking.
     #[must_use]
     pub fn new(task: TaskKind, out_dim: usize, w: Vec<f32>, b: Vec<f32>, var_w: Vec<f32>, var_b: f32) -> Self {
         assert_eq!(w.len(), out_dim * EMBEDDING_DIM, "weight shape mismatch");
@@ -108,6 +164,40 @@ impl LinearHead {
         Self { task, w, b, out_dim, var_w, var_b }
     }
 
+    /// Fallible constructor: validate the weight shapes and return a typed
+    /// [`RfHeadError`] on mismatch instead of panicking (ADR-155 M2 §3).
+    ///
+    /// Use this when `w` / `b` / `var_w` originate from a checkpoint or any
+    /// untrusted source. On success the produced head is byte-for-byte identical
+    /// to [`LinearHead::new`] with the same arguments.
+    ///
+    /// # Errors
+    ///
+    /// Returns [`RfHeadError`] when any of:
+    /// - `w.len() != out_dim * EMBEDDING_DIM`
+    /// - `b.len() != out_dim`
+    /// - `var_w.len() != EMBEDDING_DIM`
+    pub fn try_new(
+        task: TaskKind,
+        out_dim: usize,
+        w: Vec<f32>,
+        b: Vec<f32>,
+        var_w: Vec<f32>,
+        var_b: f32,
+    ) -> Result<Self, RfHeadError> {
+        let expected_w = out_dim * EMBEDDING_DIM;
+        if w.len() != expected_w {
+            return Err(RfHeadError::WeightShape { expected: expected_w, got: w.len() });
+        }
+        if b.len() != out_dim {
+            return Err(RfHeadError::BiasShape { expected: out_dim, got: b.len() });
+        }
+        if var_w.len() != EMBEDDING_DIM {
+            return Err(RfHeadError::VarWeightShape { expected: EMBEDDING_DIM, got: var_w.len() });
+        }
+        Ok(Self { task, w, b, out_dim, var_w, var_b })
+    }
+
     /// A zero-initialised head (uncertainty = softplus(0) ≈ 0.693).
     #[must_use]
     pub fn zeros(task: TaskKind, out_dim: usize) -> Self {
@@ -136,9 +226,14 @@ impl LinearHead {
     }
 }
 
+/// Input magnitude above which `softplus(x) ≈ x` to f32 precision, so the
+/// `exp` is skipped to avoid overflow (ADR-155 M2 §8: de-magicked from a bare
+/// `20.0`; value unchanged). At x = 20, `ln(1+e^20) − 20 ≈ 2e-9`, below f32 eps.
+const SOFTPLUS_LINEAR_THRESHOLD: f32 = 20.0;
+
 fn softplus(x: f32) -> f32 {
     // Numerically stable softplus.
-    if x > 20.0 {
+    if x > SOFTPLUS_LINEAR_THRESHOLD {
         x
     } else {
         (1.0 + x.exp()).ln()
@@ -270,6 +365,48 @@ mod tests {
         RfEmbedding::new(vec![fill; EMBEDDING_DIM])
     }
 
+    /// ADR-155 M2 §8: the de-magicked softplus linear-threshold must equal the
+    /// prior inline `20.0` literal exactly (operating-value guard).
+    #[test]
+    fn softplus_threshold_unchanged_from_literal() {
+        assert_eq!(SOFTPLUS_LINEAR_THRESHOLD, 20.0_f32);
+    }
+
+    /// ADR-155 M2 §3: `try_new` accepts correctly-shaped weights and produces a
+    /// head byte-identical to `new`, but returns a typed error on a mismatched
+    /// (e.g. corrupt-checkpoint) shape instead of panicking.
+    #[test]
+    fn try_new_accepts_valid_and_rejects_each_bad_shape() {
+        let out_dim = 2;
+        let w = vec![0.0; out_dim * EMBEDDING_DIM];
+        let b = vec![0.0; out_dim];
+        let var_w = vec![0.0; EMBEDDING_DIM];
+
+        // Valid: try_new == new (forward identical on a probe embedding).
+        let head = LinearHead::try_new(TaskKind::Presence, out_dim, w.clone(), b.clone(), var_w.clone(), 0.0)
+            .expect("valid shapes must construct");
+        let reference = LinearHead::new(TaskKind::Presence, out_dim, w.clone(), b.clone(), var_w.clone(), 0.0);
+        assert_eq!(head.forward(&emb(0.5)).values, reference.forward(&emb(0.5)).values);
+
+        // Bad weight length.
+        assert_eq!(
+            LinearHead::try_new(TaskKind::Presence, out_dim, vec![0.0; 3], b.clone(), var_w.clone(), 0.0)
+                .unwrap_err(),
+            RfHeadError::WeightShape { expected: out_dim * EMBEDDING_DIM, got: 3 }
+        );
+        // Bad bias length.
+        assert_eq!(
+            LinearHead::try_new(TaskKind::Presence, out_dim, w.clone(), vec![0.0; 1], var_w.clone(), 0.0)
+                .unwrap_err(),
+            RfHeadError::BiasShape { expected: out_dim, got: 1 }
+        );
+        // Bad var-weight length.
+        assert_eq!(
+            LinearHead::try_new(TaskKind::Presence, out_dim, w, b, vec![0.0; 5], 0.0).unwrap_err(),
+            RfHeadError::VarWeightShape { expected: EMBEDDING_DIM, got: 5 }
+        );
+    }
+
     #[test]
     fn head_forward_produces_values_and_finite_uncertainty() {
         let head = LinearHead::zeros(TaskKind::Presence, 2);

v2/crates/wifi-densepose-ruvector/benches/sketch_bench.rs

@@ -185,17 +185,25 @@ fn bench_topk(c: &mut Criterion) {
 /// reads it back, so the criterion timing is meaningless here on purpose — the
 /// value is the `println!` summary.
 fn bench_pass2_coverage(c: &mut Criterion) {
-    use wifi_densepose_ruvector::coverage::{measure_pass1, measure_pass2, CoverageParams};
+    use wifi_densepose_ruvector::coverage::{
+        measure_estimator, measure_estimator_euclidean, measure_pass1, measure_pass2,
+        CoverageParams,
+    };
 
     let base = CoverageParams::aether_default(0xAD00_0084);
     let rot_seed = 0x5EED_C0DE_1234_5678u64;
 
-    println!("\n=== ADR-156 §8 RaBitQ Pass-2 coverage (anisotropic planted clusters) ===");
+    println!("\n=== ADR-156 §8/§11 RaBitQ coverage (anisotropic planted clusters) ===");
     println!(
         "dim={} N={} K={} clusters={} noise={} queries={} master_seed=0x{:X} rot_seed=0x{:X}",
         base.dim, base.n, base.k, base.n_clusters, base.noise, base.n_queries, base.seed, rot_seed
     );
     println!("(coverage = |sketch_topK ∩ float_cosine_topK| / K, ADR-084 bar = 90%)");
+    println!("estimator side info = 8 B/vec (residual_norm + x_dot_o, 2x f32)");
+    println!(
+        "  {:<12} {:>8} {:>8} {:>11} {:>11}",
+        "candidate_k", "P1-sign", "P2-sign", "Est-cosine", "Est-euclid"
+    );
     for &cand in &[8usize, 16, 24, 32, 64] {
         let p = CoverageParams {
             candidate_k: cand,
@@ -203,11 +211,17 @@ fn bench_pass2_coverage(c: &mut Criterion) {
         };
         let p1 = measure_pass1(p).coverage;
         let p2 = measure_pass2(p, rot_seed).coverage;
-        let flag = if p2 >= 0.90 { "Pass2≥90%" } else { "" };
+        let est_cos = measure_estimator(p, rot_seed).coverage;
+        let est_euc = measure_estimator_euclidean(p, rot_seed).coverage;
+        let flag = if est_cos >= 0.90 { "EST≥90%" } else { "" };
+        let strict = if cand == base.k { " STRICT" } else { "" };
         println!(
-            "  candidate_k={cand:<3}  Pass1={:6.2}%  Pass2={:6.2}%  {flag}",
+            "  {:<12} {:>7.2}% {:>7.2}% {:>10.2}% {:>10.2}%  {flag}{strict}",
+            cand,
             p1 * 100.0,
-            p2 * 100.0
+            p2 * 100.0,
+            est_cos * 100.0,
+            est_euc * 100.0
         );
     }
     println!("========================================================================\n");

v2/crates/wifi-densepose-ruvector/src/coverage.rs

@@ -33,6 +33,7 @@
 //! value derives from a seed via SplitMix64, so the whole harness is
 //! reproducible bit-for-bit.
 
+use crate::estimator::EstimatorBank;
 use crate::{Rotation, SketchBank};
 
 /// SplitMix64 step — reproducible PRNG for fixture generation (dependency-free).
@@ -205,6 +206,80 @@ pub fn measure_pass2(p: CoverageParams, rotation_seed: u64) -> CoverageResult {
     measure_inner(p, Some(rot))
 }
 
+/// Measure mean top-K coverage of the **RaBitQ unbiased estimator** rerank
+/// (ADR-156 Milestone-2) against the full-float top-K, on the **same**
+/// anisotropic synthetic fixture and query stream as [`measure_pass1`] /
+/// [`measure_pass2`].
+///
+/// This is the whole point of Milestone-2: instead of ranking candidates by
+/// raw Hamming over sign bits ([`measure_pass2`]), rank them by the RaBitQ
+/// *unbiased distance estimate* recovered from the 1-bit code + per-vector side
+/// info ([`crate::estimator`]). `rotation_seed` fixes the rotation (index and
+/// query share it). The fixture, cluster centres, query draws, and ground-truth
+/// cosine top-K are **bit-identical** to `measure_pass2`, so the only variable
+/// is sign-Hamming vs estimator-rerank — an honest apples-to-apples coverage
+/// comparison.
+pub fn measure_estimator(p: CoverageParams, rotation_seed: u64) -> CoverageResult {
+    // Cosine ground truth ⇒ rerank by the estimated COSINE key (the angular
+    // sensor's natural metric). See `measure_estimator_euclidean` for the
+    // squared-euclidean key, reported alongside for honesty.
+    measure_estimator_inner(p, rotation_seed, EstimatorRank::Cosine)
+}
+
+/// Same as [`measure_estimator`] but reranks by the estimated **squared
+/// euclidean** distance key instead of cosine. Reported alongside the cosine
+/// rerank so the ADR shows both honestly: against a *cosine* ground truth, the
+/// cosine key is the apples-to-apples comparison to sign-Hamming (also angular),
+/// while the euclidean key mixes in residual-norm and generally ranks worse here.
+pub fn measure_estimator_euclidean(p: CoverageParams, rotation_seed: u64) -> CoverageResult {
+    measure_estimator_inner(p, rotation_seed, EstimatorRank::Euclidean)
+}
+
+#[derive(Clone, Copy)]
+enum EstimatorRank {
+    Cosine,
+    Euclidean,
+}
+
+fn measure_estimator_inner(
+    p: CoverageParams,
+    rotation_seed: u64,
+    rank: EstimatorRank,
+) -> CoverageResult {
+    let rot = Rotation::new(rotation_seed, p.dim);
+    let float_bank = make_fixture(p);
+    let centres = cluster_centres(p.dim, p.n_clusters.max(1), p.seed);
+
+    // Estimator bank over the SAME fixture vectors.
+    let mut bank = EstimatorBank::new(rot);
+    for (i, v) in float_bank.iter().enumerate() {
+        bank.insert_embedding(i as u32, v);
+    }
+
+    let mut total = 0.0f64;
+    for q in 0..p.n_queries {
+        // IDENTICAL query draw to measure_inner (same seed expression).
+        let c = q % p.n_clusters.max(1);
+        let qv = realize(
+            &centres[c],
+            p.dim,
+            p.noise,
+            p.seed ^ 0xDEAD_0000_0000 ^ (q as u64).wrapping_mul(0x2545_F491),
+        );
+        let truth = float_topk(&float_bank, &qv, p.k);
+        let cand = match rank {
+            EstimatorRank::Cosine => bank.topk_estimated_cosine(&qv, p.candidate_k),
+            EstimatorRank::Euclidean => bank.topk_estimated(&qv, p.candidate_k),
+        };
+        let cand_ids: std::collections::HashSet<u32> = cand.into_iter().map(|(id, _)| id).collect();
+        let hit = truth.iter().filter(|id| cand_ids.contains(id)).count();
+        total += hit as f64 / p.k as f64;
+    }
+    CoverageResult {
+        coverage: total / p.n_queries as f64,
+    }
+}
+
 /// Measure mean top-K coverage of a **multi-bit (Pass-3)** rotated sketch:
 /// `bits` bits per dimension instead of 1, ranked by L1 distance over the
 /// per-dim codes (the natural multi-bit generalization of hamming). This is the
@@ -409,6 +484,92 @@ mod tests {
         );
     }
 
+    #[test]
+    fn estimator_rerank_not_worse_than_sign() {
+        // ADR-156 Milestone-2 core regression: on a fixed anisotropic fixture,
+        // reranking the candidate set by the RaBitQ unbiased ESTIMATE must be
+        // >= ranking by sign-only Hamming (Pass-2). The estimator must never
+        // make coverage WORSE — it strictly refines the same 1-bit codes with
+        // side info. (We assert >= here, not a hard 90% bar — the bar is the
+        // measured number reported in the ADR, not a unit invariant.)
+        let p = CoverageParams {
+            n: 512,
+            n_queries: 64,
+            n_clusters: 32,
+            ..CoverageParams::aether_default(0x00C0_FFEE)
+        };
+        let rot_seed = 0x1234_5678_9ABC_DEF0u64;
+        let sign = measure_pass2(p, rot_seed).coverage;
+        let est = measure_estimator(p, rot_seed).coverage;
+        assert!(
+            est + 1e-9 >= sign,
+            "estimator rerank coverage {est:.4} regressed below sign-only Pass-2 {sign:.4}"
+        );
+    }
+
+    #[test]
+    fn estimator_coverage_is_deterministic() {
+        // Same params + rotation seed ⇒ same measured coverage, twice.
+        let p = CoverageParams {
+            n: 256,
+            n_queries: 16,
+            n_clusters: 16,
+            ..CoverageParams::aether_default(0xE571_3A7E)
+        };
+        let a = measure_estimator(p, 0xFEED_FACE_0000_0001).coverage;
+        let b = measure_estimator(p, 0xFEED_FACE_0000_0001).coverage;
+        assert_eq!(a, b, "estimator coverage must be deterministic");
+        assert!((0.0..=1.0).contains(&a));
+    }
+
+    /// Deterministic, test-runnable coverage measurement that PRINTS the
+    /// Milestone-2 strict-K table: Pass-1 | Pass-2-sign | Pass-2+estimator, at
+    /// the strict bar (candidate_k == K) plus the over-fetch curve. Run with:
+    ///   cargo test -p wifi-densepose-ruvector --no-default-features \
+    ///     estimator_coverage_report -- --nocapture
+    #[test]
+    fn estimator_coverage_report() {
+        let base = CoverageParams::aether_default(0xAD00_0084);
+        let rot_seed = 0x5EED_C0DE_1234_5678u64;
+        println!(
+            "\n=== ADR-156 Milestone-2 RaBitQ estimator coverage (anisotropic synthetic) ==="
+        );
+        println!(
+            "dim={} N={} K={} queries={} clusters={} noise={} master_seed=0x{:X} rotation_seed=0x{:X}",
+            base.dim, base.n, base.k, base.n_queries, base.n_clusters, base.noise, base.seed, rot_seed
+        );
+        println!("side info = 8 B/vec (residual_norm + x_dot_o, 2x f32)");
+        println!(
+            "{:<12} {:>9} {:>9} {:>11} {:>11} {:>9}",
+            "candidate_k", "P1-sign", "P2-sign", "Est-cosine", "Est-euclid", "vs 90%"
+        );
+        for &c in &[base.k, 16usize, 24, 32, 64] {
+            let pc = CoverageParams {
+                candidate_k: c,
+                ..base
+            };
+            let p1 = measure_pass1(pc).coverage;
+            let p2 = measure_pass2(pc, rot_seed).coverage;
+            let est_cos = measure_estimator(pc, rot_seed).coverage;
+            let est_euc = measure_estimator_euclidean(pc, rot_seed).coverage;
+            let bar = if est_cos >= 0.90 { "EST≥90%" } else { "below" };
+            let strict = if c == base.k { " (STRICT)" } else { "" };
+            println!(
+                "{:<12} {:>8.2}% {:>8.2}% {:>10.2}% {:>10.2}% {:>9}{}",
+                c,
+                p1 * 100.0,
+                p2 * 100.0,
+                est_cos * 100.0,
+                est_euc * 100.0,
+                bar,
+                strict
+            );
+        }
+        println!("============================================================================\n");
+        let strict = measure_estimator(base, rot_seed).coverage;
+        assert!((0.0..=1.0).contains(&strict));
+    }
+
     #[test]
     fn fixture_is_deterministic() {
         let p = CoverageParams::aether_default(12345);

v2/crates/wifi-densepose-ruvector/src/estimator.rs

@@ -0,0 +1,685 @@
+//! RaBitQ **unbiased distance estimator** — the real Gao & Long (SIGMOD 2024)
+//! contribution, on top of the Pass-2 rotation ([`crate::rotation`]).
+//!
+//! ## Why this exists (ADR-156 Milestone-2)
+//!
+//! Pass-1 ([`crate::sketch`]) and Pass-2 ([`crate::rotation`]) use only the
+//! **sign** of each rotated coordinate and rank candidates by **Hamming /
+//! bit distance** — a coarse, monotone-but-lossy proxy for the true angle.
+//! ADR-156 §10 measured that sign-only Pass-2 leaves strict-K
+//! (`candidate_k == K`) top-K coverage at **~46%**, well below the ADR-084
+//! **≥90%** bar, and only clears 90% with ~3× over-fetch.
+//!
+//! RaBitQ's *actual* algorithmic contribution is not the sign bits — it is an
+//! **unbiased estimator of the inner product / squared distance** recovered
+//! from the 1-bit code **plus a few bytes of per-vector side information**.
+//! That estimate is far sharper than the raw Hamming proxy, so it can
+//! **rerank** the candidate set and (the question this module measures) close
+//! the strict-K coverage gap.
+//!
+//! ## The estimator (paper formula + our simplification, stated honestly)
+//!
+//! Notation follows the paper. Let `P` be the Pass-2 orthogonal rotation
+//! ([`crate::Rotation`], `R = H·D`). For a data vector `o_raw` and a query
+//! `q_raw`:
+//!
+//! 1. **Centroid.** The paper centres each vector on its (per-cluster)
+//!    centroid `c`: residual `o_r = o_raw − c`. **We use a zero / global
+//!    centroid `c = 0`** (`o_r = o_raw`). This is an explicit simplification
+//!    (no IVF/k-means cluster structure in the current sketch path) — it costs
+//!    accuracy when the data is far off-origin, and we document it rather than
+//!    hide it. With `c = 0`, the residual *is* the raw vector.
+//!
+//! 2. **Unit residual + 1-bit code.** `o = o_r / ‖o_r‖`. Rotate:
+//!    `o' = P·o`. The 1-bit code is `x̄_i = sign(o'_i) · (1/√D)`, so `x̄`
+//!    is a **unit vector** in `{±1/√D}^D` (the corner of the hypercube nearest
+//!    `o'`). `D` is the rotation's padded dimension (`next_pow2(dim)`), because
+//!    the FHT operates on the padded length and `x̄` is unit over that length.
+//!
+//! 3. **Per-vector side information** (the "few bytes"): we store, per sketch,
+//!    - `residual_norm = ‖o_r‖` (an `f32`), and
+//!    - `x_dot_o = ⟨x̄, o'⟩` (an `f32`), the cosine between the code and the
+//!      rotated unit residual. This is the quantity the paper calls `⟨x̄, o⟩`
+//!      (after rotation); it lies in `(0, 1]` and is `1` only when `o'`
+//!      already sits exactly on a hypercube corner.
+//!
+//!    That is **8 bytes/vector** of side info (2× `f32`).
+//!
+//! 4. **Query-time estimate.** Rotate the query residual: `q' = P·q_r`. The
+//!    **unbiased estimator of `⟨o', q'⟩`** (equivalently `⟨o, q_r⟩`, since `P`
+//!    is orthogonal) is
+//!
+//!    ```text
+//!        ⟨o', q'⟩  ≈  ⟨x̄, q'⟩ / ⟨x̄, o'⟩  =  ⟨x̄, q'⟩ / x_dot_o
+//!    ```
+//!
+//!    This is RaBitQ Eq. (in the paper, the estimator `<q, o> ≈ <q̄, ...>`):
+//!    the random rotation makes the quantization error of `x̄` (relative to
+//!    `o'`) orthogonal **in expectation** to `q'`, so dividing the measured
+//!    `⟨x̄, q'⟩` by `x_dot_o` is **unbiased** for `⟨o', q'⟩`, with the paper's
+//!    `O(1/√D)` error bound. The only per-candidate cost is one length-`D`
+//!    dot product `⟨x̄, q'⟩` — which, because `x̄ ∈ {±1/√D}`, is just a signed
+//!    sum of the query coordinates (`±` chosen by the stored sign bits),
+//!    i.e. as cheap as the Hamming proxy plus one multiply.
+//!
+//! 5. **Inner product and squared distance.** Un-normalize:
+//!    `⟨o_r, q_r⟩ = ‖o_r‖ · ⟨o, q_r⟩`. Then
+//!
+//!    ```text
+//!        ‖q_r − o_r‖²  =  ‖q_r‖²  +  ‖o_r‖²  −  2·⟨o_r, q_r⟩
+//!    ```
+//!
+//!    For **ranking** a candidate set against one fixed query, `‖q_r‖²` is a
+//!    per-query constant and can be dropped; we keep it in
+//!    [`DistanceEstimator::estimate_sq_distance`] so the value is a genuine
+//!    distance estimate (used by the unbiasedness test), and expose the
+//!    cheaper ranking key separately.
+//!
+//! ## What is unbiased, and what we measure
+//!
+//! The estimator of `⟨o', q'⟩` is unbiased over the random rotation. We pin
+//! that on a small hand-checkable fixture (`estimator_unbiased_on_fixture`):
+//! averaging the estimate over many random rotation seeds converges to the true
+//! inner product within tolerance. We then measure whether **reranking the
+//! candidate set by this estimate** closes the strict-K coverage gap that the
+//! sign-only Pass-2 left at ~46% — reported honestly in ADR-156 §10 / §11
+//! whether it clears 90% or not.
+//!
+//! ## Backward compatibility
+//!
+//! This module is **purely additive**. It introduces an *extended* sketch type
+//! ([`EstimatorSketch`]) and bank ([`EstimatorBank`]) that carry the side info;
+//! the Pass-1 [`crate::Sketch`] / Pass-2 [`crate::SketchBank`] paths and the
+//! [`crate::WireSketch`] wire format are **untouched**. Nothing on the existing
+//! surface changes.
+
+use crate::rotation::{next_pow2, Rotation};
+
+/// The per-vector side information RaBitQ needs to turn a 1-bit code into an
+/// **unbiased** distance estimate (§ module docs step 3).
+///
+/// Two `f32`s = **8 bytes/vector** on top of the packed sign bits.
+#[derive(Debug, Clone, Copy, PartialEq)]
+pub struct SideInfo {
+    /// `‖o_r‖` — L2 norm of the (zero-centroid) residual = the raw vector norm.
+    pub residual_norm: f32,
+    /// `⟨x̄, o'⟩` — dot product of the unit 1-bit code with the rotated unit
+    /// residual. In `(0, 1]`; the paper's `⟨x̄, o⟩`. Drives the unbiased
+    /// rescaling `⟨x̄, q'⟩ / x_dot_o`.
+    pub x_dot_o: f32,
+}
+
+/// A Pass-2 sketch **plus** the RaBitQ side information, sufficient to compute
+/// the unbiased distance estimate at query time.
+///
+/// Stores the packed sign bits over the **padded** rotation length `D`
+/// (`next_pow2(dim)`) — the frame `x̄` actually lives in — together with the
+/// [`SideInfo`]. Construct via [`EstimatorSketch::from_embedding`]; the index
+/// and the query **must** use the same [`Rotation`] (same seed + dim), exactly
+/// as for a Pass-2 sketch.
+#[derive(Debug, Clone)]
+pub struct EstimatorSketch {
+    /// Sign bits of the rotated *padded* unit residual, MSB-first per byte.
+    /// Length is `ceil(D / 8)` where `D = next_pow2(dim)`. Bit set ⇒ `o'_i ≥ 0`
+    /// ⇒ code coordinate `+1/√D`; clear ⇒ `−1/√D`.
+    bits: Vec<u8>,
+    /// Padded rotation dimension `D = next_pow2(dim)`; the code is unit over `D`.
+    padded_dim: usize,
+    /// Source embedding dimension (for compatibility checks / reporting).
+    embedding_dim: usize,
+    /// The RaBitQ side info for the unbiased estimate.
+    side: SideInfo,
+}
+
+impl EstimatorSketch {
+    /// Build an estimator sketch from a dense embedding and a [`Rotation`].
+    ///
+    /// Zero-centroid (`c = 0`): the residual is the raw embedding. The vector is
+    /// rotated through `rotation` over its padded length `D = next_pow2(dim)`,
+    /// the sign of each rotated coordinate is packed, and the side info
+    /// (`‖o_r‖`, `⟨x̄, o'⟩`) is computed in the same pass.
+    ///
+    /// A zero (or all-equal-to-its-own-mean) input yields `residual_norm = 0`;
+    /// its estimate degenerates to `0` (handled in
+    /// [`EstimatorBank`]) rather than dividing by zero.
+    pub fn from_embedding(embedding: &[f32], rotation: &Rotation) -> Self {
+        Self::from_embedding_centred(embedding, rotation, None)
+    }
+
+    /// Build an estimator sketch with an **explicit centroid** `c` subtracted
+    /// before rotation (the paper's per-cluster centroid; `o_r = o_raw − c`).
+    ///
+    /// Pass `None` for the zero-centroid simplification (`c = 0`, identical to
+    /// [`EstimatorSketch::from_embedding`]). Pass `Some(centroid)` (length `dim`)
+    /// to centre on a shared global / cluster centroid — the index and the query
+    /// **must** use the *same* centroid, exactly as they must share the rotation.
+    /// This path exists so ADR-156 can **measure the cost of the zero-centroid
+    /// simplification** honestly rather than assert it.
+    pub fn from_embedding_centred(
+        embedding: &[f32],
+        rotation: &Rotation,
+        centroid: Option<&[f32]>,
+    ) -> Self {
+        let dim = rotation.dim();
+        let padded = next_pow2(dim);
+        // Residual o_r = o_raw − c (c = 0 when centroid is None). Build it once.
+        let residual: Vec<f32> = (0..dim)
+            .map(|i| {
+                let v = embedding.get(i).copied().unwrap_or(0.0);
+                let c = centroid.and_then(|c| c.get(i)).copied().unwrap_or(0.0);
+                v - c
+            })
+            .collect();
+        let residual_norm = {
+            let mut acc = 0.0f64;
+            for &v in &residual {
+                acc += (v as f64) * (v as f64);
+            }
+            acc.sqrt() as f32
+        };
+
+        // Rotate the RESIDUAL over the PADDED length so the code frame matches
+        // what `x_dot_o` and the query dot product use.
+        let rotated_padded = rotation.apply_padded(&residual);
+        debug_assert_eq!(rotated_padded.len(), padded);
+
+        // 1-bit code over the padded length: x̄_i = sign(o'_i)/√D on the *unit*
+        // residual. Since o' = P·o = P·(o_r/‖o_r‖) = (P·o_r)/‖o_r‖, and sign is
+        // scale-invariant, sign(o'_i) == sign((P·o_r)_i) == sign(rotated_padded_i).
+        // ⟨x̄, o'⟩ = (1/√D)·Σ sign(o'_i)·o'_i = (1/√D)·Σ |o'_i|
+        //         = (1/√D)·(Σ|(P·o_r)_i|) / ‖o_r‖.
+        let inv_sqrt_d = 1.0f32 / (padded as f32).sqrt();
+        let mut bits = vec![0u8; padded.div_ceil(8)];
+        let mut sum_abs = 0.0f64; // Σ |(P·o_r)_i|
+        for (i, &c) in rotated_padded.iter().enumerate() {
+            if c >= 0.0 {
+                bits[i / 8] |= 1 << (7 - (i % 8));
+            }
+            sum_abs += (c as f64).abs();
+        }
+        // ⟨x̄, o'⟩ with o' the rotated *unit* residual.
+        let x_dot_o = if residual_norm > 0.0 {
+            (inv_sqrt_d as f64 * sum_abs / residual_norm as f64) as f32
+        } else {
+            0.0
+        };
+
+        Self {
+            bits,
+            padded_dim: padded,
+            embedding_dim: dim,
+            side: SideInfo {
+                residual_norm,
+                x_dot_o,
+            },
+        }
+    }
+
+    /// The padded rotation dimension `D` the code lives in.
+    #[inline]
+    pub fn padded_dim(&self) -> usize {
+        self.padded_dim
+    }
+
+    /// Source embedding dimension.
+    #[inline]
+    pub fn embedding_dim(&self) -> usize {
+        self.embedding_dim
+    }
+
+    /// The RaBitQ side information.
+    #[inline]
+    pub fn side_info(&self) -> SideInfo {
+        self.side
+    }
+
+    /// `‖o_r‖` of the residual (zero-centroid ⇒ raw vector norm).
+    #[inline]
+    pub fn residual_norm(&self) -> f32 {
+        self.side.residual_norm
+    }
+
+    /// Side-information byte cost (excluding the packed sign bits): 8 bytes.
+    pub const SIDE_INFO_BYTES: usize = 2 * std::mem::size_of::<f32>();
+
+    /// `⟨x̄, q'⟩` — the dot product of this sketch's unit 1-bit code with a
+    /// rotated query `q'` (length `padded_dim`). Because `x̄_i = ±1/√D`, this is
+    /// `(1/√D)·Σ ±q'_i` with the sign taken from the stored bit. The single
+    /// per-candidate cost of the estimator.
+    #[inline]
+    fn code_dot(&self, q_rotated_padded: &[f32]) -> f32 {
+        debug_assert_eq!(q_rotated_padded.len(), self.padded_dim);
+        let inv_sqrt_d = 1.0f32 / (self.padded_dim as f32).sqrt();
+        let mut acc = 0.0f32;
+        for (i, &q) in q_rotated_padded.iter().enumerate() {
+            let bit = (self.bits[i / 8] >> (7 - (i % 8))) & 1;
+            if bit == 1 {
+                acc += q;
+            } else {
+                acc -= q;
+            }
+        }
+        acc * inv_sqrt_d
+    }
+}
+
+/// A pre-rotated query, computed **once** per query and reused across all
+/// candidates. Carries `q' = P·q_r` (over the padded length) and `‖q_r‖²`.
+#[derive(Debug, Clone)]
+pub struct EstimatorQuery {
+    /// `q' = P·q_r` over the padded rotation length.
+    q_rotated_padded: Vec<f32>,
+    /// `‖q_r‖²` — per-query constant in the squared-distance expansion.
+    q_norm_sq: f32,
+}
+
+impl EstimatorQuery {
+    /// Pre-rotate a query embedding through `rotation` (zero-centroid).
+    pub fn new(query: &[f32], rotation: &Rotation) -> Self {
+        Self::new_centred(query, rotation, None)
+    }
+
+    /// Pre-rotate a query residual `q_r = q − c` through `rotation`. The
+    /// centroid **must** match the one used to build the bank's sketches.
+    pub fn new_centred(query: &[f32], rotation: &Rotation, centroid: Option<&[f32]>) -> Self {
+        let dim = rotation.dim();
+        let residual: Vec<f32> = (0..dim)
+            .map(|i| {
+                let v = query.get(i).copied().unwrap_or(0.0);
+                let c = centroid.and_then(|c| c.get(i)).copied().unwrap_or(0.0);
+                v - c
+            })
+            .collect();
+        let mut q_norm_sq = 0.0f64;
+        for &v in &residual {
+            q_norm_sq += (v as f64) * (v as f64);
+        }
+        Self {
+            q_rotated_padded: rotation.apply_padded(&residual),
+            q_norm_sq: q_norm_sq as f32,
+        }
+    }
+}
+
+/// Computes RaBitQ unbiased estimates from an [`EstimatorSketch`] + a
+/// pre-rotated [`EstimatorQuery`].
+///
+/// Stateless — the methods are associated functions. Kept as a type for
+/// discoverability and to group the estimator formula in one place.
+pub struct DistanceEstimator;
+
+impl DistanceEstimator {
+    /// Unbiased estimate of `⟨o_r, q_r⟩` (the inner product of the residuals).
+    ///
+    /// `⟨o_r, q_r⟩ = ‖o_r‖ · (⟨x̄, q'⟩ / ⟨x̄, o'⟩)`. Returns `0.0` when the
+    /// stored `x_dot_o` is non-positive (degenerate / zero residual), which
+    /// cannot happen for a non-zero input but keeps the call total.
+    pub fn estimate_inner_product(sketch: &EstimatorSketch, query: &EstimatorQuery) -> f32 {
+        let x_dot_o = sketch.side.x_dot_o;
+        if x_dot_o <= 0.0 {
+            return 0.0;
+        }
+        let code_dot_q = sketch.code_dot(&query.q_rotated_padded);
+        // ⟨o, q_r⟩ ≈ ⟨x̄, q'⟩ / x_dot_o   (unit residual o)
+        let inner_unit = code_dot_q / x_dot_o;
+        sketch.side.residual_norm * inner_unit
+    }
+
+    /// Unbiased estimate of the **squared euclidean distance** `‖q_r − o_r‖²`.
+    ///
+    /// `= ‖q_r‖² + ‖o_r‖² − 2·⟨o_r, q_r⟩`, using the estimated inner product.
+    /// This is the value the unbiasedness test checks.
+    pub fn estimate_sq_distance(sketch: &EstimatorSketch, query: &EstimatorQuery) -> f32 {
+        let ip = Self::estimate_inner_product(sketch, query);
+        let o_norm = sketch.side.residual_norm;
+        query.q_norm_sq + o_norm * o_norm - 2.0 * ip
+    }
+
+    /// The cheap **euclidean ranking key** for nearest-neighbour reranking:
+    /// monotone in the estimated squared distance with the per-query constant
+    /// `‖q_r‖²` dropped. Smaller = nearer. Equals `‖o_r‖² − 2·⟨o_r, q_r⟩`.
+    ///
+    /// Use this (not [`Self::estimate_sq_distance`]) for top-K reranking under a
+    /// **euclidean** ground truth — it avoids adding the same `q_norm_sq` to
+    /// every candidate. For a **cosine** ground truth (AETHER / the coverage
+    /// harness), use [`Self::cosine_ranking_key`] instead.
+    #[inline]
+    pub fn ranking_key(sketch: &EstimatorSketch, query: &EstimatorQuery) -> f32 {
+        let ip = Self::estimate_inner_product(sketch, query);
+        let o_norm = sketch.side.residual_norm;
+        o_norm * o_norm - 2.0 * ip
+    }
+
+    /// The cheap **cosine ranking key**: smaller = nearer in cosine distance.
+    ///
+    /// Cosine distance is `1 − ⟨o_r,q_r⟩ / (‖o_r‖·‖q_r‖)`. `‖q_r‖` is a
+    /// per-query constant, so ranking by cosine distance ascending is ranking by
+    /// `⟨o_r,q_r⟩ / ‖o_r‖` **descending**, i.e. by `−⟨o, q_r⟩` ascending. And
+    /// `⟨o, q_r⟩ = ⟨x̄, q'⟩ / x_dot_o` — the unit-residual inner product, which
+    /// needs **only the code and `x_dot_o`**, not even `residual_norm`. We
+    /// return `−⟨o, q_r⟩` so "smaller = nearer" matches the euclidean key's
+    /// convention.
+    ///
+    /// This is the correct key when the sketch is used (as in ADR-084) as an
+    /// **angular** sensor graded against a cosine top-K: the 1-bit code is a
+    /// rotated-angle estimator, and dividing by `x_dot_o` is the RaBitQ unbiased
+    /// rescale of that angle's inner product.
+    #[inline]
+    pub fn cosine_ranking_key(sketch: &EstimatorSketch, query: &EstimatorQuery) -> f32 {
+        let x_dot_o = sketch.side.x_dot_o;
+        if x_dot_o <= 0.0 {
+            return 0.0;
+        }
+        // ⟨o, q_r⟩ = ⟨x̄, q'⟩ / x_dot_o ; nearer in cosine ⇒ larger ⇒ negate.
+        -(sketch.code_dot(&query.q_rotated_padded) / x_dot_o)
+    }
+}
+
+/// A bank of [`EstimatorSketch`]es with stable IDs, reranked by the RaBitQ
+/// **unbiased distance estimate** instead of raw Hamming.
+///
+/// All sketches share one [`Rotation`] (the index/query frame). The bank rotates
+/// every inserted embedding and every query through it, so the estimator is
+/// always computed in a consistent frame.
+///
+/// # Invariants
+/// - All sketches share the bank's `embedding_dim` and `Rotation`.
+/// - IDs are caller-assigned and stable.
+#[derive(Debug, Clone)]
+pub struct EstimatorBank {
+    rotation: Rotation,
+    entries: Vec<(u32, EstimatorSketch)>,
+    embedding_dim: usize,
+    /// Optional shared centroid subtracted from every embedding/query before
+    /// rotation. `None` = zero-centroid (the default simplification).
+    centroid: Option<Vec<f32>>,
+}
+
+impl EstimatorBank {
+    /// Create an empty bank over `rotation`'s dimension and frame (zero-centroid).
+    pub fn new(rotation: Rotation) -> Self {
+        let embedding_dim = rotation.dim();
+        Self {
+            rotation,
+            entries: Vec::new(),
+            embedding_dim,
+            centroid: None,
+        }
+    }
+
+    /// Create an empty bank that subtracts `centroid` from every embedding and
+    /// query before rotation (the paper's centroid path). Used by ADR-156 to
+    /// measure the cost of the zero-centroid simplification.
+    pub fn with_centroid(rotation: Rotation, centroid: Vec<f32>) -> Self {
+        let embedding_dim = rotation.dim();
+        Self {
+            rotation,
+            entries: Vec::new(),
+            embedding_dim,
+            centroid: Some(centroid),
+        }
+    }
+
+    /// The rotation (index/query frame) this bank uses.
+    #[inline]
+    pub fn rotation(&self) -> &Rotation {
+        &self.rotation
+    }
+
+    /// Number of stored sketches.
+    #[inline]
+    pub fn len(&self) -> usize {
+        self.entries.len()
+    }
+
+    /// True iff empty.
+    #[inline]
+    pub fn is_empty(&self) -> bool {
+        self.entries.is_empty()
+    }
+
+    /// Source embedding dimension.
+    #[inline]
+    pub fn embedding_dim(&self) -> usize {
+        self.embedding_dim
+    }
+
+    /// Insert a raw embedding, sketching it (with side info) through the bank's
+    /// rotation. The stored code and the queries share one rotated frame.
+    pub fn insert_embedding(&mut self, id: u32, embedding: &[f32]) {
+        let sketch = EstimatorSketch::from_embedding_centred(
+            embedding,
+            &self.rotation,
+            self.centroid.as_deref(),
+        );
+        self.entries.push((id, sketch));
+    }
+
+    /// Insert a pre-built [`EstimatorSketch`] (must have been built with this
+    /// bank's rotation; the caller is responsible for that).
+    pub fn insert(&mut self, id: u32, sketch: EstimatorSketch) {
+        self.entries.push((id, sketch));
+    }
+
+    /// Top-K nearest neighbours by the **RaBitQ unbiased estimate**, ascending
+    /// by [`DistanceEstimator::ranking_key`]. Returns up to `k` `(id, key)`
+    /// pairs. If `k == 0` or the bank is empty, returns empty. If the bank has
+    /// fewer than `k`, returns all of them.
+    ///
+    /// The query is rotated **once**; every candidate then costs one
+    /// length-`D` signed-sum dot product — the estimator is as cheap per
+    /// candidate as Hamming plus a multiply.
+    pub fn topk_estimated(&self, query: &[f32], k: usize) -> Vec<(u32, f32)> {
+        self.topk_by(query, k, DistanceEstimator::ranking_key)
+    }
+
+    /// Top-K by the estimated **cosine** distance
+    /// ([`DistanceEstimator::cosine_ranking_key`]) — the correct rerank when the
+    /// sketch is graded against a cosine top-K (AETHER / the coverage harness).
+    pub fn topk_estimated_cosine(&self, query: &[f32], k: usize) -> Vec<(u32, f32)> {
+        self.topk_by(query, k, DistanceEstimator::cosine_ranking_key)
+    }
+
+    /// Shared top-K driver parameterised on the ranking-key function. Rotates
+    /// the query once, scores every candidate with `key`, returns the `k`
+    /// smallest keys ascending.
+    fn topk_by(
+        &self,
+        query: &[f32],
+        k: usize,
+        key: fn(&EstimatorSketch, &EstimatorQuery) -> f32,
+    ) -> Vec<(u32, f32)> {
+        if k == 0 || self.entries.is_empty() {
+            return Vec::new();
+        }
+        let q = EstimatorQuery::new_centred(query, &self.rotation, self.centroid.as_deref());
+        let mut scored: Vec<(u32, f32)> = self
+            .entries
+            .iter()
+            .map(|(id, sk)| (*id, key(sk, &q)))
+            .collect();
+        // Ascending by ranking key. Total ordering via partial_cmp with a
+        // NaN-safe fallback (estimates are finite for finite input).
+        scored.sort_by(|a, b| a.1.partial_cmp(&b.1).unwrap_or(std::cmp::Ordering::Equal));
+        scored.truncate(k);
+        scored
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    fn l2(v: &[f32]) -> f32 {
+        v.iter().map(|&x| x * x).sum::<f32>().sqrt()
+    }
+
+    /// Brute-force true inner product of two residuals (zero-centroid).
+    fn true_inner(a: &[f32], b: &[f32]) -> f32 {
+        a.iter().zip(b).map(|(&x, &y)| x * y).sum()
+    }
+
+    #[test]
+    fn estimator_is_deterministic() {
+        // Same (seed, dim) rotation + same vectors ⇒ identical estimate, twice.
+        let dim = 64;
+        let rot = Rotation::new(0xC0DE_1234_5678_9ABC, dim);
+        let o: Vec<f32> = (0..dim).map(|i| (i as f32 * 0.21).sin() + 0.3).collect();
+        let qv: Vec<f32> = (0..dim).map(|i| (i as f32 * 0.11).cos() - 0.2).collect();
+
+        let s1 = EstimatorSketch::from_embedding(&o, &rot);
+        let s2 = EstimatorSketch::from_embedding(&o, &rot);
+        let q1 = EstimatorQuery::new(&qv, &rot);
+        let q2 = EstimatorQuery::new(&qv, &Rotation::new(0xC0DE_1234_5678_9ABC, dim));
+
+        let e1 = DistanceEstimator::estimate_inner_product(&s1, &q1);
+        let e2 = DistanceEstimator::estimate_inner_product(&s2, &q2);
+        assert_eq!(e1, e2, "estimator must be deterministic for a fixed seed");
+
+        // Bank topk is deterministic too.
+        let mut bank = EstimatorBank::new(Rotation::new(7, dim));
+        for id in 0..16u32 {
+            let v: Vec<f32> = (0..dim).map(|i| ((i + id as usize) as f32 * 0.07).sin()).collect();
+            bank.insert_embedding(id, &v);
+        }
+        let a = bank.topk_estimated(&qv, 5);
+        let b = bank.topk_estimated(&qv, 5);
+        assert_eq!(a, b, "topk_estimated must be deterministic");
+    }
+
+    #[test]
+    fn estimator_unbiased_on_fixture() {
+        // The core unbiasedness claim: averaging the estimate of ⟨o_r, q_r⟩ over
+        // MANY random rotation seeds converges to the true inner product.
+        //
+        // Hand-checkable small case: two fixed vectors, known true inner
+        // product, average the estimator over many seeds and assert it lands
+        // within a tolerance that a BIASED estimator would miss.
+        let dim = 32;
+        let o: Vec<f32> = (0..dim).map(|i| ((i % 7) as f32 - 3.0) * 0.4 + 0.5).collect();
+        let qv: Vec<f32> = (0..dim).map(|i| ((i % 5) as f32 - 2.0) * 0.3 - 0.1).collect();
+        let truth = true_inner(&o, &qv);
+
+        let n_seeds = 4000u64;
+        let mut acc = 0.0f64;
+        for seed in 0..n_seeds {
+            let rot = Rotation::new(seed.wrapping_mul(0x9E37_79B9_7F4A_7C15) ^ 0xABCD, dim);
+            let sk = EstimatorSketch::from_embedding(&o, &rot);
+            let q = EstimatorQuery::new(&qv, &rot);
+            acc += DistanceEstimator::estimate_inner_product(&sk, &q) as f64;
+        }
+        let mean = (acc / n_seeds as f64) as f32;
+
+        // Tolerance scaled to the magnitudes involved. The estimator is
+        // unbiased, so the Monte-Carlo mean must be CLOSE to truth; a sign-only
+        // Hamming proxy (or a biased rescale) would be systematically off.
+        let scale = l2(&o) * l2(&qv);
+        let tol = 0.06 * scale; // ~6% of the ‖o‖‖q‖ envelope over 4000 seeds
+        assert!(
+            (mean - truth).abs() < tol,
+            "estimator biased: mean={mean:.4} truth={truth:.4} tol={tol:.4} (scale={scale:.4})"
+        );
+    }
+
+    #[test]
+    fn estimator_self_distance_is_small() {
+        // Estimating the distance of a vector to itself should be ~0 (the
+        // estimate of ⟨o,o⟩ ≈ ‖o‖², so ‖q-o‖² ≈ 0). Not exactly 0 (1-bit code),
+        // but small relative to ‖o‖².
+        let dim = 128;
+        let rot = Rotation::new(0xBEEF_CAFE, dim);
+        let o: Vec<f32> = (0..dim).map(|i| (i as f32 * 0.37).cos() + 0.2).collect();
+        let sk = EstimatorSketch::from_embedding(&o, &rot);
+        let q = EstimatorQuery::new(&o, &rot);
+        let sq = DistanceEstimator::estimate_sq_distance(&sk, &q);
+        let o_norm_sq = l2(&o) * l2(&o);
+        assert!(
+            sq.abs() < 0.25 * o_norm_sq,
+            "self sq-distance estimate {sq:.3} too large vs ‖o‖²={o_norm_sq:.3}"
+        );
+    }
+
+    #[test]
+    fn side_info_is_eight_bytes() {
+        assert_eq!(EstimatorSketch::SIDE_INFO_BYTES, 8);
+    }
+
+    #[test]
+    fn x_dot_o_in_unit_range() {
+        // ⟨x̄, o'⟩ ∈ (0, 1] for any non-zero input (it's the cosine between the
+        // rotated residual and its nearest hypercube corner).
+        let dim = 96;
+        let rot = Rotation::new(0x1357_9BDF, dim);
+        for s in 0..20u32 {
+            let v: Vec<f32> = (0..dim).map(|i| (((i + s as usize) * 13 % 23) as f32 - 11.0) * 0.2).collect();
+            let sk = EstimatorSketch::from_embedding(&v, &rot);
+            let x = sk.side_info().x_dot_o;
+            assert!(x > 0.0 && x <= 1.0 + 1e-5, "x_dot_o out of (0,1]: {x}");
+        }
+    }
+
+    #[test]
+    fn zero_input_does_not_panic() {
+        let dim = 64;
+        let rot = Rotation::new(1, dim);
+        let sk = EstimatorSketch::from_embedding(&vec![0.0f32; dim], &rot);
+        assert_eq!(sk.residual_norm(), 0.0);
+        let q = EstimatorQuery::new(&vec![1.0f32; dim], &rot);
+        // No divide-by-zero; degenerate estimate is 0 inner product.
+        assert_eq!(DistanceEstimator::estimate_inner_product(&sk, &q), 0.0);
+    }
+
+    #[test]
+    fn centroid_path_self_query_ranks_self_first() {
+        // The paper-faithful centroid path (o_r = o − c) must still rank a
+        // stored vector first when queried with itself, with a shared centroid.
+        let dim = 64;
+        let rot = Rotation::new(0x9999, dim);
+        let centroid: Vec<f32> = (0..dim).map(|i| (i as f32 * 0.05).sin()).collect();
+        let mut bank = EstimatorBank::with_centroid(rot, centroid.clone());
+        let target: Vec<f32> = (0..dim).map(|i| (i as f32 * 0.23).cos() + 1.5).collect();
+        bank.insert_embedding(7, &target);
+        for id in 0..24u32 {
+            let v: Vec<f32> = (0..dim)
+                .map(|i| ((i as f32 + id as f32) * 0.09).sin() + 1.4)
+                .collect();
+            bank.insert_embedding(id, &v);
+        }
+        let top = bank.topk_estimated_cosine(&target, 1);
+        assert_eq!(top.len(), 1);
+        assert_eq!(top[0].0, 7, "centroid-path self-query should rank self first");
+    }
+
+    #[test]
+    fn centroid_zero_matches_default() {
+        // from_embedding_centred(None) must be byte-identical to from_embedding.
+        let dim = 48;
+        let rot = Rotation::new(0x4242, dim);
+        let v: Vec<f32> = (0..dim).map(|i| (i as f32 * 0.3).sin() - 0.1).collect();
+        let a = EstimatorSketch::from_embedding(&v, &rot);
+        let b = EstimatorSketch::from_embedding_centred(&v, &rot, None);
+        assert_eq!(a.residual_norm(), b.residual_norm());
+        assert_eq!(a.side_info(), b.side_info());
+    }
+
+    #[test]
+    fn bank_self_query_ranks_self_first() {
+        // A bank queried with one of its own stored vectors should rank that id
+        // first under the estimator (its estimated distance to itself is the
+        // smallest).
+        let dim = 128;
+        let rot = Rotation::new(0xABCD_1234, dim);
+        let mut bank = EstimatorBank::new(rot);
+        let target: Vec<f32> = (0..dim).map(|i| (i as f32 * 0.19).sin() * 2.0).collect();
+        bank.insert_embedding(99, &target);
+        for id in 0..32u32 {
+            let v: Vec<f32> = (0..dim)
+                .map(|i| ((i as f32 + id as f32 * 3.0) * 0.05).cos())
+                .collect();
+            bank.insert_embedding(id, &v);
+        }
+        let top = bank.topk_estimated(&target, 1);
+        assert_eq!(top.len(), 1);
+        assert_eq!(top[0].0, 99, "self-query should rank the stored self first");
+    }
+}

v2/crates/wifi-densepose-ruvector/src/lib.rs

@@ -29,6 +29,7 @@
 #[cfg(feature = "crv")]
 pub mod crv;
 pub mod coverage;
+pub mod estimator;
 pub mod event_log;
 pub mod mat;
 pub mod rotation;
@@ -36,6 +37,9 @@ pub mod signal;
 pub mod sketch;
 pub mod viewpoint;
 
+pub use estimator::{
+    DistanceEstimator, EstimatorBank, EstimatorQuery, EstimatorSketch, SideInfo,
+};
 pub use event_log::{NoveltyEvent, PrivacyEventLog};
 pub use rotation::Rotation;
 pub use sketch::{

v2/crates/wifi-densepose-ruvector/src/rotation.rs

@@ -144,6 +144,29 @@ impl Rotation {
     /// rounding — see [`Rotation::apply`] tests and
     /// `rotation_preserves_norm`.
     pub fn apply(&self, embedding: &[f32]) -> Vec<f32> {
+        if self.dim == 0 {
+            return Vec::new();
+        }
+        let mut buf = self.apply_padded(embedding);
+        // Read back the first `dim` rotated coordinates as the sketch input.
+        buf.truncate(self.dim);
+        buf
+    }
+
+    /// Apply the rotation `R = H·D` and return **all `padded_dim` rotated
+    /// coordinates** (not truncated to `dim`).
+    ///
+    /// This is the frame the RaBitQ estimator ([`crate::estimator`]) works in:
+    /// the 1-bit code `x̄ ∈ {±1/√D}^D` is unit over the **padded** length `D`,
+    /// and the query dot product `⟨x̄, q'⟩` must be taken over that same `D`. For
+    /// a power-of-two `dim`, `padded_dim == dim` and this equals
+    /// [`Rotation::apply`]; for a non-power-of-two `dim` the tail coordinates
+    /// (the zero-padded energy redistributed by the FHT) are retained here but
+    /// dropped by `apply`.
+    ///
+    /// `dim == 0` yields an empty vector. Ragged input is handled charitably
+    /// (truncate / zero-extend to `dim`), as in [`Rotation::apply`].
+    pub fn apply_padded(&self, embedding: &[f32]) -> Vec<f32> {
         if self.dim == 0 {
             return Vec::new();
         }
@@ -157,9 +180,6 @@ impl Rotation {
 
         // In-place normalized Fast Hadamard Transform.
         fht_normalized(&mut buf);
-
-        // Read back the first `dim` rotated coordinates as the sketch input.
-        buf.truncate(self.dim);
         buf
     }
 }

v2/crates/wifi-densepose-sensing-server/src/field_localize.rs

@@ -0,0 +1,241 @@
+//! Field-peak localization for the Observatory 3D view (issue #1050).
+//!
+//! ## What this is (and is not)
+//!
+//! The `/ws/sensing` `sensing_update` frame already carries a real `signal_field`
+//! — a 20×20 grid built by `generate_signal_field()` from **measured subcarrier
+//! variances** weighted by the **measured motion-band power**. The grid's hot
+//! cells are the strongest scatterers in that field representation; as the CSI
+//! changes (a person moving through the link), the peak cell moves with it.
+//!
+//! This module reads the **strongest peak(s)** out of that real field and maps
+//! the peak cell to the Observatory room's world coordinates. That gives the
+//! 3D figure a position + motion magnitude that are **derived from real signal
+//! data**, so the figure now tracks where the field energy concentrates.
+//!
+//! ### Honesty caveat (do not over-claim)
+//!
+//! The field's subcarrier→angle mapping in `generate_signal_field()` is a
+//! *representation*, not calibrated multistatic triangulation in metric room
+//! coordinates. A single ESP32 link cannot resolve a true (x, z) room position.
+//! So the emitted `position` is **"strongest field peak in the room model"**,
+//! not survey-grade localization. It is real (a function of live CSI), it moves
+//! with real motion, and it is honest about its source — but it is NOT a
+//! calibrated person fix. Per-person skeletal `pose` keypoints in room
+//! coordinates remain gated on the pose model + paired ground-truth data
+//! (ADR-079), so `pose` here is only ever set from a real aggregate posture
+//! estimate when one exists, and is `None` otherwise (never fabricated).
+//!
+//! ## Coordinate mapping
+//!
+//! The Observatory builds its field point cloud (see `ui/observatory/js/main.js`
+//! `_buildSignalField`) as, for grid cell `(ix, iz)` of a `20×20` grid:
+//!
+//! ```text
+//! world_x = (ix - gridSize/2) * 0.6
+//! world_z = (iz - gridSize/2) * 0.5
+//! world_y = 0  (floor)
+//! ```
+//!
+//! and indexes the field as `idx = iz * gridSize + ix` — identical to the
+//! server's `generate_signal_field()` layout (`values[z * grid + x]`). We map
+//! the peak cell with the **same** transform so the figure lands exactly on the
+//! field hotspot it is standing on.
+
+/// World-space scale factor for the X (width) axis, matching the Observatory's
+/// `_buildSignalField`: `world_x = (ix - nx/2) * X_SCALE`.
+pub const X_SCALE: f64 = 0.6;
+/// World-space scale factor for the Z (depth) axis, matching the Observatory's
+/// `_buildSignalField`: `world_z = (iz - nz/2) * Z_SCALE`.
+pub const Z_SCALE: f64 = 0.5;
+
+/// Minimum normalized field value (`signal_field.values` are normalized to
+/// `[0, 1]`) for a cell to be considered a real peak rather than background
+/// attenuation. Below this we treat the field as having no localizable hotspot.
+pub const PEAK_THRESHOLD: f64 = 0.35;
+
+/// A localized field peak in Observatory world coordinates.
+#[derive(Debug, Clone, Copy, PartialEq)]
+pub struct FieldPeak {
+    /// World position `[x, y, z]` in Observatory scene units (meters). `y` is
+    /// always `0.0` — the field is a floor-plane grid with no height info.
+    pub position: [f64; 3],
+    /// Normalized field intensity at the peak cell, in `[0, 1]`.
+    pub intensity: f64,
+    /// Source grid cell `(ix, iz)` the peak was read from (for tests/debug).
+    pub cell: (usize, usize),
+}
+
+/// Map a grid cell `(ix, iz)` of an `nx × nz` field to Observatory world
+/// coordinates, matching `ui/observatory/js/main.js::_buildSignalField`.
+#[must_use]
+pub fn cell_to_world(ix: usize, iz: usize, nx: usize, nz: usize) -> [f64; 3] {
+    let wx = (ix as f64 - nx as f64 / 2.0) * X_SCALE;
+    let wz = (iz as f64 - nz as f64 / 2.0) * Z_SCALE;
+    [wx, 0.0, wz]
+}
+
+/// Extract up to `max_peaks` strongest, spatially-separated peaks from a
+/// `signal_field` grid.
+///
+/// * `values` — row-major field grid, `values[iz * nx + ix]`, normalized to
+///   `[0, 1]` (as produced by `generate_signal_field`).
+/// * `nx`, `nz` — grid dimensions (the field's `grid_size` is `[nx, 1, nz]`).
+/// * `max_peaks` — how many person positions to extract (≥ 1).
+///
+/// Returns peaks sorted strongest-first. Each successive peak is forced to be
+/// at least `min_separation_cells` away from all previously selected peaks so
+/// two persons don't collapse onto the same hotspot. Returns an **empty**
+/// vector when no cell exceeds [`PEAK_THRESHOLD`] — an empty / no-presence
+/// field yields no phantom person.
+#[must_use]
+pub fn extract_peaks(
+    values: &[f64],
+    nx: usize,
+    nz: usize,
+    max_peaks: usize,
+    min_separation_cells: f64,
+) -> Vec<FieldPeak> {
+    if nx == 0 || nz == 0 || values.len() < nx * nz || max_peaks == 0 {
+        return Vec::new();
+    }
+
+    // Collect all cells above threshold, strongest first.
+    let mut candidates: Vec<(usize, usize, f64)> = Vec::new();
+    for iz in 0..nz {
+        for ix in 0..nx {
+            let v = values[iz * nx + ix];
+            if v >= PEAK_THRESHOLD {
+                candidates.push((ix, iz, v));
+            }
+        }
+    }
+    candidates.sort_by(|a, b| b.2.total_cmp(&a.2));
+
+    let mut peaks: Vec<FieldPeak> = Vec::new();
+    for (ix, iz, v) in candidates {
+        if peaks.len() >= max_peaks {
+            break;
+        }
+        // Enforce spatial separation from already-chosen peaks (in cell units).
+        let too_close = peaks.iter().any(|p| {
+            let dx = p.cell.0 as f64 - ix as f64;
+            let dz = p.cell.1 as f64 - iz as f64;
+            (dx * dx + dz * dz).sqrt() < min_separation_cells
+        });
+        if too_close {
+            continue;
+        }
+        peaks.push(FieldPeak {
+            position: cell_to_world(ix, iz, nx, nz),
+            intensity: v,
+            cell: (ix, iz),
+        });
+    }
+    peaks
+}
+
+/// Convert measured `motion_band_power` to the `motion_score` scale the
+/// Observatory UI expects.
+///
+/// The UI compares `motion_score > 50` to switch between calm and energetic
+/// emission (see `_updateDotMatrixMist` / `_updateParticleTrail`). The raw
+/// `motion_band_power` is already in roughly that band for live ESP32 data
+/// (the issue reports `motion_band_power: 63.3` while moving), so we pass it
+/// through directly, clamped to a sane `[0, 100]` display range. This keeps the
+/// emitted value a **direct, real** function of measured motion energy rather
+/// than a re-scaled invention.
+#[must_use]
+pub fn motion_score_from_power(motion_band_power: f64) -> f64 {
+    motion_band_power.clamp(0.0, 100.0)
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn cell_to_world_matches_observatory_layout() {
+        // Center cell of a 20×20 grid maps near origin.
+        let c = cell_to_world(10, 10, 20, 20);
+        assert!((c[0] - 0.0).abs() < 1e-9);
+        assert_eq!(c[1], 0.0);
+        assert!((c[2] - 0.0).abs() < 1e-9);
+
+        // Corner cell (0,0) maps to the room's near-left corner.
+        let corner = cell_to_world(0, 0, 20, 20);
+        assert!((corner[0] - (-6.0)).abs() < 1e-9); // (0-10)*0.6
+        assert!((corner[2] - (-5.0)).abs() < 1e-9); // (0-10)*0.5
+    }
+
+    #[test]
+    fn extract_peaks_finds_known_hotspot() {
+        // 20×20 field, all background, single strong peak at cell (15, 4).
+        let nx = 20;
+        let nz = 20;
+        let mut values = vec![0.05; nx * nz];
+        let peak_ix = 15;
+        let peak_iz = 4;
+        values[peak_iz * nx + peak_ix] = 1.0;
+
+        let peaks = extract_peaks(&values, nx, nz, 1, 3.0);
+        assert_eq!(peaks.len(), 1);
+        assert_eq!(peaks[0].cell, (peak_ix, peak_iz));
+
+        // Position must match the Observatory cell→world transform within tol.
+        let expected = cell_to_world(peak_ix, peak_iz, nx, nz);
+        assert!((peaks[0].position[0] - expected[0]).abs() < 1e-9);
+        assert!((peaks[0].position[2] - expected[2]).abs() < 1e-9);
+        // Sanity: (15-10)*0.6 = 3.0, (4-10)*0.5 = -3.0
+        assert!((peaks[0].position[0] - 3.0).abs() < 1e-9);
+        assert!((peaks[0].position[2] - (-3.0)).abs() < 1e-9);
+    }
+
+    #[test]
+    fn empty_field_yields_no_peaks() {
+        let nx = 20;
+        let nz = 20;
+        // All cells below PEAK_THRESHOLD — no presence.
+        let values = vec![0.10; nx * nz];
+        let peaks = extract_peaks(&values, nx, nz, 3, 3.0);
+        assert!(
+            peaks.is_empty(),
+            "below-threshold field must not produce a phantom peak"
+        );
+    }
+
+    #[test]
+    fn two_separated_peaks_do_not_collapse() {
+        let nx = 20;
+        let nz = 20;
+        let mut values = vec![0.05; nx * nz];
+        values[2 * nx + 3] = 0.95; // peak A at (3, 2)
+        values[15 * nx + 17] = 0.90; // peak B at (17, 15)
+
+        let peaks = extract_peaks(&values, nx, nz, 2, 3.0);
+        assert_eq!(peaks.len(), 2);
+        // Strongest first.
+        assert_eq!(peaks[0].cell, (3, 2));
+        assert_eq!(peaks[1].cell, (17, 15));
+    }
+
+    #[test]
+    fn nearby_secondary_peak_is_suppressed() {
+        let nx = 20;
+        let nz = 20;
+        let mut values = vec![0.05; nx * nz];
+        values[10 * nx + 10] = 1.00; // primary
+        values[10 * nx + 11] = 0.99; // adjacent — should be suppressed (sep 3.0)
+
+        let peaks = extract_peaks(&values, nx, nz, 2, 3.0);
+        assert_eq!(peaks.len(), 1, "adjacent cell must not become a 2nd person");
+        assert_eq!(peaks[0].cell, (10, 10));
+    }
+
+    #[test]
+    fn motion_score_passthrough_and_clamp() {
+        assert!((motion_score_from_power(63.3) - 63.3).abs() < 1e-9);
+        assert_eq!(motion_score_from_power(-5.0), 0.0);
+        assert_eq!(motion_score_from_power(250.0), 100.0);
+    }
+}

v2/crates/wifi-densepose-sensing-server/src/main.rs

@@ -14,6 +14,7 @@ pub mod cli;
 pub mod csi;
 mod engine_bridge;
 mod field_bridge;
+mod field_localize;
 mod model_format;
 mod multistatic_bridge;
 pub mod pose;
@@ -406,6 +407,24 @@ struct PersonDetection {
     keypoints: Vec<PoseKeypoint>,
     bbox: BoundingBox,
     zone: String,
+    /// Room-world position `[x, y, z]` (Observatory scene units / meters),
+    /// derived from the strongest `signal_field` peak this person sits on
+    /// (issue #1050). `y` is `0.0` — the field is a floor-plane grid. This is
+    /// a real field-peak readout, not calibrated triangulation; see
+    /// `field_localize` for the honesty caveat. Defaults to `[0,0,0]` until
+    /// field positions are attached by `attach_field_positions`.
+    #[serde(default)]
+    position: [f64; 3],
+    /// Motion magnitude on the Observatory's `0..100` scale, passed through
+    /// from the measured `motion_band_power` (issue #1050).
+    #[serde(default)]
+    motion_score: f64,
+    /// Coarse posture label (`"standing"`/`"lying"`/…) when a **real** aggregate
+    /// posture estimate exists, else `None`. Never fabricated — per-person
+    /// skeletal pose in room coordinates remains gated on the pose model
+    /// (ADR-079). The Observatory defaults to `'standing'` when this is absent.
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pose: Option<String>,
 }
 
 #[derive(Debug, Clone, Serialize, Deserialize)]
@@ -2572,6 +2591,8 @@ async fn windows_wifi_task(state: SharedState, tick_ms: u64) {
         if !tracked.is_empty() {
             update.persons = Some(tracked);
         }
+        // #1050: attach real signal_field-peak positions to each person.
+        attach_field_positions(&mut update);
 
         if let Ok(json) = serde_json::to_string(&update) {
             let _ = s.tx.send(json);
@@ -2725,6 +2746,8 @@ async fn windows_wifi_fallback_tick(state: &SharedState, seq: u32) {
     if !tracked.is_empty() {
         update.persons = Some(tracked);
     }
+    // #1050: attach real signal_field-peak positions to each person.
+    attach_field_positions(&mut update);
 
     if let Ok(json) = serde_json::to_string(&update) {
         let _ = s.tx.send(json);
@@ -3163,12 +3186,21 @@ async fn handle_ws_pose_client(mut socket: WebSocket, state: SharedState) {
                                                 x: kp[0], y: kp[1], z: kp[2], confidence: kp[3],
                                             })
                                             .collect();
+                                        let [nx, _ny, nz] = sensing.signal_field.grid_size;
+                                        let peak = field_localize::extract_peaks(
+                                            &sensing.signal_field.values, nx, nz, 1, 3.0,
+                                        ).into_iter().next();
                                         vec![PersonDetection {
                                             id: 1,
                                             confidence: sensing.classification.confidence,
                                             bbox: BoundingBox { x: 260.0, y: 150.0, width: 120.0, height: 220.0 },
                                             keypoints,
                                             zone: "zone_1".into(),
+                                            position: peak.map_or([0.0, 0.0, 0.0], |p| p.position),
+                                            motion_score: field_localize::motion_score_from_power(
+                                                sensing.features.motion_band_power,
+                                            ),
+                                            pose: sensing.posture.clone(),
                                         }]
                                     }).unwrap_or_else(|| {
                                         // Prefer tracked persons from broadcast if available
@@ -3947,6 +3979,53 @@ fn derive_single_person_pose(
             height: (max_y - min_y).max(160.0),
         },
         zone: format!("zone_{}", person_idx + 1),
+        // Position/motion_score/pose are attached from the real signal_field
+        // peaks by `attach_field_positions` after the tracker step (#1050);
+        // default here so the synthetic-skeleton geometry stays unchanged.
+        position: [0.0, 0.0, 0.0],
+        motion_score: 0.0,
+        pose: None,
+    }
+}
+
+/// Attach real, field-derived per-person world positions to a `SensingUpdate`'s
+/// `persons` (issue #1050).
+///
+/// For each detected person we read a strongest-peak position out of the frame's
+/// real `signal_field` (the same grid the Observatory already renders) and map
+/// it to room-world coordinates via `field_localize::cell_to_world`. `motion_score`
+/// is passed through from the measured `motion_band_power`; `pose` is taken from
+/// the real aggregate `posture` estimate when present, else left `None` (never
+/// fabricated). Persons beyond the number of resolvable field peaks fall back to
+/// the strongest peak so they remain co-located with real energy rather than at
+/// a fake origin; if the field has no peak above threshold the position stays at
+/// `[0,0,0]` and `motion_score` still reflects real motion power.
+fn attach_field_positions(update: &mut SensingUpdate) {
+    let Some(persons) = update.persons.as_mut() else {
+        return;
+    };
+    if persons.is_empty() {
+        return;
+    }
+
+    let [nx, _ny, nz] = update.signal_field.grid_size;
+    let peaks = field_localize::extract_peaks(
+        &update.signal_field.values,
+        nx,
+        nz,
+        persons.len().max(1),
+        3.0,
+    );
+
+    let motion_score = field_localize::motion_score_from_power(update.features.motion_band_power);
+    let pose_label = update.posture.clone();
+
+    for (i, person) in persons.iter_mut().enumerate() {
+        if let Some(peak) = peaks.get(i).or_else(|| peaks.first()) {
+            person.position = peak.position;
+        }
+        person.motion_score = motion_score;
+        person.pose = pose_label.clone();
     }
 }
 
@@ -5473,6 +5552,8 @@ async fn udp_receiver_task(state: SharedState, udp_port: u16) {
                     if !tracked.is_empty() {
                         update.persons = Some(tracked);
                     }
+                    // #1050: attach real signal_field-peak positions to each person.
+                    attach_field_positions(&mut update);
 
                     if let Ok(json) = serde_json::to_string(&update) {
                         let _ = s.tx.send(json);
@@ -5903,6 +5984,8 @@ async fn udp_receiver_task(state: SharedState, udp_port: u16) {
                     if !tracked.is_empty() {
                         update.persons = Some(tracked);
                     }
+                    // #1050: attach real signal_field-peak positions to each person.
+                    attach_field_positions(&mut update);
 
                     if let Ok(json) = serde_json::to_string(&update) {
                         let _ = s.tx.send(json);
@@ -6076,6 +6159,8 @@ async fn simulated_data_task(state: SharedState, tick_ms: u64) {
         if !tracked.is_empty() {
             update.persons = Some(tracked);
         }
+        // #1050: attach real signal_field-peak positions to each person.
+        attach_field_positions(&mut update);
 
         if update.classification.presence {
             s.total_detections += 1;
@@ -8220,3 +8305,171 @@ mod export_rvf_mode_tests {
         assert!(!export_emits_placeholder_demo(false, true, false));
     }
 }
+
+#[cfg(test)]
+mod observatory_persons_field_position_tests {
+    //! Issue #1050 — the Observatory 3D figure animates from per-person
+    //! `position` / `motion_score` / `pose` carried on `sensing_update.persons`.
+    //!
+    //! These tests pin the public WS contract: a frame that detects a person on
+    //! a known signal_field peak must emit a `persons` array whose first entry
+    //! carries a `position` derived from that peak (matching the Observatory's
+    //! cell→world transform), a real `motion_score`, and a serialized frame
+    //! that round-trips. An empty / no-presence field must emit `persons: []`
+    //! (or no person), never a phantom person at a fabricated origin.
+
+    use super::*;
+
+    /// Build a 20×20 signal_field that is background everywhere except a single
+    /// strong normalized peak at grid cell `(ix, iz)`.
+    fn field_with_peak(ix: usize, iz: usize) -> SignalField {
+        let nx = 20usize;
+        let nz = 20usize;
+        let mut values = vec![0.05f64; nx * nz];
+        values[iz * nx + ix] = 1.0;
+        SignalField {
+            grid_size: [nx, 1, nz],
+            values,
+        }
+    }
+
+    /// Build an all-background (below-threshold) 20×20 field — no localizable
+    /// hotspot, modelling an empty / no-presence room.
+    fn empty_field() -> SignalField {
+        SignalField {
+            grid_size: [20, 1, 20],
+            values: vec![0.05f64; 20 * 20],
+        }
+    }
+
+    fn base_update(signal_field: SignalField, presence: bool, motion_band_power: f64) -> SensingUpdate {
+        SensingUpdate {
+            msg_type: "sensing_update".to_string(),
+            timestamp: 1.0,
+            source: "test".to_string(),
+            tick: 1,
+            nodes: vec![],
+            features: FeatureInfo {
+                mean_rssi: -60.0,
+                variance: 48.6,
+                motion_band_power,
+                breathing_band_power: 0.0,
+                dominant_freq_hz: 1.0,
+                change_points: 0,
+                spectral_power: 0.0,
+            },
+            classification: ClassificationInfo {
+                motion_level: if presence { "present_moving".to_string() } else { "absent".to_string() },
+                presence,
+                confidence: 0.8,
+            },
+            signal_field,
+            vital_signs: None,
+            enhanced_motion: None,
+            enhanced_breathing: None,
+            posture: None,
+            signal_quality_score: None,
+            quality_verdict: None,
+            bssid_count: None,
+            pose_keypoints: None,
+            model_status: None,
+            persons: None,
+            estimated_persons: Some(1),
+            node_features: None,
+        }
+    }
+
+    #[test]
+    fn sensing_update_emits_persons_with_field_derived_position() {
+        // Person present, motion energy 63.3, a hotspot at cell (15, 4).
+        let peak_ix = 15;
+        let peak_iz = 4;
+        let mut update = base_update(field_with_peak(peak_ix, peak_iz), true, 63.3);
+
+        // Pipeline order: derive raw skeleton, then attach real field positions.
+        update.persons = Some(derive_pose_from_sensing(&update));
+        attach_field_positions(&mut update);
+
+        let persons = update.persons.as_ref().expect("persons should be Some");
+        assert!(!persons.is_empty(), "a present person must be emitted");
+
+        // Position must match the Observatory cell→world transform for (15, 4):
+        // x = (15-10)*0.6 = 3.0 ; z = (4-10)*0.5 = -3.0 ; y = 0.
+        let p0 = &persons[0];
+        assert!((p0.position[0] - 3.0).abs() < 1e-6, "x={}", p0.position[0]);
+        assert!((p0.position[1] - 0.0).abs() < 1e-9);
+        assert!((p0.position[2] - (-3.0)).abs() < 1e-6, "z={}", p0.position[2]);
+
+        // motion_score is the measured motion_band_power passed through (≤100).
+        assert!((p0.motion_score - 63.3).abs() < 1e-6, "motion_score={}", p0.motion_score);
+
+        // The serialized WS frame must carry the new fields by their exact
+        // contract names the Observatory UI reads.
+        let v = serde_json::to_value(&update).unwrap();
+        let arr = v["persons"].as_array().expect("persons must be a JSON array");
+        assert_eq!(arr.len(), persons.len());
+        let pj = &arr[0];
+        assert!(pj.get("position").is_some(), "person.position missing from WS frame");
+        assert!(pj.get("motion_score").is_some(), "person.motion_score missing from WS frame");
+        assert!((pj["position"][0].as_f64().unwrap() - 3.0).abs() < 1e-6);
+        assert!((pj["position"][2].as_f64().unwrap() - (-3.0)).abs() < 1e-6);
+        assert!((pj["motion_score"].as_f64().unwrap() - 63.3).abs() < 1e-6);
+    }
+
+    #[test]
+    fn pose_is_real_when_posture_present_and_absent_otherwise() {
+        // No aggregate posture estimate → pose is None (never fabricated).
+        let mut no_posture = base_update(field_with_peak(10, 10), true, 40.0);
+        no_posture.persons = Some(derive_pose_from_sensing(&no_posture));
+        attach_field_positions(&mut no_posture);
+        let p = &no_posture.persons.as_ref().unwrap()[0];
+        assert!(p.pose.is_none(), "pose must stay None when no real posture exists");
+        // skip_serializing_if drops the key entirely (UI defaults to 'standing').
+        let v = serde_json::to_value(&no_posture).unwrap();
+        assert!(v["persons"][0].get("pose").is_none());
+
+        // Real aggregate posture present → pose is carried through verbatim.
+        let mut with_posture = base_update(field_with_peak(10, 10), true, 40.0);
+        with_posture.posture = Some("lying".to_string());
+        with_posture.persons = Some(derive_pose_from_sensing(&with_posture));
+        attach_field_positions(&mut with_posture);
+        let p2 = &with_posture.persons.as_ref().unwrap()[0];
+        assert_eq!(p2.pose.as_deref(), Some("lying"));
+        let v2 = serde_json::to_value(&with_posture).unwrap();
+        assert_eq!(v2["persons"][0]["pose"], "lying");
+    }
+
+    #[test]
+    fn empty_room_yields_no_phantom_person() {
+        // No presence → derive_pose_from_sensing returns no persons at all.
+        let mut update = base_update(empty_field(), false, 2.0);
+        update.persons = Some(derive_pose_from_sensing(&update));
+        attach_field_positions(&mut update);
+
+        let persons = update.persons.as_ref().unwrap();
+        assert!(
+            persons.is_empty(),
+            "no-presence frame must not emit a phantom person, got {} persons",
+            persons.len()
+        );
+
+        // And in the serialized frame the array is empty (no fake origin person).
+        let v = serde_json::to_value(&update).unwrap();
+        assert_eq!(v["persons"].as_array().unwrap().len(), 0);
+    }
+
+    #[test]
+    fn present_but_below_threshold_field_keeps_position_at_origin_not_fabricated() {
+        // Presence is true but the field has no peak above PEAK_THRESHOLD — we
+        // must NOT invent a position; it stays at the [0,0,0] default while
+        // motion_score still reflects the real measured motion power. This is
+        // the honest degenerate case (no localizable hotspot to report).
+        let mut update = base_update(empty_field(), true, 55.0);
+        update.persons = Some(derive_pose_from_sensing(&update));
+        attach_field_positions(&mut update);
+
+        let p = &update.persons.as_ref().unwrap()[0];
+        assert_eq!(p.position, [0.0, 0.0, 0.0], "no peak → default origin, not fabricated coords");
+        assert!((p.motion_score - 55.0).abs() < 1e-6, "motion_score stays real");
+    }
+}

v2/crates/wifi-densepose-sensing-server/src/pose.rs

@@ -192,6 +192,11 @@ pub fn derive_single_person_pose(
             height: (max_y - min_y).max(160.0),
         },
         zone: format!("zone_{}", person_idx + 1),
+        // Field-derived fields (#1050) — defaulted here; the live `/ws/sensing`
+        // path attaches real positions via `attach_field_positions`.
+        position: [0.0, 0.0, 0.0],
+        motion_score: 0.0,
+        pose: None,
     }
 }
 

v2/crates/wifi-densepose-sensing-server/src/tracker_bridge.rs

@@ -176,6 +176,13 @@ pub fn tracker_to_person_detections(tracker: &PoseTracker) -> Vec<PersonDetectio
                 keypoints,
                 bbox,
                 zone: "tracked".to_string(),
+                // Field-derived position/motion_score/pose are (re)attached from
+                // the live signal_field by `attach_field_positions` after this
+                // tracker step (#1050); the Kalman tracker smooths keypoints only,
+                // so we default here and let the field readout fill them in.
+                position: [0.0, 0.0, 0.0],
+                motion_score: 0.0,
+                pose: None,
             }
         })
         .collect()
@@ -329,6 +336,9 @@ mod tests {
                 height: 1.0,
             },
             zone: "test".to_string(),
+            position: [0.0, 0.0, 0.0],
+            motion_score: 0.0,
+            pose: None,
         }
     }
 

v2/crates/wifi-densepose-sensing-server/src/types.rs

@@ -203,6 +203,21 @@ pub struct PersonDetection {
     pub keypoints: Vec<PoseKeypoint>,
     pub bbox: BoundingBox,
     pub zone: String,
+    /// Room-world position `[x, y, z]` (Observatory scene units / meters),
+    /// derived from the strongest `signal_field` peak (issue #1050). `y` is
+    /// `0.0` — the field is a floor-plane grid. Real field-peak readout, not
+    /// calibrated triangulation. Defaults to `[0,0,0]`.
+    #[serde(default)]
+    pub position: [f64; 3],
+    /// Motion magnitude on the Observatory's `0..100` scale, passed through
+    /// from the measured `motion_band_power` (issue #1050).
+    #[serde(default)]
+    pub motion_score: f64,
+    /// Coarse posture label when a real aggregate posture estimate exists,
+    /// else `None`. Never fabricated; per-person skeletal pose remains gated
+    /// on the pose model (ADR-079).
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub pose: Option<String>,
 }
 
 #[derive(Debug, Clone, Serialize, Deserialize)]

v2/crates/wifi-densepose-signal/Cargo.toml

@@ -71,6 +71,12 @@ harness = false
 name = "features_bench"
 harness = false
 
+## ADR-154 Milestone-2: P2 "bench-first" perf items (§7.4 #5/#6/#7/#8/#20).
+## #8 (field_model eigendecompose) is measured only under the eigenvalue feature.
+[[bench]]
+name = "dsp_perf_bench"
+harness = false
+
 ## ADR-134: CIR estimator throughput benchmarks
 [[bench]]
 name = "cir_bench"

v2/crates/wifi-densepose-signal/benches/dsp_perf_bench.rs

@@ -0,0 +1,353 @@
+//! ADR-154 Milestone-2 perf benchmarks (§7.4 P2 "bench-first" items).
+//!
+//! PROOF discipline (ADR-154 §0): every P2 item is **benched before touched**.
+//! A micro-opt is landed only if the bench proves the path hot; otherwise the
+//! committed bench *is* the result — a MEASURED-NULL that proves the rewrite was
+//! unnecessary (exactly the §5.x "already amortized" pattern). No speedup is
+//! claimed without a before/after number from here.
+//!
+//! Reproduce (compile-only):
+//!   cargo bench -p wifi-densepose-signal --no-default-features \
+//!     --bench dsp_perf_bench --no-run
+//!
+//! Reproduce (full run, writes target/criterion/ HTML):
+//!   cargo bench -p wifi-densepose-signal --no-default-features --bench dsp_perf_bench
+//!
+//! Groups:
+//!   * `multistatic_attention` (#5) — `node_attention_weights` at 2..8 nodes ×
+//!       56 subcarriers. Re-derives consensus/softmax each call; no scratch to
+//!       reuse → expected MEASURED-NULL.
+//!   * `tomography_reconstruct` (#6) — full ISTA solve. The two voxel buffers are
+//!       allocated once per `reconstruct()` (then `.fill`-reused across
+//!       iterations), so the per-solve alloc is 2×n_voxels vs an
+//!       O(iters·links·voxels) compute → expected MEASURED-NULL.
+//!   * `pose_kalman_update` (#7) — Kalman predict+update loop. The "gain
+//!       matrices" are fixed-size **stack** arrays (`[[f32;3];6]`), not heap —
+//!       nothing to reuse → expected MEASURED-NULL.
+//!   * `spectrogram_multi_subcarrier` (#20) — `compute_multi_subcarrier_spectrogram`:
+//!       fresh-planner-per-subcarrier (BEFORE) vs hoisted-plan (AFTER, shipped).
+//!       The per-subcarrier FFT re-plan is the likely real win.
+//!   * `field_model_occupancy` (#8, `eigenvalue` only) — per-call n×n
+//!       eigendecomposition in `estimate_occupancy`. MEASUREMENT-ONLY: quantifies
+//!       the recompute cost; incremental SVD is a sized future project, not a
+//!       micro-fix.
+
+use criterion::{black_box, criterion_group, criterion_main, BenchmarkId, Criterion, Throughput};
+use ndarray::Array2;
+use rustfft::FftPlanner;
+use std::f64::consts::PI;
+use std::time::Duration;
+
+use wifi_densepose_signal::ruvsense::multistatic::node_attention_weights;
+use wifi_densepose_signal::ruvsense::pose_tracker::KeypointState;
+use wifi_densepose_signal::ruvsense::tomography::{
+    LinkGeometry, Position3D, RfTomographer, TomographyConfig,
+};
+use wifi_densepose_signal::spectrogram::{
+    compute_multi_subcarrier_spectrogram, compute_spectrogram, Spectrogram, SpectrogramConfig,
+    WindowFunction,
+};
+
+// ---------------------------------------------------------------------------
+// #5 multistatic node_attention_weights
+// ---------------------------------------------------------------------------
+
+fn make_node_amplitudes(n_nodes: usize, n_sub: usize) -> Vec<Vec<f32>> {
+    (0..n_nodes)
+        .map(|n| {
+            (0..n_sub)
+                .map(|s| {
+                    let phase = (n as f32 * 0.31 + s as f32 * 0.07) % std::f32::consts::TAU;
+                    0.5 + 0.4 * phase.sin()
+                })
+                .collect()
+        })
+        .collect()
+}
+
+fn bench_multistatic_attention(c: &mut Criterion) {
+    let mut group = c.benchmark_group("multistatic_attention");
+    group.measurement_time(Duration::from_secs(3));
+    let n_sub = 56; // canonical-56 grid
+
+    for &n_nodes in &[2usize, 4, 8] {
+        let owned = make_node_amplitudes(n_nodes, n_sub);
+        let refs: Vec<&[f32]> = owned.iter().map(|v| v.as_slice()).collect();
+        group.throughput(Throughput::Elements(1));
+        group.bench_with_input(
+            BenchmarkId::new("weights", n_nodes),
+            &refs,
+            |b, amplitudes| {
+                b.iter(|| black_box(node_attention_weights(black_box(amplitudes), 1.0)));
+            },
+        );
+    }
+    group.finish();
+}
+
+// ---------------------------------------------------------------------------
+// #6 tomography reconstruct (ISTA L1)
+// ---------------------------------------------------------------------------
+
+fn make_tomographer(n_links: usize) -> (RfTomographer, Vec<f64>) {
+    // A modest 8x8x4 grid (256 voxels), n_links TX/RX pairs around the box.
+    let config = TomographyConfig {
+        nx: 8,
+        ny: 8,
+        nz: 4,
+        bounds: [0.0, 0.0, 0.0, 4.0, 4.0, 2.0],
+        lambda: 0.01,
+        max_iterations: 50,
+        tolerance: 1e-6,
+        min_links: 8,
+    };
+    let mut links = Vec::with_capacity(n_links);
+    for i in 0..n_links {
+        let t = i as f64 / n_links as f64;
+        links.push(LinkGeometry {
+            tx: Position3D {
+                x: 4.0 * (t * PI).cos().abs(),
+                y: 0.0,
+                z: 1.0,
+            },
+            rx: Position3D {
+                x: 4.0 * (t * PI).sin().abs(),
+                y: 4.0,
+                z: 1.0,
+            },
+            link_id: i,
+        });
+    }
+    let tomo = RfTomographer::new(config, &links).unwrap();
+    // Deterministic attenuations (one occupied region in the middle).
+    let attenuations: Vec<f64> = (0..n_links)
+        .map(|i| 0.1 + 0.05 * ((i as f64 * 0.3).sin()))
+        .collect();
+    (tomo, attenuations)
+}
+
+fn bench_tomography_reconstruct(c: &mut Criterion) {
+    let mut group = c.benchmark_group("tomography_reconstruct");
+    group.measurement_time(Duration::from_secs(4));
+
+    for &n_links in &[16usize, 32] {
+        let (tomo, atten) = make_tomographer(n_links);
+        group.throughput(Throughput::Elements(1));
+        group.bench_with_input(
+            BenchmarkId::new("solve", n_links),
+            &(tomo, atten),
+            |b, (tomo, atten)| {
+                b.iter(|| black_box(tomo.reconstruct(black_box(atten)).unwrap().occupied_count));
+            },
+        );
+    }
+    group.finish();
+}
+
+// ---------------------------------------------------------------------------
+// #7 pose tracker Kalman update loop
+// ---------------------------------------------------------------------------
+
+fn bench_pose_kalman_update(c: &mut Criterion) {
+    let mut group = c.benchmark_group("pose_kalman_update");
+    group.measurement_time(Duration::from_secs(3));
+
+    // 17 keypoints (COCO-17), N predict+update cycles — a realistic frame batch.
+    for &n_updates in &[17usize, 170] {
+        group.throughput(Throughput::Elements(n_updates as u64));
+        group.bench_with_input(BenchmarkId::new("cycles", n_updates), &n_updates, |b, &n| {
+            b.iter(|| {
+                let mut acc = 0.0_f32;
+                for k in 0..n {
+                    let mut state = KeypointState::new(
+                        (k as f32 * 0.1).sin(),
+                        (k as f32 * 0.2).cos(),
+                        1.0 + (k as f32 * 0.05),
+                    );
+                    state.predict(0.05, 0.5);
+                    let meas = [
+                        (k as f32 * 0.1).sin() + 0.01,
+                        (k as f32 * 0.2).cos() - 0.01,
+                        1.0 + (k as f32 * 0.05),
+                    ];
+                    state.update(&meas, 0.1, 1.0);
+                    acc += state.state[0];
+                }
+                black_box(acc)
+            });
+        });
+    }
+    group.finish();
+}
+
+// ---------------------------------------------------------------------------
+// #20 multi-subcarrier spectrogram: fresh-planner vs hoisted plan
+// ---------------------------------------------------------------------------
+
+fn make_csi_temporal(n_samples: usize, n_sc: usize) -> Array2<f64> {
+    Array2::from_shape_fn((n_samples, n_sc), |(t, sc)| {
+        let freq = 0.7 + sc as f64 * 0.13;
+        (2.0 * PI * freq * t as f64 / 100.0).sin()
+            + 0.3 * (2.0 * PI * (freq * 2.1) * t as f64 / 100.0).cos()
+    })
+}
+
+/// BEFORE: re-plan the FFT inside `compute_spectrogram` for every subcarrier.
+/// Faithful transcription of the pre-ADR-154-M2 `compute_multi_subcarrier_spectrogram`.
+fn multi_fresh_planner(
+    csi: &Array2<f64>,
+    sample_rate: f64,
+    config: &SpectrogramConfig,
+) -> Vec<Spectrogram> {
+    let (_, n_sc) = csi.dim();
+    (0..n_sc)
+        .map(|sc| {
+            let col: Vec<f64> = csi.column(sc).to_vec();
+            // compute_spectrogram builds a fresh FftPlanner on every call.
+            compute_spectrogram(&col, sample_rate, config).unwrap()
+        })
+        .collect()
+}
+
+fn bench_spectrogram_multi_subcarrier(c: &mut Criterion) {
+    let mut group = c.benchmark_group("spectrogram_multi_subcarrier");
+    group.measurement_time(Duration::from_secs(5));
+    let sample_rate = 100.0;
+
+    // Realistic: 600 temporal samples (~6 s @ 100 Hz) across 56 subcarriers,
+    // window 128. n_sc re-plans removed by the hoist.
+    for &(n_samples, n_sc, window) in &[(600usize, 56usize, 128usize), (600, 56, 256)] {
+        let csi = make_csi_temporal(n_samples, n_sc);
+        let config = SpectrogramConfig {
+            window_size: window,
+            hop_size: 64,
+            window_fn: WindowFunction::Hann,
+            power: true,
+        };
+        group.throughput(Throughput::Elements(n_sc as u64));
+
+        // BEFORE: fresh planner per subcarrier.
+        group.bench_with_input(
+            BenchmarkId::new("fresh_planner", format!("sc{n_sc}_w{window}")),
+            &config,
+            |b, cfg| {
+                b.iter(|| black_box(multi_fresh_planner(black_box(&csi), sample_rate, cfg).len()));
+            },
+        );
+
+        // AFTER: hoisted plan (the shipped `compute_multi_subcarrier_spectrogram`).
+        group.bench_with_input(
+            BenchmarkId::new("hoisted_plan", format!("sc{n_sc}_w{window}")),
+            &config,
+            |b, cfg| {
+                b.iter(|| {
+                    black_box(
+                        compute_multi_subcarrier_spectrogram(black_box(&csi), sample_rate, cfg)
+                            .unwrap()
+                            .len(),
+                    )
+                });
+            },
+        );
+    }
+    group.finish();
+}
+
+// A standalone FftPlanner sanity micro-bench documenting the cost the hoist
+// removes: building+planning a length-N forward FFT once.
+fn bench_fft_plan_cost(c: &mut Criterion) {
+    let mut group = c.benchmark_group("fft_plan_cost");
+    group.measurement_time(Duration::from_secs(2));
+    for &n in &[128usize, 256] {
+        group.bench_with_input(BenchmarkId::new("plan_forward", n), &n, |b, &n| {
+            b.iter(|| {
+                let mut planner = FftPlanner::<f64>::new();
+                black_box(planner.plan_fft_forward(black_box(n)))
+            });
+        });
+    }
+    group.finish();
+}
+
+// ---------------------------------------------------------------------------
+// #8 field_model SVD/eigendecomposition recompute (MEASUREMENT-ONLY)
+// ---------------------------------------------------------------------------
+// `estimate_occupancy` builds an n×n covariance and eigendecomposes it on every
+// call (BLAS, `eigenvalue` feature). This bench quantifies that per-call cost so
+// ADR-154 §7.4 #8 can record a number; incremental SVD is a sized future item,
+// NOT attempted here.
+#[cfg(feature = "eigenvalue")]
+mod eig {
+    use super::*;
+    use wifi_densepose_signal::ruvsense::field_model::{FieldModel, FieldModelConfig};
+
+    fn calibrated_model(n_sub: usize, n_links: usize) -> FieldModel {
+        let config = FieldModelConfig {
+            n_subcarriers: n_sub,
+            n_links,
+            n_modes: 3,
+            min_calibration_frames: 20,
+            baseline_expiry_s: 86_400.0,
+        };
+        let mut model = FieldModel::new(config).unwrap();
+        // Feed deterministic calibration frames: [n_links][n_sub] per observation.
+        for f in 0..30 {
+            let obs: Vec<Vec<f64>> = (0..n_links)
+                .map(|l| {
+                    (0..n_sub)
+                        .map(|s| {
+                            0.5 + 0.3
+                                * ((f as f64 * 0.1 + l as f64 * 0.2 + s as f64 * 0.05).sin())
+                        })
+                        .collect()
+                })
+                .collect();
+            model.feed_calibration(&obs).unwrap();
+        }
+        model.finalize_calibration(0, 0).unwrap();
+        model
+    }
+
+    pub fn bench_field_model_occupancy(c: &mut Criterion) {
+        let mut group = c.benchmark_group("field_model_occupancy");
+        group.measurement_time(Duration::from_secs(4));
+        let n_sub = 56;
+        let model = calibrated_model(n_sub, 4);
+        // Sliding window of recent frames (50 ~ 2.5 s @ 20 Hz).
+        let frames: Vec<Vec<f64>> = (0..50)
+            .map(|t| {
+                (0..n_sub)
+                    .map(|s| 0.5 + 0.3 * ((t as f64 * 0.15 + s as f64 * 0.07).sin()))
+                    .collect()
+            })
+            .collect();
+        group.throughput(Throughput::Elements(1));
+        group.bench_function(BenchmarkId::new("eigh", n_sub), |b| {
+            b.iter(|| black_box(model.estimate_occupancy(black_box(&frames))));
+        });
+        group.finish();
+    }
+}
+
+#[cfg(feature = "eigenvalue")]
+criterion_group!(
+    benches,
+    bench_multistatic_attention,
+    bench_tomography_reconstruct,
+    bench_pose_kalman_update,
+    bench_spectrogram_multi_subcarrier,
+    bench_fft_plan_cost,
+    eig::bench_field_model_occupancy,
+);
+
+#[cfg(not(feature = "eigenvalue"))]
+criterion_group!(
+    benches,
+    bench_multistatic_attention,
+    bench_tomography_reconstruct,
+    bench_pose_kalman_update,
+    bench_spectrogram_multi_subcarrier,
+    bench_fft_plan_cost,
+);
+
+criterion_main!(benches);

v2/crates/wifi-densepose-signal/src/csi_ratio.rs

@@ -197,4 +197,61 @@ mod tests {
             Err(CsiRatioError::LengthMismatch { .. })
         ));
     }
+
+    // ADR-154 §7.4 #19: the CSI *ratio model*. The classic ratio is
+    // `H_i[k] / H_j[k]`, which blows up (±inf / NaN) when `H_j[k]` approaches
+    // zero — the case a `1e-12` division-guard epsilon is meant to protect. This
+    // module deliberately implements the ratio as the **conjugate product**
+    // `H_i * conj(H_j)` (SpotFi/IndoTrack), which has *no division* and is
+    // therefore finite even at and below the `1e-12` magnitude boundary. This
+    // test pins that property: at the epsilon boundary the output is finite and
+    // exactly the conjugate product (no silent NaN/inf from a hidden divide).
+    #[test]
+    fn ratio_finite_at_and_below_1e_12_epsilon() {
+        let eps = 1e-12_f64;
+        // Reference at unit magnitude; target swept across / under the epsilon
+        // boundary a naive H_i/H_j division would need to guard.
+        let h_ref = vec![
+            Complex64::from_polar(1.0, 0.3),
+            Complex64::from_polar(1.0, 0.3),
+            Complex64::from_polar(1.0, 0.3),
+            Complex64::from_polar(1.0, 0.3),
+        ];
+        let h_target = vec![
+            Complex64::new(eps, 0.0),           // exactly at the epsilon
+            Complex64::new(eps * 0.5, 0.0),     // below the epsilon
+            Complex64::new(0.0, eps),           // imaginary axis, at epsilon
+            Complex64::new(0.0, 0.0),           // exact zero — div would be inf/NaN
+        ];
+
+        let ratio = conjugate_multiply(&h_ref, &h_target).unwrap();
+        assert_eq!(ratio.len(), 4);
+        for (k, r) in ratio.iter().enumerate() {
+            assert!(
+                r.re.is_finite() && r.im.is_finite(),
+                "conjugate-multiply ratio must be finite at boundary k={k}: {r:?}"
+            );
+        }
+
+        // The near-zero / zero target collapses the product toward zero (the
+        // physically correct "no measurable path" answer), never to inf/NaN.
+        assert!(
+            ratio[3].norm() == 0.0,
+            "exact-zero target → zero product, got {}",
+            ratio[3].norm()
+        );
+        // The at-epsilon entries equal the exact conjugate product (bit-exact).
+        let expected0 = h_ref[0] * h_target[0].conj();
+        assert_eq!(ratio[0].re.to_bits(), expected0.re.to_bits());
+        assert_eq!(ratio[0].im.to_bits(), expected0.im.to_bits());
+
+        // The full pipeline (amplitude/phase extraction) is also finite here.
+        let mut m = Array2::<Complex64>::zeros((1, 4));
+        for (k, &v) in ratio.iter().enumerate() {
+            m[[0, k]] = v;
+        }
+        let (amp, phase) = ratio_to_amplitude_phase(&m);
+        assert!(amp.iter().all(|a| a.is_finite()));
+        assert!(phase.iter().all(|p| p.is_finite()));
+    }
 }

v2/crates/wifi-densepose-signal/src/hampel.rs

@@ -43,11 +43,22 @@ pub struct HampelResult {
 /// MAD = 0.6745 * σ → σ = MAD / 0.6745 = 1.4826 * MAD
 const MAD_SCALE: f64 = 1.4826;
 
+/// Zero-MAD epsilon (ADR-154 §7.4 — de-magicked). When the estimated σ falls
+/// at/below this, the window is treated as constant (degenerate MAD): any
+/// deviation larger than this same epsilon flags the sample as an outlier.
+/// Empirical guard against an all-equal window, not a tuned operating point.
+const ZERO_MAD_EPSILON: f64 = 1e-15;
+
 /// Apply Hampel filter to a 1D signal.
 ///
 /// For each sample, computes the median and MAD of the surrounding window.
 /// If the sample deviates from the median by more than `threshold * σ_est`,
 /// it is replaced with the median.
+///
+/// # Errors
+/// - [`HampelError::EmptySignal`] if `signal` is empty.
+/// - [`HampelError::InvalidWindow`] if `config.half_window == 0` (a window of
+///   one sample has zero MAD and cannot estimate σ).
 pub fn hampel_filter(signal: &[f64], config: &HampelConfig) -> Result<HampelResult, HampelError> {
     if signal.is_empty() {
         return Err(HampelError::EmptySignal);
@@ -75,13 +86,13 @@ pub fn hampel_filter(signal: &[f64], config: &HampelConfig) -> Result<HampelResu
         sigma_estimates.push(sigma);
 
         let deviation = (signal[i] - med).abs();
-        let is_outlier = if sigma > 1e-15 {
+        let is_outlier = if sigma > ZERO_MAD_EPSILON {
             // Normal case: compare deviation to threshold * sigma
             deviation > config.threshold * sigma
         } else {
             // Zero-MAD case: all window values identical except possibly this sample.
             // Any non-zero deviation from the median is an outlier.
-            deviation > 1e-15
+            deviation > ZERO_MAD_EPSILON
         };
 
         if is_outlier {
@@ -233,4 +244,48 @@ mod tests {
             Err(HampelError::EmptySignal)
         ));
     }
+
+    // -- ADR-154 §7.4: de-magic-constant + boundary characterization tests.
+
+    /// De-magicked zero-MAD epsilon must equal the prior literal.
+    #[test]
+    fn zero_mad_epsilon_unchanged_from_literal() {
+        assert_eq!(ZERO_MAD_EPSILON, 1e-15);
+        assert_eq!(MAD_SCALE, 1.4826);
+    }
+
+    /// `half_window == 0` is the documented invalid-window boundary; pins the
+    /// previously-untested error path.
+    #[test]
+    fn test_zero_half_window_error() {
+        let config = HampelConfig {
+            half_window: 0,
+            threshold: 3.0,
+        };
+        assert!(matches!(
+            hampel_filter(&[1.0, 2.0, 3.0], &config),
+            Err(HampelError::InvalidWindow)
+        ));
+        // half_window = 1 is the smallest valid window.
+        let ok = HampelConfig {
+            half_window: 1,
+            threshold: 3.0,
+        };
+        assert!(hampel_filter(&[1.0, 2.0, 3.0], &ok).is_ok());
+    }
+
+    /// Zero-MAD (constant) window: a single deviating sample is flagged via the
+    /// degenerate-MAD branch; a fully constant signal flags nothing.
+    #[test]
+    fn test_zero_mad_constant_window() {
+        // Fully constant -> no outliers (deviation is 0, not > epsilon).
+        let constant = vec![5.0; 20];
+        let r = hampel_filter(&constant, &HampelConfig::default()).unwrap();
+        assert!(r.outlier_indices.is_empty());
+        // A single spike in an otherwise-constant signal -> flagged.
+        let mut spiked = vec![5.0; 20];
+        spiked[10] = 5.5;
+        let r = hampel_filter(&spiked, &HampelConfig::default()).unwrap();
+        assert!(r.outlier_indices.contains(&10));
+    }
 }

v2/crates/wifi-densepose-signal/src/motion.rs

@@ -8,6 +8,66 @@ use chrono::{DateTime, Utc};
 use serde::{Deserialize, Serialize};
 use std::collections::VecDeque;
 
+// ---------------------------------------------------------------------------
+// Tuning constants (ADR-154 §7.4 #18 — de-magicked; EMPIRICAL DEFAULTS).
+//
+// These were previously bare literals inside the scoring functions. They are
+// lifted to named, documented consts so the implicit weighting becomes
+// explicit and a future retune is a visible, tested change. The values are
+// **unchanged** from the original literals — boundary/characterization tests
+// pin the current behaviour. None of these is calibrated against labelled
+// occupancy data; they are heuristic fusion weights.
+// ---------------------------------------------------------------------------
+
+/// Motion-score fusion weights when a Doppler component is present.
+/// `(variance, correlation, phase, doppler)` — sums to 1.0.
+const MOTION_WEIGHTS_WITH_DOPPLER: (f64, f64, f64, f64) = (0.3, 0.2, 0.2, 0.3);
+
+/// Motion-score fusion weights with no Doppler component.
+/// `(variance, correlation, phase)` — sums to 1.0.
+const MOTION_WEIGHTS_NO_DOPPLER: (f64, f64, f64) = (0.4, 0.3, 0.3);
+
+/// Doppler magnitude (Hz-ish, arbitrary units) that maps to a full-scale
+/// (1.0) Doppler motion component. Larger magnitudes saturate at 1.0.
+const DOPPLER_FULL_SCALE_MAGNITUDE: f64 = 100.0;
+
+/// Reference variance that maps to a full-scale (1.0) heuristic motion score
+/// when no calibrated baseline is available. Empirical default.
+const VARIANCE_HEURISTIC_FULL_SCALE: f64 = 0.5;
+
+/// Reference phase variance that maps to a full-scale (1.0) phase motion
+/// component. Empirical default.
+const PHASE_VARIANCE_FULL_SCALE: f64 = 0.5;
+
+/// Blend weight between phase-variance and phase-coherence in the phase score.
+const PHASE_SCORE_VARIANCE_WEIGHT: f64 = 0.5;
+
+/// Reference dynamic range that maps to a full-scale (1.0) amplitude-quality
+/// confidence indicator. Empirical default.
+const AMP_QUALITY_FULL_SCALE_RANGE: f64 = 2.0;
+
+/// Confidence-indicator blend weights (`amplitude`, `phase`, `correlation`,
+/// `doppler`) — each is the fraction of total confidence that indicator
+/// contributes when present.
+const CONF_WEIGHT_AMPLITUDE: f64 = 0.3;
+const CONF_WEIGHT_PHASE: f64 = 0.3;
+const CONF_WEIGHT_CORRELATION: f64 = 0.2;
+const CONF_WEIGHT_DOPPLER: f64 = 0.2;
+
+/// Minimum baseline floor added before dividing by the calibration baseline
+/// variance, preventing a divide-by-zero on an all-constant calibration.
+const BASELINE_VARIANCE_FLOOR: f64 = 1e-10;
+
+/// Lower / upper clamp for the adaptive human-detection threshold
+/// (`mean + 1σ` of recent motion scores). Keeps the adaptive threshold inside
+/// a sane operating band. Empirical default.
+const ADAPTIVE_THRESHOLD_MIN: f64 = 0.3;
+const ADAPTIVE_THRESHOLD_MAX: f64 = 0.95;
+
+/// Minimum history length before the adaptive threshold engages; below this
+/// the configured fixed threshold is used.
+const ADAPTIVE_THRESHOLD_MIN_HISTORY: usize = 10;
+
 /// Motion score with component breakdown
 #[derive(Debug, Clone, Serialize, Deserialize)]
 pub struct MotionScore {
@@ -37,12 +97,11 @@ impl MotionScore {
     ) -> Self {
         // Calculate weighted total
         let total = if let Some(doppler) = doppler_component {
-            0.3 * variance_component
-                + 0.2 * correlation_component
-                + 0.2 * phase_component
-                + 0.3 * doppler
+            let (wv, wc, wp, wd) = MOTION_WEIGHTS_WITH_DOPPLER;
+            wv * variance_component + wc * correlation_component + wp * phase_component + wd * doppler
         } else {
-            0.4 * variance_component + 0.3 * correlation_component + 0.3 * phase_component
+            let (wv, wc, wp) = MOTION_WEIGHTS_NO_DOPPLER;
+            wv * variance_component + wc * correlation_component + wp * phase_component
         };
 
         Self {
@@ -304,7 +363,7 @@ impl MotionDetector {
         // Calculate Doppler-based score if available
         let doppler_score = features.doppler.as_ref().map(|d| {
             // Normalize Doppler magnitude to 0-1 range
-            (d.mean_magnitude / 100.0).clamp(0.0, 1.0)
+            (d.mean_magnitude / DOPPLER_FULL_SCALE_MAGNITUDE).clamp(0.0, 1.0)
         });
 
         let motion_score = MotionScore::new(
@@ -355,11 +414,11 @@ impl MotionDetector {
 
         // Normalize using baseline if available
         if let Some(baseline) = self.baseline_variance {
-            let ratio = mean_variance / (baseline + 1e-10);
+            let ratio = mean_variance / (baseline + BASELINE_VARIANCE_FLOOR);
             (ratio - 1.0).max(0.0).tanh()
         } else {
             // Use heuristic normalization
-            (mean_variance / 0.5).clamp(0.0, 1.0)
+            (mean_variance / VARIANCE_HEURISTIC_FULL_SCALE).clamp(0.0, 1.0)
         }
     }
 
@@ -393,7 +452,9 @@ impl MotionDetector {
         let coherence_factor = 1.0 - phase.coherence.abs();
 
         // Combine factors
-        let score = 0.5 * (mean_variance / 0.5).clamp(0.0, 1.0) + 0.5 * coherence_factor;
+        let w = PHASE_SCORE_VARIANCE_WEIGHT;
+        let score = w * (mean_variance / PHASE_VARIANCE_FULL_SCALE).clamp(0.0, 1.0)
+            + (1.0 - w) * coherence_factor;
         score.clamp(0.0, 1.0)
     }
 
@@ -416,26 +477,27 @@ impl MotionDetector {
         let mut weight_sum = 0.0;
 
         // Amplitude quality indicator
-        let amp_quality = (features.amplitude.dynamic_range / 2.0).clamp(0.0, 1.0);
-        confidence += amp_quality * 0.3;
-        weight_sum += 0.3;
+        let amp_quality =
+            (features.amplitude.dynamic_range / AMP_QUALITY_FULL_SCALE_RANGE).clamp(0.0, 1.0);
+        confidence += amp_quality * CONF_WEIGHT_AMPLITUDE;
+        weight_sum += CONF_WEIGHT_AMPLITUDE;
 
         // Phase coherence indicator
         let phase_quality = features.phase.coherence.abs();
-        confidence += phase_quality * 0.3;
-        weight_sum += 0.3;
+        confidence += phase_quality * CONF_WEIGHT_PHASE;
+        weight_sum += CONF_WEIGHT_PHASE;
 
         // Correlation consistency indicator
         let corr_quality = (1.0 - features.correlation.correlation_spread).clamp(0.0, 1.0);
-        confidence += corr_quality * 0.2;
-        weight_sum += 0.2;
+        confidence += corr_quality * CONF_WEIGHT_CORRELATION;
+        weight_sum += CONF_WEIGHT_CORRELATION;
 
         // Doppler quality if available
         if let Some(ref doppler) = features.doppler {
             let doppler_quality =
                 (doppler.spread / doppler.mean_magnitude.max(1.0)).clamp(0.0, 1.0);
-            confidence += (1.0 - doppler_quality) * 0.2;
-            weight_sum += 0.2;
+            confidence += (1.0 - doppler_quality) * CONF_WEIGHT_DOPPLER;
+            weight_sum += CONF_WEIGHT_DOPPLER;
         }
 
         if weight_sum > 0.0 {
@@ -542,7 +604,7 @@ impl MotionDetector {
 
     /// Calculate adaptive threshold based on recent history
     fn calculate_adaptive_threshold(&self) -> f64 {
-        if self.motion_history.len() < 10 {
+        if self.motion_history.len() < ADAPTIVE_THRESHOLD_MIN_HISTORY {
             return self.config.human_detection_threshold;
         }
 
@@ -555,7 +617,7 @@ impl MotionDetector {
         };
 
         // Threshold is mean + 1 std deviation, clamped to reasonable range
-        (mean + std).clamp(0.3, 0.95)
+        (mean + std).clamp(ADAPTIVE_THRESHOLD_MIN, ADAPTIVE_THRESHOLD_MAX)
     }
 
     /// Update baseline variance (for calibration)
@@ -838,4 +900,127 @@ mod tests {
         let stats = detector.get_statistics();
         assert_eq!(stats.history_size, 10); // Should not exceed max
     }
+
+    // -- ADR-154 §7.4 #18: de-magic-constant + boundary characterization tests.
+    // These pin CURRENT behaviour so a future retune is a visible, tested change.
+
+    /// The de-magicked tuning consts MUST equal the prior bare literals exactly
+    /// (this milestone is cleanup — operating values are unchanged).
+    #[test]
+    fn motion_tuning_consts_unchanged_from_literals() {
+        assert_eq!(MOTION_WEIGHTS_WITH_DOPPLER, (0.3, 0.2, 0.2, 0.3));
+        assert_eq!(MOTION_WEIGHTS_NO_DOPPLER, (0.4, 0.3, 0.3));
+        assert_eq!(DOPPLER_FULL_SCALE_MAGNITUDE, 100.0);
+        assert_eq!(VARIANCE_HEURISTIC_FULL_SCALE, 0.5);
+        assert_eq!(PHASE_VARIANCE_FULL_SCALE, 0.5);
+        assert_eq!(PHASE_SCORE_VARIANCE_WEIGHT, 0.5);
+        assert_eq!(AMP_QUALITY_FULL_SCALE_RANGE, 2.0);
+        assert_eq!(CONF_WEIGHT_AMPLITUDE, 0.3);
+        assert_eq!(CONF_WEIGHT_PHASE, 0.3);
+        assert_eq!(CONF_WEIGHT_CORRELATION, 0.2);
+        assert_eq!(CONF_WEIGHT_DOPPLER, 0.2);
+        assert_eq!(BASELINE_VARIANCE_FLOOR, 1e-10);
+        assert_eq!(ADAPTIVE_THRESHOLD_MIN, 0.3);
+        assert_eq!(ADAPTIVE_THRESHOLD_MAX, 0.95);
+        assert_eq!(ADAPTIVE_THRESHOLD_MIN_HISTORY, 10);
+        // Fusion weights are a convex combination (sum to 1.0).
+        let (wv, wc, wp, wd) = MOTION_WEIGHTS_WITH_DOPPLER;
+        assert!((wv + wc + wp + wd - 1.0).abs() < 1e-12);
+        let (wv, wc, wp) = MOTION_WEIGHTS_NO_DOPPLER;
+        assert!((wv + wc + wp - 1.0).abs() < 1e-12);
+    }
+
+    /// Doppler component saturates at full scale (`/100.0` then clamp(0,1)).
+    /// Pins behaviour at/just-below/just-above the full-scale magnitude.
+    #[test]
+    fn doppler_component_saturates_at_full_scale() {
+        use crate::features::DopplerFeatures;
+        use ndarray::Array1;
+        let make = |mag: f64| DopplerFeatures {
+            shifts: Array1::zeros(1),
+            peak_frequency: 0.0,
+            mean_magnitude: mag,
+            spread: 0.0,
+        };
+        let detector = MotionDetector::default_config();
+        // just below full scale -> < 1.0
+        let mut features = create_test_features(0.5);
+        features.doppler = Some(make(DOPPLER_FULL_SCALE_MAGNITUDE - 1.0));
+        let below = detector.analyze_motion(&features).score.doppler_component.unwrap();
+        assert!(below < 1.0 && below > 0.98);
+        // exactly full scale -> 1.0
+        features.doppler = Some(make(DOPPLER_FULL_SCALE_MAGNITUDE));
+        let at = detector.analyze_motion(&features).score.doppler_component.unwrap();
+        assert_eq!(at, 1.0);
+        // above full scale -> clamped to 1.0
+        features.doppler = Some(make(DOPPLER_FULL_SCALE_MAGNITUDE * 10.0));
+        let above = detector.analyze_motion(&features).score.doppler_component.unwrap();
+        assert_eq!(above, 1.0);
+    }
+
+    /// `calculate_correlation_score` returns 0.0 for n<2 (the small-matrix
+    /// guard) and a finite, clamped value for n>=2. Pins the n=1 boundary.
+    #[test]
+    fn correlation_score_zero_below_n2_boundary() {
+        use crate::features::CorrelationFeatures;
+        use ndarray::Array2;
+        let detector = MotionDetector::default_config();
+        let one = CorrelationFeatures {
+            matrix: Array2::from_elem((1, 1), 1.0),
+            mean_correlation: 0.0,
+            max_correlation: 0.0,
+            correlation_spread: 0.0,
+        };
+        assert_eq!(detector.calculate_correlation_score(&one), 0.0);
+        let two = CorrelationFeatures {
+            matrix: Array2::from_shape_fn((2, 2), |(i, j)| if i == j { 1.0 } else { 0.0 }),
+            mean_correlation: 0.0,
+            max_correlation: 0.0,
+            correlation_spread: 0.0,
+        };
+        let s = detector.calculate_correlation_score(&two);
+        assert!(s.is_finite() && (0.0..=1.0).contains(&s));
+    }
+
+    /// `calculate_temporal_variance` returns 0.0 with fewer than 2 history
+    /// entries, finite otherwise. Pins the len<2 boundary.
+    #[test]
+    fn temporal_variance_zero_below_two_history() {
+        let mut detector = MotionDetector::default_config();
+        assert_eq!(detector.calculate_temporal_variance(), 0.0); // 0 entries
+        detector
+            .motion_history
+            .push_back(MotionScore::new(0.5, 0.5, 0.5, None));
+        assert_eq!(detector.calculate_temporal_variance(), 0.0); // 1 entry
+        detector
+            .motion_history
+            .push_back(MotionScore::new(0.1, 0.1, 0.1, None));
+        assert!(detector.calculate_temporal_variance() > 0.0); // 2 entries
+    }
+
+    /// The adaptive threshold engages only at/after `ADAPTIVE_THRESHOLD_MIN_HISTORY`
+    /// history entries; below it falls back to the configured fixed threshold.
+    /// Pins the history=9 (fixed) vs history=10 (adaptive) boundary.
+    #[test]
+    fn adaptive_threshold_engages_at_history_boundary() {
+        let config = MotionDetectorConfig::builder()
+            .adaptive_threshold(true)
+            .human_detection_threshold(0.8)
+            .history_size(50)
+            .build();
+        let mut detector = MotionDetector::new(config);
+        // Push exactly 9 entries: still uses the fixed configured threshold.
+        for _ in 0..(ADAPTIVE_THRESHOLD_MIN_HISTORY - 1) {
+            detector
+                .motion_history
+                .push_back(MotionScore::new(0.5, 0.5, 0.5, None));
+        }
+        assert_eq!(detector.calculate_adaptive_threshold(), 0.8);
+        // 10th entry: adaptive band kicks in, clamped to [MIN, MAX].
+        detector
+            .motion_history
+            .push_back(MotionScore::new(0.5, 0.5, 0.5, None));
+        let t = detector.calculate_adaptive_threshold();
+        assert!((ADAPTIVE_THRESHOLD_MIN..=ADAPTIVE_THRESHOLD_MAX).contains(&t));
+    }
 }

v2/crates/wifi-densepose-signal/src/ruvsense/attractor_drift.rs

@@ -24,6 +24,18 @@ use midstreamer_attractor::{AttractorAnalyzer, AttractorType, PhasePoint};
 
 use super::longitudinal::DriftMetric;
 
+// ---------------------------------------------------------------------------
+// Internal constants (ADR-154 §7.4 — de-magicked; values unchanged)
+// ---------------------------------------------------------------------------
+
+/// Per-metric ring-buffer capacity: one year of daily observations.
+const METRIC_BUFFER_CAPACITY: usize = 365;
+
+/// Number of most-recent values averaged to estimate a point-attractor's
+/// stable centre. Empirical default — a short tail that tracks the latest
+/// converged level without over-smoothing.
+const STABLE_CENTER_WINDOW: usize = 10;
+
 // ---------------------------------------------------------------------------
 // Configuration
 // ---------------------------------------------------------------------------
@@ -232,7 +244,7 @@ impl AttractorDriftAnalyzer {
 
         let buffers = DriftMetric::all()
             .iter()
-            .map(|&m| MetricBuffer::new(m, 365)) // 1 year of daily observations
+            .map(|&m| MetricBuffer::new(m, METRIC_BUFFER_CAPACITY))
             .collect();
 
         Ok(Self {
@@ -296,8 +308,12 @@ impl AttractorDriftAnalyzer {
 
                 match info.attractor_type {
                     AttractorType::PointAttractor => {
-                        // Compute center as mean of last few values
-                        let recent = &values[values.len().saturating_sub(10)..];
+                        // Compute center as the mean of the last STABLE_CENTER_WINDOW
+                        // values. `recent` is non-empty here: the `count < min_needed`
+                        // guard above guarantees `values.len() >= min_observations >= 1`
+                        // before this branch, so `recent.len() >= 1` and the division
+                        // below cannot be a divide-by-zero.
+                        let recent = &values[values.len().saturating_sub(STABLE_CENTER_WINDOW)..];
                         let center = recent.iter().sum::<f64>() / recent.len() as f64;
                         BiophysicalAttractor::Stable { center }
                     }
@@ -563,4 +579,38 @@ mod tests {
         let dbg = format!("{:?}", a);
         assert!(dbg.contains("AttractorDriftAnalyzer"));
     }
+
+    // -- ADR-154 §7.4: de-magic-constant + boundary characterization tests.
+
+    /// De-magicked internal constants must equal the prior inline literals.
+    #[test]
+    fn attractor_consts_unchanged_from_literals() {
+        assert_eq!(METRIC_BUFFER_CAPACITY, 365);
+        assert_eq!(STABLE_CENTER_WINDOW, 10);
+    }
+
+    /// `analyze` returns InsufficientData strictly below `min_observations` and
+    /// succeeds at exactly `min_observations`. Pins the off-by-one boundary
+    /// (previously only the well-below case was tested) and, with it, the
+    /// implicit `recent.len() >= 1` divide-safety in the PointAttractor branch.
+    #[test]
+    fn analyze_min_observations_boundary() {
+        let cfg = AttractorDriftConfig {
+            min_observations: 12,
+            ..Default::default()
+        };
+        let mut a = AttractorDriftAnalyzer::new(7, cfg.clone()).unwrap();
+        // One below the boundary -> InsufficientData.
+        for i in 0..(cfg.min_observations - 1) {
+            a.add_observation(DriftMetric::GaitSymmetry, 0.1 + i as f64 * 0.001);
+        }
+        assert!(matches!(
+            a.analyze(DriftMetric::GaitSymmetry, 0),
+            Err(AttractorDriftError::InsufficientData { needed: 12, have: 11 })
+        ));
+        // Exactly at the boundary -> Ok (no panic, finite center if Stable).
+        a.add_observation(DriftMetric::GaitSymmetry, 0.111);
+        let report = a.analyze(DriftMetric::GaitSymmetry, 0).unwrap();
+        assert_eq!(report.observation_count, 12);
+    }
 }

v2/crates/wifi-densepose-signal/src/ruvsense/calibration.rs

@@ -40,6 +40,30 @@ const VERSION: u8 = 1;
 const HEADER_LEN: usize = 16; // magic(4) + version(1) + tier(1) + reserved(2) + unix_s(8)
 const SUBCARRIER_RECORD_LEN: usize = 16; // 4 × f32
 
+// ADR-154 §7.4 — de-magicked (values unchanged). The tuning thresholds below
+// are EMPIRICAL DEFAULTS pending labelled empty-vs-occupied calibration traces.
+
+/// Default minimum frames for a baseline finalization (30 s @ 20 Hz). Shared by
+/// every tier constructor (`ht20`/`ht40`/`he20`/`he40`).
+const DEFAULT_MIN_FRAMES: u32 = 600;
+
+/// Amplitude standard-deviation floor used as the z-score divisor in
+/// `deviation()`, guarding against a zero-variance baseline subcarrier.
+const AMP_STD_FLOOR: f32 = 1e-12;
+
+/// `deviation()` flags motion when the median amplitude z-score exceeds this
+/// many σ. EMPIRICAL DEFAULT.
+const MOTION_AMP_Z_THRESHOLD: f32 = 2.0;
+
+/// `deviation()` flags motion when the median phase drift exceeds this many
+/// radians (π/6 = 30°). EMPIRICAL DEFAULT.
+const MOTION_PHASE_DRIFT_THRESHOLD: f32 = std::f32::consts::PI / 6.0;
+
+/// Minimum complex magnitude in `subtract_in_place` below which a bin is left
+/// untouched (a near-zero bin has no meaningful baseline to subtract and the
+/// `(norm - baseline)/norm` scaling would be ill-conditioned).
+const SUBTRACT_MIN_NORM: f64 = 1e-30;
+
 // ---------------------------------------------------------------------------
 // PHY tier
 // ---------------------------------------------------------------------------
@@ -103,11 +127,11 @@ pub struct CalibrationConfig {
 impl CalibrationConfig {
     /// HT20 defaults: 64 FFT, 52 active, 600 frame minimum (30 s @ 20 Hz).
     pub fn ht20() -> Self {
-        Self { tier: PhyTier::Ht20, num_subcarriers: 64, num_active: 52, min_frames: 600, max_phase_variance: 0.3 }
+        Self { tier: PhyTier::Ht20, num_subcarriers: 64, num_active: 52, min_frames: DEFAULT_MIN_FRAMES, max_phase_variance: 0.3 }
     }
     /// HT40 defaults: 128 FFT, 114 active.
     pub fn ht40() -> Self {
-        Self { tier: PhyTier::Ht40, num_subcarriers: 128, num_active: 114, min_frames: 600, max_phase_variance: 0.3 }
+        Self { tier: PhyTier::Ht40, num_subcarriers: 128, num_active: 114, min_frames: DEFAULT_MIN_FRAMES, max_phase_variance: 0.3 }
     }
     /// HE20 defaults: 256 FFT, **256 active** (record all delivered bins).
     ///
@@ -128,11 +152,11 @@ impl CalibrationConfig {
     /// `cir.rs` (`HE20_ACTIVE`), where the Φ sensing matrix genuinely needs it;
     /// the baseline recorder does not.
     pub fn he20() -> Self {
-        Self { tier: PhyTier::He20, num_subcarriers: 256, num_active: 256, min_frames: 600, max_phase_variance: 0.3 }
+        Self { tier: PhyTier::He20, num_subcarriers: 256, num_active: 256, min_frames: DEFAULT_MIN_FRAMES, max_phase_variance: 0.3 }
     }
     /// HE40 defaults: 512 FFT, 484 active.
     pub fn he40() -> Self {
-        Self { tier: PhyTier::He40, num_subcarriers: 512, num_active: 484, min_frames: 600, max_phase_variance: 0.3 }
+        Self { tier: PhyTier::He40, num_subcarriers: 512, num_active: 484, min_frames: DEFAULT_MIN_FRAMES, max_phase_variance: 0.3 }
     }
 }
 
@@ -264,7 +288,7 @@ impl BaselineCalibration {
         for (ki, (c, baseline)) in y.iter().zip(self.subcarriers.iter()).enumerate() {
             let _ = ki;
             let amp = c.norm();
-            let std = baseline.amp_variance.sqrt().max(1e-12_f32);
+            let std = baseline.amp_variance.sqrt().max(AMP_STD_FLOOR);
             z_amp.push((amp - baseline.amp_mean) / std);
             let theta = c.arg();
             let drift = circular_distance(theta, baseline.phase_mean);
@@ -273,7 +297,8 @@ impl BaselineCalibration {
         let amplitude_z_median = median_abs(&z_amp);
         let amplitude_z_max = z_amp.iter().map(|v| v.abs()).fold(0.0_f32, f32::max);
         let phase_drift_median = median_slice(&phase_drift);
-        let motion_flagged = amplitude_z_median > 2.0 || phase_drift_median > std::f32::consts::PI / 6.0;
+        let motion_flagged =
+            amplitude_z_median > MOTION_AMP_Z_THRESHOLD || phase_drift_median > MOTION_PHASE_DRIFT_THRESHOLD;
         Ok(CalibrationDeviationScore { amplitude_z_median, amplitude_z_max, phase_drift_median, motion_flagged })
     }
 
@@ -338,7 +363,7 @@ impl BaselineCalibration {
             for s in 0..n_streams {
                 let c = frame.data[[s, ki]];
                 let norm = c.norm();
-                if norm > 1e-30 {
+                if norm > SUBTRACT_MIN_NORM {
                     let scale = ((norm - baseline_amp).max(0.0)) / norm;
                     frame.data[[s, ki]] = num_complex::Complex64::new(c.re * scale, c.im * scale);
                 }
@@ -491,7 +516,8 @@ impl CalibrationRecorder {
         let amplitude_z_median = median_slice(&z_amp_abs);
         let amplitude_z_max = z_amp_abs.iter().copied().fold(0.0_f32, f32::max);
         let phase_drift_median = median_slice(&phase_drift);
-        let motion_flagged = amplitude_z_median > 2.0 || phase_drift_median > std::f32::consts::PI / 6.0;
+        let motion_flagged =
+            amplitude_z_median > MOTION_AMP_Z_THRESHOLD || phase_drift_median > MOTION_PHASE_DRIFT_THRESHOLD;
         Ok(CalibrationDeviationScore { amplitude_z_median, amplitude_z_max, phase_drift_median, motion_flagged })
     }
 
@@ -736,6 +762,27 @@ mod tests {
         }
     }
 
+    // -- ADR-154 §7.4: de-magic-constant pin test.
+
+    /// The de-magicked calibration constants MUST equal the prior literals, and
+    /// every tier constructor MUST share the one DEFAULT_MIN_FRAMES default.
+    #[test]
+    fn calibration_consts_unchanged_from_literals() {
+        assert_eq!(DEFAULT_MIN_FRAMES, 600);
+        assert_eq!(AMP_STD_FLOOR, 1e-12_f32);
+        assert_eq!(MOTION_AMP_Z_THRESHOLD, 2.0_f32);
+        assert_eq!(MOTION_PHASE_DRIFT_THRESHOLD, std::f32::consts::PI / 6.0);
+        assert_eq!(SUBTRACT_MIN_NORM, 1e-30_f64);
+        for cfg in [
+            CalibrationConfig::ht20(),
+            CalibrationConfig::ht40(),
+            CalibrationConfig::he20(),
+            CalibrationConfig::he40(),
+        ] {
+            assert_eq!(cfg.min_frames, DEFAULT_MIN_FRAMES);
+        }
+    }
+
     // Binary magic / version check.
     #[test]
     fn binary_magic_and_version() {

v2/crates/wifi-densepose-signal/src/ruvsense/cir.rs

@@ -1458,6 +1458,79 @@ mod tests {
         }
     }
 
+    /// ADR-154 §7.4 #14: the `fft_operator` path *changes the witness hash*
+    /// (documented in `CirConfig::fft_operator`), so it must be pinned as
+    /// numerically **close** to the dense path — not silently divergent. The
+    /// existing `fft_estimate_matches_dense_dominant_tap` covers HT20 / one tau;
+    /// this test asserts the **full `Cir` output** (every tap + every scalar
+    /// field) stays within a documented relative tolerance on the production
+    /// **canonical-56** config across several realistic delays. A regression
+    /// that lets the FFT path drift (wrong scaling, off-by-one Φ column, etc.)
+    /// fails here instead of corrupting a downstream witness unnoticed.
+    #[test]
+    fn fft_operator_within_tolerance_of_dense_canonical56() {
+        // Relative tolerances — documented, not silent. The FFT operator sums the
+        // same Φ entries in a different order, so taps agree to ~float epsilon
+        // scaled by the dominant-tap magnitude; ISTA can differ by a few last
+        // bits over its trajectory, hence 1e-2 (same order as the existing test).
+        const TAP_REL_TOL: f32 = 1e-2;
+        const RATIO_ABS_TOL: f32 = 1e-2;
+        const SPREAD_REL_TOL: f64 = 1e-2;
+
+        for &tau in &[20e-9_f64, 50e-9, 90e-9] {
+            let dense_cfg = CirConfig::canonical56();
+            let mut fft_cfg = CirConfig::canonical56();
+            fft_cfg.fft_operator = true;
+
+            let frame = make_single_tap_frame(dense_cfg.num_subcarriers, tau);
+            let dense = CirEstimator::new(dense_cfg).estimate(&frame).unwrap();
+            let fast = CirEstimator::new(fft_cfg).estimate(&frame).unwrap();
+
+            assert_eq!(dense.taps.len(), fast.taps.len());
+
+            // Full tap vector close (relative to the dominant tap magnitude).
+            let dom = dense.taps[dense.dominant_tap_idx].norm().max(1e-6);
+            let mut max_tap_err = 0.0_f32;
+            for (a, b) in dense.taps.iter().zip(&fast.taps) {
+                max_tap_err = max_tap_err.max((a - b).norm());
+            }
+            assert!(
+                max_tap_err <= TAP_REL_TOL * dom,
+                "tau={tau:e}: FFT taps diverged from dense — max err {max_tap_err} > {TAP_REL_TOL} * {dom} (NOT numerically close)"
+            );
+
+            // The dominant tap and the scalar summary fields must agree too —
+            // these feed the witness, so a silent divergence here is the bug #14
+            // guards against.
+            assert_eq!(
+                dense.dominant_tap_idx, fast.dominant_tap_idx,
+                "tau={tau:e}: dominant tap index moved"
+            );
+            assert!(
+                (dense.dominant_tap_ratio - fast.dominant_tap_ratio).abs() <= RATIO_ABS_TOL,
+                "tau={tau:e}: dominant_tap_ratio drift {} vs {}",
+                dense.dominant_tap_ratio,
+                fast.dominant_tap_ratio
+            );
+            assert_eq!(
+                dense.active_tap_count, fast.active_tap_count,
+                "tau={tau:e}: active_tap_count changed"
+            );
+            assert_eq!(
+                dense.ranging_valid, fast.ranging_valid,
+                "tau={tau:e}: ranging_valid flipped"
+            );
+            let spread_ref = dense.rms_delay_spread_s.abs().max(1e-12);
+            assert!(
+                (dense.rms_delay_spread_s - fast.rms_delay_spread_s).abs()
+                    <= SPREAD_REL_TOL * spread_ref,
+                "tau={tau:e}: rms_delay_spread drift {} vs {}",
+                dense.rms_delay_spread_s,
+                fast.rms_delay_spread_s
+            );
+        }
+    }
+
     /// The default configs keep the FFT operator off — the dense, bit-exact
     /// witness path is the default (enabling FFT shifts float results).
     #[test]

v2/crates/wifi-densepose-signal/src/ruvsense/coherence.rs

@@ -79,7 +79,7 @@ impl CoherenceState {
         Self {
             reference: vec![0.0; n_subcarriers],
             variance: vec![1.0; n_subcarriers],
-            decay: 0.95,
+            decay: DEFAULT_EMA_DECAY,
             current_score: 1.0,
             stale_count: 0,
             drift_profile: DriftProfile::Stable,
@@ -200,8 +200,8 @@ impl CoherenceState {
             let diff = obs - old_ref;
             *v = self.decay * *v + alpha * diff * diff;
             // Ensure variance does not collapse to zero
-            if *v < 1e-6 {
-                *v = 1e-6;
+            if *v < VARIANCE_FLOOR {
+                *v = VARIANCE_FLOOR;
             }
         }
     }
@@ -229,7 +229,7 @@ pub fn coherence_score(current: &[f32], reference: &[f32], variance: &[f32]) ->
         return 0.0;
     }
 
-    let epsilon = 1e-6_f32;
+    let epsilon = VARIANCE_FLOOR;
     let mut weighted_sum = 0.0_f32;
     let mut weight_sum = 0.0_f32;
 
@@ -260,6 +260,18 @@ const DRIFT_STABLE_SCORE: f32 = 0.85;
 /// DATA-GATED). EMPIRICAL DEFAULT pending labelled calibration.
 const DRIFT_STEP_CHANGE_MAX_STALE: u64 = 10;
 
+/// Variance floor (ADR-154 §7.4 — de-magicked): the online variance estimate
+/// is never allowed to collapse below this, which keeps the inverse-variance
+/// weight and the z-score divisor finite. Used as both the floor in
+/// `update_reference` and the epsilon in `coherence_score` /
+/// `per_subcarrier_zscores`. Value unchanged from the prior `1e-6` literals.
+const VARIANCE_FLOOR: f32 = 1e-6;
+
+/// Default EMA decay rate for the reference/variance update (ADR-154 §7.4 —
+/// de-magicked from the inline `0.95` in `CoherenceState::new`). EMPIRICAL
+/// DEFAULT; override via [`CoherenceState::with_decay`].
+const DEFAULT_EMA_DECAY: f32 = 0.95;
+
 /// Classify drift profile based on coherence history.
 fn classify_drift(score: f32, stale_count: u64) -> DriftProfile {
     if score >= DRIFT_STABLE_SCORE {
@@ -280,7 +292,7 @@ pub fn per_subcarrier_zscores(current: &[f32], reference: &[f32], variance: &[f3
     let n = current.len().min(reference.len()).min(variance.len());
     (0..n)
         .map(|i| {
-            let var = variance[i].max(1e-6);
+            let var = variance[i].max(VARIANCE_FLOOR);
             (current[i] - reference[i]).abs() / var.sqrt()
         })
         .collect()
@@ -439,6 +451,23 @@ mod tests {
     fn drift_consts_unchanged_from_literals() {
         assert_eq!(DRIFT_STABLE_SCORE, 0.85);
         assert_eq!(DRIFT_STEP_CHANGE_MAX_STALE, 10);
+        // ADR-154 §7.4 M3: variance-floor + default-decay de-magic.
+        assert_eq!(VARIANCE_FLOOR, 1e-6_f32);
+        assert_eq!(DEFAULT_EMA_DECAY, 0.95_f32);
+    }
+
+    /// `coherence_score` stays finite and in [0,1] when a subcarrier reports
+    /// zero variance — the [`VARIANCE_FLOOR`] keeps the z-score divisor and the
+    /// inverse-variance weight finite. Pins the floor's effect.
+    #[test]
+    fn coherence_score_finite_with_zero_variance() {
+        let current = [1.0_f32, 2.0, 3.0];
+        let reference = [1.0_f32, 2.0, 3.0];
+        let zero_var = [0.0_f32, 0.0, 0.0];
+        let s = coherence_score(&current, &reference, &zero_var);
+        assert!(s.is_finite() && (0.0..=1.0).contains(&s));
+        // Perfect agreement with floored variance -> ~1.0.
+        assert!((s - 1.0).abs() < 1e-3);
     }
 
     /// Stable score boundary: `>= 0.85` is Stable; just below flips to a

v2/crates/wifi-densepose-signal/src/ruvsense/cross_room.rs

@@ -23,6 +23,10 @@
 //! # References
 //! - ADR-030 Tier 5: Cross-Room Identity Continuity
 
+/// Denominator guard for cosine similarity (ADR-154 §7.4 — de-magicked):
+/// a product of norms below this is treated as a zero-norm vector ⇒ 0.0.
+const COSINE_SIMILARITY_EPSILON: f32 = 1e-9;
+
 // ---------------------------------------------------------------------------
 // Error types
 // ---------------------------------------------------------------------------
@@ -359,12 +363,15 @@ impl CrossRoomTracker {
 }
 
 /// Cosine similarity between two f32 vectors.
+///
+/// Returns `0.0` when either vector has (near-)zero norm — the product of
+/// norms falls below [`COSINE_SIMILARITY_EPSILON`] and the division is skipped.
 fn cosine_similarity_f32(a: &[f32], b: &[f32]) -> f32 {
     let dot: f32 = a.iter().zip(b.iter()).map(|(x, y)| x * y).sum();
     let norm_a: f32 = a.iter().map(|x| x * x).sum::<f32>().sqrt();
     let norm_b: f32 = b.iter().map(|x| x * x).sum::<f32>().sqrt();
     let denom = norm_a * norm_b;
-    if denom < 1e-9 {
+    if denom < COSINE_SIMILARITY_EPSILON {
         0.0
     } else {
         dot / denom
@@ -623,4 +630,23 @@ mod tests {
         let sim = cosine_similarity_f32(&a, &b);
         assert!(sim.abs() < 1e-5);
     }
+
+    // -- ADR-154 §7.4: de-magic-constant + boundary characterization tests.
+
+    /// De-magicked epsilon must equal the prior literal.
+    #[test]
+    fn cosine_epsilon_unchanged_from_literal() {
+        assert_eq!(COSINE_SIMILARITY_EPSILON, 1e-9_f32);
+    }
+
+    /// A zero-norm vector falls below the denominator epsilon ⇒ similarity 0.0.
+    /// Previously untested (both existing tests use unit-norm vectors).
+    #[test]
+    fn test_cosine_similarity_zero_vector() {
+        let zero = vec![0.0_f32; 4];
+        let v = vec![1.0_f32, 2.0, 3.0, 4.0];
+        assert_eq!(cosine_similarity_f32(&zero, &v), 0.0);
+        assert_eq!(cosine_similarity_f32(&v, &zero), 0.0);
+        assert_eq!(cosine_similarity_f32(&zero, &zero), 0.0);
+    }
 }

v2/crates/wifi-densepose-signal/src/ruvsense/fusion_quality.rs

@@ -14,6 +14,15 @@
 
 use super::QualityScored;
 
+/// Multiplicative coherence penalty applied per recorded contradiction
+/// (ADR-154 §7.4 — de-magicked; EMPIRICAL DEFAULT). `n` contradictions scale
+/// coherence by `CONTRADICTION_PENALTY.powi(n)`.
+const CONTRADICTION_PENALTY: f32 = 0.8;
+
+/// Confidence-bound half-width added per recorded contradiction (clamped so the
+/// interval stays within `[0, 1]`). EMPIRICAL DEFAULT.
+const CONTRADICTION_BOUND_HALFWIDTH: f32 = 0.1;
+
 /// Identifies which sensing family produced a fused frame, so one
 /// [`QualityScore`] can be correlated across the signal-domain fuser
 /// (`multistatic.rs`) and the embedding-domain fuser (`viewpoint/fusion.rs`).
@@ -113,7 +122,7 @@ impl QualityScore {
     /// streaming engine routes/gates on.
     #[must_use]
     pub fn penalized_coherence(&self) -> f32 {
-        let penalty = 0.8_f32.powi(self.contradiction_flags.len() as i32);
+        let penalty = CONTRADICTION_PENALTY.powi(self.contradiction_flags.len() as i32);
         (self.base_coherence * penalty).clamp(0.0, 1.0)
     }
 }
@@ -127,7 +136,8 @@ impl QualityScored for QualityScore {
         // Width grows with the number of tolerated contradictions: each adds
         // ±0.1 of uncertainty around the penalized coherence, clamped to [0,1].
         let c = self.penalized_coherence();
-        let half = (0.1 * self.contradiction_flags.len() as f32).min(c.min(1.0 - c));
+        let half =
+            (CONTRADICTION_BOUND_HALFWIDTH * self.contradiction_flags.len() as f32).min(c.min(1.0 - c));
         ((c - half).max(0.0), (c + half).min(1.0))
     }
 }
@@ -185,4 +195,24 @@ mod tests {
         assert!((0.0..=1.0).contains(&s));
         assert!(0.0 <= lo && lo <= hi && hi <= 1.0);
     }
+
+    // -- ADR-154 §7.4: de-magic-constant + boundary characterization tests.
+
+    /// De-magicked penalty/bound consts must equal the prior literals.
+    #[test]
+    fn fusion_quality_consts_unchanged_from_literals() {
+        assert_eq!(CONTRADICTION_PENALTY, 0.8_f32);
+        assert_eq!(CONTRADICTION_BOUND_HALFWIDTH, 0.1_f32);
+    }
+
+    /// Zero contradictions: penalty is `0.8^0 = 1.0` (coherence unchanged) and
+    /// the confidence bounds collapse to a point. Pins the n=0 boundary.
+    #[test]
+    fn no_contradiction_is_identity() {
+        let q = base();
+        assert!(q.contradiction_flags.is_empty());
+        assert!((q.penalized_coherence() - q.base_coherence).abs() < 1e-6);
+        let (lo, hi) = q.confidence_bounds();
+        assert!((hi - lo).abs() < 1e-6); // half-width is 0 with no contradictions
+    }
 }

v2/crates/wifi-densepose-signal/src/ruvsense/gesture.rs

@@ -19,6 +19,16 @@
 //! - Sakoe & Chiba (1978), "Dynamic programming algorithm optimization
 //!   for spoken word recognition" IEEE TASSP
 
+// ---------------------------------------------------------------------------
+// Tuning constants (ADR-154 §7.4 — de-magicked; value unchanged)
+// ---------------------------------------------------------------------------
+
+/// Minimum second-best DTW distance below which the relative-margin
+/// confidence formula `1 - best/second_best` would divide by a near-zero
+/// denominator. Below this we fall back to the `max_distance`-relative
+/// confidence. Empirical guard, not a tuned operating point.
+const CONFIDENCE_SECOND_BEST_EPSILON: f64 = 1e-10;
+
 // ---------------------------------------------------------------------------
 // Error types
 // ---------------------------------------------------------------------------
@@ -236,7 +246,10 @@ impl GestureClassifier {
         let recognized = best_dist <= self.config.max_distance;
 
         // Confidence: how much better is the best match vs second best
-        let confidence = if recognized && second_best_dist.is_finite() && second_best_dist > 1e-10 {
+        let confidence = if recognized
+            && second_best_dist.is_finite()
+            && second_best_dist > CONFIDENCE_SECOND_BEST_EPSILON
+        {
             (1.0 - best_dist / second_best_dist).clamp(0.0, 1.0)
         } else if recognized {
             (1.0 - best_dist / self.config.max_distance).clamp(0.0, 1.0)
@@ -364,7 +377,24 @@ fn dtw_distance(seq_a: &[Vec<f64>], seq_b: &[Vec<f64>], band_width: usize) -> f6
 }
 
 /// Euclidean distance between two feature vectors.
+///
+/// # Caller contract (ADR-154 §7.4 #12)
+/// `a` and `b` are expected to have the **same** dimension (`feature_dim`).
+/// The implementation `zip`s the two slices, so on a length mismatch it
+/// **silently truncates to the shorter vector** rather than erroring. Every
+/// in-tree caller (`dtw_distance` over a single classifier's templates)
+/// already enforces equal `feature_dim`, so a mismatch indicates a
+/// construction bug; a `debug_assert!` makes that loud in debug builds while
+/// keeping the release operating path (and its output) unchanged.
 fn euclidean_distance(a: &[f64], b: &[f64]) -> f64 {
+    debug_assert_eq!(
+        a.len(),
+        b.len(),
+        "euclidean_distance: feature-vector length mismatch ({} vs {}) — \
+         zip() would silently truncate; callers must use a uniform feature_dim",
+        a.len(),
+        b.len()
+    );
     a.iter()
         .zip(b.iter())
         .map(|(x, y)| (x - y) * (x - y))
@@ -688,4 +718,34 @@ mod tests {
         assert_eq!(GestureType::Circle.name(), "circle");
         assert_eq!(GestureType::Custom.name(), "custom");
     }
+
+    // -- ADR-154 §7.4 #12 + de-magic: boundary / characterization tests.
+
+    /// De-magicked confidence epsilon must equal the prior literal.
+    #[test]
+    fn confidence_epsilon_unchanged_from_literal() {
+        assert_eq!(CONFIDENCE_SECOND_BEST_EPSILON, 1e-10);
+    }
+
+    /// `dtw_distance` returns +inf when EITHER sequence is empty. Pins the
+    /// n=0 / m=0 boundary (previously exercised only with n,m >= 3).
+    #[test]
+    fn dtw_empty_sequence_is_infinite() {
+        let nonempty: Vec<Vec<f64>> = vec![vec![1.0], vec![2.0]];
+        let empty: Vec<Vec<f64>> = vec![];
+        assert!(dtw_distance(&empty, &nonempty, 3).is_infinite());
+        assert!(dtw_distance(&nonempty, &empty, 3).is_infinite());
+        assert!(dtw_distance(&empty, &empty, 3).is_infinite());
+    }
+
+    /// `euclidean_distance` over equal-length vectors is the L2 norm of the
+    /// difference. Pins the documented same-dimension caller contract (#12);
+    /// the mismatch case is guarded by a debug_assert in debug builds and
+    /// truncates in release — not exercised here to keep the test
+    /// release/debug-agnostic.
+    #[test]
+    fn euclidean_distance_equal_length_is_l2() {
+        assert!((euclidean_distance(&[1.0, 2.0, 2.0], &[0.0, 0.0, 0.0]) - 3.0).abs() < 1e-12);
+        assert_eq!(euclidean_distance(&[], &[]), 0.0);
+    }
 }

v2/crates/wifi-densepose-signal/src/ruvsense/intention.rs

@@ -21,6 +21,11 @@
 
 use std::collections::VecDeque;
 
+/// Minimum acceleration magnitude (ADR-154 §7.4 — de-magicked) below which the
+/// lead-time estimate `t = (v_thresh - v) / a` would divide by a near-zero
+/// acceleration; below this the lead time is reported as 0.0.
+const LEAD_TIME_MIN_ACCEL: f64 = 1e-10;
+
 // ---------------------------------------------------------------------------
 // Error types
 // ---------------------------------------------------------------------------
@@ -233,7 +238,7 @@ impl IntentionDetector {
         let detected = self.sustained_count >= self.config.min_sustained_frames;
 
         // Estimate lead time based on current acceleration and velocity
-        let estimated_lead = if detected && accel_mag > 1e-10 {
+        let estimated_lead = if detected && accel_mag > LEAD_TIME_MIN_ACCEL {
             // Time until velocity reaches threshold: t = (v_thresh - v) / a
             let remaining = (self.config.max_pre_movement_velocity - velocity_mag) / accel_mag;
             remaining.clamp(0.0, self.config.max_lead_time_s)
@@ -508,4 +513,29 @@ mod tests {
         let sd = embedding_second_diff(&a, &b, &c, 1.0);
         assert!((sd[0] - 2.0).abs() < 1e-10);
     }
+
+    // -- ADR-154 §7.4: de-magic-constant + boundary characterization tests.
+
+    /// De-magicked lead-time accel guard must equal the prior literal.
+    #[test]
+    fn lead_time_accel_const_unchanged_from_literal() {
+        assert_eq!(LEAD_TIME_MIN_ACCEL, 1e-10);
+    }
+
+    /// A static (zero-motion) embedding stream produces ~zero acceleration, so
+    /// the lead-time estimate stays at the 0.0 sentinel rather than dividing by
+    /// a near-zero acceleration. Pins the `accel_mag <= LEAD_TIME_MIN_ACCEL`
+    /// branch behaviour.
+    #[test]
+    fn lead_time_zero_for_static_stream() {
+        let config = make_config();
+        let mut detector = IntentionDetector::new(config).unwrap();
+        let mut last = None;
+        for frame in 0..6_u64 {
+            last = Some(detector.update(&static_embedding(), frame * 50_000).unwrap());
+        }
+        let signal = last.unwrap();
+        assert!(signal.acceleration_magnitude < LEAD_TIME_MIN_ACCEL.max(1e-9));
+        assert_eq!(signal.estimated_lead_time_s, 0.0);
+    }
 }

v2/crates/wifi-densepose-signal/src/ruvsense/longitudinal.rs

@@ -18,6 +18,38 @@
 
 use crate::ruvsense::field_model::WelfordStats;
 
+// ---------------------------------------------------------------------------
+// Drift-detection thresholds (ADR-154 §7.4 — de-magicked; EMPIRICAL DEFAULTS).
+//
+// These encode the "Key Invariants" documented in the module header. They were
+// previously bare literals scattered through `update_daily`/`is_ready`. Lifting
+// them to named consts makes the policy explicit and a future retune a visible,
+// tested change. Values are unchanged.
+// ---------------------------------------------------------------------------
+
+/// Minimum observation days before drift detection activates.
+const BASELINE_MIN_OBSERVATION_DAYS: u32 = 7;
+
+/// EMA update weight applied to the embedding centroid each day (the new
+/// sample's weight; the centroid retains `1 - EMBEDDING_EMA_ALPHA` of its old
+/// value, i.e. a decay of 0.95). Kept as the literal `0.05` rather than
+/// `1.0 - 0.95_f32` to stay bit-identical (the f32 subtraction is not exactly
+/// 0.05).
+const EMBEDDING_EMA_ALPHA: f32 = 0.05;
+
+/// Per-metric absolute z-score above which a day counts toward sustained drift.
+const DRIFT_ZSCORE_SIGMA: f64 = 2.0;
+
+/// Consecutive drift days required before a drift report is emitted.
+const DRIFT_SUSTAINED_DAYS: u32 = 3;
+
+/// Consecutive drift days at/above which monitoring escalates from `Drift`
+/// to `RiskCorrelation`.
+const DRIFT_ESCALATION_DAYS: u32 = 7;
+
+/// Denominator guard for cosine similarity (zero-norm vectors ⇒ 0.0).
+const COSINE_SIMILARITY_EPSILON: f32 = 1e-9;
+
 // ---------------------------------------------------------------------------
 // Error types
 // ---------------------------------------------------------------------------
@@ -226,7 +258,7 @@ impl PersonalBaseline {
 
     /// Whether baseline has enough data for drift detection.
     pub fn is_ready(&self) -> bool {
-        self.observation_days >= 7
+        self.observation_days >= BASELINE_MIN_OBSERVATION_DAYS
     }
 
     /// Update baseline with a daily summary.
@@ -240,10 +272,10 @@ impl PersonalBaseline {
         self.observation_days += 1;
         self.updated_at_us = timestamp_us;
 
-        // Update embedding centroid with EMA (decay = 0.95)
+        // Update embedding centroid with EMA (decay 0.95, alpha = 1 - 0.95)
         if let Some(ref emb) = summary.embedding_centroid {
             if emb.len() == self.embedding_centroid.len() {
-                let alpha = 0.05_f32; // 1 - 0.95
+                let alpha = EMBEDDING_EMA_ALPHA;
                 for (c, e) in self.embedding_centroid.iter_mut().zip(emb.iter()) {
                     *c = (1.0 - alpha) * *c + alpha * *e;
                 }
@@ -271,20 +303,20 @@ impl PersonalBaseline {
 
             let idx = Self::metric_index(metric);
 
-            if z.abs() > 2.0 {
+            if z.abs() > DRIFT_ZSCORE_SIGMA {
                 self.drift_counters[idx] += 1;
             } else {
                 self.drift_counters[idx] = 0;
             }
 
-            if self.drift_counters[idx] >= 3 {
+            if self.drift_counters[idx] >= DRIFT_SUSTAINED_DAYS {
                 let direction = if z > 0.0 {
                     DriftDirection::Increasing
                 } else {
                     DriftDirection::Decreasing
                 };
 
-                let level = if self.drift_counters[idx] >= 7 {
+                let level = if self.drift_counters[idx] >= DRIFT_ESCALATION_DAYS {
                     MonitoringLevel::RiskCorrelation
                 } else {
                     MonitoringLevel::Drift
@@ -310,7 +342,7 @@ impl PersonalBaseline {
 
     /// Check readiness at a specific observation day count (internal helper).
     fn is_ready_at(&self, days: u32) -> bool {
-        days >= 7
+        days >= BASELINE_MIN_OBSERVATION_DAYS
     }
 
     /// Get current drift counter for a metric.
@@ -545,12 +577,15 @@ impl EmbeddingHistory {
 }
 
 /// Cosine similarity between two f32 vectors.
+///
+/// Returns `0.0` if either vector has (near-)zero norm — the product of norms
+/// falls below [`COSINE_SIMILARITY_EPSILON`], so the division is skipped.
 fn cosine_similarity(a: &[f32], b: &[f32]) -> f32 {
     let dot: f32 = a.iter().zip(b.iter()).map(|(x, y)| x * y).sum();
     let norm_a: f32 = a.iter().map(|x| x * x).sum::<f32>().sqrt();
     let norm_b: f32 = b.iter().map(|x| x * x).sum::<f32>().sqrt();
     let denom = norm_a * norm_b;
-    if denom < 1e-9 {
+    if denom < COSINE_SIMILARITY_EPSILON {
         0.0
     } else {
         dot / denom
@@ -1017,4 +1052,40 @@ mod tests {
             assert!(*i < h.len());
         }
     }
+
+    // -- ADR-154 §7.4: de-magic-constant + boundary characterization tests.
+
+    /// The de-magicked drift thresholds MUST equal the prior bare literals.
+    #[test]
+    fn drift_consts_unchanged_from_literals() {
+        assert_eq!(BASELINE_MIN_OBSERVATION_DAYS, 7);
+        assert_eq!(EMBEDDING_EMA_ALPHA, 0.05_f32);
+        assert_eq!(DRIFT_ZSCORE_SIGMA, 2.0);
+        assert_eq!(DRIFT_SUSTAINED_DAYS, 3);
+        assert_eq!(DRIFT_ESCALATION_DAYS, 7);
+        assert_eq!(COSINE_SIMILARITY_EPSILON, 1e-9_f32);
+    }
+
+    /// `is_ready_at` pins the exact day-6 (not ready) / day-7 (ready) boundary
+    /// independent of Welford state.
+    #[test]
+    fn is_ready_at_day_boundary() {
+        let baseline = PersonalBaseline::new(1, 8);
+        assert!(!baseline.is_ready_at(BASELINE_MIN_OBSERVATION_DAYS - 1)); // day 6
+        assert!(baseline.is_ready_at(BASELINE_MIN_OBSERVATION_DAYS)); // day 7
+        assert!(baseline.is_ready_at(BASELINE_MIN_OBSERVATION_DAYS + 1)); // day 8
+    }
+
+    /// Cosine similarity returns 0.0 for a zero-norm vector (denominator below
+    /// `COSINE_SIMILARITY_EPSILON`) and a finite value otherwise.
+    #[test]
+    fn cosine_similarity_zero_vector_is_zero() {
+        let zero = [0.0_f32; 4];
+        let v = [1.0_f32, 2.0, 3.0, 4.0];
+        assert_eq!(cosine_similarity(&zero, &v), 0.0);
+        assert_eq!(cosine_similarity(&v, &zero), 0.0);
+        assert_eq!(cosine_similarity(&zero, &zero), 0.0);
+        // identical non-zero vectors -> ~1.0
+        assert!((cosine_similarity(&v, &v) - 1.0).abs() < 1e-5);
+    }
 }

v2/crates/wifi-densepose-signal/src/ruvsense/multiband.rs

@@ -198,7 +198,15 @@ fn compute_cross_channel_coherence(frames: &[CanonicalCsiFrame]) -> f32 {
     ((mean_corr + 1.0) / 2.0).clamp(0.0, 1.0) as f32
 }
 
+/// Denominator guard for the Pearson correlation (ADR-154 §7.4 — de-magicked):
+/// a product of standard deviations below this is treated as a zero-variance
+/// (constant) input ⇒ correlation 0.0.
+const PEARSON_DENOMINATOR_EPSILON: f32 = 1e-12;
+
 /// Pearson correlation coefficient between two f32 slices.
+///
+/// Returns `0.0` for empty inputs or when either slice has (near-)zero
+/// variance (the denominator falls below [`PEARSON_DENOMINATOR_EPSILON`]).
 fn pearson_correlation_f32(a: &[f32], b: &[f32]) -> f32 {
     let n = a.len().min(b.len());
     if n == 0 {
@@ -222,7 +230,7 @@ fn pearson_correlation_f32(a: &[f32], b: &[f32]) -> f32 {
     }
 
     let denom = (var_a * var_b).sqrt();
-    if denom < 1e-12 {
+    if denom < PEARSON_DENOMINATOR_EPSILON {
         return 0.0;
     }
 
@@ -439,4 +447,24 @@ mod tests {
         assert_eq!(cfg.window_us, 200_000);
         assert!((cfg.min_coherence - 0.3).abs() < f32::EPSILON);
     }
+
+    // -- ADR-154 §7.4: de-magic-constant + boundary characterization tests.
+
+    /// De-magicked denominator epsilon must equal the prior literal.
+    #[test]
+    fn pearson_epsilon_unchanged_from_literal() {
+        assert_eq!(PEARSON_DENOMINATOR_EPSILON, 1e-12_f32);
+    }
+
+    /// A constant (zero-variance) input makes the denominator fall below the
+    /// epsilon ⇒ correlation 0.0. Previously untested (existing tests use
+    /// non-constant inputs).
+    #[test]
+    fn pearson_correlation_zero_variance() {
+        let constant = vec![3.0_f32; 5];
+        let varying = vec![1.0_f32, 2.0, 3.0, 4.0, 5.0];
+        assert_eq!(pearson_correlation_f32(&constant, &varying), 0.0);
+        assert_eq!(pearson_correlation_f32(&varying, &constant), 0.0);
+        assert_eq!(pearson_correlation_f32(&constant, &constant), 0.0);
+    }
 }

v2/crates/wifi-densepose-signal/src/ruvsense/phase_align.rs

@@ -201,12 +201,29 @@ fn find_static_subcarriers(
 
 /// Estimate per-channel phase offsets using iterative Neumann-style refinement.
 ///
-/// Channel 0 is the reference (offset = 0).
+/// Channel 0 is the reference (offset = 0). Thin wrapper that drops the
+/// iteration count; `estimate_phase_offsets_counted` is the instrumented core.
 fn estimate_phase_offsets(
     frames: &[CanonicalCsiFrame],
     static_indices: &[usize],
     config: &PhaseAlignConfig,
 ) -> std::result::Result<Vec<f32>, PhaseAlignError> {
+    estimate_phase_offsets_counted(frames, static_indices, config).map(|(offsets, _iters)| offsets)
+}
+
+/// Core of [`estimate_phase_offsets`], also returning the number of refinement
+/// iterations actually executed.
+///
+/// The returned count is bounded by `config.max_iterations` — that bound is the
+/// convergence cap that guarantees termination on inputs the damped Neumann
+/// update never drives below `config.tolerance` (ADR-154 §7.4 #16). The offset
+/// vector is identical to the public `estimate_phase_offsets` path; only the
+/// iteration count is surfaced (for the cap test).
+fn estimate_phase_offsets_counted(
+    frames: &[CanonicalCsiFrame],
+    static_indices: &[usize],
+    config: &PhaseAlignConfig,
+) -> std::result::Result<(Vec<f32>, usize), PhaseAlignError> {
     let n_ch = frames.len();
     let mut offsets = vec![0.0_f32; n_ch];
 
@@ -220,7 +237,7 @@ fn estimate_phase_offsets(
     }
 
     // Iterative refinement (Neumann-style)
-    for _iter in 0..config.max_iterations {
+    for iter in 0..config.max_iterations {
         let mut max_update = 0.0_f32;
 
         for c in 1..n_ch {
@@ -241,12 +258,13 @@ fn estimate_phase_offsets(
         }
 
         if max_update < config.tolerance {
-            return Ok(offsets);
+            return Ok((offsets, iter + 1));
         }
     }
 
-    // Even if we do not converge tightly, return best estimate
-    Ok(offsets)
+    // Even if we do not converge tightly, return best estimate. The loop ran the
+    // full cap — termination is guaranteed by `config.max_iterations`.
+    Ok((offsets, config.max_iterations))
 }
 
 /// Apply phase correction: subtract offset from each subcarrier phase.
@@ -446,6 +464,73 @@ mod tests {
         assert_eq!(cfg.min_static_subcarriers, 5);
     }
 
+    // ADR-154 §7.4 #16: the iterative LO-offset refinement must TERMINATE at the
+    // `max_iterations` cap on a non-converging input — no unbounded loop.
+    //
+    // We force non-convergence by setting `tolerance` to an unreachable value
+    // (the damped Neumann update on bounded phase residuals can never drive
+    // `max_update` below 0.0), so the `max_update < tolerance` early-exit is
+    // never taken. The instrumented core must then run *exactly*
+    // `max_iterations` and return — proving the cap, not convergence, is what
+    // bounds the loop.
+    #[test]
+    fn refinement_terminates_at_iteration_cap_when_not_converging() {
+        let n_sub = 56;
+        let max_iterations = 7;
+        let config = PhaseAlignConfig {
+            max_iterations,
+            // Unreachable tolerance: `max_update` is always ≥ 0, never < 0.0,
+            // so the convergence branch can never fire.
+            tolerance: 0.0,
+            static_fraction: 0.3,
+            min_static_subcarriers: 5,
+        };
+        // Two channels with a real, persistent offset so each iteration keeps
+        // producing a non-zero update.
+        let f0 = make_frame_with_phase(n_sub, 0.0, 0.0);
+        let f1 = make_frame_with_phase(n_sub, 0.0, 1.3);
+        let frames = vec![f0, f1];
+        let static_indices = find_static_subcarriers(&frames, &config).unwrap();
+
+        let (offsets, iters) =
+            estimate_phase_offsets_counted(&frames, &static_indices, &config).unwrap();
+
+        // The cap, not convergence, terminated the loop.
+        assert_eq!(
+            iters, max_iterations,
+            "expected the loop to run the full cap ({max_iterations}), got {iters}"
+        );
+        // It still returns a finite best-estimate offset vector.
+        assert_eq!(offsets.len(), 2);
+        assert!(offsets.iter().all(|o| o.is_finite()));
+        // Reference channel offset stays 0.
+        assert_eq!(offsets[0], 0.0);
+    }
+
+    // Convergent companion: a near-identical input converges *before* the cap,
+    // so the cap is an upper bound, not the only exit.
+    #[test]
+    fn refinement_converges_before_cap_on_easy_input() {
+        let n_sub = 56;
+        let config = PhaseAlignConfig {
+            max_iterations: 50,
+            tolerance: 1e-2, // loose: a tiny offset converges in a few iters
+            static_fraction: 0.3,
+            min_static_subcarriers: 5,
+        };
+        let f0 = make_frame_with_phase(n_sub, 0.0, 0.0);
+        let f1 = make_frame_with_phase(n_sub, 0.0, 0.02);
+        let frames = vec![f0, f1];
+        let static_indices = find_static_subcarriers(&frames, &config).unwrap();
+        let (_offsets, iters) =
+            estimate_phase_offsets_counted(&frames, &static_indices, &config).unwrap();
+        assert!(
+            iters < config.max_iterations,
+            "easy input should converge before the cap, ran {iters}/{}",
+            config.max_iterations
+        );
+    }
+
     #[test]
     fn phase_correction_preserves_amplitude() {
         let mut aligner = PhaseAligner::new(2);

v2/crates/wifi-densepose-signal/src/ruvsense/rf_slam.rs

@@ -13,6 +13,27 @@
 
 use crate::ruvsense::field_model::WelfordStats;
 
+/// Nanoseconds per day, for migration-rate (m/day) conversion (ADR-154 §7.4 —
+/// de-magicked from the inline `86_400_000_000_000.0` literal). 24·60·60·1e9.
+const NS_PER_DAY: f64 = 86_400_000_000_000.0;
+
+/// Minimum observed span (in days) below which migration rate is reported as
+/// 0.0 — guards `cumulative_drift_m / span_days` against a near-zero span.
+const MIGRATION_MIN_SPAN_DAYS: f64 = 1e-9;
+
+// ADR-154 §7.4: the v1 fixed-map defaults below were bare literals in
+// `fixed_map()`. They are EMPIRICAL DEFAULTS (ADR-143), unchanged.
+
+/// Default association radius (m): a sighting within this of a reflector's
+/// running mean is folded into it; otherwise it seeds a new reflector.
+const FIXED_MAP_ASSOC_RADIUS_M: f64 = 0.5;
+
+/// Default minimum sightings before a reflector counts as "persistent".
+const FIXED_MAP_MIN_SIGHTINGS: u64 = 20;
+
+/// Default minimum tap coherence for a sighting to be admitted.
+const FIXED_MAP_MIN_COHERENCE: f32 = 0.6;
+
 /// Classification of a discovered persistent reflector (mirrors ADR-139
 /// `AnchorKind`; kept local to avoid a crate dependency on the WorldGraph).
 #[derive(Debug, Clone, Copy, PartialEq, Eq)]
@@ -102,8 +123,8 @@ impl PersistentReflector {
         if span_ns == 0 {
             return 0.0;
         }
-        let span_days = span_ns as f64 / 86_400_000_000_000.0; // ns → days
-        if span_days < 1e-9 {
+        let span_days = span_ns as f64 / NS_PER_DAY; // ns → days
+        if span_days < MIGRATION_MIN_SPAN_DAYS {
             return 0.0;
         }
         self.cumulative_drift_m / span_days
@@ -145,9 +166,9 @@ impl RfSlam {
     pub fn fixed_map() -> Self {
         Self {
             reflectors: Vec::new(),
-            assoc_radius_m: 0.5,
-            min_sightings: 20,
-            min_coherence: 0.6,
+            assoc_radius_m: FIXED_MAP_ASSOC_RADIUS_M,
+            min_sightings: FIXED_MAP_MIN_SIGHTINGS,
+            min_coherence: FIXED_MAP_MIN_COHERENCE,
             discovery_enabled: false,
         }
     }
@@ -298,4 +319,29 @@ mod tests {
         assert_eq!(anchors.len(), 1);
         assert_eq!(anchors[0].1, ReflectorClass::Wall);
     }
+
+    // -- ADR-154 §7.4: de-magic-constant + boundary characterization tests.
+
+    /// De-magicked constants must equal the prior inline literals.
+    #[test]
+    fn migration_consts_unchanged_from_literals() {
+        assert_eq!(NS_PER_DAY, 86_400_000_000_000.0);
+        assert_eq!(NS_PER_DAY, 24.0 * 60.0 * 60.0 * 1e9);
+        assert_eq!(MIGRATION_MIN_SPAN_DAYS, 1e-9);
+        assert_eq!(FIXED_MAP_ASSOC_RADIUS_M, 0.5);
+        assert_eq!(FIXED_MAP_MIN_SIGHTINGS, 20);
+        assert_eq!(FIXED_MAP_MIN_COHERENCE, 0.6_f32);
+    }
+
+    /// A single sighting has first_ns == last_ns ⇒ zero span ⇒ migration rate
+    /// 0.0 (pins the `span_ns == 0` / `span_days < MIGRATION_MIN_SPAN_DAYS`
+    /// guard, and that such a reflector classifies as a Wall).
+    #[test]
+    fn migration_zero_span_is_zero_rate() {
+        let mut slam = RfSlam::with_discovery(0.5, 1, 0.6);
+        slam.observe(&obs([1.0, 2.0, 0.0], 12_345));
+        let r = slam.persistent()[0];
+        assert_eq!(r.migration_m_per_day(), 0.0);
+        assert_eq!(r.classify(0.05, 1.0), ReflectorClass::Wall);
+    }
 }

v2/crates/wifi-densepose-signal/src/ruvsense/temporal_gesture.rs

@@ -18,6 +18,16 @@ use midstreamer_temporal_compare::{ComparisonAlgorithm, Sequence, TemporalCompar
 
 use super::gesture::{GestureConfig, GestureError, GestureResult, GestureTemplate};
 
+/// Minimum second-best distance (ADR-154 §7.4 — de-magicked) below which the
+/// relative-margin confidence `1 - best/second_best` would divide by a
+/// near-zero denominator; below this we fall back to the `max_distance`-relative
+/// confidence. Mirrors the same guard in `gesture.rs`.
+const CONFIDENCE_SECOND_BEST_EPSILON: f64 = 1e-10;
+
+/// Fixed-point scale used to quantize a frame's L2 norm to an i64 for the
+/// integer temporal comparator (norm·SCALE truncated). Empirical resolution.
+const NORM_QUANTIZATION_SCALE: f64 = 1000.0;
+
 // ---------------------------------------------------------------------------
 // Configuration
 // ---------------------------------------------------------------------------
@@ -192,7 +202,10 @@ impl TemporalGestureClassifier {
         let recognized = best_distance <= self.config.max_distance;
 
         // Confidence based on margin between best and second-best
-        let confidence = if recognized && second_best.is_finite() && second_best > 1e-10 {
+        let confidence = if recognized
+            && second_best.is_finite()
+            && second_best > CONFIDENCE_SECOND_BEST_EPSILON
+        {
             (1.0 - best_distance / second_best).clamp(0.0, 1.0)
         } else if recognized {
             (1.0 - best_distance / self.config.max_distance).clamp(0.0, 1.0)
@@ -244,13 +257,13 @@ impl TemporalGestureClassifier {
 
     /// Convert a feature sequence to a midstreamer `Sequence<i64>`.
     ///
-    /// Each frame's L2 norm is quantized to an i64 (multiplied by 1000)
-    /// for use with the generic comparator.
+    /// Each frame's L2 norm is quantized to an i64 (multiplied by
+    /// [`NORM_QUANTIZATION_SCALE`]) for use with the generic comparator.
     fn to_sequence(frames: &[Vec<f64>]) -> Sequence<i64> {
         let mut seq = Sequence::new();
         for (i, frame) in frames.iter().enumerate() {
             let norm = frame.iter().map(|x| x * x).sum::<f64>().sqrt();
-            let quantized = (norm * 1000.0) as i64;
+            let quantized = (norm * NORM_QUANTIZATION_SCALE) as i64;
             seq.push(quantized, i as u64);
         }
         seq
@@ -537,4 +550,14 @@ mod tests {
         let dbg = format!("{:?}", classifier);
         assert!(dbg.contains("TemporalGestureClassifier"));
     }
+
+    // -- ADR-154 §7.4: de-magic-constant pin test.
+
+    /// De-magicked confidence epsilon + quantization scale must equal the
+    /// prior inline literals.
+    #[test]
+    fn temporal_gesture_consts_unchanged_from_literals() {
+        assert_eq!(CONFIDENCE_SECOND_BEST_EPSILON, 1e-10);
+        assert_eq!(NORM_QUANTIZATION_SCALE, 1000.0);
+    }
 }

v2/crates/wifi-densepose-signal/src/spectrogram.rs

@@ -9,9 +9,10 @@
 
 use ndarray::Array2;
 use num_complex::Complex64;
-use rustfft::FftPlanner;
+use rustfft::{Fft, FftPlanner};
 use ruvector_attn_mincut::attn_mincut;
 use std::f64::consts::PI;
+use std::sync::Arc;
 
 /// Configuration for spectrogram generation.
 #[derive(Debug, Clone)]
@@ -87,12 +88,40 @@ pub fn compute_spectrogram(
         return Err(SpectrogramError::InvalidWindowSize);
     }
 
-    let n_frames = (signal.len() - config.window_size) / config.hop_size + 1;
-    let n_freq = config.window_size / 2 + 1;
-    let window = make_window(config.window_fn, config.window_size);
-
     let mut planner = FftPlanner::new();
     let fft = planner.plan_fft_forward(config.window_size);
+    let window = make_window(config.window_fn, config.window_size);
+    Ok(compute_spectrogram_with_plan(
+        signal,
+        sample_rate,
+        config,
+        &fft,
+        &window,
+    ))
+}
+
+/// STFT core that runs against a **pre-planned** FFT and pre-built window.
+///
+/// ADR-154 §7.4 #20: `compute_spectrogram` re-plans the FFT on every call, so
+/// `compute_multi_subcarrier_spectrogram` (which calls it once per subcarrier)
+/// re-planned the same length-`window_size` FFT for *every* subcarrier. This
+/// helper hoists the plan + window out of the per-subcarrier loop. The numeric
+/// body is byte-for-byte the old loop — only the plan/window construction is
+/// lifted — so the output is **bit-identical** to the per-call path (asserted by
+/// `multi_subcarrier_hoisted_plan_bit_identical`). Callers must pass a plan
+/// built for exactly `config.window_size` and a window of that length.
+fn compute_spectrogram_with_plan(
+    signal: &[f64],
+    sample_rate: f64,
+    config: &SpectrogramConfig,
+    fft: &Arc<dyn Fft<f64>>,
+    window: &[f64],
+) -> Spectrogram {
+    debug_assert_eq!(window.len(), config.window_size, "window/plan size mismatch");
+    debug_assert_eq!(fft.len(), config.window_size, "FFT/window size mismatch");
+
+    let n_frames = (signal.len() - config.window_size) / config.hop_size + 1;
+    let n_freq = config.window_size / 2 + 1;
 
     let mut data = Array2::zeros((n_freq, n_frames));
 
@@ -116,13 +145,13 @@ pub fn compute_spectrogram(
         }
     }
 
-    Ok(Spectrogram {
+    Spectrogram {
         data,
         n_freq,
         n_time: n_frames,
         freq_resolution: sample_rate / config.window_size as f64,
         time_resolution: config.hop_size as f64 / sample_rate,
-    })
+    }
 }
 
 /// Compute spectrogram for each subcarrier from a temporal CSI matrix.
@@ -134,12 +163,40 @@ pub fn compute_multi_subcarrier_spectrogram(
     sample_rate: f64,
     config: &SpectrogramConfig,
 ) -> Result<Vec<Spectrogram>, SpectrogramError> {
-    let (_, n_sc) = csi_temporal.dim();
-    let mut spectrograms = Vec::with_capacity(n_sc);
+    let (n_samples, n_sc) = csi_temporal.dim();
 
+    // ADR-154 §7.4 #20: validate *once* (same checks `compute_spectrogram`
+    // makes), then plan the FFT + build the window *once* and reuse them across
+    // every subcarrier instead of re-planning per column. The window length is
+    // identical for all subcarriers, so this is pure hoisting — output stays
+    // bit-identical to the per-call path.
+    if n_samples < config.window_size {
+        return Err(SpectrogramError::SignalTooShort {
+            signal_len: n_samples,
+            window_size: config.window_size,
+        });
+    }
+    if config.hop_size == 0 {
+        return Err(SpectrogramError::InvalidHopSize);
+    }
+    if config.window_size == 0 {
+        return Err(SpectrogramError::InvalidWindowSize);
+    }
+
+    let mut planner = FftPlanner::new();
+    let fft = planner.plan_fft_forward(config.window_size);
+    let window = make_window(config.window_fn, config.window_size);
+
+    let mut spectrograms = Vec::with_capacity(n_sc);
     for sc in 0..n_sc {
         let col: Vec<f64> = csi_temporal.column(sc).to_vec();
-        spectrograms.push(compute_spectrogram(&col, sample_rate, config)?);
+        spectrograms.push(compute_spectrogram_with_plan(
+            &col,
+            sample_rate,
+            config,
+            &fft,
+            &window,
+        ));
     }
 
     Ok(spectrograms)
@@ -372,6 +429,67 @@ mod tests {
             assert_eq!(spec.n_freq, 65);
         }
     }
+
+    // ADR-154 §7.4 #20: the FFT-planner hoist in
+    // `compute_multi_subcarrier_spectrogram` must produce **bit-identical**
+    // output to calling `compute_spectrogram` (fresh planner) per subcarrier.
+    // We compare `f64::to_bits` of every spectrogram value across several
+    // window functions and a realistic 56-subcarrier CSI matrix — the planner
+    // change only reorders *when* the (identical) plan is built, never the math.
+    #[test]
+    fn multi_subcarrier_hoisted_plan_bit_identical() {
+        let n_samples = 600;
+        let n_sc = 56; // canonical-56 grid — the production subcarrier count
+        let sample_rate = 100.0;
+        let csi = Array2::from_shape_fn((n_samples, n_sc), |(t, sc)| {
+            // Deterministic, non-trivial per-subcarrier content.
+            let freq = 0.7 + sc as f64 * 0.13;
+            (2.0 * PI * freq * t as f64 / sample_rate).sin()
+                + 0.3 * (2.0 * PI * (freq * 2.1) * t as f64 / sample_rate).cos()
+        });
+
+        for window_fn in [
+            WindowFunction::Hann,
+            WindowFunction::Hamming,
+            WindowFunction::Blackman,
+            WindowFunction::Rectangular,
+        ] {
+            for &power in &[true, false] {
+                let config = SpectrogramConfig {
+                    window_size: 128,
+                    hop_size: 37, // non-divisor hop to exercise frame edges
+                    window_fn,
+                    power,
+                };
+
+                // AFTER: hoisted-plan path.
+                let hoisted =
+                    compute_multi_subcarrier_spectrogram(&csi, sample_rate, &config).unwrap();
+
+                // BEFORE: independent per-subcarrier fresh-planner path.
+                let reference: Vec<Spectrogram> = (0..n_sc)
+                    .map(|sc| {
+                        let col: Vec<f64> = csi.column(sc).to_vec();
+                        compute_spectrogram(&col, sample_rate, &config).unwrap()
+                    })
+                    .collect();
+
+                assert_eq!(hoisted.len(), reference.len());
+                for (sc, (h, r)) in hoisted.iter().zip(reference.iter()).enumerate() {
+                    assert_eq!(h.data.dim(), r.data.dim(), "dim sc={sc} {window_fn:?}");
+                    for (a, b) in h.data.iter().zip(r.data.iter()) {
+                        assert_eq!(
+                            a.to_bits(),
+                            b.to_bits(),
+                            "bit mismatch sc={sc} {window_fn:?} power={power}: {a} vs {b}"
+                        );
+                    }
+                    assert_eq!(h.freq_resolution.to_bits(), r.freq_resolution.to_bits());
+                    assert_eq!(h.time_resolution.to_bits(), r.time_resolution.to_bits());
+                }
+            }
+        }
+    }
 }
 
 #[cfg(test)]

v2/crates/wifi-densepose-train/src/domain.rs

@@ -10,6 +10,11 @@
 // Helper math functions
 // ---------------------------------------------------------------------------
 
+/// LayerNorm numerical-stability epsilon added under the variance square root
+/// (`(x − μ)/√(σ² + ε)`). The standard transformer default (ADR-155 M2 §8:
+/// de-magicked from a bare `1e-5`; value unchanged, no behaviour change).
+const LAYER_NORM_EPS: f32 = 1e-5;
+
 /// GELU activation (Hendrycks & Gimpel, 2016 approximation).
 pub fn gelu(x: f32) -> f32 {
     let c = (2.0_f32 / std::f32::consts::PI).sqrt();
@@ -24,7 +29,7 @@ pub fn layer_norm(x: &[f32]) -> Vec<f32> {
     }
     let mean = x.iter().sum::<f32>() / n;
     let var = x.iter().map(|v| (v - mean).powi(2)).sum::<f32>() / n;
-    let inv_std = 1.0 / (var + 1e-5_f32).sqrt();
+    let inv_std = 1.0 / (var + LAYER_NORM_EPS).sqrt();
     x.iter().map(|v| (v - mean) * inv_std).collect()
 }
 
@@ -390,6 +395,13 @@ mod tests {
         assert!(layer_norm(&[]).is_empty());
     }
 
+    /// ADR-155 M2 §8: the de-magicked LayerNorm epsilon must equal the prior
+    /// inline `1e-5` literal exactly (operating-value guard).
+    #[test]
+    fn layer_norm_eps_unchanged_from_literal() {
+        assert_eq!(LAYER_NORM_EPS, 1e-5_f32);
+    }
+
     #[test]
     fn mean_pool_simple() {
         let p = global_mean_pool(&[1.0, 2.0, 3.0, 5.0, 6.0, 7.0], 2, 3);

v2/crates/wifi-densepose-train/src/eval.rs

@@ -5,6 +5,12 @@
 
 use std::collections::HashMap;
 
+/// Smallest in-domain / few-shot MPJPE treated as positive before it divides a
+/// ratio. Below this the denominator is considered ≈0 and the ratio falls back
+/// to a sentinel (`1.0` or `INFINITY`) rather than dividing by ≈0 (ADR-155 M2
+/// §8: de-magicked from a bare `1e-10`; value unchanged, no behaviour change).
+const MIN_POSITIVE_MPJPE: f32 = 1e-10;
+
 /// Aggregated cross-domain evaluation metrics.
 #[derive(Debug, Clone)]
 pub struct CrossDomainMetrics {
@@ -79,14 +85,14 @@ impl CrossDomainEvaluator {
         } else {
             cross_dom
         };
-        let gap = if in_dom > 1e-10 {
+        let gap = if in_dom > MIN_POSITIVE_MPJPE {
             cross_dom / in_dom
-        } else if cross_dom > 1e-10 {
+        } else if cross_dom > MIN_POSITIVE_MPJPE {
             f32::INFINITY
         } else {
             1.0
         };
-        let speedup = if few_shot > 1e-10 {
+        let speedup = if few_shot > MIN_POSITIVE_MPJPE {
             cross_dom / few_shot
         } else {
             1.0
@@ -132,6 +138,43 @@ fn mean_of(v: Option<&Vec<f32>>) -> f32 {
 mod tests {
     use super::*;
 
+    /// ADR-155 M2 §8: the de-magicked division-guard floor must equal the prior
+    /// inline `1e-10` literal exactly (operating-value guard).
+    #[test]
+    fn eval_min_positive_mpjpe_unchanged_from_literal() {
+        assert_eq!(MIN_POSITIVE_MPJPE, 1e-10_f32);
+    }
+
+    /// Characterize the `in_dom ≈ 0` boundary: a perfect in-domain fit but
+    /// nonzero cross-domain error yields the `INFINITY` gap sentinel (the
+    /// middle branch), not a divide-by-≈0 NaN.
+    #[test]
+    fn domain_gap_infinite_when_in_domain_perfect_but_cross_nonzero() {
+        let ev = CrossDomainEvaluator::new(1);
+        let preds = vec![
+            (vec![1.0, 2.0, 3.0], vec![1.0, 2.0, 3.0]), // dom 0: err 0
+            (vec![0.0, 0.0, 0.0], vec![2.0, 0.0, 0.0]), // dom 1: err 2
+        ];
+        let m = ev.evaluate(&preds, &[0, 1]);
+        assert!((m.in_domain_mpjpe).abs() < MIN_POSITIVE_MPJPE);
+        assert!(m.domain_gap_ratio.is_infinite());
+    }
+
+    /// Characterize the all-perfect boundary: in-domain AND cross-domain both ≈0
+    /// ⇒ gap falls back to the `1.0` sentinel (the final else branch), never NaN.
+    #[test]
+    fn domain_gap_unity_when_everything_perfect() {
+        let ev = CrossDomainEvaluator::new(1);
+        let preds = vec![
+            (vec![1.0, 2.0, 3.0], vec![1.0, 2.0, 3.0]),
+            (vec![4.0, 5.0, 6.0], vec![4.0, 5.0, 6.0]),
+        ];
+        let m = ev.evaluate(&preds, &[0, 1]);
+        assert!((m.domain_gap_ratio - 1.0).abs() < 1e-6);
+        // few_shot derived = (0+0)/2 = 0 ⇒ speedup also falls back to 1.0.
+        assert!((m.adaptation_speedup - 1.0).abs() < 1e-6);
+    }
+
     #[test]
     fn mpjpe_known_value() {
         assert!((mpjpe(&[0.0, 0.0, 0.0], &[3.0, 4.0, 0.0], 1) - 5.0).abs() < 1e-6);

v2/crates/wifi-densepose-train/src/geometry.rs

@@ -166,6 +166,13 @@ impl DeepSets {
     }
 
     /// Encode a set of embeddings (each of length `geometry_dim`) into one vector.
+    ///
+    /// # Panics
+    ///
+    /// Panics if `ap_embeddings` is empty — a permutation-invariant mean-pool
+    /// over zero elements is undefined. Callers with optional AP sets must guard
+    /// for the empty case before calling (no behaviour change; documents the
+    /// existing `assert!`).
     pub fn encode(&self, ap_embeddings: &[Vec<f32>]) -> Vec<f32> {
         assert!(
             !ap_embeddings.is_empty(),

v2/crates/wifi-densepose-train/src/metrics_core.rs

@@ -72,6 +72,28 @@ pub const CANON_LEFT_HIP: usize = 11;
 /// COCO joint index of the right hip.
 pub const CANON_RIGHT_HIP: usize = 12;
 
+// --- Tuning constants (ADR-155 M2 §8: de-magicked from bare literals; values
+// are bit-identical to the prior inline literals — documentation only, no
+// behaviour change). ---
+
+/// Visibility cutoff: a keypoint counts as *visible* iff `visibility[j] >= 0.5`.
+///
+/// This is the COCO convention (visibility flag 2 = "labelled and visible";
+/// any soft confidence ≥ 0.5 is treated as present). Used identically in
+/// [`bounding_box_diagonal`], [`canonical_torso_size`], [`pck_canonical`] and
+/// [`oks_canonical`].
+const VISIBILITY_THRESHOLD: f32 = 0.5;
+
+/// Minimum positive extent for a usable reference scale (torso width or bbox
+/// diagonal). Below this the sample has no measurable evidence and is reported
+/// as unscoreable (PCK `(0,0,0.0)` / OKS `0.0`) rather than dividing by ≈0.
+const MIN_REFERENCE_EXTENT: f32 = 1e-6;
+
+/// Fallback per-joint OKS sigma for joint indices beyond the 17 COCO-defined
+/// keypoints (defensive: the canonical path only ever scores `j < 17`). Mid-range
+/// of the COCO sigma band — see [`COCO_KP_SIGMAS`].
+const OKS_FALLBACK_SIGMA: f32 = 0.07;
+
 /// Compute the Euclidean diagonal of the bounding box of visible keypoints.
 ///
 /// The bounding box is defined by the axis-aligned extent of all keypoints
@@ -89,7 +111,7 @@ pub(crate) fn bounding_box_diagonal(
     let mut any_visible = false;
 
     for j in 0..num_joints {
-        if visibility[j] >= 0.5 {
+        if visibility[j] >= VISIBILITY_THRESHOLD {
             let x = kp[[j, 0]];
             let y = kp[[j, 1]];
             x_min = x_min.min(x);
@@ -123,19 +145,19 @@ pub fn canonical_torso_size(gt_kpts: &Array2<f32>, visibility: &Array1<f32>) ->
     let n = gt_kpts.shape()[0].min(visibility.len());
     if CANON_LEFT_HIP < n
         && CANON_RIGHT_HIP < n
-        && visibility[CANON_LEFT_HIP] >= 0.5
-        && visibility[CANON_RIGHT_HIP] >= 0.5
+        && visibility[CANON_LEFT_HIP] >= VISIBILITY_THRESHOLD
+        && visibility[CANON_RIGHT_HIP] >= VISIBILITY_THRESHOLD
     {
         let dx = gt_kpts[[CANON_LEFT_HIP, 0]] - gt_kpts[[CANON_RIGHT_HIP, 0]];
         let dy = gt_kpts[[CANON_LEFT_HIP, 1]] - gt_kpts[[CANON_RIGHT_HIP, 1]];
         let torso = (dx * dx + dy * dy).sqrt();
-        if torso > 1e-6 {
+        if torso > MIN_REFERENCE_EXTENT {
             return Some(torso);
         }
     }
     // Fallback: bounding-box diagonal of visible keypoints.
     let diag = bounding_box_diagonal(gt_kpts, visibility, n);
-    if diag > 1e-6 {
+    if diag > MIN_REFERENCE_EXTENT {
         Some(diag)
     } else {
         None
@@ -179,7 +201,7 @@ pub fn pck_canonical(
     let mut correct = 0usize;
     let mut total = 0usize;
     for j in 0..n {
-        if visibility[j] < 0.5 {
+        if visibility[j] < VISIBILITY_THRESHOLD {
             continue;
         }
         total += 1;
@@ -229,7 +251,7 @@ pub fn oks_canonical(
     let mut num = 0.0f32;
     let mut den = 0.0f32;
     for j in 0..n {
-        if visibility[j] < 0.5 {
+        if visibility[j] < VISIBILITY_THRESHOLD {
             continue;
         }
         den += 1.0;
@@ -239,7 +261,7 @@ pub fn oks_canonical(
         let k = if j < COCO_KP_SIGMAS.len() {
             COCO_KP_SIGMAS[j]
         } else {
-            0.07
+            OKS_FALLBACK_SIGMA
         };
         num += (-d_sq / (2.0 * s_sq * k * k)).exp();
     }
@@ -249,3 +271,65 @@ pub fn oks_canonical(
         0.0
     }
 }
+
+#[cfg(test)]
+mod consts_tests {
+    use super::*;
+
+    /// ADR-155 M2 §8: the de-magicked tuning consts must equal the prior inline
+    /// literals exactly — this pins them so a future "tidy-up" cannot silently
+    /// shift the metric definition (operating-value guard).
+    #[test]
+    fn metrics_core_consts_unchanged_from_literals() {
+        assert_eq!(VISIBILITY_THRESHOLD, 0.5_f32);
+        assert_eq!(MIN_REFERENCE_EXTENT, 1e-6_f32);
+        assert_eq!(OKS_FALLBACK_SIGMA, 0.07_f32);
+        assert_eq!(CANON_LEFT_HIP, 11);
+        assert_eq!(CANON_RIGHT_HIP, 12);
+    }
+
+    /// Characterize the visibility-threshold boundary: a keypoint at exactly the
+    /// cutoff (vis == 0.5) is INCLUDED (`>=`), just below (0.499) is EXCLUDED.
+    /// Pins current `>=`-inclusive behaviour at the edge.
+    #[test]
+    fn visibility_threshold_boundary_is_inclusive() {
+        // Two GT hips give a positive torso; vary the (single) scored joint's
+        // visibility around the 0.5 cutoff and confirm it flips total in/out.
+        let gt = Array2::from_shape_vec(
+            (13, 2),
+            (0..13).flat_map(|j| [j as f32, 0.0]).collect::<Vec<_>>(),
+        )
+        .unwrap();
+        // hips at 11,12 give torso = |11-12| = 1.0 along x.
+        let pred = gt.clone();
+        let mk_vis = |v0: f32| {
+            let mut vis = Array1::<f32>::zeros(13);
+            vis[CANON_LEFT_HIP] = 1.0;
+            vis[CANON_RIGHT_HIP] = 1.0;
+            vis[0] = v0; // joint 0 is the one we toggle
+            vis
+        };
+        // At exactly 0.5 → joint 0 is counted (total includes it: 3 visible).
+        let (_, total_at, _) = pck_canonical(&pred, &gt, &mk_vis(0.5), 0.2);
+        assert_eq!(total_at, 3, "vis == 0.5 must be INCLUDED (>=)");
+        // Just below → joint 0 excluded (only the 2 hips visible).
+        let (_, total_below, _) = pck_canonical(&pred, &gt, &mk_vis(0.499), 0.2);
+        assert_eq!(total_below, 2, "vis < 0.5 must be EXCLUDED");
+    }
+
+    /// Characterize the reference-extent floor: a near-zero-extent GT pose (all
+    /// keypoints coincident, hips coincident) is UNSCOREABLE → `(0,0,0.0)`,
+    /// never a trivial perfect score. Pins the `MIN_REFERENCE_EXTENT` guard.
+    #[test]
+    fn degenerate_extent_below_floor_is_unscoreable() {
+        // All 13 joints at the same point ⇒ torso ≈ 0, bbox diag ≈ 0 < 1e-6.
+        let gt = Array2::<f32>::zeros((13, 2));
+        let pred = gt.clone();
+        let mut vis = Array1::<f32>::zeros(13);
+        vis[CANON_LEFT_HIP] = 1.0;
+        vis[CANON_RIGHT_HIP] = 1.0;
+        assert!(canonical_torso_size(&gt, &vis).is_none());
+        assert_eq!(pck_canonical(&pred, &gt, &vis, 0.2), (0, 0, 0.0));
+        assert_eq!(oks_canonical(&pred, &gt, &vis), 0.0);
+    }
+}

v2/crates/wifi-densepose-train/src/rapid_adapt.rs

@@ -11,8 +11,9 @@
 //! by the code. That placeholder is gone. The two `*_loss` functions are now
 //! pure evaluators of the real objective, and [`RapidAdaptation::adapt`]
 //! descends them with a **finite-difference gradient** of that exact loss.
-//! Finite differences genuinely minimize the stated objective (to O(ε)
-//! truncation), so "the adaptation loss decreases" is now a real, reproducible
+//! Finite differences genuinely minimize the stated objective (central
+//! differences are accurate to O(ε²) truncation; see [`RapidAdaptation::adapt`]),
+//! so "the adaptation loss decreases" is now a real, reproducible
 //! measurement rather than an artefact of a hand-tuned fake step.
 //!
 //! **Scope caveat (still honest):** this minimizes a *self-supervised proxy*

v2/crates/wifi-densepose-train/src/ruview_metrics.rs

@@ -108,6 +108,31 @@ const COCO_SIGMAS: [f32; 17] = [
 /// left_hip, right_hip.
 const TORSO_INDICES: [usize; 4] = [5, 6, 11, 12];
 
+// --- Tuning constants (ADR-155 M2 §8: de-magicked from bare literals; values
+// bit-identical to the prior inline literals — documentation only, no behaviour
+// change). ---
+
+/// Number of COCO body keypoints. Loops over keypoints are bounded by this so
+/// short/adversarial inputs cannot panic (ADR-155 §Tier-2).
+const NUM_KEYPOINTS: usize = 17;
+
+/// Visibility cutoff: a keypoint is *visible* iff `visibility[j] >= 0.5`
+/// (COCO convention; matches [`crate::metrics_core`]).
+const VISIBILITY_THRESHOLD: f32 = 0.5;
+
+/// PCK acceptance ratio: a keypoint is correct iff its error ≤ `0.2 · bbox_diag`
+/// (the ADR-152 / WiFlow-STD PCK@0.2 convention).
+const PCK_THRESHOLD: f32 = 0.2;
+
+/// Floor on the GT bounding-box diagonal used as the OKS/PCK reference scale.
+/// Guards the `dist_thr = ratio · diag` and OKS `s` against a degenerate
+/// (≈0-extent) pose producing a divide-by-≈0 (Inf/NaN) score.
+const MIN_BBOX_DIAG: f32 = 1e-3;
+
+/// Floor on a tracking-sequence duration (minutes) before it divides the
+/// false-track count, so a zero-length window cannot yield `Inf` per-minute.
+const MIN_DURATION_MINUTES: f32 = 1e-6;
+
 /// Evaluate Metric 1: Joint Error.
 ///
 /// # Arguments
@@ -141,21 +166,21 @@ pub fn evaluate_joint_error(
     }
 
     // PCK@0.2 computation.
-    let pck_threshold = 0.2;
+    let pck_threshold = PCK_THRESHOLD;
     let mut all_correct = 0_usize;
     let mut all_total = 0_usize;
     let mut torso_correct = 0_usize;
     let mut torso_total = 0_usize;
     let mut oks_sum = 0.0_f64;
-    let mut per_kp_errors: Vec<Vec<f32>> = vec![Vec::new(); 17];
+    let mut per_kp_errors: Vec<Vec<f32>> = vec![Vec::new(); NUM_KEYPOINTS];
 
     for i in 0..n {
         let bbox_diag = compute_bbox_diag(&gt_kpts[i], &visibility[i]);
-        let safe_diag = bbox_diag.max(1e-3);
+        let safe_diag = bbox_diag.max(MIN_BBOX_DIAG);
         let dist_thr = pck_threshold * safe_diag;
 
         for (j, kp_errors) in per_kp_errors.iter_mut().enumerate() {
-            if visibility[i][j] < 0.5 {
+            if visibility[i][j] < VISIBILITY_THRESHOLD {
                 continue;
             }
             let dx = pred_kpts[i][[j, 0]] - gt_kpts[i][[j, 0]];
@@ -378,7 +403,7 @@ pub fn evaluate_tracking(
     };
 
     // False tracks per minute.
-    let safe_duration = duration_minutes.max(1e-6);
+    let safe_duration = duration_minutes.max(MIN_DURATION_MINUTES);
     let false_tracks_per_min = total_false_positives as f32 / safe_duration;
 
     // MOTA = 1 - (misses + false_positives + id_switches) / total_gt
@@ -612,8 +637,8 @@ fn compute_bbox_diag(kp: &Array2<f32>, vis: &Array1<f32>) -> f32 {
     let mut y_max = f32::MIN;
     let mut any = false;
 
-    for j in 0..17.min(kp.shape()[0]) {
-        if vis[j] >= 0.5 {
+    for j in 0..NUM_KEYPOINTS.min(kp.shape()[0]) {
+        if vis[j] >= VISIBILITY_THRESHOLD {
             let x = kp[[j, 0]];
             let y = kp[[j, 1]];
             x_min = x_min.min(x);
@@ -640,11 +665,11 @@ fn compute_single_oks(pred: &Array2<f32>, gt: &Array2<f32>, vis: &Array1<f32>, s
     let s_sq = s * s;
     // ADR-155 §Tier-2: bound the loop to the actual array extents so adversarial
     // / short inputs (< 17 rows, mismatched vis length) cannot panic on `[j]`.
-    let n = pred.shape()[0].min(gt.shape()[0]).min(vis.len()).min(17);
+    let n = pred.shape()[0].min(gt.shape()[0]).min(vis.len()).min(NUM_KEYPOINTS);
     let mut num = 0.0_f32;
     let mut den = 0.0_f32;
     for j in 0..n {
-        if vis[j] < 0.5 {
+        if vis[j] < VISIBILITY_THRESHOLD {
             continue;
         }
         den += 1.0;
@@ -675,7 +700,7 @@ fn compute_torso_jitter(pred_kpts: &[Array2<f32>], visibility: &[Array1<f32>]) -
             let mut cy = 0.0_f32;
             let mut count = 0_usize;
             for &idx in &TORSO_INDICES {
-                if vis[idx] >= 0.5 {
+                if vis[idx] >= VISIBILITY_THRESHOLD {
                     cx += kp[[idx, 0]];
                     cy += kp[[idx, 1]];
                     count += 1;
@@ -730,6 +755,50 @@ mod tests {
     use super::*;
     use ndarray::{Array1, Array2};
 
+    /// ADR-155 M2 §8: the de-magicked tuning consts must equal the prior inline
+    /// literals exactly (operating-value guard against a future silent shift).
+    #[test]
+    fn ruview_metrics_consts_unchanged_from_literals() {
+        assert_eq!(NUM_KEYPOINTS, 17);
+        assert_eq!(VISIBILITY_THRESHOLD, 0.5_f32);
+        assert_eq!(PCK_THRESHOLD, 0.2_f32);
+        assert_eq!(MIN_BBOX_DIAG, 1e-3_f32);
+        assert_eq!(MIN_DURATION_MINUTES, 1e-6_f32);
+    }
+
+    /// Characterize `evaluate_tracking`'s duration floor: a zero-minute window
+    /// must NOT produce an Inf per-minute false-track rate — it divides by the
+    /// `MIN_DURATION_MINUTES` floor instead. Pins the guard.
+    #[test]
+    fn tracking_zero_duration_does_not_divide_by_zero() {
+        let frames = vec![TrackingFrame {
+            frame_idx: 0,
+            gt_ids: vec![1],
+            pred_ids: vec![1, 2], // one extra ⇒ a false positive track
+            assignments: vec![(1, 1)],
+        }];
+        let r = evaluate_tracking(&frames, 0.0, &TrackingThresholds::default());
+        assert!(
+            r.false_tracks_per_min.is_finite(),
+            "zero duration must not yield Inf false-tracks/min: {}",
+            r.false_tracks_per_min
+        );
+    }
+
+    /// Characterize `compute_single_oks`'s short-array bound at exactly the
+    /// `NUM_KEYPOINTS` edge and just below: fewer than 17 rows must score the
+    /// available joints without panicking on `[j]`.
+    #[test]
+    fn oks_short_array_is_bounded_at_keypoint_count() {
+        // 16 rows (one below NUM_KEYPOINTS): must not panic, finite result.
+        let pred = Array2::<f32>::zeros((16, 2));
+        let gt = Array2::<f32>::zeros((16, 2));
+        let mut vis = Array1::<f32>::ones(16);
+        vis[0] = 1.0;
+        let oks = compute_single_oks(&pred, &gt, &vis, 1.0);
+        assert!(oks.is_finite());
+    }
+
     fn make_perfect_kpts() -> (Array2<f32>, Array2<f32>, Array1<f32>) {
         let kp = Array2::from_shape_fn((17, 2), |(j, d)| {
             if d == 0 {

v2/crates/wifi-densepose-train/src/subcarrier.rs

@@ -20,6 +20,34 @@ use ndarray::{s, Array4};
 use ruvector_solver::neumann::NeumannSolver;
 use ruvector_solver::types::CsrMatrix;
 
+// --- Sparse-interpolation tuning constants (ADR-155 M2 §8: de-magicked from
+// bare literals in `interpolate_subcarriers_sparse`; values bit-identical to the
+// prior inline literals — documentation only, no behaviour change). ---
+
+/// Gaussian-basis width (in the normalised `[0,1]` subcarrier position space)
+/// for the sparse-interpolation kernel `exp(-Δ²/σ²)`. Wider σ ⇒ smoother fit.
+const SPARSE_BASIS_SIGMA: f32 = 0.15;
+
+/// Sparsity cutoff: basis entries below this magnitude are dropped from the
+/// normal-equations assembly, keeping `AᵀA` sparse.
+const SPARSE_BASIS_THRESHOLD: f32 = 1e-4;
+
+/// Tikhonov regularisation strength `λ` added to the `AᵀA` diagonal for
+/// numerical stability of the (possibly ill-conditioned) normal equations.
+const SPARSE_REGULARIZATION_LAMBDA: f32 = 0.1;
+
+/// Magnitude below which an assembled `AᵀA` entry is treated as structurally
+/// zero and omitted from the COO triplet list.
+const SPARSE_COO_PRUNE_EPS: f32 = 1e-8;
+
+/// Convergence tolerance for the Neumann-series sparse solver (`f64` to match
+/// [`NeumannSolver::new`]).
+const SPARSE_SOLVER_TOL: f64 = 1e-5;
+
+/// Maximum Neumann-series iterations before the solver returns (falls back to
+/// linear interpolation on non-convergence).
+const SPARSE_SOLVER_MAX_ITERS: usize = 500;
+
 // ---------------------------------------------------------------------------
 // interpolate_subcarriers
 // ---------------------------------------------------------------------------
@@ -167,7 +195,7 @@ pub fn interpolate_subcarriers_sparse(arr: &Array4<f32>, target_sc: usize) -> Ar
 
     // Build the Gaussian basis matrix A: [src_sc, target_sc]
     // A[j, k] = exp(-((j/(n_sc-1) - k/(target_sc-1))^2) / sigma^2)
-    let sigma = 0.15_f32;
+    let sigma = SPARSE_BASIS_SIGMA;
     let sigma_sq = sigma * sigma;
 
     // Source and target normalized positions in [0, 1]
@@ -191,12 +219,12 @@ pub fn interpolate_subcarriers_sparse(arr: &Array4<f32>, target_sc: usize) -> Ar
         .collect();
 
     // Only include entries above a sparsity threshold
-    let threshold = 1e-4_f32;
+    let threshold = SPARSE_BASIS_THRESHOLD;
 
     // Build A^T A + λI regularized system for normal equations
     // We solve: (A^T A + λI) x = A^T b
     // A^T A is [target_sc × target_sc]
-    let lambda = 0.1_f32; // regularization
+    let lambda = SPARSE_REGULARIZATION_LAMBDA;
     let mut ata_coo: Vec<(usize, usize, f32)> = Vec::new();
 
     // Compute A^T A
@@ -226,7 +254,7 @@ pub fn interpolate_subcarriers_sparse(arr: &Array4<f32>, target_sc: usize) -> Ar
     for (k, row) in ata.iter().enumerate() {
         for (k2, &cell) in row.iter().enumerate() {
             let val = cell + if k == k2 { lambda } else { 0.0 };
-            if val.abs() > 1e-8 {
+            if val.abs() > SPARSE_COO_PRUNE_EPS {
                 ata_coo.push((k, k2, val));
             }
         }
@@ -234,7 +262,7 @@ pub fn interpolate_subcarriers_sparse(arr: &Array4<f32>, target_sc: usize) -> Ar
 
     // Build CsrMatrix for the normal equations system (A^T A + λI)
     let normal_matrix = CsrMatrix::<f32>::from_coo(target_sc, target_sc, ata_coo);
-    let solver = NeumannSolver::new(1e-5, 500);
+    let solver = NeumannSolver::new(SPARSE_SOLVER_TOL, SPARSE_SOLVER_MAX_ITERS);
 
     let mut out = Array4::<f32>::zeros((n_t, n_tx, n_rx, target_sc));
 
@@ -350,6 +378,42 @@ mod tests {
     use super::*;
     use approx::assert_abs_diff_eq;
 
+    /// ADR-155 M2 §8: the de-magicked sparse-interpolation consts must equal the
+    /// prior inline literals exactly (operating-value guard).
+    #[test]
+    fn sparse_interp_consts_unchanged_from_literals() {
+        assert_eq!(SPARSE_BASIS_SIGMA, 0.15_f32);
+        assert_eq!(SPARSE_BASIS_THRESHOLD, 1e-4_f32);
+        assert_eq!(SPARSE_REGULARIZATION_LAMBDA, 0.1_f32);
+        assert_eq!(SPARSE_COO_PRUNE_EPS, 1e-8_f32);
+        assert_eq!(SPARSE_SOLVER_TOL, 1e-5_f64);
+        assert_eq!(SPARSE_SOLVER_MAX_ITERS, 500);
+    }
+
+    /// Characterize the `target_sc == 1` boundary of `compute_interp_weights`:
+    /// the single output maps to source index 0 with zero fraction (the special
+    /// branch that avoids dividing by `target_sc - 1 == 0`).
+    #[test]
+    fn compute_interp_weights_single_target_is_index_zero() {
+        let w = compute_interp_weights(7, 1);
+        assert_eq!(w.len(), 1);
+        let (i0, i1, frac) = w[0];
+        assert_eq!(i0, 0);
+        assert_eq!(i1, 0);
+        assert_abs_diff_eq!(frac, 0.0_f32, epsilon = 1e-6);
+    }
+
+    /// Characterize sparse interpolation to a single subcarrier: must produce
+    /// the right shape and a finite value (exercises the `target_sc == 1`
+    /// normalized-position branch).
+    #[test]
+    fn sparse_interp_single_target_is_finite() {
+        let arr = Array4::<f32>::from_shape_fn((2, 1, 1, 8), |(_, _, _, k)| k as f32);
+        let out = interpolate_subcarriers_sparse(&arr, 1);
+        assert_eq!(out.shape(), &[2, 1, 1, 1]);
+        assert!(out.iter().all(|v| v.is_finite()));
+    }
+
     #[test]
     fn identity_resample() {
         let arr =

v2/crates/wifi-densepose-train/src/virtual_aug.rs

@@ -17,6 +17,15 @@
 
 use std::f32::consts::PI;
 
+/// Floor on the Box-Muller `u1` sample so `ln(u1)` stays finite when the PRNG
+/// returns ≈0 (ADR-155 M2 §8: de-magicked from a bare `1e-10`; value unchanged).
+const BOX_MULLER_U1_FLOOR: f32 = 1e-10;
+
+/// Magnitude below which `room_scale` is treated as zero and the amplitude
+/// division is skipped (guards `val / room_scale` against ÷≈0). De-magicked from
+/// a bare `1e-10`; value unchanged, no behaviour change.
+const MIN_ROOM_SCALE: f32 = 1e-10;
+
 // ---------------------------------------------------------------------------
 // Xorshift64 PRNG (matches dataset.rs pattern)
 // ---------------------------------------------------------------------------
@@ -67,7 +76,7 @@ impl Xorshift64 {
     /// Sample an approximate Gaussian (mean=0, std=1) via Box-Muller.
     #[inline]
     pub fn next_gaussian(&mut self) -> f32 {
-        let u1 = self.next_f32().max(1e-10);
+        let u1 = self.next_f32().max(BOX_MULLER_U1_FLOOR);
         let u2 = self.next_f32();
         (-2.0 * u1.ln()).sqrt() * (2.0 * PI * u2).cos()
     }
@@ -158,7 +167,7 @@ impl VirtualDomainAugmentor {
         for (k, &val) in frame.iter().enumerate() {
             let k_f = k as f32;
             // 1. Room-scale amplitude attenuation (guard against zero scale)
-            let scaled = if domain.room_scale.abs() < 1e-10 {
+            let scaled = if domain.room_scale.abs() < MIN_ROOM_SCALE {
                 val
             } else {
                 val / domain.room_scale
@@ -207,6 +216,42 @@ impl VirtualDomainAugmentor {
 mod tests {
     use super::*;
 
+    /// ADR-155 M2 §8: the de-magicked guard epsilons must equal the prior inline
+    /// `1e-10` literals exactly (operating-value guard).
+    #[test]
+    fn virtual_aug_guard_consts_unchanged_from_literals() {
+        assert_eq!(BOX_MULLER_U1_FLOOR, 1e-10_f32);
+        assert_eq!(MIN_ROOM_SCALE, 1e-10_f32);
+    }
+
+    /// Characterize the zero-room-scale guard: a `room_scale` of exactly 0 must
+    /// pass amplitude through unscaled (the guard branch), never produce
+    /// Inf/NaN from `val / 0`.
+    #[test]
+    fn augment_frame_zero_room_scale_passes_amplitude_finite() {
+        let aug = VirtualDomainAugmentor::default();
+        let domain = VirtualDomain {
+            room_scale: 0.0,
+            // reflection_coeff = 1.0 ⇒ refl = 1.0 + (1-1)·cos(..) = 1.0 (constant,
+            // so the reflection step is the identity for this characterization).
+            reflection_coeff: 1.0,
+            n_scatterers: 0, // no scatterer interference
+            noise_std: 0.0,  // no additive noise
+            domain_id: 1,
+        };
+        let frame = vec![1.0_f32, 2.0, 3.0, 4.0];
+        let out = aug.augment_frame(&frame, &domain);
+        assert_eq!(out.len(), frame.len());
+        assert!(
+            out.iter().all(|v| v.is_finite()),
+            "zero room_scale must not yield Inf/NaN: {out:?}"
+        );
+        // With every other transform neutralised, the guard leaves amplitude as-is.
+        for (o, f) in out.iter().zip(frame.iter()) {
+            assert!((o - f).abs() < 1e-6, "expected pass-through, got {o} vs {f}");
+        }
+    }
+
     fn make_domain(scale: f32, coeff: f32, scatter: usize, noise: f32, id: u32) -> VirtualDomain {
         VirtualDomain {
             room_scale: scale,

v2/crates/wifi-densepose-wifiscan/src/adapter/wlanapi_scanner.rs

@@ -309,6 +309,61 @@ impl WlanApiScanner {
         })
     }
 
+    /// Measure the **real** achieved rate of a *specific* backend over a
+    /// fixed wall-clock `window`, for an honest native-vs-netsh comparison.
+    ///
+    /// Unlike [`benchmark`](Self::benchmark) (which picks native-first and so
+    /// never exercises netsh on a box where native works), this runs back-to-
+    /// back scans on **exactly** the requested backend until `window` elapses,
+    /// then reports the measured scans/second and mean BSSIDs/scan. This is the
+    /// ADR-157 §5 #4 measurement primitive: drive it once per backend over the
+    /// same window and compare the two `rate_hz` values — no rate is assumed.
+    ///
+    /// Returns `None` for [`ScanBackend::Native`] when the native path is
+    /// unavailable (non-Windows or WLAN service error), so a caller can report
+    /// the honest negative rather than a fabricated number.
+    ///
+    /// # Errors
+    ///
+    /// Propagates the first scan error from the chosen backend.
+    pub fn benchmark_backend(
+        &self,
+        backend: ScanBackend,
+        window: Duration,
+    ) -> Result<Option<BenchmarkResult>, WifiScanError> {
+        // Probe native availability first so an unavailable native path is an
+        // honest `None`, not an error charged against the comparison.
+        if backend == ScanBackend::Native && wlanapi_native::scan_native().is_err() {
+            return Ok(None);
+        }
+
+        let start = Instant::now();
+        let mut iterations: u32 = 0;
+        let mut total_bssids: u64 = 0;
+        while start.elapsed() < window {
+            let list = match backend {
+                ScanBackend::Native => wlanapi_native::scan_native()?,
+                ScanBackend::Netsh => self.inner.scan_sync()?,
+            };
+            total_bssids += list.len() as u64;
+            iterations += 1;
+        }
+        let total = start.elapsed();
+        let secs = total.as_secs_f64().max(f64::MIN_POSITIVE);
+
+        Ok(Some(BenchmarkResult {
+            iterations,
+            total,
+            rate_hz: f64::from(iterations) / secs,
+            mean_bssids: if iterations == 0 {
+                0.0
+            } else {
+                total_bssids as f64 / f64::from(iterations)
+            },
+            backend,
+        }))
+    }
+
     /// Perform an async scan by offloading the blocking call to a
     /// background thread (native-first, netsh fallback inside the task).
     ///
@@ -560,4 +615,76 @@ mod tests {
         );
         assert!(bench.rate_hz > 0.0);
     }
+
+    /// ADR-157 §5 #4 honest native-vs-netsh throughput comparison. `#[ignore]`
+    /// (live WLAN, ~20 s). Run with:
+    /// `cargo test -p wifi-densepose-wifiscan -- --ignored --nocapture
+    /// measure_native_vs_netsh_throughput`. Drives BOTH backends over the same
+    /// fixed wall-clock window and prints the measured Hz + BSSIDs/scan for
+    /// each, plus the ratio — the real number, whatever it is (a null/negative
+    /// result is a valid outcome and must be reported, not hidden).
+    #[cfg(windows)]
+    #[test]
+    #[ignore = "live WLAN native-vs-netsh comparison; run with --ignored --nocapture"]
+    fn measure_native_vs_netsh_throughput() {
+        let scanner = WlanApiScanner::new();
+        let window = Duration::from_secs(10);
+
+        let native = scanner
+            .benchmark_backend(ScanBackend::Native, window)
+            .expect("native benchmark must not error");
+        let netsh = scanner
+            .benchmark_backend(ScanBackend::Netsh, window)
+            .expect("netsh benchmark must not error")
+            .expect("netsh is always available on Windows");
+
+        match native {
+            Some(n) => {
+                println!(
+                    "NATIVE: {:.2} Hz ({} scans / {:?}), mean {:.1} BSSIDs/scan",
+                    n.rate_hz, n.iterations, n.total, n.mean_bssids
+                );
+                println!(
+                    "NETSH:  {:.2} Hz ({} scans / {:?}), mean {:.1} BSSIDs/scan",
+                    netsh.rate_hz, netsh.iterations, netsh.total, netsh.mean_bssids
+                );
+                let ratio = n.rate_hz / netsh.rate_hz.max(f64::MIN_POSITIVE);
+                println!("RATIO native/netsh: {ratio:.2}x");
+                assert!(n.rate_hz > 0.0 && netsh.rate_hz > 0.0);
+            }
+            None => {
+                println!(
+                    "NATIVE: unavailable on this box (WLAN service error). \
+                     NETSH: {:.2} Hz, mean {:.1} BSSIDs/scan",
+                    netsh.rate_hz, netsh.mean_bssids
+                );
+            }
+        }
+    }
+
+    /// Determinism + handle-cleanup pin: N back-to-back native scans must all
+    /// succeed (or all be the same typed error) with no resource exhaustion —
+    /// a `WlanOpenHandle`/`WlanCloseHandle` leak would, after enough calls,
+    /// surface as a `ScanFailed`. Running 50 iterations here exercises the
+    /// open→enum→getlist→free→close cycle repeatedly. `#[ignore]` for CI (live
+    /// WLAN service) but RUN on this box to verify no leak.
+    #[cfg(windows)]
+    #[test]
+    #[ignore = "live WLAN handle-cleanup check; run with --ignored --nocapture"]
+    fn native_scans_dont_leak_handles() {
+        let scanner = WlanApiScanner::new();
+        let mut ok = 0u32;
+        let mut failed = 0u32;
+        for _ in 0..50 {
+            match scanner.scan_native() {
+                Ok(_) => ok += 1,
+                Err(WifiScanError::ScanFailed { .. }) => failed += 1,
+                Err(e) => panic!("unexpected error during leak check: {e:?}"),
+            }
+        }
+        println!("native leak check: {ok} ok, {failed} scan-failed of 50");
+        // No leak ⇒ behavior is consistent across all 50 calls (all ok, or all
+        // the same WLAN-service-off failure) — not a degrade partway through.
+        assert!(ok == 50 || failed == 50, "inconsistent results suggest a leak: {ok} ok / {failed} failed");
+    }
 }