feat(adr-260): RuField MFS spec + vendor/rufield submodule (#1061)

ADR-260 (Accepted — v0.1 reference stack): RuField, the open specification
for camera-free multimodal field sensing — one FieldEvent/FieldTensor/
FusionGraph/PrivacyClass/ProvenanceReceipt model above WiFi CSI/CIR/BFLD,
UWB, BLE Channel Sounding, mmWave radar, ultrasound, subsonic, infrared,
and quantum sensors.

Published standalone as github.com/ruvnet/rufield and vendored here as the
vendor/rufield submodule (the vendor/rvcsi pattern — not a v2/ workspace
member). v0.1 reference stack: 6 crates, 60 tests/0 failed, clippy-clean.
All benchmark metrics SYNTHETIC (simulator ground truth, no hardware).

Co-authored-by: ruv <ruvnet@gmail.com>

.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/
 

.gitmodules

@@ -18,3 +18,6 @@
 	path = v2/crates/ruv-neural
 	url = https://github.com/ruvnet/ruv-neural.git
 	branch = main
+[submodule "vendor/rufield"]
+	path = vendor/rufield
+	url = https://github.com/ruvnet/rufield

CHANGELOG.md

@@ -7,6 +7,9 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+### Added
+- **ADR-260: RuField MFS — the open specification for camera-free multimodal field sensing.** A common event / tensor / calibration / privacy / provenance model that sits *above* WiFi CSI/CIR/BFLD, UWB, BLE Channel Sounding, mmWave radar, ultrasound, subsonic, infrared, and future quantum sensors (each modality emits a normalized `FieldEvent` → `FieldTensor` → `FusionGraph` → `PrivacyClass` → `ProvenanceReceipt`). Published as a **standalone repo** [`ruvnet/rufield`](https://github.com/ruvnet/rufield) and vendored here as the `vendor/rufield` submodule (the `vendor/rvcsi` pattern — not a `v2/` workspace member). The v0.1 reference stack is a self-contained 6-crate Rust workspace (`rufield-core`, `-provenance` [sha256 + ed25519], `-privacy` [P0–P5 guard], `-adapters` [deterministic `SyntheticSim` across wifi_csi/mmwave_radar/infrared_thermal], `-fusion` [graph + TOML weighted-Bayes rules → 7 room-state inferences], `-bench` [deterministic runner + the §31 acceptance test]). **60 tests / 0 failed, clippy-clean.** §27 acceptance criteria 1–8 and 10 PASS; the live dashboard (9) is deferred. **All benchmark metrics are SYNTHETIC** (scored against the simulator's own ground truth — presence/breathing/bed_exit/room_transition F1 = 1.000, nocturnal_scratch 0.923 reported honestly, p95 latency ~0.01 ms, provenance coverage 100%, 0 privacy violations) — they prove the pipeline recovers known truth, **not** field accuracy; real hardware adapters (ESP32 CSI, mmWave, thermal IR) are a documented roadmap item, none validated in v0.1. The Python deterministic proof is unchanged (rufield is off the signal-processing proof path).
+
 ### 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.
@@ -15,6 +18,11 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   - **#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.
@@ -31,6 +39,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - **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.

CLAUDE.md

@@ -22,6 +22,7 @@ Dual codebase: Python v1 (`v1/`) and Rust port (`v2/`).
 | `wifi-densepose-vitals` | ESP32 CSI-grade vital sign extraction (ADR-021) |
 | `nvsim` | Deterministic NV-diamond magnetometer pipeline simulator (ADR-089) — standalone leaf, WASM-ready |
 | `vendor/rvcsi` (submodule) | **rvCSI** — edge RF sensing runtime (ADR-095/096): 9 crates (`rvcsi-core`/`-dsp`/`-events`/`-adapter-file`/`-adapter-nexmon`/`-ruvector`/`-runtime`/`-node`/`-cli`). Lives in its own repo ([github.com/ruvnet/rvcsi](https://github.com/ruvnet/rvcsi)), vendored here under `vendor/rvcsi`, published to crates.io as `rvcsi-* 0.3.x` and to npm as `@ruv/rvcsi`. Not a `v2/` workspace member — depend on the published crates (or the submodule's `crates/rvcsi-*` paths). Normalized `CsiFrame`/`CsiWindow`/`CsiEvent` schema, validate-before-FFI, reusable DSP, typed confidence-scored events, the napi-c Nexmon shim (real nexmon_csi `.pcap` from a Raspberry Pi 5 / 4 / 3B+ — BCM43455c0), the napi-rs SDK, the `rvcsi` CLI, a Claude Code plugin. |
+| `vendor/rufield` (submodule) | **RuField MFS** — the open spec for camera-free multimodal field sensing (ADR-260). A common `FieldEvent`/`FieldTensor`/`FusionGraph`/`PrivacyClass`/`ProvenanceReceipt` model *above* WiFi CSI/CIR/BFLD, UWB, BLE Channel Sounding, mmWave radar, ultrasound, subsonic, infrared, and quantum sensors. Lives in its own repo ([github.com/ruvnet/rufield](https://github.com/ruvnet/rufield)), vendored here under `vendor/rufield`. Not a `v2/` workspace member. v0.1 reference stack = 6 crates (`rufield-core`/`-provenance`/`-privacy`/`-adapters`/`-fusion`/`-bench`), 60 tests/0 failed; all benchmark metrics are **SYNTHETIC** (simulator ground truth, no hardware — real adapters are roadmap). |
 | `ruview-swarm` | Drone swarm control system (ADR-148) — hierarchical-mesh topology, Raft consensus, MARL, CSI sensing payload, MAVLink/PX4 compat, Ruflo AI-agent integration |
 
 ### RuvSense Modules (`signal/src/ruvsense/`)

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-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-260-rufield-mfs.md

@@ -0,0 +1,391 @@
+# ADR 260: RuField Multimodal Field Sensing Specification
+
+Status: Accepted — v0.1 reference stack
+
+Date: 2026 06 14
+
+Deciders: rUv
+
+Tags: sensing, rf, csi, cir, bfld, radar, ultrasonic, infrared, quantum sensing, privacy, provenance, ruvector, ruview
+
+## 1. Context
+
+RuView proved that commodity wireless signals can be used as a practical sensing substrate. The next opportunity is larger: define a common specification for multimodal ambient sensing across RF, ultrasonic, subsonic, infrared, radar, and future quantum sensors.
+
+Existing standards are valuable but fragmented.
+
+IEEE 802.11bf 2025 standardizes WLAN sensing at the WiFi MAC and PHY layers and was published on September 26, 2025. It is important, but it is WiFi specific.
+
+Bluetooth Channel Sounding standardizes techniques for obtaining phase and time delay information, but Bluetooth SIG explicitly does not define the distance algorithm. That leaves application level interpretation open.
+
+IEEE 802.15.4z HRP UWB supports secure ranging using scrambled timestamp sequence waveforms, but UWB remains one modality rather than a universal sensing grammar.
+
+Matter is a useful smart home interoperability protocol, but it is a device connectivity layer, not a multimodal field sensing specification.
+
+The gap is clear: there is no open specification that normalizes sensor observations across CSI, CIR, BFLD, radar, ultrasound, subsonic vibration, thermal infrared, and quantum field sensing into one privacy aware, provenance rich, fusion ready event model.
+
+## 2. Decision
+
+Create **RuField MFS**, the RuField Multimodal Field Sensing Specification.
+
+RuField MFS will define a common event, tensor, calibration, confidence, privacy, and provenance model for ambient field sensing.
+
+It will not replace IEEE 802.11bf, Bluetooth Channel Sounding, UWB, Matter, radar protocols, or device vendor APIs.
+
+It will sit above them.
+
+```text
+WiFi CSI
+WiFi CIR
+WiFi BFLD
+UWB
+Bluetooth Channel Sounding
+mmWave radar
+Ultrasonic
+Subsonic
+Infrared
+Quantum magnetic sensing
+Quantum inertial sensing
+
+all emit
+
+RuField Field Event
+RuField Field Tensor
+RuField Fusion Graph
+RuField Privacy Class
+RuField Provenance Receipt
+```
+
+## 3. Name
+
+Preferred name: `RuField MFS`
+
+Full name: `RuField Multimodal Field Sensing Specification`
+
+Public positioning: `The open specification for camera free field intelligence.`
+
+## 4. Problem Statement
+
+Modern sensing systems are locked into modality specific silos: CSI systems produce channel matrices; radar produces range Doppler bins; UWB produces range and time of flight; Bluetooth Channel Sounding produces phase and timing primitives; infrared produces thermal arrays; ultrasonic produces acoustic echoes; subsonic produces structural vibration signatures; quantum sensors produce magnetic, inertial, or optical field traces.
+
+Each has different sampling, calibration, confidence, privacy, and provenance semantics. This prevents reliable fusion and makes governance weak because raw sensing, derived sensing, biometric inference, and anonymous occupancy are often mixed without explicit boundaries.
+
+## 5. Goals
+
+1. Define a common multimodal sensing event format.
+2. Define a field tensor format spanning time, frequency, phase, amplitude, range, velocity, angle, temperature, vibration, and uncertainty.
+3. Define a modality registry for RF, acoustic, infrared, radar, and quantum sensing.
+4. Define privacy classes for raw waveforms, derived features, occupancy, anonymized aggregate state, and biometric inference.
+5. Define calibration receipts and provenance hashes.
+6. Define fusion rules for multimodal inference.
+7. Provide a Rust reference implementation.
+8. Provide benchmark tasks for camera free room intelligence.
+9. Make RuView one adapter inside a larger open sensing architecture.
+
+## 6. Non Goals
+
+1. Do not define a new wireless PHY.
+2. Do not replace IEEE 802.11bf.
+3. Do not replace Bluetooth Channel Sounding.
+4. Do not replace UWB secure ranging.
+5. Do not define medical diagnosis.
+6. Do not transmit speech, images, or raw biometric identity by default.
+7. Do not require cloud inference.
+8. Do not require expensive hardware.
+
+## 7. Core Abstraction — the Field Event
+
+A Field Event is a timestamped observation from any ambient field sensor.
+
+```json
+{
+  "spec": "rufield.mfs.v0.1",
+  "event_id": "01J00000000000000000000000",
+  "timestamp_ns": 1791986400000000000,
+  "sensor": {
+    "modality": "wifi_csi",
+    "vendor": "esp32_c6",
+    "device_id": "sensor_room_01",
+    "placement": "ceiling_corner",
+    "clock_domain": "local_ptp"
+  },
+  "field": {
+    "carrier_hz": 5805000000,
+    "bandwidth_hz": 80000000,
+    "sample_rate_hz": 100,
+    "channels": 234,
+    "features": ["amplitude", "phase", "doppler", "range_proxy"]
+  },
+  "observation": {
+    "space_cell": [4, 2, 1],
+    "range_m": 3.42,
+    "velocity_mps": 0.18,
+    "motion_vector": [0.12, -0.03, 0.00],
+    "confidence": 0.87,
+    "privacy_class": "P2"
+  },
+  "provenance": {
+    "raw_hash": "sha256:raw_measurement_hash",
+    "firmware_hash": "sha256:firmware_hash",
+    "model_id": "ruvector_field_encoder_v1",
+    "calibration_id": "room_cal_2026_06_14"
+  }
+}
+```
+
+## 8. Modality Registry
+
+| Code | Modality             | Example source                          |
+| ---: | -------------------- | --------------------------------------- |
+|    1 | wifi_csi             | ESP32 C6, Intel BE200, AP CSI           |
+|    2 | wifi_cir             | channel impulse response                |
+|    3 | wifi_bfld            | beamforming feedback                    |
+|    4 | uwb_hrp              | IEEE 802.15.4z ranging                  |
+|    5 | ble_channel_sounding | phase and timing primitives             |
+|    6 | mmwave_radar         | range Doppler radar                     |
+|    7 | ultrasonic           | echo and time of flight                 |
+|    8 | subsonic             | structural vibration and room resonance |
+|    9 | infrared_thermal     | thermal array or passive IR             |
+|   10 | active_infrared      | reflected IR                            |
+|   11 | lidar_phase          | phase based optical range               |
+|   12 | quantum_magnetic     | NV diamond or OPM field trace           |
+|   13 | quantum_inertial     | atom interferometer or precision IMU    |
+|   14 | event_camera         | optional visual event stream            |
+|   15 | synthetic_sim        | simulator or replay source              |
+
+## 9. Field Tensor
+
+The normalized numeric container (`Modality`, `FieldAxis`, `FieldTensor`) as specified in the implementation crate `rufield-core`.
+
+## 10. Privacy Classes
+
+| Class | Description                      | Example                         |
+| ----- | -------------------------------- | ------------------------------- |
+| P0    | Raw waveform or raw sensor frame | raw CSI, raw radar cube         |
+| P1    | Derived non identity features    | Doppler peak, thermal blob      |
+| P2    | Occupancy and motion only        | person present, bed exit        |
+| P3    | Anonymous aggregate state        | room count, zone activity       |
+| P4    | Biometric or health inference    | breathing, gait, sleep, scratch |
+| P5    | Identity linked inference        | named person state              |
+
+Default system policy: edge storage may retain P0 only temporarily; network transmission defaults to P2 or lower; P4 requires explicit consent; P5 requires explicit identity binding and audit log.
+
+## 11. Provenance Receipt
+
+Every event must be auditable (`ProvenanceReceipt`). Acceptance invariant: **No fused inference is valid unless every contributing event has a provenance receipt or is explicitly marked synthetic.**
+
+## 12. Fusion Graph
+
+Nodes: sensor, event, field_tensor, feature, object, zone, state, inference, receipt.
+Edges: observed_by, derived_from, calibrated_by, supports, contradicts, fused_into, expires_at, requires_consent.
+
+## 13. Fusion Rule Format
+
+Human readable TOML rules (`rule.person_present`, `rule.bed_exit`, `rule.nocturnal_scratch`) with `inputs`, `method`, `threshold`, `privacy_max`, optional `window_ms` and `requires_consent`.
+
+## 14. Reference Architecture
+
+Layer 0 physical sensors; Layer 1 native adapters; Layer 2 field tensor normalization; Layer 3 RuVector field embeddings; Layer 4 fusion graph; Layer 5 policy and privacy guard; Layer 6 application event stream; Layer 7 dashboard, API, MCP, Matter bridge.
+
+## 15. Rust Crate Layout
+
+`rufield-core`, `rufield-schema`, `rufield-adapters`, `rufield-fusion`, `rufield-privacy`, `rufield-provenance`, `rufield-bench`, `rufield-viewer`.
+
+## 16. Core Rust Interfaces
+
+`FieldAdapter`, `FieldEncoder`, `FusionEngine`, `PrivacyGuard` traits as specified in `rufield-core`.
+
+## 17. MVP Adapters
+
+v0.1 must support three real modalities: WiFi CSI, mmWave radar, Infrared thermal. Optional: ultrasonic, subsonic, synthetic simulator.
+
+## 18. Benchmark Suite
+
+| Task                    |   Metric |       Target |
+| ----------------------- | -------: | -----------: |
+| Presence detection      |       F1 |         0.90 |
+| Room transition         |       F1 |         0.85 |
+| Bed exit                |       F1 |         0.90 |
+| Breathing detected      |       F1 |         0.80 |
+| Nocturnal scratch       |       F1 |         0.75 |
+| Fall like event         |   Recall |         0.95 |
+| False alarm rate        | per hour |   below 0.10 |
+| Event latency           |      p95 | below 100 ms |
+| Provenance coverage     |  percent |          100 |
+| Privacy violation count |    count |            0 |
+
+## 19. First Viral Demo
+
+Camera free room intelligence: person enters, sits, breathing detected, sleeps, scratches arm, exits bed, leaves room — no camera, no identity, signed field receipts, live fusion graph, privacy class visible per event.
+
+## 20. Data Model
+
+`FieldEvent { spec_version, event_id, timestamp_ns, sensor, tensor, observation, provenance }` and `Observation { zone_id, space_cell, range_m, velocity_mps, motion_vector, confidence, labels, privacy_class }`.
+
+## 21. Decision Matrix
+
+| Option                                        | Interop | Novelty | Buildability | Business value | Risk | Score |
+| --------------------------------------------- | ------: | ------: | -----------: | -------------: | ---: | ----: |
+| Extend RuView only                            |       2 |       2 |            5 |              3 |    2 |    14 |
+| Build proprietary fusion engine               |       3 |       3 |            4 |              4 |    3 |    17 |
+| Create open RuField spec plus reference stack |       5 |       5 |            4 |              5 |    3 |    22 |
+| Attempt new hardware standard                 |       5 |       5 |            1 |              4 |    5 |    20 |
+
+Decision: **Create open RuField spec plus reference stack.** It maximizes credibility, extensibility, and ecosystem pull while avoiding the impossible burden of defining a new physical layer.
+
+## 22. Security Model
+
+| Threat                              | Impact                          | Mitigation                             |
+| ----------------------------------- | ------------------------------- | -------------------------------------- |
+| Raw waveform leakage                | privacy breach                  | P0 edge only by default                |
+| Biometric inference without consent | legal and trust risk            | P4 consent gate                        |
+| Sensor spoofing                     | false occupancy or safety event | signed sensor receipts                 |
+| Replay attack                       | forged event stream             | nonce plus timestamp plus hash chain   |
+| Model drift                         | wrong inference                 | calibration expiry and benchmark gates |
+| Overfitting to one room             | weak generalization             | room split benchmark                   |
+| Vendor firmware change              | silent degradation              | firmware hash in receipt               |
+
+## 23. Calibration Model
+
+`CalibrationReceipt` is first class. Required calibration tasks: empty room baseline, single person walk path, sit and stand, bed or couch transition, breathing reference, no motion stability period.
+
+## 24. Inference Semantics
+
+Every inference must include: label, confidence, supporting events, contradicting events, privacy class, calibration id, model id, expiry time.
+
+## 25. Consequences
+
+Positive: RuView becomes part of a larger sensing ecosystem; the spec creates a standards-style wedge without waiting for silicon vendors; multimodal fusion becomes portable; privacy and provenance become differentiators; enterprise deployment becomes easier to justify; benchmark receipts reduce skepticism.
+
+Negative: broad scope can dilute execution; hardware variability will be painful; calibration is the hardest practical problem; some will claim existing standards already solve parts of this; medical and biometric use cases require careful governance.
+
+Mitigation: keep v0.1 narrow; ship real adapters; publish benchmark receipts; do not claim medical diagnosis; position RuField above existing standards.
+
+## 26. Implementation Plan
+
+Phase 1 spec skeleton; Phase 2 Rust core; Phase 3 adapters; Phase 4 fusion graph; Phase 5 dashboard; Phase 6 benchmark.
+
+## 27. Acceptance Criteria
+
+v0.1 is accepted when:
+
+1. Three modalities stream into one event graph.
+2. Every event has a privacy class.
+3. Every event has a provenance receipt.
+4. Fusion produces at least five room state inferences.
+5. p95 event pipeline latency is below 100 ms.
+6. Benchmark runner produces deterministic reports.
+7. Raw waveform storage is disabled by default.
+8. P4 inference requires consent policy approval.
+9. Dashboard shows live camera free room intelligence.
+10. Spec is readable enough for external implementers.
+
+## 28. Reference Repository Structure
+
+Crates under `v2/crates/rufield-*` (workspace members), spec under `docs/rufield/`, benches under `rufield-bench`.
+
+## 29. Open Questions
+
+1. JSON Schema first, Protobuf first, or both?
+2. Default transport: MQTT, NATS, WebSocket, or MCP?
+3. Matter integration: bridge or first class target?
+4. P4 health inference disabled by default in public demos?
+5. Benchmark datasets synthetic first, then real world?
+6. Include quantum modality IDs even if adapters are synthetic only?
+
+## 30. Recommendation
+
+Proceed. Publish RuField as an open specification with a working Rust reference stack and a viral camera free room intelligence demo.
+
+## 31. Benchmark Acceptance Test
+
+```text
+Given a room with WiFi CSI, mmWave radar, and thermal IR sensors
+When a person enters, sits, breathes, exits bed, and leaves
+Then RuField emits signed events
+And classifies room state without a camera
+And keeps all default network events at P2 or below
+And produces p95 latency below 100 ms
+And produces a deterministic benchmark report
+```
+
+---
+
+## Implementation Status (v0.1 reference stack)
+
+The v0.1 reference stack is implemented as a **standalone Cargo workspace**
+(`rufield/`, published as `github.com/ruvnet/rufield` and vendored into RuView
+as a submodule — the `vendor/rvcsi` pattern). It is pure Rust, builds and tests
+on Windows with no native deps (`ndarray`/`tch`/`openblas` are not used), and
+depends only on `serde`, `serde_json`, `toml`, `sha2`, and `ed25519-dalek`.
+
+**All metrics below are SYNTHETIC.** They are scored against the simulator's own
+ground-truth labels. They demonstrate the pipeline recovers known truth and runs
+within latency/privacy/provenance budgets — they are **not** field-validated
+accuracy. There is no hardware in v0.1; real adapters (ESP32 CSI, mmWave, thermal
+IR) are a documented follow-up (see the repo README "Firmware" section).
+
+### Crates delivered
+
+| Crate | Implements |
+|-------|-----------|
+| `rufield-core` | §7/§9/§16/§20 data model: `Modality` (15), `FieldAxis`, `FieldTensor` (shape↔values validated), `PrivacyClass` (P0–P5), `SensorDescriptor`, `Observation`, `FieldEvent`, `CalibrationReceipt`, `InferenceQuery`, `FieldInference`, `FieldEmbedding`; `FieldAdapter`/`FieldEncoder`/`FusionEngine`/`PrivacyGuard` traits. §7 JSON example round-trips. |
+| `rufield-provenance` | Real `sha256` content hashing + deterministic `ed25519` sign/verify; §11 `is_fusable` invariant. Tests: tamper → verify fails; synthetic event fusable without signer. |
+| `rufield-privacy` | §10 default policy + `DefaultPrivacyGuard` (`authorize` → Allow/Deny/RequiresConsent). Tests: P0 transmit denied; P4 no-consent → RequiresConsent; P4 consent → Allow; P2 → Allow; P5 needs identity binding. |
+| `rufield-adapters` | Deterministic seeded `SyntheticSim` emitting the §19 sequence across 3 modalities (wifi_csi, mmwave_radar, infrared_thermal). Same seed ⇒ identical signed event stream with ground-truth labels. |
+| `rufield-fusion` | `FusionGraph` (§12) + `RuFieldFusion` engine; TOML rules (§13, ≥5 inferences: person_present, sitting, sleeping, breathing, nocturnal_scratch, bed_exit, room_transition); weighted-Bayes + temporal-window; rejects non-fusable events; `FieldInference` with §24 fields. |
+| `rufield-bench` | Deterministic runner: F1 per task (SYNTHETIC), p95 latency, provenance coverage, privacy violations; JSON + human table; §31 acceptance test as `#[test]`. |
+
+Total test count across the workspace: **60 tests, 0 failed**.
+`cargo clippy --workspace` is clean.
+
+### §27 acceptance-criteria scorecard
+
+| # | Criterion | Status |
+|---|-----------|--------|
+| 1 | Three modalities stream into one event graph | **PASS** — wifi_csi, mmwave_radar, infrared_thermal |
+| 2 | Every event has a privacy class | **PASS** — `Observation.privacy_class` (non-optional), default ≤ P2 |
+| 3 | Every event has a provenance receipt | **PASS** — every event is ed25519-signed and verifies; coverage 100% |
+| 4 | Fusion produces ≥ 5 room-state inferences | **PASS** — 7 distinct inferences produced |
+| 5 | p95 event pipeline latency < 100 ms | **PASS** — p95 ≈ 0.01 ms (in-process) |
+| 6 | Benchmark runner produces deterministic reports | **PASS** — identical report across runs (latency is the only wall-clock field) |
+| 7 | Raw waveform storage disabled by default | **PASS** — P0 network transmission denied by default policy |
+| 8 | P4 inference requires consent policy approval | **PASS** — P4 without consent → RequiresConsent; breathing/scratch rules carry `requires_consent = true` |
+| 9 | Dashboard shows live camera-free room intelligence | **DEFERRED** — no `rufield-viewer` dashboard in v0.1; the benchmark + `room_intelligence` example provide a CLI view. Follow-up. |
+| 10 | Spec readable for external implementers | **PASS** — ADR-260 + detailed standalone README with compiling usage examples |
+
+**Decision:** §27 criteria 1–8 and 10 PASS; criterion 9 (live dashboard) is
+**deferred** to a follow-up. Per the acceptance rule (1–8, 10 pass; 9 may be
+deferred), Status is set to **Accepted — v0.1 reference stack**.
+
+### Deterministic benchmark report (SYNTHETIC, seed = 2026)
+
+```text
+TASK (SYNTHETIC)       METRIC      VALUE     TARGET    MEETS
+presence                   f1      1.000      0.900      yes
+breathing                  f1      1.000      0.800      yes
+nocturnal_scratch          f1      0.923      0.750      yes
+bed_exit                   f1      1.000      0.900      yes
+room_transition            f1      1.000      0.850      yes
+-----------------------------------------------------------------------------------
+p50 latency:          0.0097 ms
+p95 latency:          0.0123 ms   (target < 100 ms: PASS)
+provenance coverage:  100.0 %      (target 100%: PASS)
+privacy violations:   0          (target 0: PASS)
+events=216  modalities=3  distinct_inferences=7
+```
+
+All five scored §18 tasks meet their F1 targets **on synthetic ground truth**.
+`nocturnal_scratch` is 0.923 (one borderline noise tick at this seed) — reported
+honestly rather than tuned to 1.0. The fall-like / false-alarm-rate §18 rows are
+not scored in v0.1 (no fall is in the demo sequence) and are a follow-up. These
+numbers prove the fusion pipeline scores correctly against known truth; they say
+**nothing** about real-world accuracy, which requires the hardware adapters that
+v0.1 deliberately does not ship.
+
+### Honest statement
+
+Every metric here is simulator-based. No ESP32 CSI, mmWave, or thermal capture
+was used. RuField v0.1 is a working, honestly-measured reference pipeline —
+data model, provenance, privacy, fusion, and a deterministic benchmark — pending
+real hardware adapters.

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/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-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-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,