berkus
/
wifi-densepose
mirror of https://github.com/ruvnet/wifi-densepose.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity
wifi-densepose/docs/adr
History
rUv 3314c8db8d
feat(cog-pose-estimation): scaffold first Cog from this repo (ADR-100 + ADR-101) (#642) 
* feat(cog-pose-estimation): scaffold first Cog from this repo (ADR-100 + ADR-101)

Adds the foundation for the pose-estimation Cog that ships from this
repo into Cognitum V0 appliances. Companion ADR-225 + crate land in
cognitum-one/v0-appliance.

ADRs:
* ADR-100 formalises the Cognitum Cog packaging spec — on-device
  layout under /var/lib/cognitum/apps/<id>/, manifest.json schema
  (incl. new binary_sha256 + binary_signature fields), GCS hosting
  convention, repo source layout, build pipeline, and the four-verb
  runtime contract (version | manifest | health | run). Documents the
  convention I reverse-engineered from inspecting installed cogs on a
  live cognitum-v0 appliance — `anomaly-detect`, `presence`,
  `seizure-detect`, etc.
* ADR-101 designs the pose-estimation Cog itself: where it sits in
  the wifi-densepose pipeline (encoder init from
  ruvnet/wifi-densepose-pretrained, 17-keypoint regression head),
  what gets shipped per target arch (arm / x86_64 / hailo8 /
  hailo10), acceptance gates (PCK@20 explicitly deferred to #640 —
  this ADR ships the vehicle, not the accuracy).

Crate v2/crates/cog-pose-estimation/:
* Cargo.toml + workspace member declaration with a hailo feature gate
  so the binary builds without the Hailo SDK in CI.
* main.rs implements the four-verb CLI exactly per ADR-100.
* config.rs / manifest.rs / publisher.rs / inference.rs / runtime.rs —
  small modules, each <100 lines.
* publisher.rs emits ADR-100 structured JSON events.
* inference.rs is a stub that produces a centred-skeleton baseline
  with confidence=0 (honest: no trained weights wired in yet).
* runtime.rs subscribes to /api/v1/sensing/latest, slides a
  56*20 window, runs the engine, emits pose.frame events.
* cog/manifest.template.json + cog/config.schema.json define the
  release artifact + runtime config schemas.
* cog/Makefile holds build / sign / upload targets.
* tests/smoke.rs covers manifest roundtrip + engine I/O surface.

Verified locally:
* cargo check -p cog-pose-estimation: clean.
* cargo test  -p cog-pose-estimation: 4/4 pass.
* ./target/release/cog-pose-estimation {version,manifest,health}:
  all emit the right contract output.

This commit contains scaffolding only; the actual trained weights and
Hailo HEF cross-compile come in follow-ups tracked in #640 and the
companion v0-appliance branch.

* feat(cog-pose-estimation): first measured run — Candle CUDA on RTX 5080

Trained pose_v1 on ruvultra (RTX 5080) via Candle 0.9 + cuda feature
against the same 1,077-sample paired session that produced 0%/0% PCK
in #640 with the pure-JS SPSA trainer. First real numbers:

  PCK@20 = 3.0%   (up from 0.0%)
  PCK@50 = 18.5%  (up from 0.0%)
  MPJPE  = 0.093  (down from 0.66, ~7x improvement)

400 epochs in 2.1 s wall time, full-batch, ~5 ms/epoch. Loss curve
0.181 -> 0.014 over the run, eval 0.010. Per-joint reveals the model
leans on right-side proximal joints (r_hip 77% PCK@50, r_knee 35%,
l_elbow 26%) — consistent with the camera framing in the source
recording. Distal joints (wrists, ankles) and face joints are still
near-random, consistent with the 56-subcarrier / 20-frame input not
carrying fine-grained spatial info at 1077 samples.

This commit:

* Adds v2/crates/cog-pose-estimation/cog/artifacts/{pose_v1.safetensors,
  train_results.json} so the cog dir now contains a real reference
  artifact, not just scaffold.
* Updates cog/README.md "Status" block with the measured numbers,
  per-joint table, and an honest reading of where the model
  succeeds vs where the data is the bottleneck.
* Adds docs/benchmarks/pose-estimation-cog.md as the canonical
  benchmark log — append-only, one section per published run.
* Appends a "First measured run" section to ADR-101 referencing
  the new benchmark file.

Still pending in the follow-up:
* Wire pose_v1.safetensors into src/inference.rs (replace stub).
* ONNX export (Candle lacks a writer — needs external conversion).
* Hailo HEF cross-compile + cluster deploy.

The data-bound gap to PCK@20 >= 35% is tracked in #640.

* feat(cog-pose-estimation): wire real weights — cog is no longer a stub

Replaces the centred-skeleton stub in src/inference.rs with a real
Candle-based loader that reads cog/artifacts/pose_v1.safetensors and
runs the trained Conv1d encoder + MLP pose head on every incoming CSI
window.

What changes:

* src/inference.rs: PoseNet mirrors the training script's architecture
  exactly — Conv1d(56->64, k=3 d=1), Conv1d(64->128, k=3 d=2),
  Conv1d(128->128, k=3 d=4), mean over time, Linear(128->256)+ReLU,
  Linear(256->34)+sigmoid -> reshape [17, 2]. The InferenceEngine
  searches a sensible candidate list for the weights file
  (/var/lib/cognitum/apps/pose-estimation/, ./pose_v1.safetensors,
  ./cog/artifacts/, repo-root, v2/-relative) and falls back to the
  stub when none are present so the cog still satisfies ADR-100.
* Cargo.toml: adds candle-core 0.9 + candle-nn 0.9 (no-default-features,
  CPU build by default) + safetensors 0.4. New `cuda` feature opt-in
  for GPU inference on hosts that have it. Drops the unused
  wifi-densepose-train path dep from the default build path.
* src/main.rs + src/publisher.rs: health.ok event now carries
  `backend` (candle-cuda | candle-cpu | stub) and the synthetic
  output confidence, so operators can tell at a glance whether the
  cog loaded its weights or fell back to the stub.
* tests/smoke.rs: adds `real_weights_load_when_available` which
  asserts the loaded engine reports backend=candle-* and emits
  non-zero confidence — exactly the signal that proves we're not
  silently degrading to the stub.

Verified locally:

* `cargo check -p cog-pose-estimation --no-default-features` — clean
* `cargo test  -p cog-pose-estimation --no-default-features` — 5/5 pass
* `./target/release/cog-pose-estimation health` emits:
  {"event":"health.ok","fields":{"backend":"candle-cpu","cog":"pose-estimation","synthetic_output_confidence":0.185}}
  — 0.185 is the published PCK@50 from cog/artifacts/train_results.json,
  emitted by the real Candle inference path (would be 0.0 if it had
  fallen back to the stub).

The cog now runs the trained pose_v1 model end-to-end. Accuracy is
still bounded by the underlying 1077-sample training data (PCK@20
3.0%, PCK@50 18.5% per docs/benchmarks/pose-estimation-cog.md) — that
gap is data-bound and tracked in #640. ONNX export + Hailo HEF
cross-compile remain follow-ups.

* docs(benchmarks): measure cog-pose-estimation cold-start latency

100 sequential `cog-pose-estimation health` invocations average 76.2 ms
each on a Windows x86_64 host using the `candle-cpu` backend. Each
invocation re-loads pose_v1.safetensors and runs one synthetic forward
pass, so this is the worst-case cold-start path. Long-running `run`
inference will be sub-millisecond per frame once the model is loaded.

Updates the benchmarks doc accordingly.

* feat(cog-pose-estimation): ONNX export — pose_v1.onnx + scripts/export-onnx.py

Adds the canonical ONNX artifact that unblocks downstream Hailo HEF
cross-compile + ONNX Runtime benchmarks. Generated on ruvultra (torch
2.12.0 + CUDA), 12,059 bytes, opset 18, dynamic batch axis.

* scripts/export-onnx.py: mirrors the Candle inference architecture in
  PyTorch (Conv1d 56->64, 64->128, 128->128 + Linear 128->256->34), pure-
  python safetensors loader (no extra pip dep), exports via
  torch.onnx.export, then verifies via onnx.checker.check_model and
  numerical parity against the torch reference.
* Verified parity vs torch: max |torch - onnx| = 8.94e-8 (1e-5
  threshold). Effectively bit-perfect.
* v2/crates/cog-pose-estimation/cog/artifacts/pose_v1.onnx — the
  artifact itself, 12 KB.
* docs/benchmarks/pose-estimation-cog.md — adds an ONNX export
  section with the verification numbers.

Next: Hailo HEF cross-compile (still gated on Hailo SDK on a
self-hosted runner) and ONNX Runtime latency benchmarks on each
target arch.

* feat(cog-pose-estimation): release v0.0.1 — signed aarch64 binary on GCS

End-to-end deploy: cross-compiled to aarch64-unknown-linux-gnu on
ruvultra, ran via qemu-aarch64-static, then smoke-tested on a real
cognitum-v0 Pi 5. Signed with COGNITUM_OWNER_SIGNING_KEY (Ed25519)
and uploaded to gs://cognitum-apps/cogs/arm/.

Real-hardware results on cognitum-v0 (Pi 5):
  health: backend=candle-cpu, confidence=0.185, real weights loaded
  30x sequential `health`: 0.251 s total -> 8.4 ms / invocation (cold)

GCS release artifacts (publicly downloadable):
  binary:  3,741,976 bytes
    sha256 1e1a7d3dd01ca05d5bfc5dbb142a5941b7866ed9f3224a21edc04d3f09a99bf5
  weights:   507,032 bytes
    sha256 eb249b9a6b2e10130437a10976ed0230b0d085f86a0553d7226e1ae6eae4b9e5
  signature (Ed25519, b64): LUN7xqLPYD3MFzm5dKB5MnYU0LvoRtek5ci5KiKPHBg+Xo6xuazwokn2Dw2JPMaLYJzmWn/SpT4djuR7hYvVDw==

Adds:
* v2/crates/cog-pose-estimation/cog/artifacts/manifest.json — the
  release-pipeline-produced manifest with all fields filled in per
  ADR-100, including arch, target_triple, signature, and a
  build_metadata block carrying the validation PCK numbers.
* docs/benchmarks/pose-estimation-cog.md — new sections covering
  the real Pi 5 smoke (8.4 ms cold-start) and the signed GCS
  release artifacts.

Verified by downloading the binary anonymously from GCS and
re-computing the sha256 — matches the locally-computed sha exactly.
Signature decoded to the expected 64-byte Ed25519 length.

Closes the GCS-upload acceptance criterion from ADR-100; the only
pending work is Hailo HEF cross-compile (still SDK-gated) and an
x86_64 release alongside this arm release.

* docs(benchmarks): record live cognitum-v0 install + 5-sec smoke run

Adds the "Live appliance install" section documenting what happened
when the signed v0.0.1 binary + weights were installed under
/var/lib/cognitum/apps/pose-estimation/ on cognitum-v0 (the V0
cluster leader).

* Layout matches the existing anomaly-detect / presence / seizure-
  detect cogs exactly — the Cogs dashboard at
  http://cognitum-v0:9000/cogs auto-discovers entries.
* `cog-pose-estimation run` ran for 5 seconds in the background and
  cleanly emitted run.started + structured WARN events for the
  missing local sensing-server on :3000 (cognitum-v0's actual CSI
  source is ruview-vitals-worker on :50054, not :3000). No crashes,
  no NaN, no leaks.
* Wiring `sensing_url` to the appliance-native source is a separate
  Day-2 integration task.
 		2026-05-19 17:03:09 -04:00
..
.issue-177-body.md ruv-neural: publish 11 crates to crates.io — full implementation, no stubs 2026-03-09 10:52:24 -04:00
ADR-001-wifi-mat-disaster-detection.md feat: Add wifi-densepose-mat disaster detection module 2026-01-13 17:24:50 +00:00
ADR-002-ruvector-rvf-integration-strategy.md chore(repo): rename rust-port/wifi-densepose-rs → v2/ (flatten to one level) (#427) 2026-04-25 21:28:13 -04:00
ADR-003-rvf-cognitive-containers-csi.md feat: Add 12 ADRs for RuVector RVF integration and proof-of-reality 2026-02-28 06:13:04 +00:00
ADR-004-hnsw-vector-search-fingerprinting.md docs: update README, CHANGELOG, and associated ADRs for MERIDIAN 2026-03-01 12:06:09 -05:00
ADR-005-sona-self-learning-pose-estimation.md docs: update README, CHANGELOG, and associated ADRs for MERIDIAN 2026-03-01 12:06:09 -05:00
ADR-006-gnn-enhanced-csi-pattern-recognition.md docs: update README, CHANGELOG, and associated ADRs for MERIDIAN 2026-03-01 12:06:09 -05:00
ADR-007-post-quantum-cryptography-secure-sensing.md feat: Add 12 ADRs for RuVector RVF integration and proof-of-reality 2026-02-28 06:13:04 +00:00
ADR-008-distributed-consensus-multi-ap.md feat: Add 12 ADRs for RuVector RVF integration and proof-of-reality 2026-02-28 06:13:04 +00:00
ADR-009-rvf-wasm-runtime-edge-deployment.md feat: Add 12 ADRs for RuVector RVF integration and proof-of-reality 2026-02-28 06:13:04 +00:00
ADR-010-witness-chains-audit-trail-integrity.md feat: Add 12 ADRs for RuVector RVF integration and proof-of-reality 2026-02-28 06:13:04 +00:00
ADR-011-python-proof-of-reality-mock-elimination.md chore(repo): move v1/ → archive/v1/ + add archive/README.md (#430) 2026-04-25 23:07:52 -04:00
ADR-012-esp32-csi-sensor-mesh.md docs(adr): update bare wifi-densepose-rs refs to v2/ in ADR-012, ADR-052 2026-04-25 21:43:21 -04:00
ADR-013-feature-level-sensing-commodity-gear.md chore(repo): move v1/ → archive/v1/ + add archive/README.md (#430) 2026-04-25 23:07:52 -04:00
ADR-014-sota-signal-processing.md feat: Implement ADR-014 SOTA signal processing (6 algorithms, 83 tests) 2026-02-28 14:34:16 +00:00
ADR-015-public-dataset-training-strategy.md docs: Update ADR-015 with verified dataset specs from research 2026-02-28 15:14:50 +00:00
ADR-016-ruvector-integration.md docs(adr): Mark ADR-016 as Accepted — all 5 integrations complete 2026-02-28 15:46:44 +00:00
ADR-017-ruvector-signal-mat-integration.md chore(repo): rename rust-port/wifi-densepose-rs → v2/ (flatten to one level) (#427) 2026-04-25 21:28:13 -04:00
ADR-018-esp32-dev-implementation.md chore(repo): move v1/ → archive/v1/ + add archive/README.md (#430) 2026-04-25 23:07:52 -04:00
ADR-019-sensing-only-ui-mode.md chore(repo): move v1/ → archive/v1/ + add archive/README.md (#430) 2026-04-25 23:07:52 -04:00
ADR-020-rust-ruvector-ai-model-migration.md chore(repo): move v1/ → archive/v1/ + add archive/README.md (#430) 2026-04-25 23:07:52 -04:00
ADR-021-vital-sign-detection-rvdna-pipeline.md chore(repo): rename rust-port/wifi-densepose-rs → v2/ (flatten to one level) (#427) 2026-04-25 21:28:13 -04:00
ADR-022-windows-wifi-enhanced-fidelity-ruvector.md chore(repo): rename rust-port/wifi-densepose-rs → v2/ (flatten to one level) (#427) 2026-04-25 21:28:13 -04:00
ADR-023-trained-densepose-model-ruvector-pipeline.md chore(repo): rename rust-port/wifi-densepose-rs → v2/ (flatten to one level) (#427) 2026-04-25 21:28:13 -04:00
ADR-024-contrastive-csi-embedding-model.md chore(repo): rename rust-port/wifi-densepose-rs → v2/ (flatten to one level) (#427) 2026-04-25 21:28:13 -04:00
ADR-025-macos-corewlan-wifi-sensing.md chore(repo): rename rust-port/wifi-densepose-rs → v2/ (flatten to one level) (#427) 2026-04-25 21:28:13 -04:00
ADR-026-survivor-track-lifecycle.md feat(mat): add ADR-026 + survivor track lifecycle module (WIP) 2026-03-01 07:53:28 +00:00
ADR-027-cross-environment-domain-generalization.md docs: add gap closure mapping for all proposed ADRs (002-011) to ADR-027 2026-03-01 11:51:32 -05:00
ADR-028-esp32-capability-audit.md chore(repo): move v1/ → archive/v1/ + add archive/README.md (#430) 2026-04-25 23:07:52 -04:00
ADR-029-ruvsense-multistatic-sensing-mode.md docs: update ADRs with ENOMEM crash fix proof (Issue #127) 2026-03-03 16:14:54 -05:00
ADR-030-ruvsense-persistent-field-model.md docs: add RuvSense persistent field model, exotic tiers, and appliance categories 2026-03-02 01:59:21 +00:00
ADR-031-ruview-sensing-first-rf-mode.md feat: combine ADR-029/030/031 + DDD domain model into implementation branch 2026-03-01 21:25:14 -05:00
ADR-032-multistatic-mesh-security-hardening.md feat: ADR-032a midstreamer QUIC transport + secure TDM + temporal gesture + attractor drift 2026-03-01 22:22:19 -05:00
ADR-033-crv-signal-line-sensing-integration.md feat: ADR-033 CRV signal-line integration + ruvector-crv 6-stage pipeline 2026-03-01 22:21:59 -05:00
ADR-034-expo-mobile-app.md feat: Implement RSSI service for iOS and Web platforms 2026-03-02 10:30:33 -05:00
ADR-035-live-sensing-ui-accuracy.md docs: update ADR-035 with dark mode, render modes, pose_source fix 2026-03-02 11:08:13 -05:00
ADR-036-rvf-training-pipeline-ui.md chore(repo): rename rust-port/wifi-densepose-rs → v2/ (flatten to one level) (#427) 2026-04-25 21:28:13 -04:00
ADR-037-multi-person-pose-detection.md docs: ADR-037 multi-person pose detection from single ESP32 CSI stream 2026-03-02 13:49:38 -05:00
ADR-038-sublinear-goal-oriented-action-planning.md docs: ADR-038 Sublinear Goal-Oriented Action Planning (GOAP) 2026-03-02 14:39:15 -05:00
ADR-039-esp32-edge-intelligence.md chore(repo): rename rust-port/wifi-densepose-rs → v2/ (flatten to one level) (#427) 2026-04-25 21:28:13 -04:00
ADR-040-wasm-programmable-sensing.md chore(repo): rename rust-port/wifi-densepose-rs → v2/ (flatten to one level) (#427) 2026-04-25 21:28:13 -04:00
ADR-041-wasm-module-collection.md feat: expand ADR-041 WASM module catalog from 37 to 60 modules 2026-03-03 00:06:39 -05:00
ADR-042-coherent-human-channel-imaging.md feat: add ADR-042 CHCI protocol, 24 new edge modules, README restructure 2026-03-03 11:35:57 -05:00
ADR-043-sensing-server-ui-api-completion.md chore(repo): rename rust-port/wifi-densepose-rs → v2/ (flatten to one level) (#427) 2026-04-25 21:28:13 -04:00
ADR-044-geospatial-satellite-integration.md feat: Real-time dense point cloud from camera + WiFi CSI (#405) 2026-04-20 12:48:54 -04:00
ADR-045-amoled-display-support.md docs: update README with ADR-045–048, Observatory, adaptive classifier, AMOLED display 2026-03-05 10:20:48 -05:00
ADR-046-android-tv-box-armbian-deployment.md docs: update README with ADR-045–048, Observatory, adaptive classifier, AMOLED display 2026-03-05 10:20:48 -05:00
ADR-047-psychohistory-observatory-visualization.md docs: update README with ADR-045–048, Observatory, adaptive classifier, AMOLED display 2026-03-05 10:20:48 -05:00
ADR-048-adaptive-csi-classifier.md feat: adaptive CSI classifier with signal smoothing pipeline (ADR-048) (#144) 2026-03-05 10:15:18 -05:00
ADR-049-cross-platform-wifi-interface-detection.md chore(repo): move v1/ → archive/v1/ + add archive/README.md (#430) 2026-04-25 23:07:52 -04:00
ADR-050-provisioning-tool-enhancements.md feat: Real-time dense point cloud from camera + WiFi CSI (#405) 2026-04-20 12:48:54 -04:00
ADR-050-quality-engineering-security-hardening.md fix: security hardening — replace fake HMAC, add path traversal protection, OTA auth (ADR-050) 2026-03-06 13:11:04 -05:00
ADR-052-ddd-bounded-contexts.md feat: complete Tauri desktop frontend with all pages and enhanced design (#198) 2026-03-08 23:31:18 -04:00
ADR-052-tauri-desktop-frontend.md docs(adr): update bare wifi-densepose-rs refs to v2/ in ADR-012, ADR-052 2026-04-25 21:43:21 -04:00
ADR-053-ui-design-system.md feat: complete Tauri desktop frontend with all pages and enhanced design (#198) 2026-03-08 23:31:18 -04:00
ADR-054-desktop-full-implementation.md feat(desktop): RuView Desktop v0.4.0 - Full ADR-054 Implementation (#212) 2026-03-09 21:58:06 -04:00
ADR-055-integrated-sensing-server.md feat(desktop): v0.4.2 - Integrated sensing server with real WebSocket data 2026-03-10 00:08:31 -04:00
ADR-056-ruview-desktop-capabilities.md feat(desktop): v0.4.2 - Integrated sensing server with real WebSocket data 2026-03-10 00:08:31 -04:00
ADR-057-firmware-csi-build-guard.md fix(firmware): enable CSI in sdkconfig and add build guard (ADR-057) 2026-03-12 13:49:20 -04:00
ADR-058-ruvector-wasm-browser-pose-example.md chore(repo): rename rust-port/wifi-densepose-rs → v2/ (flatten to one level) (#427) 2026-04-25 21:28:13 -04:00
ADR-059-live-esp32-csi-pipeline.md feat(demo): wire all 6 RuVector WASM attention mechanisms into pose fusion 2026-03-12 20:59:57 -04:00
ADR-060-provision-channel-mac-filter.md feat(firmware): --channel and --filter-mac provisioning (ADR-060) 2026-03-13 08:27:08 -04:00
ADR-061-qemu-esp32s3-firmware-testing.md feat: QEMU ESP32-S3 testing platform + swarm configurator (ADR-061/062) (#260) 2026-03-14 13:39:51 -04:00
ADR-062-qemu-swarm-configurator.md feat: QEMU ESP32-S3 testing platform + swarm configurator (ADR-061/062) (#260) 2026-03-14 13:39:51 -04:00
ADR-063-mmwave-sensor-fusion.md feat: ADR-063/064 mmWave sensor fusion + multimodal ambient intelligence (#269) 2026-03-15 16:10:10 -04:00
ADR-064-multimodal-ambient-intelligence.md feat: ADR-063/064 mmWave sensor fusion + multimodal ambient intelligence (#269) 2026-03-15 16:10:10 -04:00
ADR-065-happiness-scoring-seed-bridge.md feat: happiness scoring pipeline + ESP32 swarm with Cognitum Seed (#285) 2026-03-20 18:46:34 -04:00
ADR-066-esp32-swarm-seed-coordinator.md feat: ADR-069 ESP32 CSI → Cognitum Seed RVF pipeline (v0.5.4-esp32) 2026-04-02 19:32:18 -04:00
ADR-067-ruvector-v2.0.5-upgrade.md docs(adr): ADR-067 RuVector v2.0.5 upgrade + new crate adoption plan 2026-03-23 21:51:43 -04:00
ADR-068-per-node-state-pipeline.md feat: ADR-069 ESP32 CSI → Cognitum Seed RVF pipeline (v0.5.4-esp32) 2026-04-02 19:32:18 -04:00
ADR-069-cognitum-seed-csi-pipeline.md feat: ADR-069 ESP32 CSI → Cognitum Seed RVF pipeline (v0.5.4-esp32) 2026-04-02 19:32:18 -04:00
ADR-070-self-supervised-pretraining.md feat: ADR-070 self-supervised pretraining from live ESP32 CSI + Seed 2026-04-02 20:42:37 -04:00
ADR-071-ruvllm-training-pipeline.md feat: camera-free 17-keypoint pose training (10 sensor signals) 2026-04-02 23:05:07 -04:00
ADR-072-wiflow-architecture.md feat: ADR-072 WiFlow SOTA architecture — TCN + axial attention + pose decoder 2026-04-02 23:40:23 -04:00
ADR-073-multifrequency-mesh-scan.md feat: ADR-074 spiking neural network for real-time CSI sensing 2026-04-03 00:34:31 -04:00
ADR-074-spiking-neural-csi-sensing.md feat: ADR-074 spiking neural network for real-time CSI sensing 2026-04-03 00:34:31 -04:00
ADR-075-mincut-person-separation.md chore(repo): rename rust-port/wifi-densepose-rs → v2/ (flatten to one level) (#427) 2026-04-25 21:28:13 -04:00
ADR-076-csi-spectrogram-embeddings.md feat: ADR-076 CNN spectrogram embeddings + graph transformer fusion 2026-04-03 00:36:38 -04:00
ADR-077-novel-rf-sensing-applications.md feat: ADR-077 — 6 novel RF sensing applications 2026-04-03 08:50:48 -04:00
ADR-078-multifreq-mesh-applications.md feat: ADR-078 — 5 multi-frequency mesh applications 2026-04-03 08:52:50 -04:00
ADR-079-camera-ground-truth-training.md fix: remove hardcoded Tailscale IPs and usernames from public files 2026-04-06 14:39:21 -04:00
ADR-080-qe-remediation-plan.md chore(repo): move v1/ → archive/v1/ + add archive/README.md (#430) 2026-04-25 23:07:52 -04:00
ADR-081-adaptive-csi-mesh-firmware-kernel.md chore(repo): rename rust-port/wifi-densepose-rs → v2/ (flatten to one level) (#427) 2026-04-25 21:28:13 -04:00
ADR-082-pose-tracker-confirmed-output-filter.md fix(tracker): exclude Lost tracks from bridge output (#420, ADR-082) (#426) 2026-04-25 20:03:03 -04:00
ADR-083-per-cluster-pi-compute-hop.md docs(adr): ADR-083 — per-cluster Pi compute hop (proposed) (#428) 2026-04-25 23:08:02 -04:00
ADR-084-rabitq-similarity-sensor.md docs(adr): ADR-084 — promote Proposed → Accepted 2026-04-26 02:22:26 -04:00
ADR-085-rabitq-pipeline-expansion.md docs(adr): ADR-085 — RaBitQ pipeline expansion (proposed) (#433) 2026-04-26 00:11:32 -04:00
ADR-086-edge-novelty-gate.md docs(adr): ADR-086 — edge novelty gate (proposed) (#434) 2026-04-26 02:21:40 -04:00
ADR-089-nvsim-nv-diamond-simulator.md feat(nvsim): full simulator stack — Rust crate, dashboard, server, App Store, Ghost Murmur [ADR-089/090/091/092/093] 2026-04-27 12:41:01 -04:00
ADR-090-nvsim-lindblad-extension.md feat(nvsim): full simulator stack — Rust crate, dashboard, server, App Store, Ghost Murmur [ADR-089/090/091/092/093] 2026-04-27 12:41:01 -04:00
ADR-091-stand-off-radar-tier-research.md feat(nvsim): full simulator stack — Rust crate, dashboard, server, App Store, Ghost Murmur [ADR-089/090/091/092/093] 2026-04-27 12:41:01 -04:00
ADR-092-nvsim-dashboard-implementation.md feat(nvsim): full simulator stack — Rust crate, dashboard, server, App Store, Ghost Murmur [ADR-089/090/091/092/093] 2026-04-27 12:41:01 -04:00
ADR-093-dashboard-gap-analysis.md feat(nvsim): full simulator stack — Rust crate, dashboard, server, App Store, Ghost Murmur [ADR-089/090/091/092/093] 2026-04-27 12:41:01 -04:00
ADR-094-pointcloud-github-pages-deployment.md feat(pointcloud): integrate ESP32 CSI as optional data stream from hosted viewer 2026-04-29 20:33:00 -04:00
ADR-095-rvcsi-edge-rf-sensing-platform.md fix(rvcsi): scale-relative baseline-drift thresholds + ESP32 end-to-end validation 2026-05-12 22:19:15 -04:00
ADR-096-rvcsi-ffi-crate-layout.md fix(rvcsi): scale-relative baseline-drift thresholds + ESP32 end-to-end validation 2026-05-12 22:19:15 -04:00
ADR-097-adopt-rvcsi-as-ruview-csi-runtime.md docs(adr): ADR-097 — adopt rvCSI as RuView's primary CSI runtime (Proposed) 2026-05-13 09:23:25 -04:00
ADR-098-evaluate-midstream-fit.md docs(adr): ADR-098 — evaluate midstream for RuView's CSI/WS/mesh pipeline (Rejected) (#553) 2026-05-17 17:49:21 -04:00
ADR-099-midstream-introspection-tap.md feat(introspection): I6 — regime-changed signal + per-frame analyze + honest ADR-099 D8 amendment 2026-05-13 23:29:37 -04:00
ADR-100-cog-packaging-specification.md feat(cog-pose-estimation): scaffold first Cog from this repo (ADR-100 + ADR-101) (#642) 2026-05-19 17:03:09 -04:00
ADR-101-pose-estimation-cog.md feat(cog-pose-estimation): scaffold first Cog from this repo (ADR-100 + ADR-101) (#642) 2026-05-19 17:03:09 -04:00
README.md docs(adr): ADR-098 — evaluate midstream for RuView's CSI/WS/mesh pipeline (Rejected) (#553) 2026-05-17 17:49:21 -04:00

README.md

Architecture Decision Records

This folder contains 44 Architecture Decision Records (ADRs) that document every significant technical choice in the RuView / WiFi-DensePose project.

Why ADRs?

Building a system that turns WiFi signals into human pose estimation involves hundreds of non-obvious decisions: which signal processing algorithms to use, how to bridge ESP32 firmware to a Rust pipeline, whether to run inference on-device or on a server, how to handle multi-person separation with limited subcarriers.

ADRs capture the context, options considered, decision made, and consequences for each of these choices. They serve three purposes:

  1. Institutional memory — Six months from now, anyone (human or AI) can read why we chose IIR bandpass filters over FIR for vital sign extraction, not just see the code.

  2. AI-assisted development — When an AI agent works on this codebase, ADRs give it the constraints and rationale it needs to make changes that align with the existing architecture. Without them, AI-generated code tends to drift — reinventing patterns that already exist, contradicting earlier decisions, or optimizing for the wrong tradeoffs.

  3. Review checkpoints — Each ADR is a reviewable artifact. When a proposed change touches the architecture, the ADR forces the author to articulate tradeoffs before writing code, not after.

ADRs and Domain-Driven Design

The project uses Domain-Driven Design (DDD) to organize code into bounded contexts — each with its own language, types, and responsibilities. ADRs and DDD work together:

  • ADRs define boundaries: ADR-029 (RuvSense) established multistatic sensing as a separate bounded context from single-node CSI. ADR-042 (CHCI) defined a new aggregate root for coherent channel imaging.
  • DDD models define the language: The RuvSense domain model defines terms like "coherence gate", "dwell time", and "TDM slot" that ADRs reference precisely.
  • Together they prevent drift: An AI agent reading ADR-039 knows that edge processing tiers are configured via NVS keys, not compile-time flags — because the ADR says so. The DDD model tells it which aggregate owns that configuration.

How ADRs are structured

Each ADR follows a consistent format:

  • Context — What problem or gap prompted this decision
  • Decision — What we chose to do and how
  • Consequences — What improved, what got harder, and what risks remain
  • References — Related ADRs, papers, and code paths

Statuses: Proposed (under discussion), Accepted (approved and/or implemented), Superseded (replaced by a later ADR).

ADR Index

Hardware and firmware

ADR Title Status
ADR-012 ESP32 CSI Sensor Mesh for Distributed Sensing Accepted (partial)
ADR-018 ESP32 Development Implementation Path Proposed
ADR-028 ESP32 Capability Audit and Witness Record Accepted
ADR-029 RuvSense Multistatic Sensing Mode (TDM, channel hopping) Proposed
ADR-032 Multistatic Mesh Security Hardening Accepted
ADR-039 ESP32-S3 Edge Intelligence Pipeline (on-device vitals) Accepted (hardware-validated)
ADR-040 WASM Programmable Sensing (Tier 3) Accepted
ADR-041 WASM Module Collection (65 edge modules) Accepted (hardware-validated)
ADR-044 Provisioning Tool Enhancements Proposed

Signal processing and sensing

ADR Title Status
ADR-013 Feature-Level Sensing on Commodity Gear Accepted
ADR-014 SOTA Signal Processing Algorithms Accepted
ADR-021 Vital Sign Detection (breathing, heart rate) Partial
ADR-030 Persistent Field Model and Drift Detection Proposed
ADR-033 CRV Signal Line Sensing Integration Proposed
ADR-037 Multi-Person Pose Detection from Single ESP32 Proposed
ADR-042 Coherent Human Channel Imaging (beyond CSI) Proposed

Machine learning and training

ADR Title Status
ADR-005 SONA Self-Learning for Pose Estimation Partial
ADR-006 GNN-Enhanced CSI Pattern Recognition Partial
ADR-015 Public Dataset Strategy (MM-Fi, Wi-Pose) Accepted
ADR-016 RuVector Training Pipeline Integration Accepted
ADR-017 RuVector Signal + MAT Integration Proposed
ADR-020 Migrate AI Inference to Rust (ONNX Runtime) Accepted
ADR-023 Trained DensePose Model with RuVector Pipeline Proposed
ADR-024 Project AETHER: Contrastive CSI Embeddings Required
ADR-027 Project MERIDIAN: Cross-Environment Generalization Proposed

Platform and UI

ADR Title Status
ADR-019 Sensing-Only UI with Gaussian Splats Accepted
ADR-022 Windows WiFi Enhanced Fidelity (multi-BSSID) Partial
ADR-025 macOS CoreWLAN WiFi Sensing Proposed
ADR-031 RuView Sensing-First RF Mode Proposed
ADR-034 Expo React Native Mobile App Accepted
ADR-035 Live Sensing UI Accuracy and Data Transparency Accepted
ADR-036 Training Pipeline UI Integration Proposed
ADR-043 Sensing Server UI API Completion (14 endpoints) Accepted

Architecture and infrastructure

ADR Title Status
ADR-001 WiFi-Mat Disaster Detection Architecture Accepted
ADR-002 RuVector RVF Integration Strategy Superseded
ADR-003 RVF Cognitive Containers for CSI Proposed
ADR-004 HNSW Vector Search for Fingerprinting Partial
ADR-007 Post-Quantum Cryptography for Sensing Proposed
ADR-008 Distributed Consensus for Multi-AP Proposed
ADR-009 RVF WASM Runtime for Edge Deployment Proposed
ADR-010 Witness Chains for Audit Trail Integrity Proposed
ADR-011 Proof-of-Reality and Mock Elimination Proposed
ADR-026 Survivor Track Lifecycle (MAT crate) Accepted
ADR-038 Sublinear GOAP for Roadmap Optimization Proposed
ADR-095 rvCSI — Edge RF Sensing Runtime Platform Proposed
ADR-096 rvCSI — Crate Topology, the napi-c Shim, and the napi-rs Node Surface Proposed
ADR-097 Adopt rvCSI as RuView's primary CSI runtime (phased adoption) Proposed
ADR-098 Evaluate ruvnet/midstream for RuView's CSI / WebSocket / mesh pipeline Rejected
ADR-099 Adopt midstream as RuView's real-time introspection + low-latency tap Proposed

Related

  • DDD Domain Models — Bounded context definitions, aggregate roots, and ubiquitous language
  • User Guide — Setup, API reference, and hardware instructions
  • Build Guide — Building from source