Merge pull request #1039 from ruvnet/release/patch-1009-1004

release: patch-bump signal/sensing-server/cli for #1009+#1004 fixes (+ first-publish calibration)

CHANGELOG.md

@@ -42,6 +42,10 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - **Live trust path: sensing-server routes real frames through the governed `StreamingEngine` (parallel governed path with partial output gating).** Previously the live server ran only the *bare* `MultistaticFuser` (fused amplitudes, no trust control plane), while the privacy/provenance/witness engine (ADR-135..146) ran only on synthetic in-test frames — the gap called out in ADR-136 §8 and the beyond-SOTA system review. New `engine_bridge` module drives `StreamingEngine::process_cycle` from the server's live `NodeState` map (reusing the existing `NodeState → MultiBandCsiFrame` conversion), lazily wiring each node as a WorldGraph sensor and bounding belief growth via the retention cap; every *governed belief* carries evidence + model + calibration + privacy decision and a deterministic witness. **Honest scope:** the engine runs alongside (not instead of) the bare fusion path that feeds the live `SensingUpdate`. What its decision gates on the wire today: a cycle emitted at class `Restricted` (base mode or contradiction/mesh-risk demotion) suppresses the per-node raw amplitude vectors from the live publish — the same field mapping `wifi-densepose-bfld`'s privacy gate applies at `Restricted`; gating the remaining derived outputs (person count, classification, signal field) is tracked as a follow-up. Trust state is no longer write-only: the latest witness, effective privacy class, demotion flag, recalibration recommendation, and an engine-error counter are readable on `GET /api/v1/status`, and engine errors are counted + rate-limit logged instead of silently swallowed (`EngineBridge::observe_cycle`). Adds `wifi-densepose-engine/-worldgraph/-bfld/-geo` deps. Bridge tests cover witnessed belief with provenance, determinism, idempotent node registration, retention bound, privacy-mode propagation, trust-state recording, the error-counter path, and Restricted-class raw-output suppression.
 
 ### Fixed
+- **Real HE20 CSI no longer silently dropped or replaced with simulated data (fixes #1009, #1004).** Two ingest bugs caused real ESP32-C6 HE20 frames to be discarded or never received — the exact "real data silently lost" failure class the project fights. Each fix is pinned by a test that fails on the old code.
+  - **#1009 §1b — HE20 baseline recorder trimmed 256 → 242 bins by sequential index (`wifi-densepose-signal/src/ruvsense/calibration.rs`).** ESP-IDF v5.5.2 delivers all 256 FFT bins for an HE20 frame; `CalibrationConfig::he20()` carried `num_active: 242`, so the recorder (which has no HE20 tone map — `extract_first_stream` takes the first `num_active` columns *sequentially*) kept bins 0..242 of the 256-bin grid. Those are the lower guard band + DC, **not** the 242 active tones, silently corrupting the empty-room baseline. Now `num_active: 256` records every delivered bin, staying aligned 1:1 with the live `deviation()` path. The exact-242 tone map deliberately stays only in `cir.rs` (`HE20_ACTIVE`), where the Φ sensing matrix genuinely needs it. Test `he20_records_all_256_bins_not_trimmed_to_242` asserts the finalized baseline covers all 256 bins (was 242). HE20 synthetic/bench fixtures updated to feed 256-bin frames (the real wire format).
+  - **#1009 §1a/§1c — already-fixed u8→u16 `n_subcarriers` truncation, now regression-pinned.** The ADR-018 wire format carries `n_subcarriers` as u16 LE at bytes 6–7. A 256-bin HE20 frame (byte6=0x00, byte7=0x01) read as a single byte decodes to **0 subcarriers** → every frame skipped (invisible until HE20: ESP32-S3's ≤192 bins fit in one byte). The CLI parser (`wifi-densepose-cli/calibrate.rs`) and the sensing-server template parser (`wifi-densepose-sensing-server` `parse_esp32_frame`) were already corrected to u16 under #1005/ADR-110; added regression tests (`parse_esp32_frame_he20_256_bins_not_truncated`, CLI `test_parse_csi_packet_he_su_256_bins`) that fail on the old single-byte read so the truncation cannot silently return.
+  - **#1004 — `--source auto` latched on `simulate` forever, never binding UDP :5005 (`wifi-densepose-sensing-server/src/main.rs`).** A one-shot boot probe resolved the source once; with no CSI flowing at boot (the normal firmware/server startup race) it served simulated poses for the whole process and ignored real CSI that arrived seconds later (the prior #937 fix hard-exited instead — equally wrong, the server could never pick up late-starting CSI). New `plan_source()` state machine: in `auto` mode **always bind the UDP receiver** and serve simulated data only until the first real frame, at which point `udp_receiver_task` promotes `source` → `esp32` (mirroring the existing `esp32 → esp32:offline` reversion in `effective_source()`); `simulated_data_task` self-suspends once promoted so it never clobbers live CSI. Explicit `--source simulated` stays a hard, UDP-free override for offline demos. 6 unit tests pin the resolution/promotion machine (`auto_with_no_boot_source_still_binds_udp_and_simulates`, etc.); the auto-binds-UDP assertion fails on the old behavior.
 - **`wifi-densepose-mat` standalone `--no-default-features` build (101 errors → 0).** `pub mod api` was unconditional while its only dependency, serde, is optional behind the `api` feature — so any build without default features failed with unresolved serde imports (masked in `--workspace` runs by feature unification). The `api` module and its `create_router`/`AppState` re-export are now `#[cfg(feature = "api")]`-gated (with docsrs annotations). All feature combos compile: bare `--no-default-features`, `--no-default-features --features api`, and full default (177 tests pass).
 - **WorldGraph no longer grows unboundedly under the live loop.** `StreamingEngine::process_cycle` appended one `SemanticState` belief per cycle with no eviction — ~1.7M nodes/day at 20 Hz (identified in `docs/research/ruview-beyond-sota/04-optimization-roadmap.md`). Added `WorldGraph::prune_semantic_states(max)` — deterministic eviction of the oldest beliefs by `(valid_from_unix_ms, id)`, structural nodes (rooms/zones/sensors/anchors/tracks/events) never eligible — and wired it into the engine after each belief append (`StreamingEngine::DEFAULT_SEMANTIC_RETENTION` = 7,200 ≈ 6 min at 20 Hz; tunable via `set_semantic_retention`). The WorldGraph holds *current* beliefs; durable history is the recorder's job, so no audit data is lost. 3 new tests (bounded growth end-to-end, oldest-only eviction, deterministic tie-break).
 - **ESP32 edge heart rate no longer stuck at ~45 BPM / dropping wildly — #987.** The on-device HR estimator (`edge_processing.c`, `0xC5110002`) reported ~45 BPM regardless of true heart rate (Apple-Watch ground truth 87 BPM read as ~45) and swung frame-to-frame. Two root causes: (1) a hardcoded `sample_rate = 10.0f` that became wrong after #985's self-ping raised the CSI callback rate to a variable ~13–19 Hz — BPM scales as `assumed/actual × true`, so 87 read ~45 and the reading swung as CSI yield fluctuated; (2) the zero-crossing estimator locked onto a breathing harmonic (a 0.25 Hz breathing fundamental puts its 3rd harmonic at ~0.74 Hz ≈ 44 BPM inside the HR band). Fix: measure the real sample rate from inter-frame timestamps (used for BPM conversion + biquad re-tuning on >15% drift); replace the HR zero-crossing with an autocorrelation estimator that rejects breathing harmonics (driven by a robust autocorr breathing period); median-13 smooth the output. Hardware A/B (fixed vs unmodified control board, both `edge_tier=2`): control pegged 40–49 BPM; fixed reaches the true 88–91 BPM (vs 87 GT) and holds a stable physiological value (spread 59→0 for a steady subject). Known limitation: heavy subject motion still degrades the estimate (motion gating is a follow-up).

PROOF.md

@@ -55,6 +55,8 @@ trained checkpoint) so you can reproduce them yourself.
 | zero-copy ORT input ~1.48× (ADR-155) | **MEASURED** | `cd v2 && cargo bench -p wifi-densepose-nn --features onnx --bench onnx_bench` |
 | pointcloud splats 9→2 passes ~1.24× (ADR-160 research) | **MEASURED** | `cd v2 && cargo bench -p wifi-densepose-pointcloud --bench splats_bench` |
 | native wlanapi multi-BSSID scan 9.74 Hz (vs netsh ~2 Hz) | **MEASURED (Windows)** | `cd v2 && cargo test -p wifi-densepose-wifiscan -- --ignored measure_native_scan_rate` |
+| wasm-edge `process_frame` hot-path latency (host proxy, ADR-163) | **MEASURED-on-host** (NOT the ESP32/WASM3 budget — needs hardware) | `cd v2/crates/wifi-densepose-wasm-edge && cargo bench --features std` |
+| cog steady-state CPU infer latency ~305 µs (ADR-163; NOT the manifest cold-start) | **MEASURED-on-host** | `cd v2 && cargo bench -p cog-person-count -p cog-pose-estimation --no-default-features --bench infer_bench` |
 
 ## What we do NOT claim (the honest negatives — the strongest anti-slop signal)
 
@@ -68,8 +70,9 @@ trained checkpoint) so you can reproduce them yourself.
 
 ## Provenance
 
-Every claim above traces to a committed ADR (`docs/adr/ADR-154`…`ADR-160`), a
-test, a criterion bench, or `benchmarks/wiflow-std/RESULTS.md`. The history
+Every claim above traces to a committed ADR (`docs/adr/ADR-154`…`ADR-163`), a
+test, a criterion bench, `benchmarks/wiflow-std/RESULTS.md`, or
+`benchmarks/edge-latency/RESULTS.md`. The history
 includes published **retractions** (the 92.9% PCK retraction; the WiFlow-STD
 shipped-checkpoint refutation; the NV-diamond BOM reality check) — a faker hides
 failures; we commit them.

benchmarks/edge-latency/RESULTS.md

@@ -0,0 +1,137 @@
+# Edge-Latency Benchmark Results — ADR-163
+
+Converting **CLAIMED** edge latency budgets into **MEASURED-on-host** numbers,
+closing the measurement debt flagged by Milestones 5/6 (ADR-159 / ADR-160).
+Benches + docs only — **no production-code behavior changed**.
+
+## The honest caveat, up front (read before citing any number)
+
+Two distinct gaps separate every number below from the figure it is converting:
+
+1. **Host ≠ ESP32.** The wasm-edge skill modules document budgets *"on ESP32-S3
+   WASM3"* (e.g. `exo_time_crystal`: "H (<10 ms)"). These benches run **native
+   x86_64 on a development laptop**, not the Xtensa/WASM3 target. A native host
+   median is an **upper bound on the algorithm's work**, not the ESP32 number.
+   WASM3 interpretation on a ~240 MHz Xtensa core is typically 1–2 orders of
+   magnitude slower than native `-O` host code, so a host median far under the
+   budget **does NOT prove the ESP32 meets it.** *The ESP32 figure is NOT
+   reproduced here — it needs hardware.*
+
+2. **Bench ≠ the doc-claimed measurement.** For the cogs, the manifest cites a
+   **cold-start** number (`cold_start_ms_avg`, weight-load included); these
+   benches measure **steady-state** per-frame `infer` (warm, weights resident).
+   Different measurements; we report both, labelled.
+
+Grades (per `benchmarks/wiflow-std/RESULTS.md` / ADR-152 vocabulary):
+- **MEASURED-on-host** — reproduced in this repo on the machine below, exact
+  command recorded. NOT the ESP32 / NOT the cold-start figure.
+- **CLAIMED (ESP32)** — the doc budget; UNMEASURED on hardware here.
+
+## Machine
+
+| | |
+|---|---|
+| Host | `ruvzen` (Windows 11, this dev box) |
+| CPU | Intel Core Ultra 9 285H |
+| Toolchain | `cargo 1.91.1`, `--release` (opt-level per crate profile) |
+| Bench harness | criterion 0.5 (`time: [low **median** high]` reported below) |
+| Date | 2026-06-12 |
+
+Run-to-run spread on this box is non-trivial (criterion's low/high bracket the
+median by a few %); the medians below are single-session captures with the smoke
+settings `--warm-up-time 1 --measurement-time 2` (wasm-edge) / `3` (cogs). Re-run
+for your own machine — the absolute numbers are host-specific.
+
+---
+
+## T1 — wasm-edge `process_frame` hot paths (ADR-160 deferred item → DONE host)
+
+The crate is **excluded from the v2 workspace**; bench from the crate dir.
+
+```bash
+cd v2/crates/wifi-densepose-wasm-edge
+cargo bench --features std -- --warm-up-time 1 --measurement-time 2
+# med_seizure_detect is medical-experimental-gated:
+cargo bench --features std,medical-experimental -- --warm-up-time 1 --measurement-time 2 med_seizure
+```
+
+| Hot path (M6-audit-named) | Bench id | Host median | Grade | Doc budget (CLAIMED, ESP32) |
+|---|---|---|---|---|
+| `exo_time_crystal` 256-pt × 128-lag autocorrelation (full buffer) | `exo_time_crystal::process_frame[autocorr_256x128]` | **17.3 µs** | MEASURED-on-host | "H (<10 ms) on ESP32-S3 WASM3" — **NOT reproduced here (needs hardware)** |
+| `exo_ghost_hunter` empty-room periodicity + hidden-breathing | `exo_ghost_hunter::process_frame[empty_room_periodicity]` | **1.44 µs** | MEASURED-on-host | research/exotic; no firm ESP32 figure — host proxy only |
+| `sec_weapon_detect` per-subcarrier Welford (MAX_SC=32) | `sec_weapon_detect::process_frame[per_sc_welford]` | **0.42 µs** (420 ns) | MEASURED-on-host | research-grade; calibration-gated — host proxy only |
+| `med_seizure_detect` clonic-phase rhythm path (steady-state frame) | `med_seizure_detect::process_frame[clonic_rhythm]` | **0.10 µs** (105 ns) | MEASURED-on-host (feature-gated) | doc budget "S (<5 ms) on ESP32"; **NOT reproduced here** |
+
+Reading these honestly:
+
+- `exo_time_crystal` at **17.3 µs host** is the only one whose host cost is even
+  in the same *thousandths* of its 10 ms ESP32 budget — it does the most work
+  (~32K MACs/frame). 17.3 µs native says the algorithm is cheap; it says
+  **nothing** about whether WASM3-on-Xtensa lands under 10 ms. A naïve
+  host→ESP32 extrapolation (assume 100× interpreter+clock penalty) would put it
+  near ~1.7 ms, comfortably under — **but that is an extrapolation, not a
+  measurement**, and is recorded here only to show the host number is not
+  obviously in tension with the budget. ESP32 figure: **UNMEASURED**.
+- `med_seizure_detect`'s 105 ns is the **steady-state** per-frame cost; the
+  expensive clonic autocorrelation only fires when the state machine is in the
+  clonic phase, so this is a lower-bound on the heavy path, not the worst case.
+  It is still a real, committed host datapoint.
+- The pre-existing `tests/budget_compliance.rs` already asserts the L/S/H
+  wall-clock tiers (25 passing tests); these criterion benches add the
+  regression-grade, reproducible median that ADR-160 deferred.
+
+---
+
+## T2 — cog steady-state inference latency (ADR-159/160 deferred item → DONE)
+
+Cog crates are normal workspace members; bench from `v2/`. Real weights
+(`count_v1.safetensors` / `pose_v1.safetensors`) ship in-repo under each cog's
+`cog/artifacts/`, so the bench measures the **real Candle CPU forward**, not the
+stub (the bench `assert!`s `backend().starts_with("candle-")`).
+
+```bash
+cd v2
+cargo bench -p cog-person-count  --no-default-features --bench infer_bench -- --warm-up-time 1 --measurement-time 3
+cargo bench -p cog-pose-estimation --no-default-features --bench infer_bench -- --warm-up-time 1 --measurement-time 3
+```
+
+| Cog | Bench id | Host median (steady-state infer, CPU) | Grade | Manifest cold-start (CLAIMED, different measurement + machine) |
+|---|---|---|---|---|
+| cog-person-count | `cog_person_count::infer[cpu_real_weights_steady_state]` | **305 µs** (idle box) | MEASURED-on-host | — (person-count manifest carries comparable provenance) |
+| cog-pose-estimation | `cog_pose_estimation::infer[cpu_real_weights_steady_state]` | **305 µs** (idle box) | MEASURED-on-host | `cold_start_ms_avg: 5.4` (30 invocations, **ruvultra/RTX 5080 host**, candle 0.9 cpu) — **cold-start, NOT steady-state; NOT this machine** |
+
+> Spread caveat (observed, honest): both medians above were captured with the box
+> otherwise idle. A re-run of the validate-form command *while a second cargo job
+> was loading the same cores* gave 385 µs (person-count) / 973 µs (pose) —
+> the criterion low/high bracket widens to ~0.34–1.18 ms under contention. The
+> 305 µs figures are the idle-box datapoints; the absolute number is host- and
+> load-dependent (the ~10× pose swing is core contention, not a code change).
+
+Reading these honestly:
+
+- **Steady-state ≠ cold-start.** The pose manifest's `5.4 ms` folds in one-time
+  weight load / mmap / first-forward allocation. This bench warms the engine
+  first and times only the recurring per-frame forward, on a *different
+  machine*. The two numbers are not comparable and we do not claim this bench
+  reproduces the 5.4 ms manifest figure.
+- Both cogs share the same conv encoder; person-count adds a count head +
+  confidence head, pose adds a 256-wide MLP head. The host steady-state cost is
+  dominated by the three dilated Conv1d layers (56→64→128→128) shared by both —
+  which is why both land at ~305 µs.
+- **Empirical confirmation of the steady-state/cold-start gap:** pose
+  steady-state (305 µs host) is ~18× *under* the manifest's 5.4 ms cold-start.
+  Even accounting for the different machine, this is the expected shape — the
+  bulk of cold-start is one-time setup, not the forward pass — and it is exactly
+  why conflating the two would be dishonest.
+
+---
+
+## Status vs the deferred items
+
+| Deferred item | Was | Now |
+|---|---|---|
+| ADR-160 "Criterion benches for `process_frame` budget claims" | ACCEPTED-FUTURE | **DONE (host)**; ESP32-on-hardware still **PENDING** (needs the wasm32 target + a flashed ESP32-S3) |
+| ADR-159/160 cog inference latency (`cold_start_ms_avg` uncommitted-benched) | CLAIMED | **MEASURED-on-host (steady-state)**; cold-start-on-ruvultra remains the manifest's separate claim |
+
+Nothing here changes runtime behavior — these are benches + this results file
+only. No crate needs republishing.

docs/adr/ADR-160-edge-skill-library-honest-labeling.md

@@ -182,9 +182,15 @@ label or behavior change, consistent with leaving their claim surface intact.)
   sign-language claim requires labelled clinical/affective/ASL data and reference
   standards that do not exist in this repo. The disclaimers + feature gate are the
   honest stand-in. Nothing is claimed that is not measured.
-- **Criterion benches for `process_frame` budget claims** — **ACCEPTED-FUTURE**.
-  `tests/budget_compliance.rs` asserts L/S/H tier wall-clock budgets (25 tests,
-  passing), but a regression-grade criterion bench is not yet wired.
+- **Criterion benches for `process_frame` budget claims** — **DONE (host)**
+  (ADR-163, 2026-06-12). `benches/process_frame_bench.rs` benches the heaviest
+  hot paths (`exo_time_crystal` 256×128 autocorrelation, `exo_ghost_hunter`
+  periodicity, `sec_weapon_detect` per-subcarrier Welford, `med_seizure_detect`
+  clonic rhythm) and reports committed **host** medians
+  (`benchmarks/edge-latency/RESULTS.md`). `tests/budget_compliance.rs` continues
+  to assert the L/S/H tier wall-clock budgets (25 tests, passing). **ESP32-on-
+  hardware (Xtensa/WASM3) latency remains PENDING** — the host bench is an
+  upper-bound algorithm-cost proxy, NOT the ESP32 figure (needs hardware).
 - **`wasm32-unknown-unknown` `static_mut_refs` confirmation** — **ACCEPTED-FUTURE**
   (toolchain): the source pattern is eliminated; a CI job on the wasm target should
   assert zero `static_mut_refs` once the target is added to the build image.

docs/adr/ADR-161-homecore-server-layer-security.md

@@ -196,7 +196,8 @@ fields are **never read** for verification (only ever set to `None` in tests).
 re-doc'd **"(P4 — not yet enforced, ADR-161/B5)"** — parsed and round-tripped,
 but no integrity/signature check happens before a plugin runs. No verification
 code was added (that is P4); the doc now matches the code.
-**Grade: doc-honesty (no behavior change).**
+**Grade: doc-honesty (no behavior change).** *(Superseded by ADR-162 §P4:
+the hash/signature gate is now implemented and enforced.)*
 
 ## Negative Results (NO-ACTION positives — audited, found correct, cited not edited)
 
@@ -213,17 +214,23 @@ touched:
 
 ## Deferred Backlog (Nothing Dropped)
 
-- **Plugin authority-isolation (P5)** — `homecore_permissions` claims are parsed
-  but not enforced at the host-call boundary. **ACCEPTED-FUTURE.**
-- **Plugin signature/hash verification (P4)** — implement the
+- **Plugin authority-isolation (P5)** — ~~`homecore_permissions` claims are parsed
+  but not enforced at the host-call boundary.~~ **DONE — ADR-162 §P5.**
+  `hc_state_set` now consults a `PermissionSet` distilled from the manifest;
+  an undeclared write returns a typed `-3` to the guest.
+- **Plugin signature/hash verification (P4)** — ~~implement the
   `wasm_module_hash`/`wasm_module_sig`/`publisher_key` gate that B5 now honestly
-  says is absent. **ACCEPTED-FUTURE.**
+  says is absent.~~ **DONE — ADR-162 §P4.** `WasmtimeRuntime::load_plugin` now
+  SHA-256-checks the module, Ed25519-verifies the signature against
+  `publisher_key`, and enforces a `PluginPolicy` trust allowlist
+  (secure-default rejects unsigned/untrusted/tampered modules).
 - **HAP real pairing (P2)** — SRP/HKDF pairing + encrypted sessions; current
   bridge is an accessory-mapping surface. **ACCEPTED-FUTURE (honestly stubbed).**
-- **`RunMode::Queued`/`Restart`/`max` ordering** — `Single`/`Parallel` are
+- **`RunMode::Queued`/`Restart`/`max` ordering** — ~~`Single`/`Parallel` are
   honored; bounded queueing, restart-kill, and `max` concurrency are not yet
-  wired (every non-Single mode is parallel). **ACCEPTED-FUTURE** — the
-  `engine.rs` doc states exactly this, no over-claim.
+  wired (every non-Single mode is parallel).~~ **DONE — ADR-162 §A5.** Restart
+  aborts the in-flight task, Queued serializes via a per-automation async mutex,
+  and `max: N` caps concurrency via a per-automation semaphore.
 - **Automation YAML load-at-boot** — the engine starts empty; a YAML loader is
   P-next. The bin log states "0 automations registered" honestly.
 

docs/adr/ADR-162-plugin-security-and-bounded-runmodes.md

@@ -0,0 +1,186 @@
+# ADR-162: HOMECORE Plugin Security (Signature + Capability Isolation) & Bounded Automation RunModes — Making ADR-161's Deferred Claims TRUE
+
+- **Status**: accepted
+- **Date**: 2026-06-12
+- **Deciders**: ruv
+- **Tags**: homecore, homecore-plugins, homecore-automation, plugin-security, wasm-signature-verification, ed25519, capability-isolation, runmode, prove-everything, soundness, honest-labeling
+- **Amends**: ADR-161 (relabelled P4/P5 + §A5 deferrals → now enforced), ADR-128 (plugin manifest), ADR-129 (automation engine)
+
+## Context
+
+Beyond-SOTA sweep **Milestone 8**, scoped to `homecore-plugins` and
+`homecore-automation` only, under the project's **prove-everything /
+anti-"AI-slop"** directive.
+
+ADR-161 (Milestone 7) did the honest thing with three plugin/automation
+items it could not finish in that window: rather than fake them, it **relabelled
+them as deferred** —
+
+- **P4** (plugin signature verification): the manifest's `wasm_module_hash` /
+  `wasm_module_sig` / `publisher_key` were re-doc'd "(P4 — not yet enforced,
+  ADR-161/B5)" — parsed and round-tripped, but **never checked** before a
+  plugin runs.
+- **P5** (plugin authority isolation): `homecore_permissions` claims were
+  parsed but **never consulted**; `hc_state_set` let any plugin write any
+  entity, including `lock.*` / `alarm_control_panel.*`.
+- **§A5** (`RunMode`): `Single`/`Parallel` were honored; `Restart`/`Queued`/
+  `max: N` were honestly documented as still **unbounded-parallel**.
+
+### Headline — the deferred security items are now ENFORCED + TESTED
+
+M8 turns those honest deferrals into real, tested behavior. The plugin trust
+boundary is now sound (a tampered module, an untrusted publisher, or an
+unsigned module is rejected by the secure default), an over-privileged plugin
+write is denied with a typed error, and the bounded run-modes actually bound.
+**Every fix is pinned by a test that FAILS on the pre-M8 code** — each of the
+three RunMode tests was additionally run against a simulated unbounded-parallel
+dispatch and confirmed to panic.
+
+The Ed25519 crypto reuses the in-repo `cog-ha-matter::witness_signing` pattern
+(same `ed25519-dalek` 2.x API, same deterministic-test-key convention). SHA-256
+matches the `sha256:` prefix the manifest already declared and the
+`cog-ha-matter` cog manifest's `binary_sha256` hex convention. No new external
+dependency tree was introduced — `ed25519-dalek` / `sha2` / `hex` / `base64`
+were already in the workspace `Cargo.lock` (cog-ha-matter / bfld pull them in);
+only new dependency *edges* were added to `homecore-plugins`.
+
+Grading vocabulary (ADR-152 / ADR-158 / ADR-160 / ADR-161):
+- **MEASURED** — reproduced in this worktree, command + failing-on-old test recorded.
+- **ACCEPTED-FUTURE** — deliberately deferred, nothing dropped.
+
+## Decision — Fixes Landed
+
+### §P4 — Plugin signature & integrity verification (SECURITY) — MEASURED
+
+`homecore-plugins/src/manifest.rs` declared `wasm_module_hash` /
+`wasm_module_sig` / `publisher_key` but they were **never read** for
+verification; the load path (`wasmtime_runtime.rs`) instantiated any `.wasm`
+bytes handed to it.
+
+**Real fix** (`src/verify.rs`, wired into `WasmtimeRuntime::load_plugin`):
+before instantiation the runtime now —
+
+1. computes the **SHA-256** of the actual `.wasm` bytes and rejects if it ≠ the
+   manifest's `wasm_module_hash` (`sha256:<hex>`) — tamper detection;
+2. verifies the **Ed25519** `wasm_module_sig` (`ed25519:<base64>`, 64-byte raw)
+   over the 32-byte digest against `publisher_key` (`ed25519:<base64>`, 32-byte
+   raw) and rejects on failure;
+3. enforces a configurable **trust policy** — `PluginPolicy::trusted(&[keys])`
+   is an allowlist of publisher verifying keys; `PluginPolicy::AllowUnsigned`
+   is an explicit dev escape hatch that LOGS a loud `warn` on every load it
+   waves through. The **secure default rejects unsigned and unknown-publisher
+   modules.** `PluginPolicy::deny_all()` trusts no publisher.
+
+A typed `PluginError::SignatureRejected` is returned (no host panic). The
+legacy permission-free `load_wasm` is retained for first-party/trusted/test
+modules; production loading goes through `load_plugin`.
+
+**Failing-on-old tests** (`tests/integration.rs`, `--features wasmtime`) — all
+drive `load_plugin`, which **did not exist** on the old code (so the gate is
+genuinely new):
+- `p4_tampered_module_is_rejected` — a byte-flipped `.wasm` → hash mismatch → rejected.
+- `p4_valid_sig_from_trusted_key_loads` — a valid sig from an allowlisted key loads.
+- `p4_valid_sig_from_untrusted_key_is_rejected` — a correctly-signed module from a key NOT on the allowlist is rejected.
+- `p4_unsigned_module_rejected_by_default_loads_only_under_allow_unsigned` — unsigned rejected under `deny_all`, loads (with warn) only under `AllowUnsigned`.
+- Unit (`src/verify.rs`): `valid_sig_from_trusted_key_passes`, `tampered_module_is_rejected`, `valid_sig_from_untrusted_key_is_rejected`, `forged_signature_is_rejected`, `unsigned_module_rejected_under_default_policy`.
+
+A real deterministic keypair signs real `.wasm` bytes in the tests.
+The manifest doc now reads **"(P4 — ENFORCED, ADR-162)"**. **Grade: MEASURED. Milestone headline.**
+
+### §P5 — Plugin authority / capability isolation (SECURITY) — MEASURED
+
+`wasmtime_runtime.rs::hc_state_set` applied any write a plugin requested,
+ignoring the manifest's `homecore_permissions`.
+
+**Real fix** (`src/permissions.rs` + `hc_state_set`): the manifest's
+`homecore_permissions` (the `state:write:<glob>` form, or a bare entity glob
+like `light.*`) are distilled into a `PermissionSet` installed in the plugin's
+Wasmtime store. The `hc_state_set` host import consults
+`permissions.may_write(entity_id)` before applying a write and returns a typed
+`-3` (permission denied) to the guest on a violation — **the host is not
+panicked.** Wasmtime already gives memory isolation; this adds **authority**
+isolation. A plugin with **no** write grants can write nothing (secure default).
+
+**Failing-on-old tests** (`tests/integration.rs`, `--features wasmtime`):
+- `p5_declared_light_plugin_may_write_light_but_not_lock` — a `light.*` plugin writes `light.kitchen` (succeeds) but is REJECTED (`-3`, and the entity is not written) when it tries `lock.front_door`.
+- `p5_plugin_with_no_permissions_can_write_nothing` — a plugin with empty `homecore_permissions` cannot write `light.kitchen`.
+- Unit (`src/permissions.rs`): domain-glob, exact-grant, wildcard, read-grants-don't-confer-write, no-permissions, and explicit `state:write:` form.
+
+The manifest doc now reads **"(P5 — ENFORCED, ADR-162)"**. **Grade: MEASURED.**
+
+### §A5 — Bounded automation RunModes (Restart / Queued / max) — MEASURED
+
+`homecore-automation/src/engine.rs` (per ADR-161) honored `Single`/`Parallel`
+but spawned an unbounded parallel task for `Restart`/`Queued`/`max`.
+
+**Real fix** (`src/runmode.rs`, a per-automation `RunState` the engine owns and
+dispatches through at all three trigger sites — event loop, timer, test hook):
+- **Restart** — aborts the in-flight action task via `tokio::task::AbortHandle`, then starts a fresh one.
+- **Queued** — serializes runs in arrival order via a per-automation async `Mutex`: sequential, never concurrent, nothing dropped.
+- **max: N** — caps concurrency at N via a per-automation `Semaphore`; triggers beyond N **queue** (await a permit) rather than running concurrently. (HA bounded `parallel`/`queued` semantics — chosen and documented as *queue beyond N*, not drop.)
+- `Single`/`IgnoreFirst` re-entrancy guard and `Parallel` preserved.
+
+`engine.rs` trimmed to **433 lines**; the run-mode machinery lives in the new
+`runmode.rs` (153 lines) to keep both under the 500-line guideline.
+
+**Failing-on-old tests** (`tests/engine_behaviors.rs`) — each was run against a
+simulated unbounded-parallel dispatch and confirmed to panic:
+- `restart_mode_cancels_prior_run` — prior run is aborted: exactly **1** completion (old: both ran → 2).
+- `queued_mode_runs_sequentially_not_concurrently` — 3 rapid triggers all run, **max observed concurrency = 1** (old: 3).
+- `max_two_caps_concurrency_at_two` — 4 rapid triggers all run, **max observed concurrency ≤ 2** (old: 4).
+
+**Grade: MEASURED. Restart, Queued, and `max: N` all implemented — no remaining RunMode deferral.**
+
+## Threat model closed
+
+| Threat | Before (ADR-161) | After (ADR-162) |
+|--------|------------------|-----------------|
+| **Tampered module** — attacker swaps `.wasm` bytes after signing | loaded unconditionally (hash never checked) | rejected: SHA-256 mismatch |
+| **Untrusted publisher** — valid sig from a key the host doesn't trust | loaded (sig/key never read) | rejected: publisher_key not on allowlist |
+| **Unsigned module** — no integrity material at all | loaded | rejected by secure default; loads only under explicit `AllowUnsigned` (loud warn) |
+| **Over-privileged plugin write** — a `light.*` plugin writes `lock.front_door` / `alarm_control_panel.*` | applied (permissions never consulted) | denied: typed `-3` to guest, write not applied |
+| **Run-mode resource exhaustion** — `max`/`Queued` spawn unbounded tasks | unbounded parallel | bounded: Restart cancels, Queued serializes, `max: N` caps at N |
+
+## Remaining honest deferral (Nothing Dropped)
+
+- **Plugin-key provisioning / rotation** — the host's trust allowlist
+  (`PluginPolicy::trusted`) is supplied by the caller; sourcing it from the
+  Cognitum control-plane key store (as `cog-ha-matter` does for Seed keys) and
+  key rotation are **ACCEPTED-FUTURE** (out of M8 scope — same boundary
+  `witness_signing` draws).
+- **`InProcessRuntime` (native first-party plugins)** — has no `.wasm` bytes to
+  hash, so P4/P5 apply only to the WASM (`wasmtime`) path; native plugins remain
+  trusted-by-compilation. Honestly noted, not over-claimed.
+- **HAP real pairing (P2)** — unchanged from ADR-161; out of M8 scope.
+
+## Reproduction (MEASURED)
+
+```bash
+cd v2
+# P4/P5 (wasmtime feature needs rustc 1.91+; workspace pins 1.89 for the rest):
+cargo +1.91.1 test -p homecore-plugins --features wasmtime
+# Bounded RunModes:
+cargo test -p homecore-automation --no-default-features
+# Full workspace still builds (1.89 toolchain, no wasmtime):
+cargo build --workspace --no-default-features
+```
+
+Result at time of writing (all 0 failed):
+- **homecore-plugins** `--features wasmtime` — **32 passed** (lib 23; integration 9). (ADR-161 baseline was 15.)
+- **homecore-automation** `--no-default-features` — **45 passed** (lib 37; `engine_behaviors` 8). (ADR-161 baseline was 42.)
+- Full workspace `cargo build --workspace --no-default-features` succeeds.
+
+## Consequences
+
+- A HOMECORE WASM plugin can no longer be loaded with a tampered binary, an
+  untrusted publisher, or (by default) no signature at all — the trust boundary
+  ADR-161/B5 honestly said was absent is now real (P4).
+- A plugin can no longer write entities outside its declared
+  `homecore_permissions`; the lock/alarm escalation path is closed (P5).
+- The automation engine's `Restart`, `Queued`, and `max: N` run-modes are now
+  bounded as documented — no run-mode claims a capability the code lacks.
+- No new external dependency tree (reuses the cog-ha-matter Ed25519 stack
+  already in the lock); source files kept under the 500-line guideline
+  (`engine.rs` 433, `runmode.rs` 153, `verify.rs` 397, `permissions.rs` 168;
+  `wasmtime_runtime.rs` non-test source < 500, inline WAT tests as ADR-161 left
+  them).

docs/adr/ADR-163-edge-latency-measurement.md

@@ -0,0 +1,123 @@
+# ADR-163: Edge-Latency Measurement — CLAIMED budgets → MEASURED-on-host
+
+- **Status**: accepted
+- **Date**: 2026-06-12
+- **Deciders**: ruv
+- **Tags**: edge-latency, wasm-edge, esp32, cog-inference, criterion, prove-everything, measurement-debt
+- **Amends**: ADR-160 (deferred "criterion benches for process_frame budget claims" line now DONE-on-host); ADR-159 (cog inference latency)
+
+## Context — Milestone 9 of the beyond-SOTA sweep
+
+Prior milestones (M5/M6, ADR-159/ADR-160) flagged **measurement debt**: edge
+latency budgets asserted in doc-comments and manifests but **never reproduced by
+a committed benchmark**. Specifically:
+
+- Many `wifi-densepose-wasm-edge` skill modules document a timing budget *"on
+  ESP32-S3 WASM3"* (e.g. `exo_time_crystal`: "H (heavy, <10 ms)"). These were
+  **CLAIMED**, not benchmarked. ADR-160's deferred backlog named exactly this:
+  *"Criterion benches for `process_frame` budget claims — ACCEPTED-FUTURE."*
+- `cog-pose-estimation`'s manifest cites `cold_start_ms_avg: 5.4`, but neither
+  cog had a `benches/` directory or any committed inference-latency number.
+
+Under the project's **prove-everything / anti-"AI-slop"** directive, a CLAIMED
+latency budget that a skeptic cannot reproduce is debt. M9 pays it down — benches
+and docs only, **no production-code behavior change** (so nothing republishes).
+
+## Headline
+
+**Converted the CLAIMED edge-latency budgets into MEASURED-on-host numbers, with
+the honest host-vs-ESP32 caveat stated everywhere.** Added committed criterion
+benches over the heaviest hot paths and a results file a skeptic can re-run. The
+ESP32-on-hardware figure remains explicitly **UNMEASURED** — this milestone does
+not pretend a laptop reproduces an Xtensa/WASM3 budget.
+
+## Decision — benches landed
+
+### T1 — wasm-edge `process_frame` budget benches
+
+`v2/crates/wifi-densepose-wasm-edge/benches/process_frame_bench.rs` (criterion,
+`harness = false`, `required-features = ["std"]`). The crate is **excluded from
+the v2 workspace**, so it runs from the crate dir. Benches the M6-audit-named
+heaviest hot paths over a **fixed synthetic CSI frame**, each driven through the
+public `process_frame` after warming the relevant ring/phase buffers so the
+expensive path actually executes:
+
+- `exo_time_crystal::process_frame` — full 256-pt × 128-lag autocorrelation.
+- `exo_ghost_hunter::process_frame` — empty-room periodicity / hidden-breathing.
+- `sec_weapon_detect::process_frame` — per-subcarrier (MAX_SC=32) Welford.
+- `med_seizure_detect::process_frame` — clonic-rhythm path (`#[cfg(feature =
+  "medical-experimental")]`, only built/run with that gate).
+
+The lib's `bench = false` was set so the libtest harness does not intercept
+criterion CLI flags; the `ghost_hunter` bin is already `standalone-bin`-gated and
+not built under `--features std`.
+
+**Measured host medians** (Intel Core Ultra 9 285H, native `--release`):
+`exo_time_crystal` **17.3 µs** · `exo_ghost_hunter` **1.44 µs** ·
+`sec_weapon_detect` **0.42 µs** · `med_seizure_detect` **0.10 µs**.
+
+### T2 — cog inference latency benches
+
+`v2/crates/cog-person-count/benches/infer_bench.rs` and
+`v2/crates/cog-pose-estimation/benches/infer_bench.rs` (criterion,
+`harness = false`). Each loads the **real** shipped weights from the in-repo
+`cog/artifacts/`, asserts the Candle CPU backend (so the stub can never be
+silently benched), warms one forward, then times steady-state
+`InferenceEngine::infer` over a fixed CSI window on `Device::Cpu`.
+
+**Measured host medians:** cog-person-count **305 µs** · cog-pose-estimation
+**305 µs** (steady-state, CPU, real weights).
+
+### T3 — results file
+
+`benchmarks/edge-latency/RESULTS.md`, in the `benchmarks/wiflow-std/RESULTS.md`
+style: each number with its exact reproduce command, the machine, the
+MEASURED-on-host grade, and the honest caveat.
+
+## The honest caveat (recorded, non-negotiable)
+
+1. **Host ≠ ESP32.** The wasm-edge benches run native x86_64, not Xtensa/WASM3.
+   A host median is an **upper bound on algorithm work**, not the ESP32 number;
+   WASM3 interpretation on a ~240 MHz core is 1–2 orders of magnitude slower than
+   native `-O`. A host median under budget does **not** prove the ESP32 meets it.
+   **The ESP32 figure is NOT reproduced here — it needs hardware.**
+2. **Bench ≠ the doc-claimed measurement.** The cogs' manifest cites a
+   **cold-start** number (weight-load included); these benches measure
+   **steady-state** per-frame `infer`. We report both, labelled, and do not
+   conflate them. Empirically, pose steady-state (305 µs host) is ~18× under the
+   5.4 ms cold-start — the expected shape, and exactly why conflating would lie.
+
+## Deferred / still-pending (nothing dropped)
+
+- **ESP32-on-hardware `process_frame` latency** — **PENDING (hardware)**. Needs
+  the `wasm32-unknown-unknown` target built + flashed to an ESP32-S3 and timed
+  under WASM3. The host bench is the algorithm-cost proxy until then.
+- **Per-skill *accuracy*** remains **DATA-GATED** (unchanged from ADR-160) —
+  this ADR measures latency only, never claims detection accuracy.
+
+## Reproduction (MEASURED)
+
+```bash
+# T1 — wasm-edge (workspace-excluded → run from the crate dir)
+cd v2/crates/wifi-densepose-wasm-edge
+cargo bench --features std -- --warm-up-time 1 --measurement-time 2
+cargo bench --features std,medical-experimental -- --warm-up-time 1 --measurement-time 2 med_seizure
+
+# T2 — cogs (workspace members)
+cd v2
+cargo bench -p cog-person-count   --no-default-features --bench infer_bench
+cargo bench -p cog-pose-estimation --no-default-features --bench infer_bench
+
+# existing tests still green (behavior unchanged)
+cargo test -p cog-person-count -p cog-pose-estimation --no-default-features
+```
+
+## Consequences
+
+- ADR-160's deferred *"Criterion benches for `process_frame` budget claims"* line
+  is now **DONE (host)**; the ESP32-on-hardware confirmation is explicitly the
+  one remaining pending item.
+- The cogs now ship committed, reproducible steady-state inference-latency
+  numbers, cleanly distinguished from the manifest's cold-start claim.
+- No runtime behavior changed; no crate republishes. `PROOF.md`'s performance
+  table and `scripts/prove.sh`'s gated section reference the new benches.

scripts/prove.sh

@@ -131,6 +131,7 @@ else
   SKIP "named person-identity — DATA-GATED: needs a real enrollment feeding the AETHER/body-resonance channel (see docs/research/soul/)"
   SKIP "OccWorld trained accuracy — needs a trained checkpoint (predict() carries weights_trained=false until then)"
   SKIP "native wlanapi 9.74 Hz scan — Windows-only; run: cargo test -p wifi-densepose-wifiscan -- --ignored measure_native_scan_rate"
+  SKIP "edge-latency benches (ADR-163) — host medians, not asserted here: (cd v2/crates/wifi-densepose-wasm-edge && cargo bench --features std) and (cd v2 && cargo bench -p cog-person-count -p cog-pose-estimation --no-default-features --bench infer_bench). HOST proxy only — the ESP32/WASM3 budget is NOT reproduced on a laptop; see benchmarks/edge-latency/RESULTS.md"
   echo "  (re-run with --full to attempt the feature-gated subset where prereqs exist)"
 fi
 hr

v2/Cargo.lock

@@ -1015,6 +1015,7 @@ dependencies = [
  "candle-core 0.9.2",
  "candle-nn 0.9.2",
  "clap",
+ "criterion",
  "safetensors 0.4.5",
  "serde",
  "serde_json",
@@ -1034,6 +1035,7 @@ dependencies = [
  "candle-core 0.9.2",
  "candle-nn 0.9.2",
  "clap",
+ "criterion",
  "hex",
  "safetensors 0.4.5",
  "serde",
@@ -3554,9 +3556,13 @@ name = "homecore-plugins"
 version = "0.1.0-alpha.0"
 dependencies = [
  "async-trait",
+ "base64 0.22.1",
+ "ed25519-dalek",
+ "hex",
  "homecore",
  "serde",
  "serde_json",
+ "sha2",
  "thiserror 1.0.69",
  "tokio",
  "uuid",

v2/crates/cog-person-count/Cargo.toml

@@ -34,6 +34,12 @@ safetensors = "0.4"
 [dev-dependencies]
 tempfile = "3"
 approx = "0.5"
+# ADR-163: steady-state infer latency bench (real count_v1 weights, Device::Cpu).
+criterion = { version = "0.5", features = ["html_reports"] }
+
+[[bench]]
+name = "infer_bench"
+harness = false
 
 [features]
 default = []

v2/crates/cog-person-count/benches/infer_bench.rs

@@ -0,0 +1,95 @@
+//! Criterion bench for `cog-person-count` steady-state inference latency
+//! (ADR-163, closing the ADR-159/160 deferred "cog inference latency bench" item).
+//!
+//! ## What this measures — and what the manifest's `cold_start_ms` does NOT
+//!
+//! This benches **steady-state** `InferenceEngine::infer` over a FIXED CSI
+//! window on `Device::Cpu` with the **real** shipped `count_v1.safetensors`
+//! weights — i.e. the per-frame cost once the model is loaded and warm.
+//!
+//! The cog manifest's `build_metadata.cold_start_ms_avg` (in the pose cog;
+//! person-count's manifest carries comparable provenance) is a **DIFFERENT
+//! measurement**: it includes one-time weight load / mmap / first-forward
+//! allocation. Cold-start is a startup cost paid once; steady-state infer is the
+//! recurring per-frame cost. They are not comparable and we do not conflate them.
+//! `cold_start` was measured on ruvultra (RTX 5080 host, candle 0.9 cpu); this
+//! bench runs on whatever machine you run it on — see `benchmarks/edge-latency/RESULTS.md`
+//! for the host the committed numbers were taken on.
+//!
+//! If the weights file is absent the engine falls back to the zero-confidence
+//! stub; we skip the bench in that case rather than benchmark the stub (which
+//! would be a meaningless number) — the bench prints a notice and measures a
+//! no-op so criterion still produces a (clearly-labelled) datapoint.
+//!
+//! Run (cog crates are normal workspace members):
+//!   cd v2 && cargo bench -p cog-person-count --no-default-features
+//!   cd v2 && cargo bench -p cog-person-count --no-default-features -- --warm-up-time 1 --measurement-time 2
+
+use std::hint::black_box;
+use std::path::Path;
+
+use criterion::{criterion_group, criterion_main, Criterion};
+
+use cog_person_count::inference::{CsiWindow, InferenceEngine, INPUT_SUBCARRIERS, INPUT_TIMESTEPS};
+
+/// Deterministic fixed CSI window (seed-stable LCG), normalised-ish amplitudes.
+fn fixed_window() -> CsiWindow {
+    let mut s = 0x00C0_FFEEu32;
+    let data: Vec<f32> = (0..INPUT_SUBCARRIERS * INPUT_TIMESTEPS)
+        .map(|_| {
+            s = s.wrapping_mul(1103515245).wrapping_add(12345);
+            (s >> 16) as f32 / 32768.0 // [0, 1)
+        })
+        .collect();
+    CsiWindow { data }
+}
+
+/// Locate the real weights from the crate dir or the repo root.
+fn real_weights() -> Option<std::path::PathBuf> {
+    let candidates = [
+        "cog/artifacts/count_v1.safetensors",
+        "v2/crates/cog-person-count/cog/artifacts/count_v1.safetensors",
+        "crates/cog-person-count/cog/artifacts/count_v1.safetensors",
+    ];
+    candidates
+        .iter()
+        .map(Path::new)
+        .find(|p| p.exists())
+        .map(|p| p.to_path_buf())
+}
+
+fn bench_infer(c: &mut Criterion) {
+    let window = fixed_window();
+
+    match real_weights() {
+        Some(path) => {
+            let engine =
+                InferenceEngine::with_weights(Some(&path)).expect("load real count_v1 weights");
+            assert!(
+                engine.backend().starts_with("candle-"),
+                "expected real Candle backend, got {} — bench would measure the stub",
+                engine.backend()
+            );
+            // Sanity: one real inference before timing.
+            let _ = engine.infer(&window).expect("warmup infer");
+
+            c.bench_function("cog_person_count::infer[cpu_real_weights_steady_state]", |b| {
+                b.iter(|| {
+                    black_box(engine.infer(black_box(&window)).expect("infer"));
+                });
+            });
+        }
+        None => {
+            eprintln!(
+                "NOTE: count_v1.safetensors not found — skipping the real-weights infer bench. \
+                 (The committed RESULTS.md numbers require the in-repo weights.)"
+            );
+            c.bench_function("cog_person_count::infer[SKIPPED_no_weights]", |b| {
+                b.iter(|| black_box(1 + 1));
+            });
+        }
+    }
+}
+
+criterion_group!(benches, bench_infer);
+criterion_main!(benches);

v2/crates/cog-pose-estimation/Cargo.toml

@@ -39,6 +39,12 @@ wifi-densepose-train = { version = "0.3.1", path = "../wifi-densepose-train", de
 
 [dev-dependencies]
 tempfile = "3"
+# ADR-163: steady-state infer latency bench (real pose_v1 weights, Device::Cpu).
+criterion = { version = "0.5", features = ["html_reports"] }
+
+[[bench]]
+name = "infer_bench"
+harness = false
 
 [features]
 default = []

v2/crates/cog-pose-estimation/benches/infer_bench.rs

@@ -0,0 +1,89 @@
+//! Criterion bench for `cog-pose-estimation` steady-state inference latency
+//! (ADR-163, closing the ADR-159/160 deferred "cog inference latency bench" item).
+//!
+//! ## What this measures — and what the manifest's `cold_start_ms_avg` does NOT
+//!
+//! The pose cog's manifest (`cog/artifacts/manifests/x86_64/manifest.json`)
+//! cites `build_metadata.cold_start_ms_avg: 5.4` (30 invocations, measured on
+//! ruvultra / RTX 5080 host, candle 0.9 cpu). **That is a cold-start number** —
+//! it folds in one-time weight load / mmap / first-forward allocation.
+//!
+//! This bench measures the **steady-state** per-frame cost instead:
+//! `InferenceEngine::infer` over a FIXED CSI window on `Device::Cpu` with the
+//! **real** shipped `pose_v1.safetensors`, after a warm-up forward. Steady-state
+//! and cold-start are different measurements; we label both honestly and do not
+//! claim this reproduces the 5.4 ms manifest figure (different machine, different
+//! measurement). See `benchmarks/edge-latency/RESULTS.md`.
+//!
+//! Run (cog crates are normal workspace members):
+//!   cd v2 && cargo bench -p cog-pose-estimation --no-default-features
+//!   cd v2 && cargo bench -p cog-pose-estimation --no-default-features -- --warm-up-time 1 --measurement-time 2
+
+use std::hint::black_box;
+use std::path::Path;
+
+use criterion::{criterion_group, criterion_main, Criterion};
+
+use cog_pose_estimation::inference::{
+    CsiWindow, InferenceEngine, INPUT_SUBCARRIERS, INPUT_TIMESTEPS,
+};
+
+/// Deterministic fixed CSI window (seed-stable LCG).
+fn fixed_window() -> CsiWindow {
+    let mut s = 0x00C0_FFEEu32;
+    let data: Vec<f32> = (0..INPUT_SUBCARRIERS * INPUT_TIMESTEPS)
+        .map(|_| {
+            s = s.wrapping_mul(1103515245).wrapping_add(12345);
+            (s >> 16) as f32 / 32768.0 // [0, 1)
+        })
+        .collect();
+    CsiWindow { data }
+}
+
+fn real_weights() -> Option<std::path::PathBuf> {
+    let candidates = [
+        "cog/artifacts/pose_v1.safetensors",
+        "v2/crates/cog-pose-estimation/cog/artifacts/pose_v1.safetensors",
+        "crates/cog-pose-estimation/cog/artifacts/pose_v1.safetensors",
+    ];
+    candidates
+        .iter()
+        .map(Path::new)
+        .find(|p| p.exists())
+        .map(|p| p.to_path_buf())
+}
+
+fn bench_infer(c: &mut Criterion) {
+    let window = fixed_window();
+
+    match real_weights() {
+        Some(path) => {
+            let engine =
+                InferenceEngine::with_weights(Some(&path)).expect("load real pose_v1 weights");
+            assert!(
+                engine.backend().starts_with("candle-"),
+                "expected real Candle backend, got {} — bench would measure the stub",
+                engine.backend()
+            );
+            let _ = engine.infer(&window).expect("warmup infer");
+
+            c.bench_function("cog_pose_estimation::infer[cpu_real_weights_steady_state]", |b| {
+                b.iter(|| {
+                    black_box(engine.infer(black_box(&window)).expect("infer"));
+                });
+            });
+        }
+        None => {
+            eprintln!(
+                "NOTE: pose_v1.safetensors not found — skipping the real-weights infer bench. \
+                 (The committed RESULTS.md numbers require the in-repo weights.)"
+            );
+            c.bench_function("cog_pose_estimation::infer[SKIPPED_no_weights]", |b| {
+                b.iter(|| black_box(1 + 1));
+            });
+        }
+    }
+}
+
+criterion_group!(benches, bench_infer);
+criterion_main!(benches);

v2/crates/homecore-automation/src/engine.rs

@@ -3,14 +3,15 @@
 //!
 //! ADR-129 §2 design: one Tokio task per running automation instance.
 //!
-//! ## Run modes (ADR-161, HC-WS-05)
+//! ## Run modes (ADR-161 §A5 → completed in ADR-162)
 //!
-//! `RunMode::Single` is enforced via a per-automation `AtomicBool`
-//! guard: while an instance is executing, a second trigger is skipped.
-//! `Parallel` (and the as-yet-unbounded `Restart`/`Queued`) spawn a
-//! fresh instance on every trigger. (Before this fix the doc claimed
-//! AtomicBool enforcement but every trigger spawned unbounded parallel
-//! tasks regardless of `mode`.)
+//! Each registered automation owns a [`RunState`] that implements its
+//! `RunMode`: `Single`/`IgnoreFirst` skip re-entrant triggers, `Restart`
+//! aborts the in-flight run and starts a fresh one, `Queued` serializes
+//! runs in arrival order (nothing dropped), `Parallel` spawns on every
+//! trigger, and `max: N` caps concurrency via a per-automation semaphore.
+//! (ADR-161 only honored Single/Parallel; Restart/Queued/max were
+//! honestly documented as unbounded-parallel until ADR-162.)
 //!
 //! ## Time triggers (ADR-161, HC-WS-04)
 //!
@@ -26,7 +27,6 @@
 //! `EvalContext::with_templates`), so `template:` conditions evaluate
 //! against live state instead of always returning false.
 
-use std::sync::atomic::{AtomicBool, Ordering};
 use std::sync::{Arc, Mutex};
 
 use chrono::{Local, Timelike};
@@ -34,18 +34,18 @@ use tokio::sync::broadcast;
 
 use homecore::HomeCore;
 
-use crate::action::ExecutionContext;
-use crate::automation::{Automation, RunMode};
+use crate::automation::Automation;
 use crate::condition::EvalContext;
+use crate::runmode::RunState;
 use crate::template::TemplateEnvironment;
 use crate::trigger::{Trigger, TriggerContext};
 
 /// An automation registered with the engine, plus its runtime run-state.
 struct Registered {
     auto: Arc<Automation>,
-    /// `true` while a `Single`-mode instance is executing. Used to
-    /// skip re-entrant triggers (HC-WS-05).
-    running: Arc<AtomicBool>,
+    /// Run-mode machinery (re-entrancy guard / restart abort handle /
+    /// queue mutex / concurrency semaphore) for this automation.
+    run_state: RunState,
 }
 
 /// The automation engine. Holds a HOMECORE handle and a list of registered
@@ -69,9 +69,10 @@ impl AutomationEngine {
 
     /// Register an automation. Can be called before or after `start()`.
     pub fn register(&self, automation: Automation) {
+        let run_state = RunState::new(&automation);
         self.automations.lock().unwrap().push(Registered {
             auto: Arc::new(automation),
-            running: Arc::new(AtomicBool::new(false)),
+            run_state,
         });
     }
 
@@ -118,13 +119,13 @@ impl AutomationEngine {
             loop {
                 match rx.recv().await {
                     Ok(event) => {
-                        let snapshot: Vec<(Arc<Automation>, Arc<AtomicBool>)> = automations
+                        let snapshot: Vec<(Arc<Automation>, RunState)> = automations
                             .lock()
                             .unwrap()
                             .iter()
-                            .map(|r| (Arc::clone(&r.auto), Arc::clone(&r.running)))
+                            .map(|r| (Arc::clone(&r.auto), r.run_state.clone()))
                             .collect();
-                        for (automation, running) in snapshot {
+                        for (automation, run_state) in snapshot {
                             if !automation.enabled {
                                 continue;
                             }
@@ -148,7 +149,7 @@ impl AutomationEngine {
                             if !conditions_pass(&automation, &eval_ctx).await {
                                 continue;
                             }
-                            spawn_run(&hc, automation, running);
+                            run_state.dispatch(&hc, automation);
                         }
                     }
                     Err(broadcast::error::RecvError::Closed) => break,
@@ -183,14 +184,14 @@ impl AutomationEngine {
                         if last_fired_sec.as_deref() == Some(hhmmss.as_str()) {
                             continue;
                         }
-                        let snapshot: Vec<(Arc<Automation>, Arc<AtomicBool>)> = automations
+                        let snapshot: Vec<(Arc<Automation>, RunState)> = automations
                             .lock()
                             .unwrap()
                             .iter()
-                            .map(|r| (Arc::clone(&r.auto), Arc::clone(&r.running)))
+                            .map(|r| (Arc::clone(&r.auto), r.run_state.clone()))
                             .collect();
                         let mut fired_any = false;
-                        for (automation, running) in snapshot {
+                        for (automation, run_state) in snapshot {
                             if !automation.enabled {
                                 continue;
                             }
@@ -208,7 +209,7 @@ impl AutomationEngine {
                             if !conditions_pass(&automation, &eval_ctx).await {
                                 continue;
                             }
-                            spawn_run(&hc, automation, running);
+                            run_state.dispatch(&hc, automation);
                             fired_any = true;
                         }
                         if fired_any {
@@ -231,15 +232,15 @@ impl AutomationEngine {
     /// wall-clock second to roll over. Returns the number of automations
     /// that fired (passed conditions and were spawned).
     pub async fn fire_time_for_test(&self, hhmmss: &str) -> usize {
-        let snapshot: Vec<(Arc<Automation>, Arc<AtomicBool>)> = self
+        let snapshot: Vec<(Arc<Automation>, RunState)> = self
             .automations
             .lock()
             .unwrap()
             .iter()
-            .map(|r| (Arc::clone(&r.auto), Arc::clone(&r.running)))
+            .map(|r| (Arc::clone(&r.auto), r.run_state.clone()))
             .collect();
         let mut fired = 0usize;
-        for (automation, running) in snapshot {
+        for (automation, run_state) in snapshot {
             if !automation.enabled {
                 continue;
             }
@@ -254,7 +255,7 @@ impl AutomationEngine {
             if !conditions_pass(&automation, &eval_ctx).await {
                 continue;
             }
-            spawn_run(&self.hc, automation, running);
+            run_state.dispatch(&self.hc, automation);
             fired += 1;
         }
         fired
@@ -281,36 +282,6 @@ fn time_at_matches(at: &str, hhmmss: &str) -> bool {
     normalized == hhmmss
 }
 
-/// Spawn an automation run, honoring `RunMode::Single` re-entrancy
-/// guard (HC-WS-05). For `Single`/`IgnoreFirst` modes a run already in
-/// flight causes the new trigger to be skipped; the `running` flag is
-/// cleared when the run finishes.
-fn spawn_run(hc: &HomeCore, automation: Arc<Automation>, running: Arc<AtomicBool>) {
-    let single = matches!(automation.mode, RunMode::Single | RunMode::IgnoreFirst);
-    if single {
-        // Try to claim the running slot; if already running, skip.
-        if running
-            .compare_exchange(false, true, Ordering::SeqCst, Ordering::SeqCst)
-            .is_err()
-        {
-            return;
-        }
-    }
-    let hc_clone = hc.clone();
-    tokio::spawn(async move {
-        let mut exec_ctx = ExecutionContext::new(hc_clone, automation.id.clone());
-        for action in &automation.action {
-            if let Err(e) = action.execute(&mut exec_ctx).await {
-                eprintln!("[homecore-automation] action error in {}: {e}", automation.id);
-                break;
-            }
-        }
-        if single {
-            running.store(false, Ordering::SeqCst);
-        }
-    });
-}
-
 #[cfg(test)]
 mod tests {
     use super::*;

v2/crates/homecore-automation/src/lib.rs

@@ -19,6 +19,7 @@ pub mod condition;
 pub mod action;
 pub mod template;
 pub mod engine;
+pub mod runmode;
 pub mod error;
 
 pub use automation::{Automation, RunMode};

v2/crates/homecore-automation/src/runmode.rs

@@ -0,0 +1,153 @@
+//! Per-automation run-mode machinery (ADR-162, completes ADR-161 §A5).
+//!
+//! ADR-161 implemented `RunMode::Single` (a per-automation `AtomicBool`
+//! re-entrancy guard) and `Parallel`, but honestly left `Restart`, `Queued`
+//! and `max: N` as "ACCEPTED-FUTURE / unbounded parallel" — every non-Single
+//! mode spawned an unbounded task. This module makes them real:
+//!
+//! | Mode | Semantics implemented |
+//! |------|-----------------------|
+//! | `Single` / `IgnoreFirst` | re-entrancy guard: skip while a run is in flight (ADR-161). |
+//! | `Restart` | **cancel** the in-flight run (`tokio::task::AbortHandle`) and start a fresh one. |
+//! | `Queued` | **serialize**: runs execute sequentially in arrival order via a per-automation async mutex — nothing is dropped. |
+//! | `Parallel` | spawn on every trigger (optionally capped, see below). |
+//! | `max: N` | cap concurrency at **N** via a per-automation semaphore; triggers beyond N **queue** (await a permit) rather than running concurrently — matching HA's bounded `parallel`/`queued`. |
+//!
+//! Each registered automation owns one [`RunState`]; the engine calls
+//! [`RunState::dispatch`] on every (trigger + conditions-passed) event.
+
+use std::sync::atomic::{AtomicBool, Ordering};
+use std::sync::{Arc, Mutex};
+
+use tokio::sync::{Mutex as AsyncMutex, Semaphore};
+
+use homecore::HomeCore;
+
+use crate::action::ExecutionContext;
+use crate::automation::{Automation, RunMode};
+
+/// Per-automation runtime state backing the run-mode dispatch.
+///
+/// Cheap to clone (all fields are `Arc`); the engine clones it into each
+/// spawned run so the machinery (abort handle, queue mutex, semaphore) is
+/// shared across all triggers of the same automation.
+#[derive(Clone)]
+pub struct RunState {
+    /// `Single`/`IgnoreFirst` re-entrancy guard (ADR-161 §A5).
+    running: Arc<AtomicBool>,
+    /// `Restart`: handle to the currently-running action task, so a new
+    /// trigger can abort it before starting a fresh one.
+    current: Arc<Mutex<Option<tokio::task::AbortHandle>>>,
+    /// `Queued`: serializes runs in arrival order (one at a time, FIFO via
+    /// fair async mutex acquisition).
+    queue_lock: Arc<AsyncMutex<()>>,
+    /// `max: N` (and bounded `Parallel`): caps concurrent runs at N.
+    /// `None` when no cap applies.
+    semaphore: Option<Arc<Semaphore>>,
+}
+
+impl RunState {
+    /// Build run-state for an automation, sizing the concurrency semaphore
+    /// from its `max:` field (only meaningful for `Queued`/`Parallel`).
+    pub fn new(automation: &Automation) -> Self {
+        let semaphore = automation
+            .max
+            .filter(|n| *n > 0)
+            .map(|n| Arc::new(Semaphore::new(n)));
+        Self {
+            running: Arc::new(AtomicBool::new(false)),
+            current: Arc::new(Mutex::new(None)),
+            queue_lock: Arc::new(AsyncMutex::new(())),
+            semaphore,
+        }
+    }
+
+    /// Dispatch one trigger for `automation` according to its `RunMode`.
+    /// Honors Single re-entrancy, Restart cancel-and-replace, Queued
+    /// serialization, and `max:` concurrency capping.
+    pub fn dispatch(&self, hc: &HomeCore, automation: Arc<Automation>) {
+        match automation.mode {
+            RunMode::Single | RunMode::IgnoreFirst => self.dispatch_single(hc, automation),
+            RunMode::Restart => self.dispatch_restart(hc, automation),
+            RunMode::Queued => self.dispatch_queued(hc, automation),
+            RunMode::Parallel => self.dispatch_parallel(hc, automation),
+        }
+    }
+
+    /// `Single`: skip if a run is already in flight; clear the flag on done.
+    fn dispatch_single(&self, hc: &HomeCore, automation: Arc<Automation>) {
+        if self
+            .running
+            .compare_exchange(false, true, Ordering::SeqCst, Ordering::SeqCst)
+            .is_err()
+        {
+            return; // already running — skip re-entrant trigger.
+        }
+        let hc = hc.clone();
+        let running = Arc::clone(&self.running);
+        tokio::spawn(async move {
+            run_actions(&hc, &automation).await;
+            running.store(false, Ordering::SeqCst);
+        });
+    }
+
+    /// `Restart`: abort the in-flight run (if any), then start a fresh one
+    /// and record its abort handle.
+    fn dispatch_restart(&self, hc: &HomeCore, automation: Arc<Automation>) {
+        // Abort any prior run before starting the new one.
+        if let Some(prev) = self.current.lock().unwrap().take() {
+            prev.abort();
+        }
+        let hc = hc.clone();
+        let slot = Arc::clone(&self.current);
+        let handle = tokio::spawn(async move {
+            run_actions(&hc, &automation).await;
+        });
+        *slot.lock().unwrap() = Some(handle.abort_handle());
+    }
+
+    /// `Queued`: serialize via the per-automation async mutex. Each trigger
+    /// spawns a task that waits its turn, so all triggers run in arrival
+    /// order, one at a time — nothing is dropped.
+    fn dispatch_queued(&self, hc: &HomeCore, automation: Arc<Automation>) {
+        let hc = hc.clone();
+        let lock = Arc::clone(&self.queue_lock);
+        let sem = self.semaphore.clone();
+        tokio::spawn(async move {
+            // Optional `max:` cap still applies on top of serialization.
+            let _permit = match &sem {
+                Some(s) => Some(s.acquire().await.expect("semaphore not closed")),
+                None => None,
+            };
+            let _guard = lock.lock().await; // FIFO turn — sequential execution.
+            run_actions(&hc, &automation).await;
+        });
+    }
+
+    /// `Parallel`: spawn on every trigger, capped at `max:` if set.
+    fn dispatch_parallel(&self, hc: &HomeCore, automation: Arc<Automation>) {
+        let hc = hc.clone();
+        let sem = self.semaphore.clone();
+        tokio::spawn(async move {
+            let _permit = match &sem {
+                Some(s) => Some(s.acquire().await.expect("semaphore not closed")),
+                None => None,
+            };
+            run_actions(&hc, &automation).await;
+        });
+    }
+}
+
+/// Execute an automation's action sequence once.
+async fn run_actions(hc: &HomeCore, automation: &Automation) {
+    let mut exec_ctx = ExecutionContext::new(hc.clone(), automation.id.clone());
+    for action in &automation.action {
+        if let Err(e) = action.execute(&mut exec_ctx).await {
+            eprintln!(
+                "[homecore-automation] action error in {}: {e}",
+                automation.id
+            );
+            break;
+        }
+    }
+}

v2/crates/homecore-automation/tests/engine_behaviors.rs

@@ -257,3 +257,162 @@ async fn template_condition_evaluates_false_blocks_action() {
     sleep(Duration::from_millis(50)).await;
     assert_eq!(log.lock().unwrap().len(), 0, "false template condition should block the action");
 }
+
+// ── ADR-162 (completes ADR-161 §A5): bounded RunModes ───────────────
+//
+// ADR-161 honored only Single/Parallel; Restart/Queued/max were honestly
+// documented as unbounded-parallel. These tests drive the real
+// Restart/Queued/max machinery and FAIL on the old engine (where every
+// non-Single mode spawned an unbounded parallel task).
+
+/// A service that increments a live concurrency gauge on entry, sleeps,
+/// then decrements — recording the maximum concurrency ever observed and
+/// the total number of completed runs. Returns `(max_concurrency, completed)`.
+async fn register_gauge(
+    hc: &HomeCore,
+    domain: &str,
+    service: &str,
+    work: Duration,
+) -> (Arc<AtomicUsize>, Arc<AtomicUsize>) {
+    let live = Arc::new(AtomicUsize::new(0));
+    let max_seen = Arc::new(AtomicUsize::new(0));
+    let completed = Arc::new(AtomicUsize::new(0));
+    let (l, m, c) = (Arc::clone(&live), Arc::clone(&max_seen), Arc::clone(&completed));
+    hc.services()
+        .register(
+            ServiceName::new(domain, service),
+            FnHandler(move |_call: ServiceCall| {
+                let (l, m, c) = (Arc::clone(&l), Arc::clone(&m), Arc::clone(&c));
+                async move {
+                    let now = l.fetch_add(1, Ordering::SeqCst) + 1;
+                    m.fetch_max(now, Ordering::SeqCst);
+                    sleep(work).await;
+                    l.fetch_sub(1, Ordering::SeqCst);
+                    c.fetch_add(1, Ordering::SeqCst);
+                    Ok(serde_json::Value::Null)
+                }
+            }),
+        )
+        .await;
+    (max_seen, completed)
+}
+
+fn state_auto(id: &str, entity: &str, domain: &str, service: &str) -> Automation {
+    Automation::new(
+        id,
+        vec![Trigger::State {
+            entity_id: EntityId::parse(entity).unwrap(),
+            from: None,
+            to: None,
+        }],
+        vec![Action::ServiceCall {
+            domain: domain.into(),
+            service: service.into(),
+            data: serde_json::json!({}),
+        }],
+    )
+}
+
+// ── Restart: cancels the in-flight run ─────────────────────────────
+#[tokio::test]
+async fn restart_mode_cancels_prior_run() {
+    let hc = HomeCore::new();
+    // Each run sleeps 300ms before recording completion.
+    let (_max, completed) =
+        register_gauge(&hc, "light", "slow", Duration::from_millis(300)).await;
+
+    let engine = AutomationEngine::new(hc.clone());
+    let mut auto = state_auto("restart_auto", "switch.r", "light", "slow");
+    auto.mode = RunMode::Restart;
+    engine.register(auto);
+    let _handle = engine.start();
+
+    // Trigger 1 starts the slow run.
+    hc.states().set(EntityId::parse("switch.r").unwrap(), "a", serde_json::json!({}), Context::new());
+    sleep(Duration::from_millis(80)).await;
+    // Trigger 2 arrives mid-run → must ABORT run 1 and start run 2.
+    hc.states().set(EntityId::parse("switch.r").unwrap(), "b", serde_json::json!({}), Context::new());
+
+    // Wait long enough for run 2 (started ~80ms in) to finish, but run 1
+    // (aborted at ~80ms, would have finished at ~300ms) must NOT complete.
+    sleep(Duration::from_millis(400)).await;
+    assert_eq!(
+        completed.load(Ordering::SeqCst),
+        1,
+        "Restart must cancel the in-flight run: exactly the restarted run completes (not both). \
+         On the old engine both ran to completion → 2."
+    );
+}
+
+// ── Queued: serialize N rapid triggers, all run, never concurrent ──
+#[tokio::test]
+async fn queued_mode_runs_sequentially_not_concurrently() {
+    let hc = HomeCore::new();
+    let (max_seen, completed) =
+        register_gauge(&hc, "light", "slow", Duration::from_millis(120)).await;
+
+    let engine = AutomationEngine::new(hc.clone());
+    let mut auto = state_auto("queued_auto", "switch.q", "light", "slow");
+    auto.mode = RunMode::Queued;
+    engine.register(auto);
+    let _handle = engine.start();
+
+    // Three rapid triggers.
+    for v in ["a", "b", "c"] {
+        hc.states().set(EntityId::parse("switch.q").unwrap(), v, serde_json::json!({}), Context::new());
+        sleep(Duration::from_millis(10)).await;
+    }
+
+    // 3 runs × 120ms serialized ≈ 360ms; wait generously.
+    sleep(Duration::from_millis(600)).await;
+    assert_eq!(
+        completed.load(Ordering::SeqCst),
+        3,
+        "Queued must run every trigger (nothing dropped)"
+    );
+    assert_eq!(
+        max_seen.load(Ordering::SeqCst),
+        1,
+        "Queued must never run two instances concurrently. On the old engine all 3 ran in \
+         parallel → max concurrency 3."
+    );
+}
+
+// ── max: 2 → never more than 2 concurrent ──────────────────────────
+#[tokio::test]
+async fn max_two_caps_concurrency_at_two() {
+    let hc = HomeCore::new();
+    let (max_seen, completed) =
+        register_gauge(&hc, "light", "slow", Duration::from_millis(150)).await;
+
+    let engine = AutomationEngine::new(hc.clone());
+    let mut auto = state_auto("max_auto", "switch.m", "light", "slow");
+    auto.mode = RunMode::Parallel;
+    auto.max = Some(2);
+    engine.register(auto);
+    let _handle = engine.start();
+
+    // Four rapid triggers — without the cap all 4 would run at once.
+    for v in ["a", "b", "c", "d"] {
+        hc.states().set(EntityId::parse("switch.m").unwrap(), v, serde_json::json!({}), Context::new());
+        sleep(Duration::from_millis(10)).await;
+    }
+
+    sleep(Duration::from_millis(600)).await;
+    assert_eq!(
+        completed.load(Ordering::SeqCst),
+        4,
+        "max:2 must still run all 4 triggers (queued beyond the cap, not dropped)"
+    );
+    assert!(
+        max_seen.load(Ordering::SeqCst) <= 2,
+        "max:2 must never exceed 2 concurrent runs (observed {}). On the old engine all 4 ran \
+         concurrently → 4.",
+        max_seen.load(Ordering::SeqCst)
+    );
+    assert!(
+        max_seen.load(Ordering::SeqCst) >= 2,
+        "max:2 should reach the cap of 2 with 4 rapid triggers (observed {})",
+        max_seen.load(Ordering::SeqCst)
+    );
+}

v2/crates/homecore-plugins/Cargo.toml

@@ -50,6 +50,15 @@ serde_json = "1"
 # UUIDs for config entry IDs in host_abi.rs.
 uuid = { version = "1", features = ["v4"] }
 
+# ── ADR-162 P4: plugin signature + integrity verification ──────────────────
+# Reuses the same in-repo crypto stack as cog-ha-matter (witness_signing.rs):
+# Ed25519 over a SHA-256 module digest. All four are already in the workspace
+# Cargo.lock (cog-ha-matter / bfld pull them in) — no new external dep tree.
+ed25519-dalek = "2.1"
+sha2 = { workspace = true }
+hex = "0.4"
+base64 = "0.22"
+
 # Optional Wasmtime runtime (P2, default-off — 30 MB dep).
 # Bumped from 25.0.3 → 42 to remediate RUSTSEC-2026-0095 and RUSTSEC-2026-0096
 # (Cranelift/Winch sandbox-escape CVEs, CVSS 9.0 — iter-11 security sprint HC-03/04).

v2/crates/homecore-plugins/src/error.rs

@@ -25,6 +25,18 @@ pub enum PluginError {
     #[error("plugin setup failed: {0}")]
     SetupFailed(String),
 
+    /// The plugin failed signature/integrity verification (ADR-162 P4):
+    /// hash mismatch, bad signature, untrusted publisher, or unsigned
+    /// module under a non-dev trust policy.
+    #[error("plugin signature rejected: {0}")]
+    SignatureRejected(String),
+
+    /// A plugin attempted a host call (e.g. `hc_state_set`) on an entity
+    /// it did not declare in `homecore_permissions` (ADR-162 P5 authority
+    /// isolation).
+    #[error("plugin permission denied: {0}")]
+    PermissionDenied(String),
+
     /// The plugin's `unload` hook returned an error.
     #[error("plugin unload failed: {0}")]
     UnloadFailed(String),

v2/crates/homecore-plugins/src/lib.rs

@@ -22,8 +22,16 @@
 //! - Host ABI wiring: `hc_state_get`, `hc_state_set`, `hc_event_fire`, etc.
 //!   (P2 — requires ADR-127 state machine API freeze first).
 //! - Config entry lifecycle + hot-load (P3).
-//! - Cog registry distribution + Ed25519 signature verification (P4).
-//! - Permission enforcement (P5).
+//!
+//! ## Now enforced (ADR-162)
+//!
+//! - **Ed25519 signature + SHA-256 integrity verification (P4)** — see
+//!   [`verify`]: the plugin load path hashes the real `.wasm` bytes, checks
+//!   the manifest `wasm_module_hash`, verifies `wasm_module_sig` against
+//!   `publisher_key`, and enforces a [`verify::PluginPolicy`] allowlist.
+//! - **Permission / authority isolation (P5)** — see [`permissions`]: a
+//!   plugin's `hc_state_set` writes are gated against the entity domains/
+//!   globs it declared in `homecore_permissions`.
 //!
 //! ## Feature flags
 //!
@@ -35,9 +43,11 @@
 pub mod error;
 pub mod host_abi;
 pub mod manifest;
+pub mod permissions;
 pub mod plugin;
 pub mod registry;
 pub mod runtime;
+pub mod verify;
 
 #[cfg(feature = "wasmtime")]
 pub mod wasmtime_runtime;
@@ -45,9 +55,11 @@ pub mod wasmtime_runtime;
 pub use error::PluginError;
 pub use host_abi::{ConfigEntryJson, StateChangedEventJson};
 pub use manifest::{IotClass, IntegrationType, PluginManifest};
+pub use permissions::PermissionSet;
 pub use plugin::{HomeCorePlugin, PluginId};
 pub use registry::PluginRegistry;
 pub use runtime::{InProcessRuntime, LoadedPlugin, PluginRuntime};
+pub use verify::{verify_module, PluginPolicy};
 
 #[cfg(feature = "wasmtime")]
 pub use wasmtime_runtime::{WasmPlugin, WasmtimeRuntime};

v2/crates/homecore-plugins/src/manifest.rs

@@ -85,24 +85,26 @@ pub struct PluginManifest {
 
     /// [HOMECORE] `sha256:<hex>` hash of the wasm binary.
     ///
-    /// **(P4 — not yet enforced, ADR-161/B5):** this field is parsed and
-    /// round-tripped but is NOT verified before execution. The hash/sig
-    /// gate lands in P4; until then the presence of this field implies no
-    /// integrity guarantee.
+    /// **(P4 — ENFORCED, ADR-162):** `verify::verify_module` computes the
+    /// SHA-256 of the real `.wasm` bytes on load and rejects the module if
+    /// it does not equal this hash (tamper detection). See [`crate::verify`].
     #[serde(default, skip_serializing_if = "Option::is_none")]
     pub wasm_module_hash: Option<String>,
 
     /// [HOMECORE] Ed25519 signature of the wasm binary hash (`ed25519:<base64>`).
     ///
-    /// **(P4 — not yet enforced, ADR-161/B5):** parsed but never checked.
-    /// No signature verification happens before a plugin runs.
+    /// **(P4 — ENFORCED, ADR-162):** verified against `publisher_key` over
+    /// the SHA-256 module digest before instantiation. A bad/forged/absent
+    /// signature is rejected under the secure trust policy (the
+    /// `cog-ha-matter::witness_signing` Ed25519 pattern is reused).
     #[serde(default, skip_serializing_if = "Option::is_none")]
     pub wasm_module_sig: Option<String>,
 
     /// [HOMECORE] Ed25519 public key of the plugin publisher.
     ///
-    /// **(P4 — not yet enforced, ADR-161/B5):** parsed but never used to
-    /// verify `wasm_module_sig`.
+    /// **(P4 — ENFORCED, ADR-162):** used to verify `wasm_module_sig`, and
+    /// checked against the host's [`crate::verify::PluginPolicy`] trust
+    /// allowlist — an unknown publisher is rejected by the secure default.
     #[serde(default, skip_serializing_if = "Option::is_none")]
     pub publisher_key: Option<String>,
 
@@ -115,6 +117,12 @@ pub struct PluginManifest {
     pub host_imports_required: Vec<String>,
 
     /// [HOMECORE] Coarse-grained permission claims (glob patterns).
+    ///
+    /// **(P5 — ENFORCED, ADR-162):** `state:write:<glob>` (or a bare entity
+    /// glob like `light.*`) grants are parsed into a
+    /// [`crate::permissions::PermissionSet` ] and consulted by the
+    /// `hc_state_set` host import. A plugin can no longer write an entity it
+    /// did not declare; a plugin with no write grants can write nothing.
     #[serde(default)]
     pub homecore_permissions: Vec<PermissionClaim>,
 

v2/crates/homecore-plugins/src/permissions.rs

@@ -0,0 +1,168 @@
+//! Plugin authority / capability isolation (ADR-162, P5).
+//!
+//! Wasmtime already gives a plugin **memory** isolation — it cannot read
+//! another plugin's linear memory. It does NOT, by itself, stop a plugin
+//! from using a host import to write any entity it likes. Before this fix
+//! `hc_state_set` happily let any plugin write `lock.front_door` or
+//! `alarm_control_panel.*`, and the manifest's `homecore_permissions`
+//! claims were parsed but **never consulted** (ADR-161 deferred P5).
+//!
+//! This module adds **authority isolation**: a plugin may only write
+//! entities its manifest declared. The host import consults a
+//! [`PermissionSet`] before applying any state write and returns a typed
+//! error to the guest (it does **not** panic the host) on a violation.
+//!
+//! ## Permission grammar
+//!
+//! Each entry in `homecore_permissions` is one of:
+//!
+//!   * a bare entity glob — `"light.*"`, `"light.kitchen"`, `"*"`;
+//!   * the explicit capability form `"state:write:<glob>"` (the form the
+//!     ADR-128 manifest doc shows), e.g. `"state:write:sensor.*"`.
+//!
+//! A glob supports a single trailing `*` (HA-style domain wildcards:
+//! `light.*` matches every `light` entity) and a leading-or-bare `*`
+//! (`*` = everything). Exact strings match exactly. A plugin with **no**
+//! `state:write` entries can write **nothing** — the secure default.
+
+use crate::manifest::PluginManifest;
+
+/// The set of entity-write permissions a plugin holds, distilled from its
+/// manifest `homecore_permissions` at load time.
+#[derive(Debug, Clone, Default)]
+pub struct PermissionSet {
+    /// Glob patterns the plugin may write (state:write authority). Empty =
+    /// the plugin may write nothing.
+    write_globs: Vec<String>,
+}
+
+impl PermissionSet {
+    /// Build a permission set from a manifest's `homecore_permissions`.
+    ///
+    /// Only `state:write` authority is modelled here (the host import this
+    /// gates is `hc_state_set`). A bare glob (`"light.*"`) is treated as a
+    /// write grant; the explicit `"state:write:<glob>"` form is also
+    /// accepted. Other capability strings (`state:read:*`, future verbs)
+    /// are ignored for write-gating purposes.
+    pub fn from_manifest(manifest: &PluginManifest) -> Self {
+        let mut write_globs = Vec::new();
+        for claim in &manifest.homecore_permissions {
+            let claim = claim.trim();
+            if let Some(glob) = claim.strip_prefix("state:write:") {
+                write_globs.push(glob.trim().to_string());
+            } else if claim.starts_with("state:read:") {
+                // read authority — not relevant to write gating.
+            } else if !claim.is_empty() {
+                // Bare glob — treat as a write grant.
+                write_globs.push(claim.to_string());
+            }
+        }
+        Self { write_globs }
+    }
+
+    /// An all-allowing set (equivalent to a `"*"` grant). Used by the
+    /// legacy permission-free `WasmtimeRuntime::load_wasm` path so existing
+    /// callers/tests that do not supply a manifest keep working; the
+    /// permission-gated path uses [`Self::from_manifest`].
+    pub fn allow_all() -> Self {
+        Self {
+            write_globs: vec!["*".to_string()],
+        }
+    }
+
+    /// May this plugin write the given entity id (e.g. `"light.kitchen"`)?
+    pub fn may_write(&self, entity_id: &str) -> bool {
+        self.write_globs.iter().any(|g| glob_matches(g, entity_id))
+    }
+
+    /// Number of write-grant globs (0 = can write nothing).
+    pub fn write_grant_count(&self) -> usize {
+        self.write_globs.len()
+    }
+}
+
+/// Match `entity_id` against a single glob pattern.
+///
+/// Supported forms:
+///   * `"*"`              → matches anything.
+///   * `"light.*"`        → trailing wildcard: any id with the `light.` prefix.
+///   * `"light.kitchen"`  → exact match.
+fn glob_matches(pattern: &str, entity_id: &str) -> bool {
+    if pattern == "*" {
+        return true;
+    }
+    if let Some(prefix) = pattern.strip_suffix('*') {
+        return entity_id.starts_with(prefix);
+    }
+    pattern == entity_id
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    fn manifest_with(perms: &[&str]) -> PluginManifest {
+        PluginManifest {
+            domain: "p".into(),
+            name: "P".into(),
+            version: "1".into(),
+            documentation: None,
+            iot_class: None,
+            config_flow: false,
+            integration_type: None,
+            dependencies: vec![],
+            requirements: vec![],
+            wasm_module: None,
+            wasm_module_hash: None,
+            wasm_module_sig: None,
+            publisher_key: None,
+            min_homecore_version: None,
+            host_imports_required: vec![],
+            homecore_permissions: perms.iter().map(|s| s.to_string()).collect(),
+            cog_id: None,
+        }
+    }
+
+    #[test]
+    fn domain_glob_allows_same_domain_only() {
+        let ps = PermissionSet::from_manifest(&manifest_with(&["light.*"]));
+        assert!(ps.may_write("light.kitchen"));
+        assert!(ps.may_write("light.bedroom"));
+        assert!(!ps.may_write("lock.front_door"));
+        assert!(!ps.may_write("alarm_control_panel.home"));
+    }
+
+    #[test]
+    fn no_permissions_can_write_nothing() {
+        let ps = PermissionSet::from_manifest(&manifest_with(&[]));
+        assert_eq!(ps.write_grant_count(), 0);
+        assert!(!ps.may_write("light.kitchen"));
+        assert!(!ps.may_write("sensor.temp"));
+    }
+
+    #[test]
+    fn explicit_state_write_form_is_honored() {
+        let ps = PermissionSet::from_manifest(&manifest_with(&["state:write:sensor.*"]));
+        assert!(ps.may_write("sensor.temp"));
+        assert!(!ps.may_write("light.kitchen"));
+    }
+
+    #[test]
+    fn read_grants_do_not_confer_write() {
+        let ps = PermissionSet::from_manifest(&manifest_with(&["state:read:lock.*"]));
+        assert!(!ps.may_write("lock.front_door"));
+    }
+
+    #[test]
+    fn exact_entity_grant_is_scoped() {
+        let ps = PermissionSet::from_manifest(&manifest_with(&["light.kitchen"]));
+        assert!(ps.may_write("light.kitchen"));
+        assert!(!ps.may_write("light.bedroom"));
+    }
+
+    #[test]
+    fn wildcard_grants_everything() {
+        let ps = PermissionSet::from_manifest(&manifest_with(&["*"]));
+        assert!(ps.may_write("lock.front_door"));
+    }
+}

v2/crates/homecore-plugins/src/verify.rs

@@ -0,0 +1,397 @@
+//! Plugin signature & integrity verification (ADR-162, P4).
+//!
+//! ADR-161/B5 honestly relabelled the manifest's `wasm_module_hash` /
+//! `wasm_module_sig` / `publisher_key` fields as "(P4 — not yet enforced)":
+//! they were parsed and round-tripped but **never checked** before a plugin
+//! ran. This module makes that claim TRUE — it is the real verification gate
+//! the plugin load path runs before instantiating any `.wasm` module.
+//!
+//! ## What is verified, in order
+//!
+//! 1. **Module hash** — SHA-256 of the actual `.wasm` bytes must equal the
+//!    manifest's `wasm_module_hash` (`sha256:<hex>`). A tampered module
+//!    (one byte changed) fails here.
+//! 2. **Ed25519 signature** — `wasm_module_sig` (`ed25519:<base64>`, 64-byte
+//!    raw signature) must verify over the **32-byte SHA-256 digest** under
+//!    the `publisher_key` (`ed25519:<base64>`, 32-byte raw verifying key).
+//! 3. **Trust policy** — the `publisher_key` must be on the configured
+//!    allowlist, unless [`PluginPolicy::AllowUnsigned`] is in force (a loud
+//!    dev escape hatch).
+//!
+//! The crypto mirrors the in-repo Ed25519 pattern from
+//! `cog-ha-matter::witness_signing` (same `ed25519-dalek` 2.x API, same
+//! deterministic-test-key convention). SHA-256 matches the `sha256:` prefix
+//! the manifest doc already declared for `wasm_module_hash`, and the
+//! `cog-ha-matter` cog manifest's `binary_sha256` hex convention.
+//!
+//! ## Secure default
+//!
+//! [`PluginPolicy::trusted`] (the production constructor) **rejects**:
+//!   * an unsigned module (no hash / sig / key),
+//!   * a signature from a key not on the allowlist,
+//!   * any hash or signature mismatch.
+//!
+//! Only [`PluginPolicy::AllowUnsigned`] loosens this, and every load it
+//! waves through emits a `warn`-level log line so it cannot pass silently.
+
+use base64::Engine as _;
+use ed25519_dalek::{Signature, Verifier, VerifyingKey};
+use sha2::{Digest, Sha256};
+
+use crate::error::PluginError;
+use crate::manifest::PluginManifest;
+
+/// Trust policy governing which plugins may load.
+///
+/// The production path uses [`PluginPolicy::trusted`] with an explicit
+/// allowlist of publisher verifying keys. [`PluginPolicy::AllowUnsigned`]
+/// is the dev escape hatch — it loads anything (even unsigned modules) but
+/// logs a loud warning per load.
+#[derive(Debug, Clone)]
+pub enum PluginPolicy {
+    /// Secure default: a plugin loads only if its module hash matches, its
+    /// Ed25519 signature verifies, AND its publisher key is in this
+    /// allowlist. Each entry is the 32-byte raw Ed25519 verifying key.
+    Trusted { allowlist: Vec<[u8; 32]> },
+    /// Dev-only: skip signature/allowlist enforcement. Hash is still
+    /// checked when a `wasm_module_hash` is present (cheap integrity), but
+    /// unsigned / unknown-publisher modules are allowed. Every load logs a
+    /// loud `warn`.
+    AllowUnsigned,
+}
+
+impl PluginPolicy {
+    /// Construct the secure (production) policy from a list of trusted
+    /// publisher keys, each encoded as `ed25519:<base64>` (the same form
+    /// the manifest `publisher_key` uses).
+    pub fn trusted(publisher_keys: &[&str]) -> Result<Self, PluginError> {
+        let mut allowlist = Vec::with_capacity(publisher_keys.len());
+        for k in publisher_keys {
+            allowlist.push(decode_verifying_key(k)?.to_bytes());
+        }
+        Ok(PluginPolicy::Trusted { allowlist })
+    }
+
+    /// Secure policy that trusts no publisher at all — every signed or
+    /// unsigned module is rejected. Useful as a strict default.
+    pub fn deny_all() -> Self {
+        PluginPolicy::Trusted { allowlist: vec![] }
+    }
+
+    fn is_dev(&self) -> bool {
+        matches!(self, PluginPolicy::AllowUnsigned)
+    }
+
+    fn allows(&self, key: &VerifyingKey) -> bool {
+        match self {
+            PluginPolicy::AllowUnsigned => true,
+            PluginPolicy::Trusted { allowlist } => {
+                allowlist.iter().any(|k| k == &key.to_bytes())
+            }
+        }
+    }
+}
+
+/// Verify a `.wasm` module's integrity and signature against its manifest,
+/// under the given trust `policy`. Returns `Ok(())` only if the module may
+/// be instantiated.
+///
+/// On [`PluginPolicy::AllowUnsigned`] this still checks any present hash,
+/// but waves through missing/untrusted signatures with a loud `warn`.
+pub fn verify_module(
+    manifest: &PluginManifest,
+    wasm_bytes: &[u8],
+    policy: &PluginPolicy,
+) -> Result<(), PluginError> {
+    let signed = manifest.wasm_module_hash.is_some()
+        || manifest.wasm_module_sig.is_some()
+        || manifest.publisher_key.is_some();
+
+    if !signed {
+        // No integrity material at all.
+        if policy.is_dev() {
+            eprintln!(
+                "[PLUGIN WARN] loading UNSIGNED plugin `{}` — no wasm_module_hash/sig/publisher_key. \
+                 AllowUnsigned dev policy is active; this is INSECURE and must not be used in production.",
+                manifest.domain
+            );
+            return Ok(());
+        }
+        return Err(PluginError::SignatureRejected(format!(
+            "plugin `{}` is unsigned (no wasm_module_hash/sig/publisher_key) and the trust policy \
+             rejects unsigned modules; set PluginPolicy::AllowUnsigned to override in dev",
+            manifest.domain
+        )));
+    }
+
+    // (1) Hash check — always enforced when a hash is declared.
+    let digest = sha256_digest(wasm_bytes);
+    if let Some(declared) = &manifest.wasm_module_hash {
+        let expected = parse_sha256(declared)?;
+        if expected != digest {
+            return Err(PluginError::SignatureRejected(format!(
+                "plugin `{}` wasm hash mismatch: module does not match manifest wasm_module_hash \
+                 (tampered or wrong binary)",
+                manifest.domain
+            )));
+        }
+    } else if !policy.is_dev() {
+        return Err(PluginError::SignatureRejected(format!(
+            "plugin `{}` carries a signature/publisher_key but no wasm_module_hash to bind it to",
+            manifest.domain
+        )));
+    }
+
+    // (2) Signature check + (3) allowlist.
+    match (&manifest.wasm_module_sig, &manifest.publisher_key) {
+        (Some(sig_str), Some(key_str)) => {
+            let key = decode_verifying_key(key_str)?;
+            let sig = decode_signature(sig_str)?;
+            key.verify(&digest, &sig).map_err(|_| {
+                PluginError::SignatureRejected(format!(
+                    "plugin `{}` Ed25519 signature does not verify over the module hash under \
+                     publisher_key",
+                    manifest.domain
+                ))
+            })?;
+            if !policy.allows(&key) {
+                if policy.is_dev() {
+                    eprintln!(
+                        "[PLUGIN WARN] plugin `{}` is validly signed but its publisher_key is NOT on \
+                         the trust allowlist; AllowUnsigned dev policy loads it anyway.",
+                        manifest.domain
+                    );
+                    return Ok(());
+                }
+                return Err(PluginError::SignatureRejected(format!(
+                    "plugin `{}` is validly signed but its publisher_key is not on the trust \
+                     allowlist (untrusted publisher)",
+                    manifest.domain
+                )));
+            }
+            Ok(())
+        }
+        _ => {
+            // Hash present but signature/key incomplete.
+            if policy.is_dev() {
+                eprintln!(
+                    "[PLUGIN WARN] plugin `{}` has a hash but no complete Ed25519 signature; \
+                     AllowUnsigned dev policy loads it anyway.",
+                    manifest.domain
+                );
+                return Ok(());
+            }
+            Err(PluginError::SignatureRejected(format!(
+                "plugin `{}` is missing a complete wasm_module_sig + publisher_key pair; the trust \
+                 policy requires a valid signature",
+                manifest.domain
+            )))
+        }
+    }
+}
+
+/// SHA-256 of `bytes` as a 32-byte digest.
+fn sha256_digest(bytes: &[u8]) -> [u8; 32] {
+    let mut hasher = Sha256::new();
+    hasher.update(bytes);
+    hasher.finalize().into()
+}
+
+/// Parse a `sha256:<hex>` manifest hash into a 32-byte digest.
+fn parse_sha256(s: &str) -> Result<[u8; 32], PluginError> {
+    let hex_part = s.strip_prefix("sha256:").ok_or_else(|| {
+        PluginError::InvalidManifest(format!(
+            "wasm_module_hash must be `sha256:<hex>`, got {s:?}"
+        ))
+    })?;
+    let raw = hex::decode(hex_part).map_err(|e| {
+        PluginError::InvalidManifest(format!("wasm_module_hash hex decode: {e}"))
+    })?;
+    raw.try_into().map_err(|v: Vec<u8>| {
+        PluginError::InvalidManifest(format!(
+            "wasm_module_hash must decode to 32 bytes, got {}",
+            v.len()
+        ))
+    })
+}
+
+/// Decode an `ed25519:<base64>` 32-byte verifying key.
+fn decode_verifying_key(s: &str) -> Result<VerifyingKey, PluginError> {
+    let b64 = s.strip_prefix("ed25519:").ok_or_else(|| {
+        PluginError::InvalidManifest(format!(
+            "publisher_key must be `ed25519:<base64>`, got {s:?}"
+        ))
+    })?;
+    let raw = base64::engine::general_purpose::STANDARD
+        .decode(b64)
+        .map_err(|e| PluginError::InvalidManifest(format!("publisher_key base64: {e}")))?;
+    let bytes: [u8; 32] = raw.try_into().map_err(|v: Vec<u8>| {
+        PluginError::InvalidManifest(format!(
+            "publisher_key must decode to 32 bytes, got {}",
+            v.len()
+        ))
+    })?;
+    VerifyingKey::from_bytes(&bytes)
+        .map_err(|e| PluginError::InvalidManifest(format!("publisher_key not a valid Ed25519 point: {e}")))
+}
+
+/// Decode an `ed25519:<base64>` 64-byte signature.
+fn decode_signature(s: &str) -> Result<Signature, PluginError> {
+    let b64 = s.strip_prefix("ed25519:").ok_or_else(|| {
+        PluginError::InvalidManifest(format!(
+            "wasm_module_sig must be `ed25519:<base64>`, got {s:?}"
+        ))
+    })?;
+    let raw = base64::engine::general_purpose::STANDARD
+        .decode(b64)
+        .map_err(|e| PluginError::InvalidManifest(format!("wasm_module_sig base64: {e}")))?;
+    let bytes: [u8; 64] = raw.try_into().map_err(|v: Vec<u8>| {
+        PluginError::InvalidManifest(format!(
+            "wasm_module_sig must decode to 64 bytes, got {}",
+            v.len()
+        ))
+    })?;
+    Ok(Signature::from_bytes(&bytes))
+}
+
+/// Encode a SHA-256 digest as the manifest `sha256:<hex>` form. Exposed so
+/// tooling (and tests) can produce a manifest hash for real `.wasm` bytes.
+pub fn encode_sha256(wasm_bytes: &[u8]) -> String {
+    format!("sha256:{}", hex::encode(sha256_digest(wasm_bytes)))
+}
+
+/// Encode an Ed25519 verifying key as the manifest `ed25519:<base64>` form.
+pub fn encode_verifying_key(key: &VerifyingKey) -> String {
+    format!(
+        "ed25519:{}",
+        base64::engine::general_purpose::STANDARD.encode(key.to_bytes())
+    )
+}
+
+/// Encode an Ed25519 signature as the manifest `ed25519:<base64>` form.
+pub fn encode_signature(sig: &Signature) -> String {
+    format!(
+        "ed25519:{}",
+        base64::engine::general_purpose::STANDARD.encode(sig.to_bytes())
+    )
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use ed25519_dalek::{Signer, SigningKey};
+
+    /// Deterministic publisher key (mirrors witness_signing's fixed-bytes
+    /// seed convention — DO NOT use in production).
+    fn publisher() -> SigningKey {
+        SigningKey::from_bytes(b"homecore-plugins-pub-test-seed--")
+    }
+
+    fn attacker() -> SigningKey {
+        SigningKey::from_bytes(b"homecore-plugins-attacker-seed--")
+    }
+
+    /// Sign `wasm_bytes` with `key` and produce a manifest carrying the real
+    /// hash + signature + publisher key.
+    fn signed_manifest(wasm_bytes: &[u8], key: &SigningKey) -> PluginManifest {
+        let digest = sha256_digest(wasm_bytes);
+        let sig = key.sign(&digest);
+        PluginManifest {
+            domain: "demo".into(),
+            name: "Demo".into(),
+            version: "1.0.0".into(),
+            documentation: None,
+            iot_class: None,
+            config_flow: false,
+            integration_type: None,
+            dependencies: vec![],
+            requirements: vec![],
+            wasm_module: Some("demo.wasm".into()),
+            wasm_module_hash: Some(encode_sha256(wasm_bytes)),
+            wasm_module_sig: Some(encode_signature(&sig)),
+            publisher_key: Some(encode_verifying_key(&key.verifying_key())),
+            min_homecore_version: None,
+            host_imports_required: vec![],
+            homecore_permissions: vec![],
+            cog_id: None,
+        }
+    }
+
+    #[test]
+    fn valid_sig_from_trusted_key_passes() {
+        let wasm = b"\0asm\x01\0\0\0fake module bytes";
+        let key = publisher();
+        let manifest = signed_manifest(wasm, &key);
+        let policy =
+            PluginPolicy::trusted(&[&encode_verifying_key(&key.verifying_key())]).unwrap();
+        verify_module(&manifest, wasm, &policy).expect("trusted signed module should load");
+    }
+
+    #[test]
+    fn tampered_module_is_rejected() {
+        let wasm = b"\0asm\x01\0\0\0fake module bytes";
+        let key = publisher();
+        let manifest = signed_manifest(wasm, &key);
+        let policy =
+            PluginPolicy::trusted(&[&encode_verifying_key(&key.verifying_key())]).unwrap();
+        // Flip a byte: hash no longer matches.
+        let tampered = b"\0asm\x01\0\0\0FAKE module bytes";
+        let err = verify_module(&manifest, tampered, &policy).unwrap_err();
+        assert!(matches!(err, PluginError::SignatureRejected(_)), "got {err:?}");
+    }
+
+    #[test]
+    fn valid_sig_from_untrusted_key_is_rejected() {
+        let wasm = b"\0asm\x01\0\0\0fake module bytes";
+        // Signed correctly by the attacker, but the attacker is not trusted.
+        let manifest = signed_manifest(wasm, &attacker());
+        let policy =
+            PluginPolicy::trusted(&[&encode_verifying_key(&publisher().verifying_key())]).unwrap();
+        let err = verify_module(&manifest, wasm, &policy).unwrap_err();
+        assert!(matches!(err, PluginError::SignatureRejected(_)), "got {err:?}");
+    }
+
+    #[test]
+    fn forged_signature_is_rejected() {
+        // Manifest claims the trusted publisher_key but the signature was
+        // produced by the attacker (a forged sig under a trusted identity).
+        let wasm = b"\0asm\x01\0\0\0fake module bytes";
+        let digest = sha256_digest(wasm);
+        let forged = attacker().sign(&digest);
+        let mut manifest = signed_manifest(wasm, &publisher());
+        manifest.wasm_module_sig = Some(encode_signature(&forged));
+        let policy =
+            PluginPolicy::trusted(&[&encode_verifying_key(&publisher().verifying_key())]).unwrap();
+        let err = verify_module(&manifest, wasm, &policy).unwrap_err();
+        assert!(matches!(err, PluginError::SignatureRejected(_)), "got {err:?}");
+    }
+
+    #[test]
+    fn unsigned_module_rejected_under_default_policy() {
+        let wasm = b"\0asm\x01\0\0\0unsigned";
+        let manifest = PluginManifest {
+            domain: "u".into(),
+            name: "U".into(),
+            version: "1".into(),
+            documentation: None,
+            iot_class: None,
+            config_flow: false,
+            integration_type: None,
+            dependencies: vec![],
+            requirements: vec![],
+            wasm_module: Some("u.wasm".into()),
+            wasm_module_hash: None,
+            wasm_module_sig: None,
+            publisher_key: None,
+            min_homecore_version: None,
+            host_imports_required: vec![],
+            homecore_permissions: vec![],
+            cog_id: None,
+        };
+        let err = verify_module(&manifest, wasm, &PluginPolicy::deny_all()).unwrap_err();
+        assert!(matches!(err, PluginError::SignatureRejected(_)), "got {err:?}");
+        // ...but AllowUnsigned loads it (with a warn).
+        verify_module(&manifest, wasm, &PluginPolicy::AllowUnsigned)
+            .expect("AllowUnsigned should load an unsigned module");
+    }
+}

v2/crates/homecore-plugins/src/wasmtime_runtime.rs

@@ -30,16 +30,27 @@ use wasmtime::{Engine, Linker, Module, Store};
 
 use crate::error::PluginError;
 use crate::host_abi::{LogLevel, StateChangedEventJson, MAX_ABI_BUFFER_BYTES};
+use crate::manifest::PluginManifest;
+use crate::permissions::PermissionSet;
+use crate::verify::{verify_module, PluginPolicy};
 
 // ── Store data ─────────────────────────────────────────────────────────────
 
 /// Per-plugin state stored inside the Wasmtime [`Store`].
 ///
 /// Wasmtime's `Store<T>` exposes `T` to host functions via `caller.data()`.
-/// We store the `HomeCore` handle and a list of subscribed entity IDs here.
+/// We store the `HomeCore` handle, a list of subscribed entity IDs, and the
+/// plugin's write-permission set (ADR-162 P5 authority isolation).
 pub struct PluginStoreData {
     pub hc: HomeCore,
     pub subscriptions: Vec<String>,
+    /// Entity-write authority distilled from the manifest's
+    /// `homecore_permissions`. Consulted by `hc_state_set`. The
+    /// permission-free [`WasmtimeRuntime::load_wasm`] path installs an
+    /// all-allowing set for backward compatibility; the
+    /// [`WasmtimeRuntime::load_plugin`] path installs the manifest's
+    /// declared set.
+    pub permissions: PermissionSet,
 }
 
 // ── WasmtimeRuntime ────────────────────────────────────────────────────────
@@ -59,14 +70,53 @@ impl WasmtimeRuntime {
         Ok(Self { engine })
     }
 
-    /// Compile and instantiate a WASM plugin from raw bytes.
+    /// Compile and instantiate a WASM plugin from raw bytes, **without**
+    /// signature verification or permission gating (the plugin gets
+    /// all-write authority).
     ///
-    /// Returns a [`WasmPlugin`] handle that owns the `Store` and the
-    /// `Instance`. The handle can be used to call into the WASM module.
+    /// Retained for the legacy/test path and first-party trusted modules.
+    /// Production plugin loading should go through [`Self::load_plugin`],
+    /// which verifies the module (ADR-162 P4) and scopes its write
+    /// authority to the manifest (P5).
     pub fn load_wasm(
         &self,
         wasm_bytes: &[u8],
         hc: HomeCore,
+    ) -> Result<WasmPlugin, PluginError> {
+        self.instantiate(wasm_bytes, hc, PermissionSet::allow_all())
+    }
+
+    /// Verify and instantiate a WASM plugin from its manifest + raw bytes.
+    ///
+    /// This is the secure load path (ADR-162):
+    ///   1. **P4** — [`verify_module`] checks the SHA-256 module hash and
+    ///      Ed25519 signature against the manifest under `policy`. A
+    ///      tampered module, bad/forged signature, untrusted publisher, or
+    ///      (under the secure default) an unsigned module is rejected
+    ///      **before** any guest code runs.
+    ///   2. **P5** — the plugin's `homecore_permissions` are distilled into
+    ///      a [`PermissionSet`] installed in the store, so `hc_state_set`
+    ///      can only write entities the plugin declared.
+    pub fn load_plugin(
+        &self,
+        manifest: &PluginManifest,
+        wasm_bytes: &[u8],
+        hc: HomeCore,
+        policy: &PluginPolicy,
+    ) -> Result<WasmPlugin, PluginError> {
+        // P4: verify before instantiation.
+        verify_module(manifest, wasm_bytes, policy)?;
+        // P5: scope write authority to the manifest's declared permissions.
+        let permissions = PermissionSet::from_manifest(manifest);
+        self.instantiate(wasm_bytes, hc, permissions)
+    }
+
+    /// Shared compile + instantiate, installing the given permission set.
+    fn instantiate(
+        &self,
+        wasm_bytes: &[u8],
+        hc: HomeCore,
+        permissions: PermissionSet,
     ) -> Result<WasmPlugin, PluginError> {
         let module = Module::new(&self.engine, wasm_bytes)
             .map_err(|e| PluginError::RuntimeError(format!("WASM compile: {e}")))?;
@@ -77,6 +127,7 @@ impl WasmtimeRuntime {
         let store_data = PluginStoreData {
             hc,
             subscriptions: Vec::new(),
+            permissions,
         };
         let mut store = Store::new(&self.engine, store_data);
 
@@ -183,7 +234,9 @@ fn register_hc_state_get(
 /// Sets the state for the entity whose UTF-8 ID is at `[eid_ptr,eid_ptr+eid_len)`.
 /// The new state string is at `[state_ptr,state_ptr+state_len)`.
 /// The attributes JSON is at `[attrs_ptr,attrs_ptr+attrs_len)`.
-/// Returns 0 on success, negative on error.
+/// Returns 0 on success, negative on error: -1 (bad memory/args), -2
+/// (invalid entity id), -3 (permission denied — entity not in the
+/// plugin's declared `homecore_permissions`, ADR-162 P5).
 fn register_hc_state_set(
     linker: &mut Linker<PluginStoreData>,
 ) -> Result<(), PluginError> {
@@ -224,6 +277,20 @@ fn register_hc_state_set(
                     Ok(id) => id,
                     Err(_) => return -2,
                 };
+
+                // ── P5 authority isolation (ADR-162) ──────────────────────
+                // Reject a write to an entity the plugin did not declare in
+                // `homecore_permissions`. Return a typed error code to the
+                // guest (-3); do NOT panic the host.
+                if !caller.data().permissions.may_write(entity_id.as_str()) {
+                    eprintln!(
+                        "[PLUGIN WARN] denied hc_state_set on `{}` — not in plugin's declared \
+                         homecore_permissions (P5 authority isolation)",
+                        entity_id.as_str()
+                    );
+                    return -3;
+                }
+
                 let attrs: serde_json::Value =
                     serde_json::from_str(&attrs_str).unwrap_or(serde_json::json!({}));
 

v2/crates/homecore-plugins/tests/integration.rs

@@ -371,4 +371,259 @@ mod wasmtime_tests {
         let r = plugin.call_setup("{}").expect("setup");
         assert_eq!(r, 0);
     }
+
+    // ── ADR-162 P4: signature/integrity verification ────────────────────────
+    //
+    // Each of these FAILS on the pre-ADR-162 code, which had no
+    // `load_plugin` / `verify_module` at all — the manifest hash/sig/key
+    // were parsed and discarded. They drive the real verification gate.
+
+    use ed25519_dalek::{Signer, SigningKey};
+    use homecore_plugins::manifest::PluginManifest;
+    use homecore_plugins::verify::{encode_sha256, encode_signature, encode_verifying_key};
+    use homecore_plugins::PluginPolicy;
+
+    /// Deterministic publisher key (fixed seed — never use in production;
+    /// mirrors the cog-ha-matter witness_signing test-key convention).
+    fn publisher_key() -> SigningKey {
+        SigningKey::from_bytes(b"hc-plugins-integration-pub-seed-")
+    }
+
+    fn untrusted_key() -> SigningKey {
+        SigningKey::from_bytes(b"hc-plugins-integration-evil-seed")
+    }
+
+    /// A minimal valid module that writes `light.kitchen` on setup, plus a
+    /// `light.*` permission grant. Returns the WAT source.
+    const WRITE_LIGHT_WAT: &str = r#"
+(module
+  (import "env" "hc_state_get"       (func $hc_state_get (param i32 i32 i32 i32) (result i32)))
+  (import "env" "hc_state_set"       (func $hc_state_set (param i32 i32 i32 i32 i32 i32) (result i32)))
+  (import "env" "hc_state_subscribe" (func $hc_state_subscribe (param i32 i32) (result i32)))
+  (import "env" "hc_log"             (func $hc_log (param i32 i32 i32)))
+  (memory (export "memory") 1)
+  (global $bump (mut i32) (i32.const 512))
+  (data (i32.const 0)   "light.kitchen")
+  (data (i32.const 64)  "on")
+  (data (i32.const 128) "{}")
+  (func (export "alloc") (param i32) (result i32)
+    (local $p i32)
+    (local.set $p (global.get $bump))
+    (global.set $bump (i32.add (global.get $bump) (local.get 0)))
+    (local.get $p))
+  (func (export "dealloc") (param i32 i32))
+  (func (export "plugin_setup") (param i32 i32) (result i32)
+    (call $hc_state_set
+      (i32.const 0) (i32.const 13)   ;; "light.kitchen"
+      (i32.const 64) (i32.const 2)   ;; "on"
+      (i32.const 128) (i32.const 2)) ;; "{}"
+    drop
+    (i32.const 0))
+  (func (export "plugin_handle_state_changed") (param i32 i32) (result i32) (i32.const 0))
+)
+"#;
+
+    /// Build a manifest signed by `key` over the SHA-256 of `wasm_bytes`,
+    /// with the given write-permission grants.
+    fn signed_manifest(
+        wasm_bytes: &[u8],
+        key: &SigningKey,
+        perms: &[&str],
+    ) -> PluginManifest {
+        use sha2::{Digest, Sha256};
+        let digest: [u8; 32] = Sha256::digest(wasm_bytes).into();
+        let sig = key.sign(&digest);
+        let mut m = PluginManifest::parse_json(
+            r#"{"domain":"demo","name":"Demo","version":"1.0.0"}"#,
+        )
+        .unwrap();
+        m.wasm_module = Some("demo.wasm".into());
+        m.wasm_module_hash = Some(encode_sha256(wasm_bytes));
+        m.wasm_module_sig = Some(encode_signature(&sig));
+        m.publisher_key = Some(encode_verifying_key(&key.verifying_key()));
+        m.homecore_permissions = perms.iter().map(|s| s.to_string()).collect();
+        m
+    }
+
+    #[test]
+    fn p4_valid_sig_from_trusted_key_loads() {
+        let wasm = wat::parse_str(WRITE_LIGHT_WAT).expect("WAT");
+        let key = publisher_key();
+        let manifest = signed_manifest(&wasm, &key, &["light.*"]);
+        let policy =
+            PluginPolicy::trusted(&[&encode_verifying_key(&key.verifying_key())]).unwrap();
+
+        let rt = WasmtimeRuntime::new().expect("rt");
+        let hc = HomeCore::new();
+        rt.load_plugin(&manifest, &wasm, hc, &policy)
+            .expect("a validly-signed, trusted plugin must load");
+    }
+
+    #[test]
+    fn p4_tampered_module_is_rejected() {
+        let wasm = wat::parse_str(WRITE_LIGHT_WAT).expect("WAT");
+        let key = publisher_key();
+        // Manifest signs the original bytes; we then load DIFFERENT bytes.
+        let manifest = signed_manifest(&wasm, &key, &["light.*"]);
+        let policy =
+            PluginPolicy::trusted(&[&encode_verifying_key(&key.verifying_key())]).unwrap();
+
+        // Re-compile a byte-different module (writes "off" not "on").
+        let tampered_src = WRITE_LIGHT_WAT.replace(r#""on""#, r#""of""#);
+        let tampered = wat::parse_str(&tampered_src).expect("WAT");
+        assert_ne!(wasm, tampered, "test bug: bytes must differ");
+
+        let rt = WasmtimeRuntime::new().expect("rt");
+        let hc = HomeCore::new();
+        match rt.load_plugin(&manifest, &tampered, hc, &policy) {
+            Err(homecore_plugins::PluginError::SignatureRejected(_)) => {}
+            Ok(_) => panic!("tampered module must be rejected (hash mismatch), but it loaded"),
+            Err(e) => panic!("expected SignatureRejected, got {e:?}"),
+        }
+    }
+
+    #[test]
+    fn p4_valid_sig_from_untrusted_key_is_rejected() {
+        let wasm = wat::parse_str(WRITE_LIGHT_WAT).expect("WAT");
+        // Correctly signed by the untrusted key — but it is not on the allowlist.
+        let manifest = signed_manifest(&wasm, &untrusted_key(), &["light.*"]);
+        let policy =
+            PluginPolicy::trusted(&[&encode_verifying_key(&publisher_key().verifying_key())])
+                .unwrap();
+
+        let rt = WasmtimeRuntime::new().expect("rt");
+        let hc = HomeCore::new();
+        match rt.load_plugin(&manifest, &wasm, hc, &policy) {
+            Err(homecore_plugins::PluginError::SignatureRejected(_)) => {}
+            Ok(_) => panic!("untrusted publisher must be rejected, but it loaded"),
+            Err(e) => panic!("expected SignatureRejected, got {e:?}"),
+        }
+    }
+
+    #[test]
+    fn p4_unsigned_module_rejected_by_default_loads_only_under_allow_unsigned() {
+        let wasm = wat::parse_str(WRITE_LIGHT_WAT).expect("WAT");
+        let mut manifest = PluginManifest::parse_json(
+            r#"{"domain":"u","name":"U","version":"1"}"#,
+        )
+        .unwrap();
+        manifest.wasm_module = Some("u.wasm".into());
+        manifest.homecore_permissions = vec!["light.*".into()];
+        // No hash/sig/key → unsigned.
+
+        let rt = WasmtimeRuntime::new().expect("rt");
+        // Secure default: rejected.
+        match rt.load_plugin(&manifest, &wasm, HomeCore::new(), &PluginPolicy::deny_all()) {
+            Err(homecore_plugins::PluginError::SignatureRejected(_)) => {}
+            Ok(_) => panic!("unsigned module must be rejected under the secure default"),
+            Err(e) => panic!("expected SignatureRejected, got {e:?}"),
+        }
+        // Dev escape hatch: loads (with a loud warn).
+        rt.load_plugin(
+            &manifest,
+            &wasm,
+            HomeCore::new(),
+            &PluginPolicy::AllowUnsigned,
+        )
+        .expect("AllowUnsigned dev policy must load an unsigned module");
+    }
+
+    // ── ADR-162 P5: authority / capability isolation ────────────────────────
+    //
+    // FAILS on the pre-ADR-162 code, where `hc_state_set` ignored
+    // `homecore_permissions` entirely and let any plugin write any entity.
+
+    /// Module that writes `lock.front_door` on setup (an over-privileged
+    /// write a `light.*` plugin must NOT be allowed to perform).
+    const WRITE_LOCK_WAT: &str = r#"
+(module
+  (import "env" "hc_state_get"       (func $hc_state_get (param i32 i32 i32 i32) (result i32)))
+  (import "env" "hc_state_set"       (func $hc_state_set (param i32 i32 i32 i32 i32 i32) (result i32)))
+  (import "env" "hc_state_subscribe" (func $hc_state_subscribe (param i32 i32) (result i32)))
+  (import "env" "hc_log"             (func $hc_log (param i32 i32 i32)))
+  (memory (export "memory") 1)
+  (global $bump (mut i32) (i32.const 512))
+  (data (i32.const 0)   "lock.front_door")
+  (data (i32.const 64)  "unlocked")
+  (data (i32.const 128) "{}")
+  (func (export "alloc") (param i32) (result i32)
+    (local $p i32)
+    (local.set $p (global.get $bump))
+    (global.set $bump (i32.add (global.get $bump) (local.get 0)))
+    (local.get $p))
+  (func (export "dealloc") (param i32 i32))
+  ;; plugin_setup returns the hc_state_set result code so the host test can
+  ;; assert the guest saw the typed permission-denied error (-3).
+  (func (export "plugin_setup") (param i32 i32) (result i32)
+    (call $hc_state_set
+      (i32.const 0) (i32.const 15)   ;; "lock.front_door"
+      (i32.const 64) (i32.const 8)   ;; "unlocked"
+      (i32.const 128) (i32.const 2))) ;; "{}"
+  (func (export "plugin_handle_state_changed") (param i32 i32) (result i32) (i32.const 0))
+)
+"#;
+
+    #[test]
+    fn p5_declared_light_plugin_may_write_light_but_not_lock() {
+        let key = publisher_key();
+        let trusted = PluginPolicy::trusted(&[&encode_verifying_key(&key.verifying_key())]).unwrap();
+        let rt = WasmtimeRuntime::new().expect("rt");
+
+        // (a) A `light.*` plugin writing `light.kitchen` → ALLOWED.
+        let light_wasm = wat::parse_str(WRITE_LIGHT_WAT).expect("WAT");
+        let light_manifest = signed_manifest(&light_wasm, &key, &["light.*"]);
+        let hc_a = HomeCore::new();
+        let plugin_a = rt
+            .load_plugin(&light_manifest, &light_wasm, hc_a.clone(), &trusted)
+            .expect("light plugin loads");
+        let r = plugin_a.call_setup("{}").expect("setup");
+        assert_eq!(r, 0, "write to declared light.kitchen should succeed");
+        let kitchen = homecore::EntityId::parse("light.kitchen").unwrap();
+        assert_eq!(
+            hc_a.states().get(&kitchen).expect("light.kitchen written").state,
+            "on"
+        );
+
+        // (b) The SAME `light.*` plugin attempting to write `lock.front_door`
+        // → REJECTED with the typed -3 code, and the lock is NOT written.
+        let lock_wasm = wat::parse_str(WRITE_LOCK_WAT).expect("WAT");
+        let lock_manifest = signed_manifest(&lock_wasm, &key, &["light.*"]);
+        let hc_b = HomeCore::new();
+        let plugin_b = rt
+            .load_plugin(&lock_manifest, &lock_wasm, hc_b.clone(), &trusted)
+            .expect("module loads (verification ok); the WRITE is what's gated");
+        let denied = plugin_b.call_setup("{}").expect("setup runs without trapping host");
+        assert_eq!(
+            denied, -3,
+            "over-privileged write to lock.front_door must return -3 (permission denied)"
+        );
+        let lock = homecore::EntityId::parse("lock.front_door").unwrap();
+        assert!(
+            hc_b.states().get(&lock).is_none(),
+            "lock.front_door must NOT have been written by a light-only plugin"
+        );
+    }
+
+    #[test]
+    fn p5_plugin_with_no_permissions_can_write_nothing() {
+        let key = publisher_key();
+        let trusted = PluginPolicy::trusted(&[&encode_verifying_key(&key.verifying_key())]).unwrap();
+        let rt = WasmtimeRuntime::new().expect("rt");
+
+        let wasm = wat::parse_str(WRITE_LIGHT_WAT).expect("WAT");
+        // No permissions declared at all.
+        let manifest = signed_manifest(&wasm, &key, &[]);
+        let hc = HomeCore::new();
+        let plugin = rt
+            .load_plugin(&manifest, &wasm, hc.clone(), &trusted)
+            .expect("module loads; the write is gated");
+        // WRITE_LIGHT_WAT drops the host-import result and returns 0, so we
+        // assert the denial via the side-effect: the write must NOT land.
+        plugin.call_setup("{}").expect("setup runs without trapping host");
+        let kitchen = homecore::EntityId::parse("light.kitchen").unwrap();
+        assert!(
+            hc.states().get(&kitchen).is_none(),
+            "no-permission plugin must not write light.kitchen (P5 authority isolation)"
+        );
+    }
 }

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

@@ -1,6 +1,6 @@
 [package]
 name = "wifi-densepose-cli"
-version.workspace = true
+version = "0.3.1"
 edition.workspace = true
 description = "CLI for WiFi-DensePose"
 authors.workspace = true

v2/crates/wifi-densepose-cli/src/calibrate.rs

@@ -405,7 +405,9 @@ mod tests {
     #[test]
     fn test_tier_config_he20() {
         let cfg = tier_config("he20");
-        assert_eq!(cfg.num_active, 242);
+        // Issue #1009 §1b: HE20 baseline records all 256 delivered bins
+        // (no tone map in the recorder), not the 242 active tones.
+        assert_eq!(cfg.num_active, 256);
     }
 
     #[test]

v2/crates/wifi-densepose-pointcloud/src/camera.rs

@@ -188,6 +188,8 @@ Thread.sleep(forTimeInterval: 3)"#,
     bail!("macOS camera capture requires GUI session with camera permission")
 }
 
+// Used only by the macOS capture path above; dead on other targets.
+#[allow(dead_code)]
 fn decode_jpeg_to_rgb(path: &PathBuf, _width: u32, _height: u32) -> Result<Frame> {
     let data = std::fs::read(path)?;
     let _ = std::fs::remove_file(path);

v2/crates/wifi-densepose-ruvector/src/viewpoint/coherence.rs

@@ -261,9 +261,15 @@ pub enum ClockGateDecision {
     /// Both terms pass: node admitted at full weight.
     Admit,
     /// Phase OK but clock degraded: evidence-only, NO environment/model update.
-    MonitorOnly { clock_quality: f32 },
+    MonitorOnly {
+        /// Combined clock-quality score in [0, 1] (dispersion × age terms).
+        clock_quality: f32,
+    },
     /// Either term fails hard: node excluded this cycle.
-    Reject { reason: ClockRejectReason },
+    Reject {
+        /// Which hard term failed (phase, dispersion, or age).
+        reason: ClockRejectReason,
+    },
 }
 
 /// Clock-quality gate: combines the phase [`CoherenceGate`] with clock

v2/crates/wifi-densepose-sensing-server/Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "wifi-densepose-sensing-server"
-version = "0.3.2"
+version = "0.3.3"
 edition.workspace = true
 description = "Lightweight Axum server for WiFi sensing UI with RuVector signal processing"
 license.workspace = true

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

@@ -1483,6 +1483,65 @@ fn parse_esp32_frame(buf: &[u8]) -> Option<Esp32Frame> {
     })
 }
 
+#[cfg(test)]
+mod issue_1009_n_subcarriers_u16_tests {
+    //! Issue #1009 §1c — `parse_esp32_frame` must read `n_subcarriers` as a
+    //! u16 LE at bytes 6..7 (ADR-018 wire format), not a single byte at 6.
+    //!
+    //! An ESP32-C6 HE20 frame carries 256 subcarriers → byte 6 = 0x00,
+    //! byte 7 = 0x01. The pre-#1005 single-byte read decoded this as 0
+    //! subcarriers, silently dropping every real HE20 frame. This was the same
+    //! truncation as the CLI parser (`wifi-densepose-cli` calibrate.rs); this
+    //! module pins that the sensing-server template stays u16-correct.
+    use super::*;
+
+    /// Build an ADR-018 CSI frame (magic 0xC511_0001, 20-byte header).
+    fn build_csi_frame(n_subcarriers: u16) -> Vec<u8> {
+        let mut buf = vec![0u8; 20 + n_subcarriers as usize * 2];
+        buf[0..4].copy_from_slice(&0xC511_0001u32.to_le_bytes());
+        buf[4] = 7; // node_id
+        buf[5] = 1; // n_antennas
+        buf[6..8].copy_from_slice(&n_subcarriers.to_le_bytes()); // u16 LE
+        buf[8..12].copy_from_slice(&5180u32.to_le_bytes()); // freq_mhz (5 GHz HE)
+        buf[12..16].copy_from_slice(&42u32.to_le_bytes()); // sequence
+        buf[16] = (-40i8) as u8; // rssi
+        buf[17] = (-90i8) as u8; // noise_floor
+        buf[18] = 0; // ppdu_type
+        buf[19] = 0;
+        for k in 0..n_subcarriers as usize {
+            buf[20 + k * 2] = (5 + (k % 40) as i8) as u8; // i
+            buf[20 + k * 2 + 1] = (k % 30) as u8; // q
+        }
+        buf
+    }
+
+    #[test]
+    fn parse_esp32_frame_he20_256_bins_not_truncated() {
+        // 256 = 0x0100 LE: byte6 = 0x00, byte7 = 0x01. A u8 read of byte 6
+        // would see 0 subcarriers; a u16 read sees 256.
+        let buf = build_csi_frame(256);
+        assert_eq!(buf.len(), 532, "256-bin frame wire size = 20 + 256*2");
+        let frame = parse_esp32_frame(&buf).expect("256-bin HE20 frame must parse");
+        assert_eq!(
+            frame.n_subcarriers, 256,
+            "n_subcarriers must read as u16 (256), not the byte-6-only 0"
+        );
+        assert_eq!(frame.amplitudes.len(), 256);
+        assert_eq!(frame.node_id, 7);
+        assert_eq!(frame.rssi, -40);
+        assert_eq!(frame.sequence, 42);
+    }
+
+    #[test]
+    fn parse_esp32_frame_ht20_64_bins_still_parses() {
+        // Regression guard for the common single-byte (≤255) case.
+        let buf = build_csi_frame(64);
+        let frame = parse_esp32_frame(&buf).expect("64-bin HT20 frame must parse");
+        assert_eq!(frame.n_subcarriers, 64);
+        assert_eq!(frame.amplitudes.len(), 64);
+    }
+}
+
 // ── Signal field generation ──────────────────────────────────────────────────
 
 /// Generate a signal field that reflects where motion and signal changes are occurring.
@@ -2694,6 +2753,203 @@ async fn probe_esp32(port: u16) -> bool {
     }
 }
 
+// ── Source resolution state machine (issue #1004) ────────────────────────────
+
+/// What background tasks to start, derived from `--source` and the boot probes.
+///
+/// Issue #1004: a one-shot startup probe latched `auto` to `simulate` forever
+/// when no CSI happened to be flowing at boot (the normal case — the firmware
+/// and the server race to come up). The UDP :5005 receiver was then never
+/// bound, so real CSI arriving seconds later was silently ignored and the
+/// server served simulated poses for the rest of the process. The UI looked
+/// live; the data was fake. This is the exact "where's the real data?" failure
+/// class the project fights.
+///
+/// The robust resolution: in `auto` mode **always bind the UDP receiver**
+/// regardless of the boot probe. If no real source is up yet, serve simulated
+/// data *and* keep the UDP receiver listening; the receiver promotes
+/// `source` → `esp32` the instant the first real frame lands (see
+/// `udp_receiver_task`, which sets `s.source = "esp32"`), mirroring the inverse
+/// `esp32 → esp32:offline` reversion already in `effective_source()`.
+///
+/// Explicit `--source simulated` is a hard override for offline demos: it does
+/// NOT bind UDP, so no promotion ever happens.
+#[derive(Debug, Clone, PartialEq, Eq)]
+struct SourcePlan {
+    /// The `AppStateInner.source` value to start with.
+    initial_source: String,
+    /// Bind the UDP :5005 receiver (and thus allow simulate→esp32 promotion).
+    bind_udp: bool,
+    /// Run the simulated-data generator (serves poses until a real frame arrives).
+    run_simulator: bool,
+    /// Run the Windows WiFi capture task.
+    run_wifi: bool,
+}
+
+/// Pure decision function — fully unit-testable without binding sockets.
+///
+/// `requested` is the normalized `--source` value. `esp32_detected` /
+/// `wifi_detected` are the boot-probe results (only consulted in `auto` mode).
+/// Returns `None` for an unknown source that names neither a real source nor a
+/// simulate alias (the caller maps that to its own pass-through/exit policy).
+fn plan_source(requested: &str, esp32_detected: bool, wifi_detected: bool) -> SourcePlan {
+    match requested {
+        "auto" => {
+            if esp32_detected {
+                // Real CSI already flowing — bind UDP, no simulator.
+                SourcePlan {
+                    initial_source: "esp32".to_string(),
+                    bind_udp: true,
+                    run_simulator: false,
+                    run_wifi: false,
+                }
+            } else if wifi_detected {
+                SourcePlan {
+                    initial_source: "wifi".to_string(),
+                    bind_udp: false,
+                    run_simulator: false,
+                    run_wifi: true,
+                }
+            } else {
+                // No real source *yet*. Serve simulated data, but ALSO bind UDP
+                // so the receiver can promote to esp32 when the first real
+                // frame arrives (issue #1004). Never latch on simulate.
+                SourcePlan {
+                    initial_source: "simulated".to_string(),
+                    bind_udp: true,
+                    run_simulator: true,
+                    run_wifi: false,
+                }
+            }
+        }
+        // Explicit overrides. "simulate" is a back-compat alias for "simulated".
+        "simulate" | "simulated" => SourcePlan {
+            initial_source: "simulated".to_string(),
+            bind_udp: false, // hard override: offline demo, no live promotion
+            run_simulator: true,
+            run_wifi: false,
+        },
+        "esp32" => SourcePlan {
+            initial_source: "esp32".to_string(),
+            bind_udp: true,
+            run_simulator: false,
+            run_wifi: false,
+        },
+        "wifi" => SourcePlan {
+            initial_source: "wifi".to_string(),
+            bind_udp: false,
+            run_simulator: false,
+            run_wifi: true,
+        },
+        // Unknown source — preserve it verbatim, no tasks (caller's policy).
+        other => SourcePlan {
+            initial_source: other.to_string(),
+            bind_udp: false,
+            run_simulator: false,
+            run_wifi: false,
+        },
+    }
+}
+
+#[cfg(test)]
+mod issue_1004_source_plan_tests {
+    //! Issue #1004 — `--source auto` must NOT latch on `simulate` forever.
+    //!
+    //! Old behavior: a one-shot boot probe resolved the source once. With no CSI
+    //! flowing at boot (the normal case), the server either latched on simulate
+    //! (never binding UDP :5005, so later real CSI was silently ignored) or
+    //! hard-exited (#937), never picking up CSI that started after launch.
+    //!
+    //! New behavior (`plan_source`): in `auto` the UDP receiver is ALWAYS bound,
+    //! simulated data is served only until the first real frame, then
+    //! `udp_receiver_task` promotes `source` → "esp32". These tests pin the
+    //! resolution/promotion state machine directly (no sockets bound).
+    use super::*;
+
+    // FAILS ON OLD CODE: the old `auto`-with-no-source path bound no UDP
+    // receiver (it spawned only `simulated_data_task`, or exited). This asserts
+    // UDP IS bound even when the boot probe finds no source.
+    #[test]
+    fn auto_with_no_boot_source_still_binds_udp_and_simulates() {
+        let plan = plan_source("auto", false, false);
+        assert!(plan.bind_udp, "auto must bind UDP :5005 even with no boot source (#1004)");
+        assert!(plan.run_simulator, "auto must serve simulated data until real CSI arrives");
+        assert!(!plan.run_wifi);
+        assert_eq!(plan.initial_source, "simulated");
+    }
+
+    #[test]
+    fn auto_with_esp32_detected_binds_udp_no_simulator() {
+        let plan = plan_source("auto", true, false);
+        assert!(plan.bind_udp);
+        assert!(!plan.run_simulator, "real CSI present → no synthetic frames");
+        assert_eq!(plan.initial_source, "esp32");
+    }
+
+    #[test]
+    fn auto_with_wifi_detected_runs_wifi_no_udp() {
+        let plan = plan_source("auto", false, true);
+        assert!(plan.run_wifi);
+        assert!(!plan.bind_udp);
+        assert!(!plan.run_simulator);
+        assert_eq!(plan.initial_source, "wifi");
+    }
+
+    // Explicit `--source simulated` is a hard offline override: it must NOT bind
+    // UDP (so it can never be promoted to live), distinguishing it from
+    // auto-mode simulate.
+    #[test]
+    fn explicit_simulated_is_offline_override_no_udp() {
+        for s in ["simulated", "simulate"] {
+            let plan = plan_source(s, false, false);
+            assert!(!plan.bind_udp, "{s}: explicit simulate must not bind UDP (offline demo)");
+            assert!(plan.run_simulator);
+            assert_eq!(plan.initial_source, "simulated");
+        }
+    }
+
+    #[test]
+    fn explicit_esp32_binds_udp() {
+        let plan = plan_source("esp32", false, false);
+        assert!(plan.bind_udp);
+        assert!(!plan.run_simulator);
+        assert_eq!(plan.initial_source, "esp32");
+    }
+
+    // Promotion check: the runtime promotes by setting `AppStateInner.source`
+    // to "esp32" on the first real frame; `effective_source()` then reports it
+    // (and reverts to "esp32:offline" after a 5 s gap). This asserts the
+    // promotion direction the simulator/receiver rely on, without binding a
+    // socket — it exercises the same `source` field the UDP task writes.
+    #[test]
+    fn effective_source_promotes_from_simulated_to_esp32_on_real_frame() {
+        // Start as the auto/simulate plan would: source = "simulated".
+        let mut src = "simulated".to_string();
+        // effective_source() logic for the simulate state: stays "simulated".
+        assert_eq!(promote_view(&src, None), "simulated");
+        // First real frame arrives → udp_receiver_task sets source = "esp32".
+        src = "esp32".to_string();
+        let fresh = Some(std::time::Duration::from_millis(10));
+        assert_eq!(promote_view(&src, fresh), "esp32", "fresh esp32 frame ⇒ live");
+        // After a >5 s gap it reverts to offline (inverse machinery, #1004).
+        let stale = Some(ESP32_OFFLINE_TIMEOUT + std::time::Duration::from_secs(1));
+        assert_eq!(promote_view(&src, stale), "esp32:offline");
+    }
+
+    /// Mirror of `AppStateInner::effective_source` over just (source, age) so the
+    /// promotion/reversion logic is testable without constructing full state.
+    fn promote_view(source: &str, last_frame_age: Option<std::time::Duration>) -> String {
+        if source == "esp32" {
+            if let Some(age) = last_frame_age {
+                if age > ESP32_OFFLINE_TIMEOUT {
+                    return "esp32:offline".to_string();
+                }
+            }
+        }
+        source.to_string()
+    }
+}
+
 // ── Simulated data generator ─────────────────────────────────────────────────
 
 fn generate_simulated_frame(tick: u64) -> Esp32Frame {
@@ -5699,6 +5955,18 @@ async fn simulated_data_task(state: SharedState, tick_ms: u64) {
         interval.tick().await;
 
         let mut s = state.write().await;
+
+        // Issue #1004: in `auto` mode this task runs alongside `udp_receiver_task`.
+        // Once a real frame promotes `source` → "esp32", stop emitting synthetic
+        // frames so we never clobber live CSI with simulated poses. (For an
+        // explicit `--source simulated` demo, `source` stays "simulated" and the
+        // simulator keeps running — that path never binds UDP, so it is never
+        // promoted.) The task stays alive so it can resume serving if the real
+        // source later ages out to "esp32:offline".
+        if s.effective_source() == "esp32" {
+            continue;
+        }
+
         s.tick += 1;
         let tick = s.tick;
 
@@ -6584,48 +6852,48 @@ async fn main() {
     info!("  UI path:   {}", args.ui_path.display());
     info!("  Source:    {}", args.source);
 
-    // Auto-detect data source.
+    // Resolve the data source into a concrete task plan (issue #1004).
     //
-    // Issue #937 / sibling fix: previously `auto` silently fell back to the
-    // synthetic data source when no ESP32 or Windows WiFi was reachable, with
-    // only an `info!` log line as the signal. Downstream API consumers
-    // (`/api/v1/sensing/latest`, `/ws/sensing`) had no in-band way to know they
-    // were being served fake CSI tagged as production telemetry. That is the
-    // exact "where's the real data?" pattern external reviewers (#943, #934)
-    // cited as the most damaging evidence of the project misrepresenting its
-    // posture. Synthetic-data is now opt-in only — operators who want demo
-    // mode must explicitly set `--source simulated` or `CSI_SOURCE=simulated`.
-    let source = match args.source.as_str() {
-        "auto" => {
-            info!("Auto-detecting data source...");
-            if probe_esp32(args.udp_port).await {
-                info!("  ESP32 CSI detected on UDP :{}", args.udp_port);
-                "esp32"
-            } else if probe_windows_wifi().await {
-                info!("  Windows WiFi detected");
-                "wifi"
-            } else {
-                error!(
-                    "No real CSI source detected. Auto-detection refuses to silently \
-                     fall back to synthetic data because that would expose downstream \
-                     consumers (/api/v1/sensing/latest, /ws/sensing) to fake telemetry \
-                     tagged as production. To run with synthetic data, set the source \
-                     explicitly: --source simulated (or CSI_SOURCE=simulated in Docker). \
-                     To use real hardware: provision an ESP32 to emit CSI on UDP :{} or \
-                     install the Windows WiFi capture driver. See \
-                     https://github.com/ruvnet/RuView/issues/937 for context.",
-                    args.udp_port
-                );
-                std::process::exit(78); // EX_CONFIG
-            }
+    // Issue #937 (prior fix): `auto` must never serve fake CSI *tagged as
+    // production telemetry*. We keep that guarantee — in the gap before real
+    // CSI arrives, `source` is the honest string "simulated" (downstream
+    // `/api/v1/sensing/latest`, `/ws/sensing` see `source: "simulated"`, not a
+    // production tag). What #937's hard-exit got wrong: at boot the firmware and
+    // server race, so CSI usually is NOT flowing during the 2 s probe. Exiting
+    // (or latching on simulate) meant the server could never pick up CSI that
+    // started seconds later. The robust resolution (see `plan_source`): in
+    // `auto` always bind the UDP :5005 receiver; serve simulated until the first
+    // real frame; then `udp_receiver_task` promotes `source` → "esp32". Explicit
+    // `--source simulated` stays a hard, UDP-free override for offline demos.
+    let normalized = if args.source == "simulate" { "simulated" } else { args.source.as_str() };
+    let plan = if normalized == "auto" {
+        info!("Auto-detecting data source (UDP :{} bound either way)...", args.udp_port);
+        let esp32 = probe_esp32(args.udp_port).await;
+        let wifi = if esp32 { false } else { probe_windows_wifi().await };
+        if esp32 {
+            info!("  ESP32 CSI detected on UDP :{}", args.udp_port);
+        } else if wifi {
+            info!("  Windows WiFi detected");
+        } else {
+            warn!(
+                "No real CSI source at boot — serving SIMULATED data (tagged as \
+                 'simulated', not production) while the UDP :{} receiver stays bound. \
+                 The server promotes to live the instant a real frame arrives (issue \
+                 #1004). For an offline demo with no live promotion, pass \
+                 --source simulated explicitly.",
+                args.udp_port
+            );
         }
-        // "simulate" is a synonym for "simulated" (back-compat alias kept so
-        // existing operators who already opted in don't get broken by this fix).
-        "simulate" => "simulated",
-        other => other,
+        plan_source("auto", esp32, wifi)
+    } else {
+        plan_source(normalized, false, false)
     };
+    let source: &str = plan.initial_source.as_str();
 
-    info!("Data source: {source}");
+    info!(
+        "Data source: {source} (udp_receiver={}, simulator={}, wifi={})",
+        plan.bind_udp, plan.run_simulator, plan.run_wifi
+    );
 
     // Shared state
     // Vital sign sample rate derives from tick interval (e.g. 500ms tick => 2 Hz)
@@ -6905,18 +7173,22 @@ async fn main() {
         data_dir: data_dir.clone(),
     }));
 
-    // Start background tasks based on source
-    match source {
-        "esp32" => {
-            tokio::spawn(udp_receiver_task(state.clone(), args.udp_port));
-            tokio::spawn(broadcast_tick_task(state.clone(), args.tick_ms));
-        }
-        "wifi" => {
-            tokio::spawn(windows_wifi_task(state.clone(), args.tick_ms));
-        }
-        _ => {
-            tokio::spawn(simulated_data_task(state.clone(), args.tick_ms));
-        }
+    // Start background tasks from the resolved plan (issue #1004).
+    //
+    // In `auto` mode with no boot source, `bind_udp` AND `run_simulator` are
+    // both true: the UDP receiver is bound so real CSI can promote the source,
+    // and the simulator serves poses in the meantime (it self-suspends once
+    // promoted — see `simulated_data_task`). Explicit `--source simulated` has
+    // `bind_udp = false`, so it serves simulated data only, with no live binding.
+    if plan.bind_udp {
+        tokio::spawn(udp_receiver_task(state.clone(), args.udp_port));
+        tokio::spawn(broadcast_tick_task(state.clone(), args.tick_ms));
+    }
+    if plan.run_wifi {
+        tokio::spawn(windows_wifi_task(state.clone(), args.tick_ms));
+    }
+    if plan.run_simulator {
+        tokio::spawn(simulated_data_task(state.clone(), args.tick_ms));
     }
 
     // ADR-050: Parse bind address once, use for all listeners

v2/crates/wifi-densepose-sensing-server/src/matter/clusters.rs

@@ -145,6 +145,8 @@ pub fn matter_mapping(entity: EntityKind) -> Option<MatterClusterMapping> {
 }
 
 /// True iff the entity has a Matter exposure on a current spec cluster.
+// P2 Matter-publisher API surface; real Matter exposure is deferred (ADR-159 §A5).
+#[allow(dead_code)]
 pub fn entity_on_matter(entity: EntityKind) -> bool {
     matter_mapping(entity).is_some()
 }
@@ -152,6 +154,8 @@ pub fn entity_on_matter(entity: EntityKind) -> bool {
 /// Compute the next available endpoint ID for a node-scoped entity,
 /// given a starting offset (the bridge's first child endpoint). Used
 /// by the publisher to assign per-primitive endpoints deterministically.
+// P2 Matter-publisher API surface; real Matter exposure is deferred (ADR-159 §A5).
+#[allow(dead_code)]
 pub fn next_endpoint(base: u16, primitive_index: u16) -> u16 {
     base.saturating_add(primitive_index)
 }

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

@@ -1,6 +1,6 @@
 [package]
 name = "wifi-densepose-signal"
-version = "0.3.3"
+version = "0.3.4"
 edition.workspace = true
 description = "WiFi CSI signal processing for DensePose estimation"
 license.workspace = true

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

@@ -1,7 +1,7 @@
 //! Criterion benchmarks for the empty-room baseline calibration module (ADR-135).
 //!
 //! Measures per-call throughput of CalibrationRecorder and BaselineCalibration
-//! across HT20 (K=52), HT40 (K=114), HE20 (K=242), and HE40 (K=484).
+//! across HT20 (K=52), HT40 (K=114), HE20 (K=256, all bins; #1009), and HE40 (K=484).
 //!
 //! Run (compile-only — no execution):
 //!   cargo bench -p wifi-densepose-signal --no-default-features --bench calibration_bench --no-run
@@ -63,7 +63,8 @@ fn tiers() -> Vec<TierSpec> {
     vec![
         TierSpec { label: "ht20", n_active: 52,  bandwidth_mhz: 20, config: CalibrationConfig::ht20() },
         TierSpec { label: "ht40", n_active: 114, bandwidth_mhz: 40, config: CalibrationConfig::ht40() },
-        TierSpec { label: "he20", n_active: 242, bandwidth_mhz: 20, config: CalibrationConfig::he20() },
+        // Issue #1009 §1b: HE20 records all 256 delivered bins (he20().num_active == 256).
+        TierSpec { label: "he20", n_active: 256, bandwidth_mhz: 20, config: CalibrationConfig::he20() },
         TierSpec { label: "he40", n_active: 484, bandwidth_mhz: 40, config: CalibrationConfig::he40() },
     ]
 }

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

@@ -109,9 +109,26 @@ impl CalibrationConfig {
     pub fn ht40() -> Self {
         Self { tier: PhyTier::Ht40, num_subcarriers: 128, num_active: 114, min_frames: 600, max_phase_variance: 0.3 }
     }
-    /// HE20 defaults: 256 FFT, 242 active.
+    /// HE20 defaults: 256 FFT, **256 active** (record all delivered bins).
+    ///
+    /// Issue #1009: the ESP-IDF v5.5.2 driver delivers all 256 FFT bins on the
+    /// wire for an HE20 frame (242 data tones + pilots + guards + DC; n_subc =
+    /// 0x0100 LE, wire-verified on ESP32-C6). We set `num_active: 256` so the
+    /// recorder accumulates statistics over **every** delivered bin rather than
+    /// trimming to the first 242 columns.
+    ///
+    /// Why not 242? `CalibrationRecorder` has no HE20 tone map — `extract_first_stream`
+    /// takes the first `num_active` columns *sequentially*. With 242 it would
+    /// keep bins 0..242 of the 256-bin grid, which are NOT the 242 active tones
+    /// (they include the lower guard band and DC) — silently corrupting the
+    /// empty-room baseline. Recording all 256 bins keeps amplitude/phase stats
+    /// aligned 1:1 with the live `deviation()` path (which also sees 256 bins),
+    /// so guard/DC bins simply carry near-zero, stable statistics and never
+    /// generate false occupancy alarms. The exact-242 tone map lives only in
+    /// `cir.rs` (`HE20_ACTIVE`), where the Φ sensing matrix genuinely needs it;
+    /// the baseline recorder does not.
     pub fn he20() -> Self {
-        Self { tier: PhyTier::He20, num_subcarriers: 256, num_active: 242, min_frames: 600, max_phase_variance: 0.3 }
+        Self { tier: PhyTier::He20, num_subcarriers: 256, num_active: 256, min_frames: 600, max_phase_variance: 0.3 }
     }
     /// HE40 defaults: 512 FFT, 484 active.
     pub fn he40() -> Self {
@@ -674,13 +691,38 @@ mod tests {
 
         let he20 = CalibrationConfig::he20();
         assert_eq!(he20.num_subcarriers, 256);
-        assert_eq!(he20.num_active, 242);
+        // Issue #1009: HE20 records all 256 delivered bins (no tone map in the
+        // baseline recorder), not the 242 active tones — see he20() rationale.
+        assert_eq!(he20.num_active, 256);
 
         let he40 = CalibrationConfig::he40();
         assert_eq!(he40.num_subcarriers, 512);
         assert_eq!(he40.num_active, 484);
     }
 
+    // Issue #1009 §1b: a real HE20 frame carries all 256 FFT bins. The recorder
+    // must accept it AND build the baseline over all 256 bins — not silently
+    // trim to the first 242 columns (which are guards/DC, not active tones).
+    //
+    // FAILS ON OLD CODE: with `he20().num_active == 242` the finalised baseline
+    // had only 242 subcarriers (256 → 242 sequential trim). This asserts 256.
+    #[test]
+    fn he20_records_all_256_bins_not_trimmed_to_242() {
+        let mut cfg = CalibrationConfig::he20();
+        cfg.min_frames = 1;
+        let mut rec = CalibrationRecorder::new(cfg);
+        // Feed a 256-bin frame exactly as ESP-IDF v5.5.2 delivers it.
+        let frame = constant_frame(256, 1.0, 0.0);
+        rec.record(&frame).expect("256-bin HE20 frame must be accepted");
+        let baseline = rec.finalize().expect("finalize after 1 frame (min_frames=1)");
+        assert_eq!(
+            baseline.subcarriers.len(),
+            256,
+            "HE20 baseline must cover all 256 delivered bins, not a 242-trim"
+        );
+        assert_eq!(baseline.tier, PhyTier::He20);
+    }
+
     // Additional: insufficient frames → error.
     #[test]
     fn finalize_requires_min_frames() {

v2/crates/wifi-densepose-signal/tests/calibration_synthetic.rs

@@ -67,7 +67,10 @@ fn ht40_spec() -> TierSpec {
     TierSpec { label: "HT40", n_active: 114, bandwidth_mhz: 40, config: CalibrationConfig::ht40() }
 }
 fn he20_spec() -> TierSpec {
-    TierSpec { label: "HE20", n_active: 242, bandwidth_mhz: 20, config: CalibrationConfig::he20() }
+    // Issue #1009 §1b: real HE20 frames carry all 256 FFT bins (242 data +
+    // pilots/guards/DC), and the recorder now records all 256 (he20().num_active
+    // == 256). Feed 256-bin frames to match the wire format.
+    TierSpec { label: "HE20", n_active: 256, bandwidth_mhz: 20, config: CalibrationConfig::he20() }
 }
 
 // ---------------------------------------------------------------------------

v2/crates/wifi-densepose-wasm-edge/Cargo.lock

@@ -2,6 +2,33 @@
 # It is not intended for manual editing.
 version = 4
 
+[[package]]
+name = "aho-corasick"
+version = "1.1.4"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "ddd31a130427c27518df266943a5308ed92d4b226cc639f5a8f1002816174301"
+dependencies = [
+ "memchr",
+]
+
+[[package]]
+name = "anes"
+version = "0.1.6"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "4b46cbb362ab8752921c97e041f5e366ee6297bd428a31275b9fcf1e380f7299"
+
+[[package]]
+name = "anstyle"
+version = "1.0.14"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "940b3a0ca603d1eade50a4846a2afffd5ef57a9feac2c0e2ec2e14f9ead76000"
+
+[[package]]
+name = "autocfg"
+version = "1.5.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "f2032f911046de80f0a198e0901378627c33f59ea0ac00e363d481118bd70a53"
+
 [[package]]
 name = "block-buffer"
 version = "0.10.4"
@@ -11,12 +38,76 @@ dependencies = [
  "generic-array",
 ]
 
+[[package]]
+name = "bumpalo"
+version = "3.20.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "72f5acc6cb2ba439de613abc23857ec3d78374d8ed5ac84e9d11336e87da8649"
+
+[[package]]
+name = "cast"
+version = "0.3.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "37b2a672a2cb129a2e41c10b1224bb368f9f37a2b16b612598138befd7b37eb5"
+
 [[package]]
 name = "cfg-if"
 version = "1.0.4"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "9330f8b2ff13f34540b44e946ef35111825727b38d33286ef986142615121801"
 
+[[package]]
+name = "ciborium"
+version = "0.2.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "42e69ffd6f0917f5c029256a24d0161db17cea3997d185db0d35926308770f0e"
+dependencies = [
+ "ciborium-io",
+ "ciborium-ll",
+ "serde",
+]
+
+[[package]]
+name = "ciborium-io"
+version = "0.2.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "05afea1e0a06c9be33d539b876f1ce3692f4afea2cb41f740e7743225ed1c757"
+
+[[package]]
+name = "ciborium-ll"
+version = "0.2.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "57663b653d948a338bfb3eeba9bb2fd5fcfaecb9e199e87e1eda4d9e8b240fd9"
+dependencies = [
+ "ciborium-io",
+ "half",
+]
+
+[[package]]
+name = "clap"
+version = "4.6.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "1ddb117e43bbf7dacf0a4190fef4d345b9bad68dfc649cb349e7d17d28428e51"
+dependencies = [
+ "clap_builder",
+]
+
+[[package]]
+name = "clap_builder"
+version = "4.6.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "714a53001bf66416adb0e2ef5ac857140e7dc3a0c48fb28b2f10762fc4b5069f"
+dependencies = [
+ "anstyle",
+ "clap_lex",
+]
+
+[[package]]
+name = "clap_lex"
+version = "1.1.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "c8d4a3bb8b1e0c1050499d1815f5ab16d04f0959b233085fb31653fbfc9d98f9"
+
 [[package]]
 name = "cpufeatures"
 version = "0.2.17"
@@ -26,6 +117,73 @@ dependencies = [
  "libc",
 ]
 
+[[package]]
+name = "criterion"
+version = "0.5.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "f2b12d017a929603d80db1831cd3a24082f8137ce19c69e6447f54f5fc8d692f"
+dependencies = [
+ "anes",
+ "cast",
+ "ciborium",
+ "clap",
+ "criterion-plot",
+ "is-terminal",
+ "itertools",
+ "num-traits",
+ "once_cell",
+ "oorandom",
+ "plotters",
+ "rayon",
+ "regex",
+ "serde",
+ "serde_derive",
+ "serde_json",
+ "tinytemplate",
+ "walkdir",
+]
+
+[[package]]
+name = "criterion-plot"
+version = "0.5.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "6b50826342786a51a89e2da3a28f1c32b06e387201bc2d19791f622c673706b1"
+dependencies = [
+ "cast",
+ "itertools",
+]
+
+[[package]]
+name = "crossbeam-deque"
+version = "0.8.6"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "9dd111b7b7f7d55b72c0a6ae361660ee5853c9af73f70c3c2ef6858b950e2e51"
+dependencies = [
+ "crossbeam-epoch",
+ "crossbeam-utils",
+]
+
+[[package]]
+name = "crossbeam-epoch"
+version = "0.9.18"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "5b82ac4a3c2ca9c3460964f020e1402edd5753411d7737aa39c3714ad1b5420e"
+dependencies = [
+ "crossbeam-utils",
+]
+
+[[package]]
+name = "crossbeam-utils"
+version = "0.8.21"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "d0a5c400df2834b80a4c3327b3aad3a4c4cd4de0629063962b03235697506a28"
+
+[[package]]
+name = "crunchy"
+version = "0.2.4"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "460fbee9c2c2f33933d720630a6a0bac33ba7053db5344fac858d4b8952d77d5"
+
 [[package]]
 name = "crypto-common"
 version = "0.1.7"
@@ -46,6 +204,36 @@ dependencies = [
  "crypto-common",
 ]
 
+[[package]]
+name = "either"
+version = "1.16.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "91622ff5e7162018101f2fea40d6ebf4a78bbe5a49736a2020649edf9693679e"
+
+[[package]]
+name = "futures-core"
+version = "0.3.32"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "7e3450815272ef58cec6d564423f6e755e25379b217b0bc688e295ba24df6b1d"
+
+[[package]]
+name = "futures-task"
+version = "0.3.32"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "037711b3d59c33004d3856fbdc83b99d4ff37a24768fa1be9ce3538a1cde4393"
+
+[[package]]
+name = "futures-util"
+version = "0.3.32"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "389ca41296e6190b48053de0321d02a77f32f8a5d2461dd38762c0593805c6d6"
+dependencies = [
+ "futures-core",
+ "futures-task",
+ "pin-project-lite",
+ "slab",
+]
+
 [[package]]
 name = "generic-array"
 version = "0.14.7"
@@ -56,6 +244,60 @@ dependencies = [
  "version_check",
 ]
 
+[[package]]
+name = "half"
+version = "2.7.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "6ea2d84b969582b4b1864a92dc5d27cd2b77b622a8d79306834f1be5ba20d84b"
+dependencies = [
+ "cfg-if",
+ "crunchy",
+ "zerocopy",
+]
+
+[[package]]
+name = "hermit-abi"
+version = "0.5.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "fc0fef456e4baa96da950455cd02c081ca953b141298e41db3fc7e36b1da849c"
+
+[[package]]
+name = "is-terminal"
+version = "0.4.17"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "3640c1c38b8e4e43584d8df18be5fc6b0aa314ce6ebf51b53313d4306cca8e46"
+dependencies = [
+ "hermit-abi",
+ "libc",
+ "windows-sys",
+]
+
+[[package]]
+name = "itertools"
+version = "0.10.5"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "b0fd2260e829bddf4cb6ea802289de2f86d6a7a690192fbe91b3f46e0f2c8473"
+dependencies = [
+ "either",
+]
+
+[[package]]
+name = "itoa"
+version = "1.0.18"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "8f42a60cbdf9a97f5d2305f08a87dc4e09308d1276d28c869c684d7777685682"
+
+[[package]]
+name = "js-sys"
+version = "0.3.100"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "f2025f20d7a4fa7785846e7b63d10a76d3f1cee98ee5cb79ea59703f95e42162"
+dependencies = [
+ "cfg-if",
+ "futures-util",
+ "wasm-bindgen",
+]
+
 [[package]]
 name = "libc"
 version = "0.2.182"
@@ -68,6 +310,192 @@ version = "0.2.16"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "b6d2cec3eae94f9f509c767b45932f1ada8350c4bdb85af2fcab4a3c14807981"
 
+[[package]]
+name = "memchr"
+version = "2.8.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "88904434abc2901f197fe8cc55f0445e7ded921dba5911dad2e2b39b48e663c4"
+
+[[package]]
+name = "num-traits"
+version = "0.2.19"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "071dfc062690e90b734c0b2273ce72ad0ffa95f0c74596bc250dcfd960262841"
+dependencies = [
+ "autocfg",
+]
+
+[[package]]
+name = "once_cell"
+version = "1.21.4"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "9f7c3e4beb33f85d45ae3e3a1792185706c8e16d043238c593331cc7cd313b50"
+
+[[package]]
+name = "oorandom"
+version = "11.1.5"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "d6790f58c7ff633d8771f42965289203411a5e5c68388703c06e14f24770b41e"
+
+[[package]]
+name = "pin-project-lite"
+version = "0.2.17"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "a89322df9ebe1c1578d689c92318e070967d1042b512afbe49518723f4e6d5cd"
+
+[[package]]
+name = "plotters"
+version = "0.3.7"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "5aeb6f403d7a4911efb1e33402027fc44f29b5bf6def3effcc22d7bb75f2b747"
+dependencies = [
+ "num-traits",
+ "plotters-backend",
+ "plotters-svg",
+ "wasm-bindgen",
+ "web-sys",
+]
+
+[[package]]
+name = "plotters-backend"
+version = "0.3.7"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "df42e13c12958a16b3f7f4386b9ab1f3e7933914ecea48da7139435263a4172a"
+
+[[package]]
+name = "plotters-svg"
+version = "0.3.7"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "51bae2ac328883f7acdfea3d66a7c35751187f870bc81f94563733a154d7a670"
+dependencies = [
+ "plotters-backend",
+]
+
+[[package]]
+name = "proc-macro2"
+version = "1.0.106"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "8fd00f0bb2e90d81d1044c2b32617f68fcb9fa3bb7640c23e9c748e53fb30934"
+dependencies = [
+ "unicode-ident",
+]
+
+[[package]]
+name = "quote"
+version = "1.0.45"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "41f2619966050689382d2b44f664f4bc593e129785a36d6ee376ddf37259b924"
+dependencies = [
+ "proc-macro2",
+]
+
+[[package]]
+name = "rayon"
+version = "1.12.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "fb39b166781f92d482534ef4b4b1b2568f42613b53e5b6c160e24cfbfa30926d"
+dependencies = [
+ "either",
+ "rayon-core",
+]
+
+[[package]]
+name = "rayon-core"
+version = "1.13.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "22e18b0f0062d30d4230b2e85ff77fdfe4326feb054b9783a3460d8435c8ab91"
+dependencies = [
+ "crossbeam-deque",
+ "crossbeam-utils",
+]
+
+[[package]]
+name = "regex"
+version = "1.12.4"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "f1292b7759ae1cb9ec195452d1390a074f0cd8541ab7a5a8c31cd6db45d4a6ba"
+dependencies = [
+ "aho-corasick",
+ "memchr",
+ "regex-automata",
+ "regex-syntax",
+]
+
+[[package]]
+name = "regex-automata"
+version = "0.4.14"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "6e1dd4122fc1595e8162618945476892eefca7b88c52820e74af6262213cae8f"
+dependencies = [
+ "aho-corasick",
+ "memchr",
+ "regex-syntax",
+]
+
+[[package]]
+name = "regex-syntax"
+version = "0.8.11"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "d6f6ff9a378485b298a5286656da665ba74413d36db0979633275d2e708145d4"
+
+[[package]]
+name = "rustversion"
+version = "1.0.22"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "b39cdef0fa800fc44525c84ccb54a029961a8215f9619753635a9c0d2538d46d"
+
+[[package]]
+name = "same-file"
+version = "1.0.6"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "93fc1dc3aaa9bfed95e02e6eadabb4baf7e3078b0bd1b4d7b6b0b68378900502"
+dependencies = [
+ "winapi-util",
+]
+
+[[package]]
+name = "serde"
+version = "1.0.228"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "9a8e94ea7f378bd32cbbd37198a4a91436180c5bb472411e48b5ec2e2124ae9e"
+dependencies = [
+ "serde_core",
+ "serde_derive",
+]
+
+[[package]]
+name = "serde_core"
+version = "1.0.228"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "41d385c7d4ca58e59fc732af25c3983b67ac852c1a25000afe1175de458b67ad"
+dependencies = [
+ "serde_derive",
+]
+
+[[package]]
+name = "serde_derive"
+version = "1.0.228"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "d540f220d3187173da220f885ab66608367b6574e925011a9353e4badda91d79"
+dependencies = [
+ "proc-macro2",
+ "quote",
+ "syn",
+]
+
+[[package]]
+name = "serde_json"
+version = "1.0.150"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "e8014e44b4736ed0538adeecded0fce2a272f22dc9578a7eb6b2d9993c74cfb9"
+dependencies = [
+ "itoa",
+ "memchr",
+ "serde",
+ "serde_core",
+ "zmij",
+]
+
 [[package]]
 name = "sha2"
 version = "0.10.9"
@@ -79,22 +507,171 @@ dependencies = [
  "digest",
 ]
 
+[[package]]
+name = "slab"
+version = "0.4.12"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "0c790de23124f9ab44544d7ac05d60440adc586479ce501c1d6d7da3cd8c9cf5"
+
+[[package]]
+name = "syn"
+version = "2.0.117"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "e665b8803e7b1d2a727f4023456bbbbe74da67099c585258af0ad9c5013b9b99"
+dependencies = [
+ "proc-macro2",
+ "quote",
+ "unicode-ident",
+]
+
+[[package]]
+name = "tinytemplate"
+version = "1.2.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "be4d6b5f19ff7664e8c98d03e2139cb510db9b0a60b55f8e8709b689d939b6bc"
+dependencies = [
+ "serde",
+ "serde_json",
+]
+
 [[package]]
 name = "typenum"
 version = "1.19.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "562d481066bde0658276a35467c4af00bdc6ee726305698a55b86e61d7ad82bb"
 
+[[package]]
+name = "unicode-ident"
+version = "1.0.24"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "e6e4313cd5fcd3dad5cafa179702e2b244f760991f45397d14d4ebf38247da75"
+
 [[package]]
 name = "version_check"
 version = "0.9.5"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "0b928f33d975fc6ad9f86c8f283853ad26bdd5b10b7f1542aa2fa15e2289105a"
 
+[[package]]
+name = "walkdir"
+version = "2.5.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "29790946404f91d9c5d06f9874efddea1dc06c5efe94541a7d6863108e3a5e4b"
+dependencies = [
+ "same-file",
+ "winapi-util",
+]
+
+[[package]]
+name = "wasm-bindgen"
+version = "0.2.123"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "a254a4b10c19a76f09a27640e7ffbf9bc30bf67e16a3bf28aaefa4920fe81563"
+dependencies = [
+ "cfg-if",
+ "once_cell",
+ "rustversion",
+ "wasm-bindgen-macro",
+ "wasm-bindgen-shared",
+]
+
+[[package]]
+name = "wasm-bindgen-macro"
+version = "0.2.123"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "24a40fc75b0ec6f3746ceb10d36f53a93dcd68a93b11b6445983945d79eba0dc"
+dependencies = [
+ "quote",
+ "wasm-bindgen-macro-support",
+]
+
+[[package]]
+name = "wasm-bindgen-macro-support"
+version = "0.2.123"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "908f34bd9b9ce3d4caf07b72dfab63d61504d156856c6bd3cd87fa350cf3985b"
+dependencies = [
+ "bumpalo",
+ "proc-macro2",
+ "quote",
+ "syn",
+ "wasm-bindgen-shared",
+]
+
+[[package]]
+name = "wasm-bindgen-shared"
+version = "0.2.123"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "7acbf7616c27b194bbb550bf77ed0c2c3e5b7fd1260a93082b95fb7f47959b92"
+dependencies = [
+ "unicode-ident",
+]
+
+[[package]]
+name = "web-sys"
+version = "0.3.100"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "6e0871acf327f283dc6da28a1696cdc64fb355ba9f935d052021fa77f35cce69"
+dependencies = [
+ "js-sys",
+ "wasm-bindgen",
+]
+
 [[package]]
 name = "wifi-densepose-wasm-edge"
 version = "0.3.0"
 dependencies = [
+ "criterion",
  "libm",
  "sha2",
 ]
+
+[[package]]
+name = "winapi-util"
+version = "0.1.11"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "c2a7b1c03c876122aa43f3020e6c3c3ee5c05081c9a00739faf7503aeba10d22"
+dependencies = [
+ "windows-sys",
+]
+
+[[package]]
+name = "windows-link"
+version = "0.2.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "f0805222e57f7521d6a62e36fa9163bc891acd422f971defe97d64e70d0a4fe5"
+
+[[package]]
+name = "windows-sys"
+version = "0.61.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "ae137229bcbd6cdf0f7b80a31df61766145077ddf49416a728b02cb3921ff3fc"
+dependencies = [
+ "windows-link",
+]
+
+[[package]]
+name = "zerocopy"
+version = "0.8.52"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "ce1022995ff5ff5d841ad7d994facc23098cd40152f2c1d11cd607c6f530653f"
+dependencies = [
+ "zerocopy-derive",
+]
+
+[[package]]
+name = "zerocopy-derive"
+version = "0.8.52"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "1ae7f38b72ec2a254e2b87ef277cf2cd4fb97cbebf944faa6f33354da0867930"
+dependencies = [
+ "proc-macro2",
+ "quote",
+ "syn",
+]
+
+[[package]]
+name = "zmij"
+version = "1.0.21"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "b8848ee67ecc8aedbaf3e4122217aff892639231befc6a1b58d29fff4c2cabaa"

v2/crates/wifi-densepose-wasm-edge/Cargo.toml

@@ -11,6 +11,20 @@ categories = ["embedded", "wasm", "science"]
 
 [lib]
 crate-type = ["cdylib", "rlib"]
+# The lib's libtest harness does not understand criterion CLI flags
+# (`--warm-up-time` etc.), so exclude it from `cargo bench` — only the criterion
+# bench target below should receive bench args (ADR-163).
+bench = false
+
+# ADR-163: host-measured process_frame latency benches (closes the ADR-160
+# "criterion benches for process_frame budget claims" deferred item — HOST only;
+# the ESP32-S3 WASM3 budget remains unmeasured, see the bench header).
+# `std` is required (criterion is a host crate); the crate is workspace-EXCLUDED
+# so run from the crate dir: `cargo bench --features std`.
+[[bench]]
+name = "process_frame_bench"
+harness = false
+required-features = ["std"]
 
 [dependencies]
 # no_std math
@@ -18,6 +32,11 @@ libm = "0.2"
 # SHA-256 for RVF build hash (optional, used by builder)
 sha2 = { version = "0.10", optional = true, default-features = false }
 
+[dev-dependencies]
+# Host-only latency regression benches (ADR-163). Pinned to match the rest of
+# the workspace's bench crates.
+criterion = { version = "0.5", features = ["html_reports"] }
+
 [features]
 default = ["default-pipeline"]
 # Enable std for testing on host + RVF builder

v2/crates/wifi-densepose-wasm-edge/benches/process_frame_bench.rs

@@ -0,0 +1,259 @@
+//! Criterion benches for the heaviest `process_frame` hot paths in the edge
+//! skill library (ADR-163, closing the ADR-160 §"Deferred Backlog" item
+//! "Criterion benches for process_frame budget claims").
+//!
+//! ## HONEST SCOPE — read this before citing any number here
+//!
+//! These benches measure **HOST** wall-clock latency on a development laptop.
+//! The per-module doc budgets (e.g. `exo_time_crystal` "H (heavy, <10ms) on
+//! ESP32-S3 WASM3") are **for a different target**: an Xtensa ESP32-S3 running
+//! the WASM3 interpreter. A native x86_64 host with `-O` is an **upper-bound
+//! proxy for the ALGORITHM cost only**; it is NOT the ESP32 number and does NOT
+//! reproduce the ESP32 budget. WASM3 interpretation on a ~240 MHz Xtensa core is
+//! typically 1-2 orders of magnitude slower than native host code, so a host
+//! median well under the budget does NOT prove the ESP32 meets it — it only
+//! bounds the work. The ESP32 figure remains UNMEASURED (needs hardware).
+//!
+//! What these benches DO prove (MEASURED-on-host):
+//!   * the hot paths run, on a fixed synthetic CSI frame, with a real median;
+//!   * a regression guard exists so a future change that 10×'s the host cost
+//!     is caught in CI/dev even before anyone reflashes an ESP32.
+//!
+//! Run (the crate is EXCLUDED from the v2 workspace — bench from the crate dir):
+//!   cd v2/crates/wifi-densepose-wasm-edge
+//!   cargo bench --features std
+//!   # quick smoke:
+//!   cargo bench --features std -- --warm-up-time 1 --measurement-time 2
+//!
+//! `med_seizure_detect` is gated behind `medical-experimental`; its bench is
+//! `#[cfg(feature = "medical-experimental")]` and only runs when that feature is
+//! also enabled:
+//!   cargo bench --features std,medical-experimental
+
+use criterion::{criterion_group, criterion_main, BatchSize, Criterion};
+use std::hint::black_box;
+
+use wifi_densepose_wasm_edge::exo_ghost_hunter::GhostHunterDetector;
+use wifi_densepose_wasm_edge::exo_time_crystal::TimeCrystalDetector;
+use wifi_densepose_wasm_edge::sec_weapon_detect::WeaponDetector;
+
+// ── Fixed synthetic CSI fixtures (deterministic LCG, seed-stable) ────────────
+
+/// Deterministic pseudo-random in [lo, hi) from a 32-bit LCG, matching the
+/// generator style used by `tests/budget_compliance.rs`.
+fn lcg(seed: &mut u32) -> f32 {
+    *seed = seed.wrapping_mul(1103515245).wrapping_add(12345);
+    (*seed >> 16) as f32 / 32768.0
+}
+
+fn synthetic_phases(n: usize, seed: u32) -> Vec<f32> {
+    let mut s = seed;
+    (0..n).map(|_| lcg(&mut s) * 6.2832 - 3.1416).collect()
+}
+
+fn synthetic_amplitudes(n: usize, seed: u32) -> Vec<f32> {
+    let mut s = seed;
+    (0..n).map(|_| lcg(&mut s) * 10.0 + 0.1).collect()
+}
+
+fn synthetic_variance(n: usize, seed: u32) -> Vec<f32> {
+    let mut s = seed;
+    (0..n).map(|_| lcg(&mut s) * 2.0 + 0.05).collect()
+}
+
+const N_SC: usize = 32; // per-subcarrier width (matches both modules' MAX_SC)
+
+// ── exo_time_crystal: compute_autocorrelation 256×128 hot path ───────────────
+//
+// `compute_autocorrelation` is private, so we drive it through the public
+// `process_frame`. To hit the full 256-point × 128-lag autocorrelation the
+// circular buffer must be FULL (≥256 samples) and the signal must be
+// non-constant (the module early-outs on `buf_var < 1e-8`). We pre-fill once
+// with a periodic-plus-noise motion-energy stream, then bench a single
+// `process_frame` (each call recomputes the full 256×128 autocorrelation =
+// ~32K multiply-accumulates, the M6-audit-named hot path).
+
+fn prefilled_time_crystal() -> TimeCrystalDetector {
+    let mut d = TimeCrystalDetector::new();
+    let mut s = 0xC0FFEEu32;
+    // 300 frames (> BUF_LEN=256) so the buffer is full and statistics are warm.
+    for i in 0..300 {
+        // period-10 square wave + small noise → guarantees buf_var > 0 and a
+        // genuine autocorrelation structure (the expensive path runs).
+        let base = if (i % 10) < 5 { 1.0 } else { 0.0 };
+        let me = base + lcg(&mut s) * 0.05;
+        black_box(d.process_frame(black_box(me)));
+    }
+    d
+}
+
+fn bench_exo_time_crystal(c: &mut Criterion) {
+    c.bench_function("exo_time_crystal::process_frame[autocorr_256x128]", |b| {
+        let mut s = 0x1357_9BDFu32;
+        b.iter_batched(
+            prefilled_time_crystal,
+            |mut d| {
+                // One frame = one full 256×128 autocorrelation pass.
+                let me = if (d.frame_count() % 10) < 5 { 1.0 } else { 0.0 } + lcg(&mut s) * 0.05;
+                black_box(d.process_frame(black_box(me)));
+            },
+            BatchSize::SmallInput,
+        );
+    });
+}
+
+// ── exo_ghost_hunter: periodicity + hidden-breathing hot path ────────────────
+//
+// Heaviest path runs only when the room is reported EMPTY (presence == 0):
+// per-group anomaly accumulation + aggregate-phase autocorrelation for hidden
+// periodic (breathing) signatures. We warm the noise floor + phase buffer first,
+// then bench one empty-room frame.
+
+fn prefilled_ghost_hunter() -> GhostHunterDetector {
+    let mut d = GhostHunterDetector::new();
+    let mut s = 0xBADC0DEu32;
+    // Warm the per-group EWMA noise floors + fill the phase buffer (PHASE_BUF_LEN=64)
+    // with a periodic phase signal so the periodicity autocorrelation has structure.
+    for i in 0..120u32 {
+        let phases: Vec<f32> = (0..N_SC)
+            .map(|k| libm::sinf(i as f32 * 0.4 + k as f32 * 0.1) * 0.3 + lcg(&mut s) * 0.02)
+            .collect();
+        let amps = synthetic_amplitudes(N_SC, 4000 + i);
+        let var = synthetic_variance(N_SC, 4500 + i);
+        black_box(d.process_frame(&phases, &amps, &var, 0, 0.05));
+    }
+    d
+}
+
+fn bench_exo_ghost_hunter(c: &mut Criterion) {
+    let amps = synthetic_amplitudes(N_SC, 9000);
+    let var = synthetic_variance(N_SC, 9500);
+    c.bench_function("exo_ghost_hunter::process_frame[empty_room_periodicity]", |b| {
+        let mut s = 0x2468_ACE0u32;
+        b.iter_batched(
+            prefilled_ghost_hunter,
+            |mut d| {
+                let i = d.frame_count();
+                let phases: Vec<f32> = (0..N_SC)
+                    .map(|k| libm::sinf(i as f32 * 0.4 + k as f32 * 0.1) * 0.3 + lcg(&mut s) * 0.02)
+                    .collect();
+                black_box(d.process_frame(
+                    black_box(&phases),
+                    black_box(&amps),
+                    black_box(&var),
+                    black_box(0),
+                    black_box(0.05),
+                ));
+            },
+            BatchSize::SmallInput,
+        );
+    });
+}
+
+// ── sec_weapon_detect: per-subcarrier Welford hot path ───────────────────────
+//
+// After calibration the detector runs a per-subcarrier online Welford update
+// over MAX_SC=32 subcarriers each frame (the M6-audit-named hot path). We
+// calibrate first (the early frames just accumulate baseline stats), then bench
+// one steady-state frame.
+
+fn calibrated_weapon_detector() -> WeaponDetector {
+    let mut d = WeaponDetector::new();
+    // Drive enough empty-room frames to complete calibration + warm the running
+    // Welford state. Calibration window is internal; 200 frames is comfortably
+    // past it for MAX_SC=32.
+    for i in 0..200u32 {
+        let phases = synthetic_phases(N_SC, 6000 + i);
+        let amps = synthetic_amplitudes(N_SC, 6500 + i);
+        let var = synthetic_variance(N_SC, 7000 + i);
+        black_box(d.process_frame(&phases, &amps, &var, 0.05, 0));
+    }
+    d
+}
+
+fn bench_sec_weapon_detect(c: &mut Criterion) {
+    c.bench_function("sec_weapon_detect::process_frame[per_sc_welford]", |b| {
+        let mut seed = 8000u32;
+        b.iter_batched(
+            calibrated_weapon_detector,
+            |mut d| {
+                seed = seed.wrapping_add(1);
+                let phases = synthetic_phases(N_SC, seed);
+                let amps = synthetic_amplitudes(N_SC, seed.wrapping_add(500));
+                let var = synthetic_variance(N_SC, seed.wrapping_add(1000));
+                black_box(d.process_frame(
+                    black_box(&phases),
+                    black_box(&amps),
+                    black_box(&var),
+                    black_box(0.3),
+                    black_box(1),
+                ));
+            },
+            BatchSize::SmallInput,
+        );
+    });
+}
+
+// ── med_seizure_detect: detect_rhythm / clonic autocorrelation hot path ──────
+//
+// Gated behind `medical-experimental` (ADR-160 §A1). The clonic-phase rhythm
+// detection autocorrelates the amplitude ring buffer (PHASE_WINDOW=100); we warm
+// the buffers with a high-energy rhythmic signal, then bench one frame.
+#[cfg(feature = "medical-experimental")]
+mod med {
+    use super::*;
+    use wifi_densepose_wasm_edge::med_seizure_detect::SeizureDetector;
+
+    fn warmed_seizure_detector() -> SeizureDetector {
+        let mut d = SeizureDetector::new();
+        let mut s = 0x5EE_D00Du32;
+        // High-energy ~4 Hz rhythmic (period ~5 frames at 20 Hz) → exercises the
+        // clonic-phase rhythm/autocorrelation path, with presence asserted.
+        for i in 0..150u32 {
+            let me = 2.5 + libm::sinf(i as f32 * 1.25) * 1.5;
+            let amp = 1.0 + lcg(&mut s) * 0.2;
+            black_box(d.process_frame(0.0, amp, me, 1));
+        }
+        d
+    }
+
+    pub fn bench_med_seizure_detect(c: &mut Criterion) {
+        c.bench_function("med_seizure_detect::process_frame[clonic_rhythm]", |b| {
+            let mut s = 0x9A_BCDE_F0u32;
+            b.iter_batched(
+                warmed_seizure_detector,
+                |mut d| {
+                    let i = d.frame_count();
+                    let me = 2.5 + libm::sinf(i as f32 * 1.25) * 1.5;
+                    let amp = 1.0 + lcg(&mut s) * 0.2;
+                    black_box(d.process_frame(
+                        black_box(0.0),
+                        black_box(amp),
+                        black_box(me),
+                        black_box(1),
+                    ));
+                },
+                BatchSize::SmallInput,
+            );
+        });
+    }
+}
+
+#[cfg(feature = "medical-experimental")]
+criterion_group!(
+    benches,
+    bench_exo_time_crystal,
+    bench_exo_ghost_hunter,
+    bench_sec_weapon_detect,
+    med::bench_med_seizure_detect,
+);
+
+#[cfg(not(feature = "medical-experimental"))]
+criterion_group!(
+    benches,
+    bench_exo_time_crystal,
+    bench_exo_ghost_hunter,
+    bench_sec_weapon_detect,
+);
+
+criterion_main!(benches);