Iter 37 — adds a fleet-summary gauge to the iter-36 Prometheus
exposition. Ops dashboards now answer "how many leaders / followers
/ no-sync nodes are there right now" in one scrape, without having
to scrape every per-node series and aggregate client-side.
# HELP wifi_densepose_mesh_node_total Per-state node count across the fleet
# TYPE wifi_densepose_mesh_node_total gauge
wifi_densepose_mesh_node_total{state="leader"} 1
wifi_densepose_mesh_node_total{state="follower"} 2
wifi_densepose_mesh_node_total{state="no_sync"} 0
- leader / follower split derived from snapshot.is_leader
- no_sync = total_nodes_in_state - nodes_with_snapshot
(so a node that has sent CSI frames but never a sync packet
shows up here, which is what an operator wants to alert on)
Implementation factored as a free function `fleet_role_counts` so the
math is testable without spinning up the axum handler. Same pattern
iter 18 (update_csi_fps_ema) and iter 30 (sync_snapshot) used.
Test added (9/9 sync_snapshot_helper_tests now green):
fleet_role_counts_classifies_correctly
Three cases:
- empty fleet → (0, 0)
- 1 leader + 2 followers → (1, 2)
- all-leaders edge case → (2, 0) (election prevents this in
practice but the gauge math must still be consistent)
Useful Grafana queries this unlocks:
- sum(wifi_densepose_mesh_node_total{state="follower"})
→ total reachable follower count
- wifi_densepose_mesh_node_total{state="no_sync"} > 0
→ alert when any node has dropped off the mesh
Co-Authored-By: claude-flow <ruv@ruv.net>
Iter 36 — Grafana / Home Assistant Prometheus integration / Cognitum
Seed observability stack can now scrape mesh state directly with no
JSON-to-metric translation layer.
Endpoint: GET /api/v1/mesh/metrics → text/plain (Prometheus exposition
format v0.0.4). Eight gauges, one per NodeSyncSnapshot field, labeled
by node:
wifi_densepose_mesh_offset_us{node="N"} <signed-int>
wifi_densepose_mesh_is_leader{node="N"} 0|1
wifi_densepose_mesh_is_valid{node="N"} 0|1
wifi_densepose_mesh_smoothed{node="N"} 0|1
wifi_densepose_mesh_sequence{node="N"} <u32>
wifi_densepose_mesh_csi_fps{node="N"} <float>
wifi_densepose_mesh_csi_fps_samples{node="N"} <u32>
wifi_densepose_mesh_staleness_ms{node="N"} <u64>
Each metric carries the standard `# HELP` + `# TYPE` headers before
its series block, exactly the format Prometheus + most scrape-format
implementations expect.
Implementation reuses iter-30's `NodeState::sync_snapshot()` as the
single source of truth — same data the JSON endpoints emit, just
text-formatted with `{node=...}` labels. Nodes without a fresh sync
are absent (Prometheus handles missing series natively).
Test added (8/8 sync_snapshot_helper_tests now green):
bool_metric_returns_zero_or_one_as_text
Pins the Prometheus convention that boolean gauges emit "0" or "1"
literally, never "false"/"true" — if anyone refactors the helper
to format!("{b}"), Prometheus would 400-reject the scrape; this
test catches that drift before production.
User-guide REST table updated with the new endpoint.
Grafana / HA scrape config:
- job_name: wifi-densepose-mesh
scrape_interval: 5s
metrics_path: /api/v1/mesh/metrics
static_configs:
- targets: ['localhost:3000']
Co-Authored-By: claude-flow <ruv@ruv.net>
Iter 35 — every cargo check / cargo test since iter 15 has emitted the
same warning:
warning: unused imports: `KeypointState`, `PoseTrack`, and `self`
--> crates/wifi-densepose-sensing-server/src/tracker_bridge.rs:10
The three unused names date from before the bridge was refactored
to use the `pose_tracker::PoseTracker` direct import on line 12.
Removing them clears the noise without changing any behavior — the
file's actual uses (`TrackLifecycleState`, `TrackId`, `NUM_KEYPOINTS`)
stay imported via the narrowed `use { ... }` list.
After this commit `cargo check -p wifi-densepose-sensing-server` shows
only the pre-existing `rvf_container.rs:128 associated function 'new'
is never used` warning, which is unrelated to ADR-110 and out of scope
for this loop.
Co-Authored-By: claude-flow <ruv@ruv.net>
Iter 34 — adds an optional `staleness_ms` field to the iter-23
NodeSyncSnapshot that exposes (Instant::now() - latest_sync_at).
Dashboards / Prometheus exporters / UI badges can now decay sync
freshness without re-deriving it from latest_sync_at on the host.
Wire compatibility: new field is `#[serde(skip_serializing_if =
"Option::is_none")]` so pre-iter-34 clients that strict-parse via
serde + deny_unknown_fields are unaffected (default serde_json
strategy is to ignore unknown fields anyway).
Sensing-server changes:
+ NodeSyncSnapshot.staleness_ms: Option<u64>
+ sync_snapshot() populates it via latest_sync_at.elapsed().as_millis()
+ iter-24 serialization tests now check 8 contract fields, not 7
+ new test `snapshot_staleness_ms_tracks_apply_time` pins
latest_sync_at to a past Instant and asserts the snapshot reports
~750 ms staleness with ±500 ms tolerance for scheduler delay
User-guide updates:
+ REST/WebSocket field table grows a `staleness_ms` row with the
UI-rendering thresholds (fade at 5 s, drop at 9 s to match the
firmware's VALID_WINDOW_MS-derived gate).
Tests passing:
sync_snapshot_helper_tests: 7/7
node_sync_snapshot_serialization_tests: 3/3 (8-field assertion green)
Co-Authored-By: claude-flow <ruv@ruv.net>
Iter 33 — closes a real test-coverage gap. The iter 17 staleness gate
(returns None when latest_sync_at is older than 9 s = 3 × the firmware's
VALID_WINDOW_MS) was shipped but never directly tested. A future
careless edit changing `from_secs(9)` to e.g. `from_secs(90)` would
silently break ADR-029/030 multistatic fusion freshness guarantees.
Test (3 assertions, no sleep — uses `Instant::checked_sub` to set
latest_sync_at to past values directly):
* 1 s old → Some (fresh)
* 8 s old → Some (just inside the gate)
* 10 s old → None (just outside the gate)
If anyone widens or narrows the gate, exactly one of these assertions
fires and points at the off-by-one. Total time for the test < 1 ms.
sync_snapshot_helper_tests: 6/6 green.
Branch-coord clean — main.rs only.
Co-Authored-By: claude-flow <ruv@ruv.net>
Iter 32 — completes the helper-extraction discipline started in iter 30.
The iter 15 inline `ns.latest_sync = Some(sync); ns.latest_sync_at = ...`
was the LAST untested receive-side mutation; now it's a named method
with 2 tests covering its full state-transition surface.
Refactor:
Add `NodeState::apply_sync_packet(pkt, now)` taking an Instant so
the test can pass deterministic timing.
udp_receiver_task now calls the method instead of touching the
fields inline — one less place to break the staleness gate.
Tests (2 new — sync_snapshot_helper_tests module now at 5 tests):
apply_sync_packet_populates_a_fresh_node
Mirrors udp_receiver_task's first-packet-from-unknown-node path:
asserts latest_sync goes from None → Some, latest_sync_at matches
the passed Instant exactly (no clock skew from real Instant::now()),
and sync_snapshot() now returns Some (REST 200 OK path lit up).
apply_sync_packet_overwrites_older_data
Subsequent packets must replace, not accumulate. Asserts sequence,
local_us advance, and the staleness clock resets. This is what
keeps the §A0.10-smoothed offset tracking the latest beacon rather
than drifting with stale state.
cargo test sync_snapshot_helper → 5/5 green.
Branch-coord clean — no Cargo.toml / cli.rs touched.
Co-Authored-By: claude-flow <ruv@ruv.net>
Iter 30 — defends the iter 29 REST endpoints + iter 23 WebSocket
broadcast with tests, AND deduplicates the four call sites that all
built the same NodeSyncSnapshot inline.
Refactor:
Add `NodeState::sync_snapshot() -> Option<NodeSyncSnapshot>` as the
single source of truth. All four call sites simplified:
1. node_sync_endpoint (REST /api/v1/nodes/:id/sync) — 12 → 5 lines
2. mesh_endpoint (REST /api/v1/mesh) — 11 → 3 lines
3. WebSocket vitals-only NodeInfo (line 4284) — 9 → 1 line
4. WebSocket CSI-frame NodeInfo (line 4617) — 9 → 1 line
Net: -35 lines, single point of contact for any future schema change.
Tests (3 new, all green; brings binary suite to 95+):
fresh_node_with_no_sync_returns_none
Mirrors REST 404 "no_sync" + WebSocket sync omission paths.
node_with_latest_sync_produces_correct_snapshot
Mirrors REST 200 OK + WebSocket sync field paths.
Asserts §A0.10's measured 1_163_565 µs offset survives the helper.
snapshot_reflects_leader_state
Leader-case shape: is_leader=true, offset≈0 (–7 µs call-stack).
These tests cover BOTH REST routes and BOTH WebSocket NodeInfo sites
through the shared helper — one test per behavioral path, no axum
state plumbing required. cargo check -p ...sensing-server → green.
Co-Authored-By: claude-flow <ruv@ruv.net>
Iter 29 — extends the iter 23 WebSocket NodeSyncSnapshot publication
with an HTTP surface so non-streaming clients (curl scripts, Home
Assistant REST sensors, Prometheus exporters, automation rule probes)
can poll mesh state without holding a WebSocket connection.
GET /api/v1/nodes/:id/sync
200 → Json(NodeSyncSnapshot) when latest_sync is present
404 → {"error": "unknown_node" | "no_sync", "node_id": N}
— "no_sync" includes a `hint` pointing operators at the
"no mesh peer or not v0.6.9+" diagnostic.
GET /api/v1/mesh
200 → { "nodes": { "<id>": NodeSyncSnapshot, ... }, "total": N }
Nodes without a recent sync are omitted; an empty `nodes` object
means no mesh peers reachable.
Both handlers reuse the iter 23 NodeSyncSnapshot struct (same JSON
shape as the WebSocket broadcast — clients get one schema, two
delivery modes). The Path<u8> extractor returns 404 on overflow
automatically (axum), so /api/v1/nodes/256/sync gives a clean error.
cargo check -p wifi-densepose-sensing-server --no-default-features → green.
Curl quick-start (added to operator playbook material in a follow-up):
curl http://localhost:3000/api/v1/mesh # full fleet
curl http://localhost:3000/api/v1/nodes/9/sync # one node
Co-Authored-By: claude-flow <ruv@ruv.net>
Iter 24 — ultra-opt for public-API stability. Iter 23 added a new JSON
field that UI clients (viz.html, future Tauri desktop, automation) now
depend on; this iter locks its exact shape so any future rename /
removal fails a named test instead of silently breaking consumers.
New module `node_sync_snapshot_serialization_tests` (3 tests, all green):
* sync_present_serializes_all_seven_fields
Builds NodeInfo with Some(sample_sync), serializes to serde_json::Value,
asserts all 7 documented field names exist (offset_us, is_leader,
is_valid, smoothed, sequence, csi_fps_ema, csi_fps_samples) and
spot-checks numeric values.
* sync_absent_omits_the_key_entirely
Builds NodeInfo with sync = None, asserts the `sync` JSON key is
DROPPED entirely (not emitted as `"sync": null`). This is the
backwards-compat contract that lets pre-iter-23 UI clients ignore
mesh-aware nodes silently.
* sync_round_trips_through_serde
to_string / from_str round-trip on a populated NodeInfo recovers
every field of the sync sub-object byte-for-byte (modulo float tol).
Test infrastructure: pure pure serde_json — no network, no fixtures,
no I/O. Adds 92 lines, 0 runtime allocs in the steady path.
Branch-coord clean (no Cargo.toml or cli.rs touched).
Co-Authored-By: claude-flow <ruv@ruv.net>
Iter 19 — without this call, iter 18's EMA fps tracking was dead code
because csi_fps_samples stayed 0 forever and mesh_aligned_us_for_csi_frame
always fell back to the 20 Hz constant.
In udp_receiver_task's parse_esp32_frame branch, replace the bare
last_frame_time assignment with NodeState::observe_csi_frame_arrival,
which computes dt vs last_frame_time, feeds update_csi_fps_ema (α=1/8),
bumps csi_fps_samples, and sets last_frame_time as a side effect (same
value the bare assignment did).
Effect: after ~5 CSI frames arrive from any node, mesh_aligned_us_for_csi_frame
returns interpolated timestamps using the node's actually-observed frame
rate instead of the 20 Hz default. Real bench rate was ~10 fps, so this
halves the per-frame timestamp error in §A0.12-style multistatic alignment.
cargo check -p wifi-densepose-sensing-server --no-default-features → green.
Co-Authored-By: claude-flow <ruv@ruv.net>
Adds `mqtt` and `matter` Cargo features (default off) plus 20+ new CLI
flags wired through cli.rs per ADR-115 §3.8 / §3.10 / §3.11 / §3.12:
- MQTT (HA-DISCO): --mqtt, --mqtt-host/--mqtt-port/--mqtt-username/
--mqtt-password-env/--mqtt-client-id/--mqtt-prefix, TLS controls
(--mqtt-tls/--mqtt-ca-file/--mqtt-client-cert/--mqtt-client-key),
rate controls (--mqtt-refresh-secs, --mqtt-rate-{vitals,motion,count,
rssi,pose}, --mqtt-publish-pose).
- Privacy (ADR-106): --privacy-mode strips HR/BR/pose pre-publish.
- Matter (HA-FABRIC): --matter, --matter-setup-file, --matter-reset,
--matter-vendor-id (dev VID 0xFFF1 per §9.9), --matter-product-id.
- Semantic (HA-MIND): --semantic (default ON), thresholds/zones files,
--semantic-baseline-window-days, --no-semantic <PRIMITIVE> repeatable.
rumqttc 0.24 added as optional dep with rustls (Windows-friendly parity
with ureq in this crate). matter-rs deferred to P7 spike per §9.10.
6 unit tests cover defaults, compound flag composition, and repeatable
--no-semantic. Tests pass:
cargo test -p wifi-densepose-sensing-server --no-default-features cli::tests
6 passed; 0 failed.
Branch coordination: this work is on feat/adr-115-ha-mqtt-matter off
main, parallel to ADR-110 work on adr-110-esp32c6 (no file overlap).
Refs #776 (ADR-115 implementation tracking issue).
Co-Authored-By: claude-flow <ruv@ruv.net>
Iter 18's commit 2997165bc accidentally absorbed the ADR-115 agent's
uncommitted MQTT/Matter additions (Cargo.toml `rumqttc` dep + [features]
block, cli.rs --mqtt CLI flags) into the adr-110-esp32c6 branch during
the cross-branch checkout described in that commit's message.
The actual iter 18 EMA work in main.rs is correct and stays; this commit
restores Cargo.toml + cli.rs to their HEAD~1 (iter 17) state so the
ADR-115 agent's stashed `stash@adr115-pending-work` can be popped cleanly
back onto their feat/adr-115-ha-mqtt-matter branch without colliding.
Net effect on adr-110-esp32c6:
- main.rs iter 18 EMA: kept ✓
- 4 fps_ema_tests: still green
- Cargo.toml: back to iter-17 state (wifi-densepose-hardware dep only)
- cli.rs: back to iter-17 state (no MQTT flags)
- Cargo.lock: synced to match
The ADR-115 agent can pop their stash on feat/adr-115-ha-mqtt-matter
and resume without merging an unrelated branch's ADR-110 work.
Co-Authored-By: claude-flow <ruv@ruv.net>
Iter 18 (after recovery from a cross-branch slip — see commit-history
context below). Replaces the hardcoded 20 Hz CSI_FPS_HZ constant in
mesh_aligned_us_for_csi_frame with a per-node EMA of observed
inter-frame intervals, falling back to 20 Hz until ≥5 samples land.
Real bench data (§A0.12 captures) showed the actual CSI rate at ~10 fps
because the firmware's CSI_MIN_SEND_INTERVAL_US gate combined with
ruv.net's traffic level paces it to that. Using 20 Hz against actual
10 fps inflates Δus 2× and shifts the recovered mesh timestamp by up
to the inter-sync interval / 2 = ~1 s. Measured fps fixes that.
State on NodeState:
csi_fps_ema: f64 — EMA (seeded at 20.0)
csi_fps_samples: u32 — counts inter-frame deltas observed
API:
NodeState::observe_csi_frame_arrival(now) — call once per CSI frame
from udp_receiver_task
update_csi_fps_ema(prev_fps, dt_sec) -> Option<f64> — free fn,
testable
mesh_aligned_us_for_csi_frame now uses the measured fps when samples ≥ 5,
falls back to 20 Hz otherwise.
4 unit tests (fps_ema_tests module, all passing on the binary):
* steady_10hz_converges_toward_10 — 40 samples at 100 ms converge to ±0.1 Hz
* steady_20hz_stays_near_20 — 20 samples at 50 ms stay within 0.05 Hz
* nonpositive_dt_rejected — dt ≤ 0 returns None
* long_gap_rejected_as_implausible — dt > 1 s rejected (likely a dropout)
Branch-coordination note: this iter's working tree was briefly applied
to feat/adr-115-ha-mqtt-matter by a `git checkout` between iter 17 and
iter 18. Stashed the ADR-115 agent's MQTT/Matter Cargo.toml work
(`stash@adr115-pending-work`) before switching back here. No code lost.
Co-Authored-By: claude-flow <ruv@ruv.net>
Iter 17 — closes the per-frame mesh-time loop for ADR-018 CSI frames
that carry no per-frame local_us field (the v1 wire format reserves no
slot — see WITNESS-LOG-110 §A0.11).
Math: pair the frame's sequence number against the sync packet's
sequence high-water + an assumed CSI frame rate. Δframes × 1/fps
estimates the node-local delta from the sync, then apply_to_local
recovers the mesh epoch.
SyncPacket::mesh_aligned_us_for_sequence(frame_seq: u32, fps_hz: f64) -> u64
3 new unit tests (13 total in sync_packet::tests, all green):
* mesh_aligned_for_sequence_identity_at_sync_point — at sync.sequence
returns sync.epoch_us exactly
* mesh_aligned_for_sequence_extrapolates_forward — 20 frames @ 20 fps
extrapolates by exactly 1 s
* mesh_aligned_for_sequence_handles_seq_wraparound — u32 sequence
wrap doesn't jump backward by 2^32 (wrapping_sub guards it)
NodeState hook:
NodeState::mesh_aligned_us_for_csi_frame(frame_sequence: u32) -> Option<u64>
Wraps the SyncPacket method, defaults fps_hz=20.0 (matches the
firmware's CSI_MIN_SEND_INTERVAL_US-implied ceiling), enforces the
same 9 s staleness gate as mesh_aligned_us.
cargo check -p wifi-densepose-sensing-server --no-default-features → green.
cargo test -p wifi-densepose-hardware sync_packet → 13/13, 122 filtered.
Downstream ADR-029/030 multistatic fusion code can now do:
if frame.adr018_flags.ieee802154_sync_valid {
if let Some(mesh_us) = ns.mesh_aligned_us_for_csi_frame(frame.sequence) {
// pair this frame with frames from sibling nodes by mesh_us
}
}
Co-Authored-By: claude-flow <ruv@ruv.net>
Iter 16 closes the math loop and updates ADR-110 to reflect the full
P1-P10 sprint outcome (per user request).
Code (the math layer that converts the iter 15 stored sync into a
per-frame mesh-aligned timestamp):
wifi-densepose-hardware:
SyncPacket::apply_to_local(local_at_frame_us: u64) -> u64
Pure integer math: offset = epoch - local; mesh = local_at_frame + offset.
3 new unit tests (10 total, all green):
- apply_to_local_recovers_packet_epoch (identity at the packet's local_us)
- apply_to_local_preserves_inter_frame_delta (Δlocal == Δmesh)
- apply_to_local_on_leader_is_near_identity (leader offset ≈ 0)
wifi-densepose-sensing-server:
NodeState::mesh_aligned_us(local_at_frame_us: u64) -> Option<u64>
Returns the recovered mesh timestamp using the most-recent sync
packet, or None if no sync seen or last one older than 9 s
(3× firmware VALID_WINDOW_MS = 9 s staleness gate).
cargo check -p wifi-densepose-sensing-server --no-default-features
→ green
ADR-110 substantial rewrite (per user "update adr 110 with details"):
- Status line: P1-P10 complete, firmware-side substrate closed at v0.7.0.
- Front matter now lists all 4 firmware releases + witness link.
- Phase table grows a P10 row capturing the v0.6.8 / v0.6.9 / v0.7.0
arc (EMA smoother + sync packet + bit-4 wire-fix + host crates).
- New §4.1 — /loop 5m SOTA sprint summary table (iters 1-16, 4 releases,
17 commits, 13 unit tests, what shipped each iter).
- New §4.2 — measured numbers table with 99.56% RX, 104.1 µs smoothed
stdev, 3.95x suppression, 1.4 ppm crystal skew, etc — every cell
backed by a witness §A0.x entry and a preserved bench log.
- New §4.3 — host-side production surface listing (sync_packet.rs +
sensing-server NodeState + Python parser, with file paths).
- §5 open question on 802.15.4 channel resolved (Kconfig, default ch26
not ch15, with the witness §D1 rationale).
- New §6 — explicit scope of what's outside this ADR (multistatic fusion
math in ADR-029/030, hardware-gated measurements needing INA / 11ax AP,
IDF upstream fixes pending).
Co-Authored-By: claude-flow <ruv@ruv.net>
Iter 15 — converts the iter 14 SyncPacket decoder from "shipped" to
"consumed" by wiring it into the sensing-server UDP receive loop.
Wiring:
- Cargo.toml gains wifi-densepose-hardware = path = "../wifi-densepose-hardware"
to pull in the SyncPacket decoder + SYNC_PACKET_MAGIC dispatch constant.
- NodeState gains two new fields:
latest_sync: Option<SyncPacket> — the parsed packet
latest_sync_at: Option<std::time::Instant> — staleness clock
- udp_receiver_task now magic-dispatches every incoming datagram against
SYNC_PACKET_MAGIC (0xC511A110) before falling through to the existing
ADR-039 vitals / ADR-040 WASM / ADR-018 CSI parsers. Same Option-returning
pattern as the other parsers, so future packet types slot in cleanly.
When a sync packet arrives:
* write-lock state, lookup-or-create NodeState by node_id
* stash the SyncPacket + Instant::now() on the node
* debug-log node, leader/valid/smoothed flags, sequence, offset_us
* continue (don't fall through — we know it's not a CSI frame)
Downstream multistatic CSI fusion now has a documented landing pad: any
CSI frame with byte 19 bit 4 set looks up the matching NodeState, applies
ns.latest_sync.epoch_us + (now_local - ns.latest_sync.local_us) to get a
mesh-aligned timestamp. Implementation of that fusion math is the next
ADR-029/030 layer (wifi-densepose-signal).
Verification:
- cargo check -p wifi-densepose-sensing-server --no-default-features → green
- cargo test -p wifi-densepose-hardware sync_packet → 7/7 pass, 122 filtered
- Zero behavioral change for nodes that don't emit sync packets — the
dispatch only fires on magic match.
Co-Authored-By: claude-flow <ruv@ruv.net>
* feat(edge-registry): ADR-102 — surface Cognitum cog catalog via /api/v1/edge/registry
Adds a new sensing-server endpoint that fetches and caches the canonical
Cognitum app registry at
https://storage.googleapis.com/cognitum-apps/app-registry.json (105 cogs
across 11 categories as of v2.1.0). RuView previously had no live
awareness of the catalog — the README's capability table was hand-
curated and went stale as Cognitum shipped new cogs (the registry was
last updated 6 days ago).
ADR:
* docs/adr/ADR-102-edge-module-registry.md — full design, response
shape, configuration flags, failure modes, and a 12-row security
review covering SSRF, response inflation, ?refresh abuse, stale-serve
semantics, TLS, cache poisoning, JSON-panic resistance, etc.
Code:
* v2/.../edge_registry.rs — EdgeRegistry struct + UreqFetcher +
MockFetcher trait + 7 unit tests. RwLock<Option<CachedEntry>> with
stale-on-error fallback. MAX_PAYLOAD_BYTES=8 MiB, 10s wire timeout.
* v2/.../main.rs — constructs Option<Arc<EdgeRegistry>> at startup,
registers GET /api/v1/edge/registry handler, wires Extension layer.
Handler runs the blocking ureq fetch via tokio::task::spawn_blocking
so the async runtime stays free.
* v2/.../cli.rs / main.rs Args — three new flags (per user request to
"allow the registry to be disabled or changed"):
--edge-registry-url <URL> (env RUVIEW_EDGE_REGISTRY_URL)
--edge-registry-ttl-secs <N> (env RUVIEW_EDGE_REGISTRY_TTL_SECS)
--no-edge-registry (env RUVIEW_NO_EDGE_REGISTRY)
When --no-edge-registry is set or the URL is empty, the endpoint
returns 404.
Cargo.toml: adds ureq (rustls), sha2, thiserror as direct deps.
README:
* New collapsed "🧩 Edge Module Catalog" section with the full 105-cog
table generated from the registry, grouped by category with practical
one-line descriptions (e.g. "Spots irregular heartbeats and abnormal
heart rhythms", "Detects walking problems and scores fall risk").
Links to https://seed.cognitum.one/store and the local appliance
/cogs page. Sits between the HF model section and How It Works.
Tests (7/7 pass):
first_call_hits_upstream_and_caches
ttl_expiry_triggers_refetch
force_refresh_bypasses_fresh_cache
stale_serve_on_upstream_failure_after_cached_success
no_cache_no_upstream_returns_error
upstream_invalid_json_is_treated_as_error
upstream_sha256_is_deterministic
Security highlights (full review in ADR-102 §"Security review"):
- The registry is metadata-only; per-cog binary signatures (ADR-100)
remain the trust root for installs. A compromised registry can
mislead a human reader but cannot ship malicious binaries.
- 8 MiB cap + 10s timeout + Option<Arc<...>> via Extension layer means
the endpoint can't be used to exhaust memory or pin tokio threads.
- Stale-on-error responses carry an explicit `stale: true` field so
upstream outages are visible to consumers rather than silently
masked.
- Endpoint sits behind the existing RUVIEW_API_TOKEN bearer gate when
set, otherwise unauthenticated (registry contents are public anyway).
* chore: refresh Cargo.lock for ureq/sha2/thiserror deps added by ADR-102
#613 fixed adaptive_classifier.rs:94 (the IQR sort) and called the audit
done, but the grep used `partial_cmp(b).unwrap()` as a literal and missed
seven additional production sites that use comparator variants:
adaptive_classifier.rs:205 AdaptiveModel::classify() argmax over softmax
probs — same per-frame hot path as #611.
NaN flows through normalise → logits → softmax
and still reaches this site even after the
IQR fix.
adaptive_classifier.rs:480 train() argmax (training accuracy loop)
adaptive_classifier.rs:500 train() per-class argmax
main.rs:2446, 2449 count_persons_mincut variance source/sink select
csi.rs:602, 605 count_persons_mincut variance source/sink select
(duplicate of main.rs logic in csi.rs)
For the variance-select sites, note that the *outer* `unwrap_or((0, &0))`
only catches an empty iterator — it cannot rescue a panic raised inside
the comparator. A single NaN in `variances[]` still aborts the process.
Same fix as #613: swap `.unwrap()` for `.unwrap_or(std::cmp::Ordering::Equal)`
inside the comparator closure. Pure behavioural change, no API surface.
Re-audit of the remaining `partial_cmp(...).unwrap()` matches in v2/:
they are all inside `#[cfg(test)]` / `#[test]` blocks (spectrogram.rs:269,
depth.rs:234, connectivity.rs:477, vital_signs.rs:737) where inputs are
controlled and panic-on-NaN is acceptable.
Integrating @schwarztim's PR #491 into main on their behalf — their fork has
fallen too far behind for a clean rebase (the PR's commit graph dropped
silently during `git rebase origin/main`), so applying as a merge from the
fork head to preserve the diff cleanly.
What this lands:
- `RollingP95` adaptive normaliser for the person-count feature scaling.
Streaming P95 over a 600-sample / ~30 s sliding window. Cold-start
(<60 samples) falls back to the legacy denominators (variance/300,
motion_band_power/250, spectral_power/500) so day-0 behaviour is
preserved on every deployment.
- `RuntimeConfig` struct + `load_runtime_config` / `save_runtime_config`
persisted to `data/config.json`. Exposes `dedup_factor` via REST so
multi-node deployments can tune cluster-deduplication without a rebuild,
including an auto-tune endpoint that derives optimal dedup from a known
person count (calibration mode).
- `compute_person_score()` now takes &AppStateInner alongside &FeatureInfo
so the adaptive denominators are reachable. All 3 call sites updated.
- New `AppStateInner` fields: `p95_variance`, `p95_motion_band_power`,
`p95_spectral_power`, `dedup_factor`, `data_dir`.
Closes#491. Directly addresses:
- #499 (double skeletons, multi-node) — the slot-clustering problem this
PR's adaptive normaliser was designed to fix
- #519 Bug 1 (ghost person detection on edge-tier 1 & 2 multi-node)
- #496 (person count over-reporting on single-room single-person)
Verified locally:
- cargo check -p wifi-densepose-sensing-server --no-default-features: 1.0s
- cargo test -p wifi-densepose-sensing-server --no-default-features --lib:
233/233 passed in 25.0s
Co-authored-by: @schwarztim
Co-Authored-By: claude-flow <ruv@ruv.net>
Reported by @ArnonEnbar with a complete reproduction.
broadcast_tick_task() re-emits the cached `latest_update` every tick so
pose WS clients keep getting data even when ESP32 pauses between
frames. The `source` field of that cached update was set to "esp32" at
the moment a fresh ESP32 frame was last decoded (main.rs:3885, :4136).
After the ESP32 loses power or network, no fresh frame is decoded —
the cached `latest_update` is still re-broadcast every tick with the
stale source: "esp32" baked in. UI's "Sensing" tab keeps showing
"LIVE — ESP32 HARDWARE Connected" with frozen vitals/features/
classification re-broadcast indefinitely. REST `/health` correctly
reports source: "esp32:offline" (via effective_source(), which checks
last_esp32_frame elapsed time against ESP32_OFFLINE_TIMEOUT=5s) — but
the WS broadcast path was the one consumer that didn't call it.
Fix: clone the cached update per tick, overwrite source with
s.effective_source(), then serialize and broadcast. UI now switches to
"esp32:offline" on the same 5s budget as the REST surface.
cargo build -p wifi-densepose-sensing-server --no-default-features:
17s, no errors (1 pre-existing unused-import warning unchanged).
Reported by @bannned-bit. Five endpoints in
v2/crates/wifi-densepose-sensing-server embedded user-controlled
identifiers in format!() paths with no sanitization:
recording.rs POST /api/v1/recording/start (session_name)
recording.rs GET /api/v1/recording/download/:id (id)
recording.rs DELETE /api/v1/recording/delete/:id (id)
model_manager.rs POST /api/v1/models/load (model_id)
training_api.rs load_recording_frames (dataset_ids[])
Each unauthenticated caller could:
- READ arbitrary files via ../../etc/passwd, ../../.env, etc.
- WRITE attacker-controlled JSONL via recording/start
- LOAD attacker-controlled .rvf model files
- DELETE arbitrary files the server process can touch
New `path_safety` module exports `safe_id(&str) -> Result<&str, PathSafetyError>`
that enforces the rejection envelope BEFORE any user input reaches a
format!() that builds a path:
- Allowed character set: [A-Za-z0-9._-]
- Reject leading '.' (rules out '.', '..', '.env', hidden files)
- Reject empty strings
- Reject anything > 64 bytes
- Reject all whitespace, path separators, null bytes, non-ASCII
Applied at all 5 sites. Errors return 400 Bad Request (download) /
status:"error" JSON (others) — not panics.
9 unit tests in path_safety::tests cover:
- accepts simple alphanumeric / hyphen / underscore / dot
- rejects empty, leading dot, path separators ('/', '\'),
null byte, whitespace, shell specials, non-ASCII (including
fullwidth slash U+FF0F), too-long, boundary at MAX_ID_LEN
test result: ok. 9 passed; 0 failed
cargo build -p wifi-densepose-sensing-server --no-default-features: 33s
Fix-marker RuView#615 in scripts/fix-markers.json prevents removing the
guard at any of the 5 call sites. CHANGELOG entry under [Unreleased] /
Security documents the patched endpoints and the rejection envelope.
Severity: critical per reporter — five remotely-reachable paths to read,
write, or delete arbitrary files. Hot per-request paths, not edge cases.
Reported by @bannned-bit. v2/crates/wifi-densepose-sensing-server/src/
adaptive_classifier.rs:94 did:
sorted.sort_by(|a, b| a.partial_cmp(b).unwrap());
f64::partial_cmp returns None on NaN, so `.unwrap()` panics. CSI data
from real ESP32 hardware can produce NaN (silent DSP div-by-zero,
empty buffer, etc.), and this code path runs on every frame in the
classify() hot path — a single NaN frame kills the entire sensing
server process.
Fix swaps for unwrap_or(Ordering::Equal), matching the pattern the
same file already uses at lines 149-150 and 155 (those sites were
already NaN-safe; this site was an oversight).
Scoped audit: greped the v2/ tree for `partial_cmp(b).unwrap()`. The
other 3 hits are in #[cfg(test)] blocks (spectrogram.rs:269,
depth.rs:234, connectivity.rs:477) where panic-on-NaN is acceptable
because test inputs are controlled. Only adaptive_classifier.rs:94
was a production-path crash.
Severity: critical per reporter — runtime panic on real-world data.
Patch: 1-line behavioural change + comment.
* v2: pin Rust 1.89 for sensing-server dependency chain
ruvector-core 2.0.5, hnsw_rs 0.3.4, and mmap-rs 0.7 require newer Cargo/rustc
than 1.82 (edition2024 manifest, is_multiple_of, stable avx512f target_feature
on x86_64). Add v2/rust-toolchain.toml so cargo build -p
wifi-densepose-sensing-server picks a compatible toolchain.
Signed-off-by: Chaitanya Tata <chaitanya@dotstarconsulting.com>
Co-authored-by: Cursor <cursoragent@cursor.com>
* sensing-server: default UI path for cwd v2/ and coalesce fallbacks
The previous default ../../ui resolves to a non-existent directory when
the binary is run from v2/ (common), so /ui/* returned 404 and the
dashboard appeared broken. Default to ../ui and try ../ui, ./ui,
../../ui when the configured path is missing.
Signed-off-by: Chaitanya Tata <chaitanya@dotstarconsulting.com>
Co-authored-by: Cursor <cursoragent@cursor.com>
---------
Signed-off-by: Chaitanya Tata <chaitanya@dotstarconsulting.com>
Co-authored-by: Cursor <cursoragent@cursor.com>
The sensing-server binds to 127.0.0.1 by default with no `Host` header
validation on either router. A foreign page can lower its DNS TTL,
re-resolve to 127.0.0.1 after the browser has accepted the origin, and
then read live pose + vital signs from /api/v1/* + /ws/sensing as
same-origin against the attacker's hostname. When `RUVIEW_API_TOKEN` is
unset (the documented LAN-mode default from #443/#547) the attacker
can also drive state-mutating POSTs (recording/start, models/load,
adaptive/train, calibration/start, sona/activate).
Defense: a small `host_validation` axum middleware that pins the `Host`
header to a configurable allowlist. The loopback names (`localhost`,
`127.0.0.1`, `[::1]`, each with or without a port) are always in the
set, so default 127.0.0.1 deployments keep working from the local
browser without any configuration change. Operators who bind to a
routable address extend the set with one or more `--allowed-host`
flags or a comma-separated `SENSING_ALLOWED_HOSTS` env var.
Reverse-proxy deployments that already canonicalise `Host` opt out
with `--disable-host-validation`.
The layer is wired into both the dedicated WebSocket router on
`--ws-port` (8765) and the main HTTP router on `--http-port` (8080),
so /ws/sensing on either listener is covered. Rejection responses are
`421 Misdirected Request` (the correct status for a request that
arrived at a server that does not consider the supplied `Host`
authoritative); missing `Host` is `400 Bad Request`.
CWE-346 (Origin Validation Error), CWE-350 (Reliance on Reverse DNS).
Severity: high.
Tests: 13 new unit tests on the middleware (loopback defaults,
case-insensitivity, IPv6 bracketing, port stripping, env-var/CLI
merge, foreign-host rejection on /health + /ws/*, disabled-allowlist
escape hatch). Full suite: 220/220 pass under
`cargo test -p wifi-densepose-sensing-server --no-default-features`.
Co-authored-by: Aeon <aeon@aaronjmars.com>
process_frame computed arithmetic mean + variance on phase values from
atan2(), which are wrapped to (-pi, pi]. Phases close across the +/-pi
discontinuity produced ~pi^2 variance instead of ~1e-6, feeding wrap
noise into the heart-rate FFT buffer.
Replace inline math with a standard circular variance helper
(1 - mean resultant length). Add 4 unit tests, one through the
production path of process_frame.
Closes#593
Three threads in this commit:
1) Per-frame attractor analysis (default analyze_every_n: 8 → 1).
The I5 benchmark put per-frame update at 0.012 ms p99 — 83× under D4's
1 ms budget. The cost case for the every-8th-frame default doesn't hold;
per-frame analysis is what makes regime_changed a viable early-detection
trigger.
2) New `regime_changed: bool` field in IntrospectionSnapshot — flips on any
frame whose attractor regime classification differs from the previous
frame's. Pairs with top_k_similarity (full-shape match) to give
downstream consumers two latencies with different robustness profiles.
3) Honest amendment of ADR-099 D8 to reflect empirical reality:
- L1 stand-in achieves 3.20× ratio (5-frame shape match vs 16-frame
event-path floor); the 10× aspirational bar is architecturally
unreachable at 1-D scalar feature resolution.
- regime_changed didn't fire in the 10-frame motion window — the
200-frame noise trajectory dominates the Lyapunov classification, and
short perturbations don't shift the regime fast enough on a scalar
feature.
- Path to 10×: ADR-208 Phase 2 (Hailo NPU vec128 embeddings) — multi-dim
partial matches discriminate from noise in 1-2 frames, not 5.
- Side finding: midstream temporal-compare::DTW uses *discrete equality*
cost (designed for LLM tokens), not numeric distance — swapping it in
for f64 amplitude scoring would be strictly worse than the L1 stand-in.
A numeric DTW is a separate concern (hand-roll or new crate).
- Revised D8: ship behind --introspection (off by default) until multi-
dim features land. Per-frame update budget IS met (0.041 ms p99 in this
bench, ~24× under the 1 ms bar) — the feature is cheap enough to
carry dark today.
cargo test -p wifi-densepose-sensing-server --no-default-features:
introspection (lib): 8 passed, 0 failed
introspection_latency (test): 5 passed, 0 failed (incl. new
regime_change_path_latency)
clippy: clean on the introspection surface (pre-existing approx_constant
lints in pose.rs / main.rs unchanged).
Co-Authored-By: claude-flow <ruv@ruv.net>
I5. Measures the architectural latency floor of the introspection path
vs. the window-aggregated event path, plus the per-frame update cost.
Result on this run:
ADR-099 D8 floor ratio : 3.20× (16 frames / 5 frames)
D8 target ≥10× — NOT YET MET on the host-side
L1 stand-in scoring; I6 closes the gap.
ADR-099 D4 update p50/p99 : 0.001 ms / 0.012 ms (~83× under the 1 ms
budget on a desktop runner; even with thermal
throttling on a Pi 5 we have orders of
magnitude of headroom).
Regime after 200 frames : Idle, lyapunov=-2.32, confidence=1.0
(attractor analyzer is firing as designed).
The D8 gap is structural to the current scoring: signature_score() uses a
length-normalised L1 over the trailing window, which requires roughly the
full signature length of in-shape frames before crossing
promotion_threshold. Closing it is the I6 work — swap in the real
midstreamer-temporal-compare DTW (partial-match scoring) and/or surface
the attractor's regime-change as an *earlier* trigger than full signature
match.
The latency-ratio test asserts a regression bar (≥3.0×) on the L1 baseline,
prints the D8 ratio + whether it's met, and explicitly defers the ≥10×
target to I6 in the docstring. Better empirical reporting than a flag that
silently fails until tuned.
ESP32 sanity (independent of the benchmark): COM7 device alive at csi_collector
cb #84500 (~30 min uptime), len=128/256 HT20/HT40, ch5, RSSI swings -44 to
-79 (= real motion in the room). UDP target still unreachable from this
host per the earlier diagnosis; that's a deployment fix, not a measurement
gate.
Co-Authored-By: claude-flow <ruv@ruv.net>
I3 (per ADR-099). Three changes in main.rs:
1) AppStateInner: + intro: IntrospectionState + intro_tx: broadcast::Sender<String>
(256-slot ring, same shape as the existing tx).
2) ESP32 frame path: after the global frame_history push, before the
per-node mutable borrow of s.node_states, compute the per-frame derived
feature (mean amplitude across subcarriers), call s.intro.update(ts_ns,
feature), and broadcast the snapshot JSON to s.intro_tx. Placement is
deliberate — between the global state's mutable touch and the per-node
&mut so borrow-checking stays linear; ns is borrowed *after* the tap
completes its s.intro / s.intro_tx access.
3) Routes:
ws_introspection_handler → /ws/introspection
api_introspection_snapshot → /api/v1/introspection/snapshot
Same Axum + tokio::sync::broadcast pattern as ws_sensing_handler,
subscribed against s.intro_tx. Wrapped by the bearer-auth middleware
already on /api/v1/* — orchestrator probes and unauthenticated /ws/sensing
reachers continue to land on the existing topic.
Verified:
cargo build -p wifi-densepose-sensing-server --no-default-features ✓
cargo test -p wifi-densepose-sensing-server --no-default-features
lib: 207 passed, 0 failed (199 pre-tap + 8 introspection)
integration suites: 70, 8, 16, 18 passed, 0 failed
cargo clippy: clean on the introspection surface (pre-existing warnings
on -core / -ruvector / -signal unchanged).
Co-Authored-By: claude-flow <ruv@ruv.net>
Closes#520, #514, #443.
## #520 / #514 — stale Docker image, missing UI assets
`ruvnet/wifi-densepose:latest` was published before `ui/observatory*` and
`ui/pose-fusion*` were added; users see /app/ui missing those files and the
v0.6+ packet format doesn't reach the server. Two fixes:
1. `docker/Dockerfile.rust` now `RUN`s a build-time guard after `COPY ui/`
that fails the build if `index.html` / `observatory.html` / `pose-fusion.html`
/ `viz.html` (or the `observatory/` / `pose-fusion/` / `components/` /
`services/` directories) are missing, plus an exec-bit check on
`/app/sensing-server`. A stale image can never be silently produced again.
2. New `.github/workflows/sensing-server-docker.yml` rebuilds + pushes on
every change to the Dockerfile, the server crate, the signal/vitals/
wifiscan crates, the workspace manifests, the `ui/` tree, or itself —
plus `v*` tags and manual dispatch. Pushes to both `docker.io/ruvnet/
wifi-densepose` AND `ghcr.io/ruvnet/wifi-densepose` with `latest` +
`vX.Y.Z` + `sha-<short>` tags, then post-push smoke-tests the artifact:
/health, /api/v1/info, the observatory + pose-fusion HTML, AND the
bearer-auth path (no token → 401, wrong → 401, correct → 200). Uses the
`DOCKERHUB_USERNAME`/`DOCKERHUB_TOKEN` repo secrets; ghcr.io rides on
the workflow's GITHUB_TOKEN.
## #443 — sensing-server REST API auth model
QE security audit raised that 40+ /api/v1/* routes have no auth layer with
a default `0.0.0.0` bind. New `wifi_densepose_sensing_server::bearer_auth`
module + middleware:
- Env-var-gated: `RUVIEW_API_TOKEN` unset/empty ⇒ middleware is a no-op
(current LAN-mode behaviour preserved — **no default change**); set ⇒
every `/api/v1/*` request must carry `Authorization: Bearer <token>`
or the server returns 401.
- Constant-time byte compare via local `ct_eq` (no new dep).
- `/health*`, `/ws/sensing`, and `/ui/*` are intentionally never gated
(orchestrator probes + local browsers).
- Startup logs which mode is active and warns when auth is ON with a
`0.0.0.0` bind.
- 8 unit tests on the middleware via `tower::ServiceExt::oneshot`
(sensing-server lib tests 191 → 199, 0 failures).
Verified locally: `cargo build --workspace --no-default-features` ✓,
`cargo test -p wifi-densepose-sensing-server --no-default-features` ✓.
Co-Authored-By: claude-flow <ruv@ruv.net>
RollingP95 adaptive normalizer (ADR-044 §5.2):
- Streaming P95 estimator (600-sample / ~30 s window) replaces fixed-scale
denominators (variance/300, motion/250, spectral/500) that saturated against
live ESP32 values, collapsing dynamic range to zero.
- Cold-start (<60 samples) falls back to legacy denominators — day-0 behaviour
is preserved.
- Three new fields on AppStateInner: p95_variance, p95_motion_band_power,
p95_spectral_power (all RollingP95::new(600, 60)).
- compute_person_score() refactored to accept &AppStateInner; all three call
sites (wifi, wifi-fallback, simulated) updated.
- 5 unit tests in rolling_p95_tests module.
dedup_factor runtime API (ADR-044 §5.3):
- New field dedup_factor: f64 (default 3.0) on AppStateInner.
- fuse_or_fallback() gains dedup_factor param; fallback switches from max() to
sum/dedup_factor (ceiling), matching the fork's sum-based aggregation.
- RuntimeConfig struct + load/save_runtime_config() for data/config.json
persistence across restarts.
- Three new REST endpoints:
GET /api/v1/config/dedup-factor
POST /api/v1/config/dedup-factor
POST /api/v1/config/ground-truth (auto-tune from known person count)
Explicitly NOT included:
- lambda=5.0 (upstream keeps its 0.1 default — deployment-specific tuning)
- CC intensity threshold 0.3 and min-cluster-size 4 hardcodes
- max_cc_size filter removal
* feat(ruvector): ADR-084 Pass 1 — sketch module foundation
Implements Pass 1 of ADR-084 (RaBitQ similarity sensor): a thin
RuView-flavored API over `ruvector_core::quantization::BinaryQuantized`,
exposed at `wifi_densepose_ruvector::{Sketch, SketchBank, SketchError}`.
API surface:
- `Sketch::from_embedding(&[f32], sketch_version: u16)` — sign-quantize
a dense embedding into a 1-bit-per-dim packed sketch.
- `Sketch::distance` — hamming distance with schema-mismatch error.
- `Sketch::distance_unchecked` — hot-path variant for sketches already
validated as same-schema.
- `SketchBank::insert/topk/novelty` — bank with caller-assigned u32 IDs,
schema locked at first insert, novelty = min_distance / embedding_dim.
Schema versioning (`sketch_version: u16` + `embedding_dim: u16`) prevents
silent comparisons across embedding-model generations. Bumping the model
forces re-sketch of the candidate bank.
Pass 1 establishes the API and unit-test foundation. Acceptance criteria
(8x-30x compare-cost reduction, 90% top-K coverage, <1pp accuracy regression)
are measured per-site in Passes 2-5.
Validated:
- 12 new tests pass (sketch construction, hamming, top-K ordering,
schema lock, schema rejection, novelty)
- cargo test --workspace --no-default-features → 1,551 passed, 0 failed,
8 ignored (was 1,539 before; +12 new tests)
- ESP32-S3 on COM7 still streaming live CSI (cb #117300)
Co-Authored-By: claude-flow <ruv@ruv.net>
* bench(ruvector): ADR-084 acceptance — sketch-vs-float compare cost
Adds sketch_bench measuring the first ADR-084 acceptance criterion
(8x-30x compare cost reduction) at three dimensions and a realistic
top-K@k=8 over 1024 sketches.
Measured (Windows host, criterion --warm-up 1s --measurement 3s):
compare_d512:
float_l2: 197.03 ns/op
float_cosine: 231.17 ns/op
sketch_hamming: 4.56 ns/op → 43-51x speedup
topk_d128_n1024_k8:
float_l2_topk: 47.59 us
sketch_hamming: 6.34 us → 7.5x speedup
Pair-wise compare exceeds the 8-30x acceptance criterion by an order
of magnitude. Top-K is at 7.5x — close to the threshold; the sort
dominates at this bank size, which is a Pass 1.5 optimization
opportunity (partial-sort heap for small K).
Co-Authored-By: claude-flow <ruv@ruv.net>
* perf(ruvector): ADR-084 Pass 1.5 — partial-sort heap in SketchBank::topk
Replace `sort_by_key + truncate` (O(n log n)) with a fixed-size max-heap
(O(n log k)) for top-K queries when n > k. Fast path when n ≤ k stays
on the simple sort.
Bench at d=128, n=1024, k=8 (Windows host, criterion 3s measurement):
Before (sort + truncate): 6.34 µs/op
After (heap): 3.83 µs/op -39.4% / +1.65× faster
Combined with the 32× memory shrink and 47.6 µs → 3.83 µs total path
saving:
topk_d128_n1024_k8 vs float_l2_topk:
Pass 1 sort_by_key: 47.59 µs / 6.34 µs = 7.5× speedup
Pass 1.5 heap: 47.59 µs / 3.83 µs = 12.4× speedup
Now over the ADR-084 acceptance criterion of 8× minimum. Heap pays off
strictly more at larger n; benchmark at n=4096 is a Pass-2 follow-up.
Co-Authored-By: claude-flow <ruv@ruv.net>
* feat(signal): ADR-084 Pass 2 — sketch-prefilter for EmbeddingHistory::search
Adds `EmbeddingHistory::with_sketch(...)` and `search_prefilter(query, k,
prefilter_factor)`. The prefilter sketches the query, hamming-ranks the
parallel sketch array to take the top `k * prefilter_factor` candidates,
then refines those with exact cosine and returns the top-K.
`EmbeddingHistory::new(...)` is unchanged — sketches are opt-in via the
new constructor. `search_prefilter` falls back to brute-force `search`
when sketches are disabled, so callers never see incorrect results.
ADR-084 acceptance criterion empirically validated:
Synthetic 128-d AETHER-shape, n=256, 16 queries:
k=8, prefilter_factor=4 → 78.9% top-K coverage (FAIL <90%)
k=8, prefilter_factor=8 → ≥90% top-K coverage (PASS)
k=16, prefilter_factor=8 → ≥90% top-K coverage (PASS)
The factor=4 default that I'd planned in Pass 1 falls below the 90% bar
on uniform-random synthetic data. Production callers should use **8**
unless their embeddings carry enough structure (real AETHER traces
likely will) to clear the bar at lower factors. Documented in the
search_prefilter docstring and asserted in
test_search_prefilter_topk_coverage_meets_adr_084.
FIFO eviction now drains the parallel sketches array in lockstep —
test_search_prefilter_evicts_sketches_on_fifo guards against the two
arrays drifting (which would silently corrupt top-K via index
mismatch).
Validated:
- cargo test --workspace --no-default-features → 1,554 passed,
0 failed, 8 ignored (was 1,551; +3 new prefilter tests)
- ESP32-S3 on COM7 still streaming live CSI (cb #3200)
Co-Authored-By: claude-flow <ruv@ruv.net>
* bench(signal): ADR-084 Pass 2 — end-to-end search_prefilter speedup
Measures EmbeddingHistory::search_prefilter (sketch + cosine refine)
vs the brute-force EmbeddingHistory::search baseline at three realistic
AETHER bank sizes, with the empirically validated prefilter_factor=8.
Measured (Windows host, criterion --warm-up 1s --measurement 3s):
d=128, k=8:
n=256 brute_force_cosine = 31.98 us, prefilter = 13.78 us → 2.3x
n=1024 brute_force_cosine = 110.4 us, prefilter = 16.64 us → 6.6x
n=4096 brute_force_cosine = 507.4 us, prefilter = 66.37 us → 7.6x
Speedup grows with bank size (sketch overhead is fixed; brute-force
scales linearly with n). At n=4k the prefilter approaches the 8x
ADR-084 acceptance criterion; at n=10k+ (realistic multi-day
deployment banks) it crosses cleanly. Below n=512 the brute-force
path is already cheap (sub-50 us) so the prefilter's narrower wins
don't materially affect the hot path.
Coverage acceptance (≥90% top-K agreement) is exercised in the
unit-test suite, not the bench. The bench measures cost only.
Co-Authored-By: claude-flow <ruv@ruv.net>
* feat(signal): ADR-084 Pass 3 — EmbeddingHistory::novelty primitive
Adds the cluster-Pi novelty-sensor primitive: `EmbeddingHistory::novelty(query)`
returns `Option<f32>` in [0.0, 1.0] where 0.0 = exact-match-in-bank
and 1.0 = no-overlap. Returns None when sketches are disabled so
callers can fall back gracefully (existing `EmbeddingHistory::new`
constructor stays sketch-disabled).
This is the building block of the cluster-Pi novelty gate
described in ADR-084 §"cluster-Pi novelty sensor": each sensor node
maintains a bank of recent feature vectors, the gate scores the
incoming frame's novelty against the bank, and the heavy CNN /
pose-model wake gate consumes the score.
Wiring novelty into sensing-server's NodeState happens in a
follow-up — that's a ~50-line surgical change touching main.rs that
deserves its own commit. This patch lands the primitive + tests so
the wiring is straightforward.
Three regression tests added:
- test_novelty_returns_none_without_sketches
(graceful fallback when bank is sketch-less)
- test_novelty_zero_for_exact_match_one_for_empty_bank
(semantic boundaries)
- test_novelty_decreases_as_bank_grows_around_query
(gradient direction — guards against reversed comparator)
Validated:
- cargo test --workspace --no-default-features → 1,557 passed,
0 failed, 8 ignored (was 1,554; +3 new novelty tests)
- ESP32-S3 on COM7 still streaming live CSI (cb #7600)
Co-Authored-By: claude-flow <ruv@ruv.net>
* feat(sensing-server): ADR-084 Pass 3 — wire novelty into NodeState
Wires the EmbeddingHistory::novelty primitive (Pass 3 prior commit)
into the per-node frame ingestion path on the cluster Pi. Each
incoming CSI frame now updates a per-node sketch bank of the last
6.4 s of feature vectors and produces a novelty score in [0.0, 1.0]
that downstream model-wake gates can consume.
Two NodeState structs were touched (one in types.rs and a
refactoring-leftover duplicate in main.rs that the call site uses);
both gain feature_history + last_novelty_score fields and an
update_novelty helper that:
- truncates / zero-pads incoming amplitudes to NOVELTY_VECTOR_DIM (56)
- scores novelty *before* inserting (so a frame doesn't see itself)
- FIFO-evicts when the bank reaches NOVELTY_HISTORY_CAPACITY (64)
Wired at the per-node ESP32 frame path in main.rs:3772 (immediately
before frame_history.push_back). Existing call sites that operate on
the singleton SensingState (not per-node) intentionally untouched —
they will be wired in a follow-up alongside the WebSocket update
envelope's novelty_score field.
Two new unit tests in novelty_tests:
- first_frame_yields_max_novelty_then_zero_on_repeat
(semantic boundaries: empty bank = 1.0, exact repeat = 0.0)
- handles_short_and_long_amplitude_vectors
(truncate / zero-pad robustness across hardware variants)
Validated:
- cargo test --workspace --no-default-features → 1,559 passed,
0 failed, 8 ignored (was 1,557; +2 new novelty tests)
- ESP32-S3 on COM7 still streaming live CSI (cb #3900)
Co-Authored-By: claude-flow <ruv@ruv.net>
* hardening(ruvector): L2 from PR #435 review — overflow on >u16::MAX dims
Pass 1.6 hardening, addressing L2 finding from the security review on
PR #435 (https://github.com/ruvnet/RuView/pull/435#issuecomment-4321285519):
The original `Sketch::from_embedding` used `debug_assert!` for the
`embedding.len() <= u16::MAX` invariant, which compiled out in release
builds. A caller passing a 65,536+ -dim embedding would silently
truncate the dimension count via `as u16` cast — two over-long inputs
would then compare as same-dimensional rather than as 64k vs 70k, and
the dimension confusion would not surface anywhere.
Two-part fix:
- `from_embedding` (infallible) now SATURATES `embedding_dim` to
`u16::MAX` rather than truncating. Two over-long inputs still get
packed bit-correctly by `BinaryQuantized` and the saturated dim is
consistent across both, so they compare predictably (just with an
upper-bounded distance).
- `try_from_embedding` (new, fallible) returns
`Err(SketchError::EmbeddingDimOverflow{got, max})` when the input
exceeds `u16::MAX`. Use this when an over-long input should fail
loudly rather than be silently saturated.
- New error variant `SketchError::EmbeddingDimOverflow` with the
observed `got` and the `max` (`u16::MAX as usize`).
- New regression test `try_from_embedding_rejects_over_long_input`
asserts both paths: try_ → Err, infallible → saturate.
Validated:
- 13 sketch unit tests pass (was 12; +1 for L2 boundary).
- cargo test --workspace --no-default-features → 1,560 passed,
0 failed, 8 ignored (was 1,559; +1).
- ESP32-S3 on COM7 streaming live CSI (cb #100, fresh boot RSSI -48 dBm).
Co-Authored-By: claude-flow <ruv@ruv.net>
* hardening(ruvector,signal): L1+L3 from PR #435 review
Two follow-ups to the security review on PR #435:
L1 — Defensive `if let Some(...)` for SketchBank::topk heap peek.
The original `.expect("heap len == k > 0")` was mathematically
unreachable (k > 0 enforced at function entry, heap.len() >= k branch
guards), but a structural pattern makes the impossibility a type
property rather than a runtime invariant. Same hot-path cost; zero
panic risk in the production binary.
L3 — Guard `embedding_dim == 0` in `EmbeddingHistory::novelty`.
A 0-dim history is constructible via `with_sketch(0, ...)`; without
the guard the function returned `NaN` (min_d as f32 / 0.0), silently
poisoning every downstream gate (model-wake, anomaly-emit, etc).
Now returns Some(1.0) — fail-loud at "no comparison possible →
maximally novel," never NaN. New regression test
`test_novelty_zero_dim_history_returns_one_not_nan` pins it down.
Validated:
- cargo test --workspace --no-default-features → 1,561 passed,
0 failed, 8 ignored (was 1,560; +1 for the L3 NaN guard test).
- ESP32-S3 on COM7 streaming live CSI (cb #12400, RSSI fresh).
L4 (f64→f32 cast) is documentation-only and lands in a follow-up
patch; L8 (always-on novelty sensor) is an observation, not a fix.
Co-Authored-By: claude-flow <ruv@ruv.net>
* feat(sensing-server): ADR-084 Pass 3.5 — novelty_score on PerNodeFeatureInfo
Adds an optional `novelty_score: Option<f32>` field to
PerNodeFeatureInfo, the per-node WebSocket envelope shape. Mirrored
on both struct definitions (types.rs canonical + main.rs's
refactoring-leftover duplicate) so the schema is consistent.
`#[serde(skip_serializing_if = "Option::is_none")]` keeps existing
WebSocket consumers unaffected — old clients see no extra field
unless the server populates it. No PerNodeFeatureInfo literal
construction sites exist today (all `node_features: None`), so this
is a schema-only addition; live population from
`NodeState::last_novelty_score` lands in a Pass 3.6 follow-up that
also wires `node_features: Some(...)` at the per-node ESP32 frame
emit path.
Validated:
- cargo test --workspace --no-default-features → 1,561 passed,
0 failed, 8 ignored (no change; schema-only).
- ESP32-S3 on COM7 streaming live CSI (cb #2100, fresh boot).
Co-Authored-By: claude-flow <ruv@ruv.net>
* feat(sensing-server): ADR-084 Pass 3.6 — populate node_features with novelty_score
Wires `node_features: Some(...)` at the two per-node ESP32 frame
emit sites (formerly `node_features: None`). Adds a `build_node_features`
helper that constructs `Vec<PerNodeFeatureInfo>` from `s.node_states`,
including the per-node `last_novelty_score`.
This completes the Pass 3.x track — novelty score now flows from
NodeState → PerNodeFeatureInfo → SensingUpdate envelope → WebSocket
clients. Cluster-Pi UI / model-wake / anomaly-emit gates can read
it without round-tripping back to the server.
Three other call sites (singleton paths at 1772, 1911, 4170) keep
`node_features: None` for now — those are for the offline /
simulated paths that don't have per-node ESP32 state. They'll get
populated when their parent flows wire up real multi-node fanout.
Stale flag uses `ESP32_OFFLINE_TIMEOUT` (5s) — same threshold the
rest of the system uses to decide a node has dropped.
Validated:
- cargo test --workspace --no-default-features → 1,561 passed,
0 failed, 8 ignored (no change; integration test would be wire-
format diff in a follow-up).
- ESP32-S3 on COM7 streaming live CSI (cb #100, fresh boot,
RSSI -49 dBm).
Co-Authored-By: claude-flow <ruv@ruv.net>
* feat(ruvector): ADR-084 Pass 4 — WireSketch wire-format primitive
Adds `WireSketch::serialize` / `deserialize` for transmitting a
sketch + novelty score over any byte-stream channel — cluster↔cluster
mesh (ADR-066 swarm bridge when it exists), sensor→cluster-Pi UDP
(ADR-086 edge gate complement), gateway→cloud QUIC. Channel-agnostic
by design.
Wire layout (12-byte header + ceil(dim/8) bytes payload, little-endian):
[0..4] magic = 0xC5110084
[4..6] format_version = 1
[6..8] sketch_version (embedding-model schema)
[8..10] embedding_dim
[10..12] novelty_q15 (novelty * 32_767, saturated)
[12..] packed sketch bits
A 128-d AETHER sketch fits in exactly 28 bytes (12 header + 16 bits).
Deserializer is paranoid by design — every untrusted byte buffer
gets validated against:
- length floor (>= header bytes)
- length ceiling (WIRE_SKETCH_MAX_BYTES = 9 KiB; defends against
memory-exhaustion attacks via claimed-but-impossible large dims)
- magic match
- format_version supported
- embedding_dim → payload bytes consistency
A malformed UDP packet from a non-RuView sender produces a typed
`WireSketchError` (variant per failure class), never a panic.
Re-exported from lib.rs alongside `Sketch` / `SketchBank`.
Seven new tests:
- wire_serialize_round_trip (correctness)
- wire_rejects_short_buffer (length floor)
- wire_rejects_oversized_buffer (length ceiling, DoS guard)
- wire_rejects_bad_magic (cross-protocol confusion guard)
- wire_rejects_unsupported_format_version (forward-compat)
- wire_rejects_payload_size_mismatch (header/body consistency)
- wire_envelope_size_for_aether_128d (sizing contract: 28 bytes)
Validated:
- cargo test --workspace --no-default-features → 1,568 passed,
0 failed, 8 ignored (was 1,561; +7 wire-format tests).
- ESP32-S3 on COM7 streaming live CSI (cb #15100, RSSI -48 dBm).
Pass 4's wire-format primitive ships first; the channel that
carries it (ADR-066 swarm-bridge or ADR-086 sensor→Pi gate) is
out-of-scope for this commit and tracked separately.
Co-Authored-By: claude-flow <ruv@ruv.net>
* feat(ruvector): ADR-084 Pass 5 — privacy-preserving event log + L4 docstring
Pass 5 — `PrivacyEventLog` and `NoveltyEvent` types in a new
`wifi_densepose_ruvector::event_log` module. Each event stores
`(timestamp, sketch_bytes, sketch_version, embedding_dim, novelty,
witness_sha256)` — explicitly NOT the raw float embedding. The
witness is SHA-256 of the WireSketch serialization (12-byte header +
packed bits + q15 novelty), making events content-addressable: two
pushes of the same `(sketch, novelty)` produce byte-identical
witnesses, enabling dedup at the receiver and verifier.
Privacy properties (ADR-084 §"Privacy-preserving event log"):
1. Non-invertibility — 1-bit sign quantization is lossy; an attacker
with read access cannot reconstruct the source CSI / embedding.
2. Content addressing — `(sketch_version, witness)` is fully qualified.
3. Bounded memory — fixed capacity ring; misbehaving senders cannot
exhaust receiver memory.
Seven new tests:
- push_grows_until_capacity_then_fifo_evicts
- zero_capacity_log_silently_drops_pushes (no-op stub case)
- witness_is_deterministic_for_same_sketch_and_novelty
(witness must NOT depend on timestamp)
- witness_differs_for_different_novelty_scores
- find_by_witness_returns_most_recent_match
- find_by_witness_returns_none_on_miss
- event_does_not_carry_raw_embedding (structural privacy guarantee)
L4 hardening (PR #435 security review) — the `f64 → f32` cast in
NodeState::update_novelty now has a docstring noting the boundary
behaviour: `f64::INFINITY` survives as `f32::INFINITY`, `f64::NAN`
propagates as `f32::NAN`. Neither panics. CSI amplitudes from healthy
firmware are well within f32 finite range.
Validated:
- cargo test --workspace --no-default-features → 1,575 passed,
0 failed, 8 ignored (was 1,568; +7 event-log tests).
- ESP32-S3 on COM7 streaming live CSI (cb #2800, RSSI -52 dBm).
Co-Authored-By: claude-flow <ruv@ruv.net>
The Rust port lived two directories deep (rust-port/wifi-densepose-rs/)
without any sibling under rust-port/ that warranted the extra level.
Move the whole workspace up to v2/ to match v1/ (Python) at the same
depth and shorten every cd / build command across the repo.
git mv preserves history for all tracked files. 60 files updated for
path references (CI workflows, ADRs, docs, scripts, READMEs, internal
.claude-flow state). Two manual fixes for relative-cd paths in
CLAUDE.md and ADR-043 that became wrong after the depth change
(cd ../.. → cd ..).
Validated:
- cargo check --workspace --no-default-features → clean (after target/
nuke; the gitignored target/ was carried by the OS rename and had
hard-coded old paths in build scripts)
- cargo test --workspace --no-default-features → 1,539 passed, 0 failed,
8 ignored (same totals as pre-rename)
- ESP32-S3 on COM7 → still streaming live CSI (cb #40300, RSSI -64 dBm)
After-merge follow-up: contributors should `rm -rf v2/target` once and
let cargo regenerate from the new path.
ruv
Rahul
dependabot[bot]
Chaitanya Tata
Timothy Schwarz
@aaronjmars
Akhilesh Arora
Deploy Bot