frank/ruvnet--RuView
1
0
Fork 0
mirror of https://github.com/ruvnet/RuView synced 2026-07-19 16:53:18 +00:00
Code Issues Packages Projects Releases Wiki Activity
Files
v1428
ruvnet--RuView/CLAUDE.md
T
rUv 9e7fa83210 feat(signal): ADR-134 CSI→CIR via ISTA + NeumannSolver warm-start (#837) 
* feat(signal): ADR-134 — CSI→CIR via ISTA + NeumannSolver warm-start

End-to-end first-class Channel Impulse Response estimation in the Rust
workspace. Bridges CSI (frequency domain) to CIR (delay domain) so
multistatic coherence gating, NLOS/LOS classification, and (at HT40+)
ToF ranging become tractable in `wifi-densepose-signal`.

Algorithm: ISTA L1 sparse recovery over a normalized DFT sub-matrix
sensing operator Φ ∈ ℂ^(K×G) with G = 3K (3× super-resolution). The
Tikhonov-regularised warm start re-uses `ruvector_solver::neumann::
NeumannSolver` — same call pattern as `fresnel.rs:280` and
`train/subcarrier.rs:225` — so no new crate dependencies.

Tiers supported: HT20 / HT40 / HE20 (Tier A-HE, C6) / HE40. The C6
HE-LTF tier is the preferred Tier A target whenever an 11ax AP is in
range; firmware substrate already shipped at v0.7.0-esp32 per ADR-110.

Measured performance (release, single CirEstimator shared across 12
links): HT20 2.72 ms / HE20 3.20 ms / HT40 13.43 ms / HE40 9.71 ms per
estimate(). HT20 12-link multistatic 17.7 ms — fits the 50 ms RuvSense
cycle; HT40 12-link 74 ms exceeds it and is flagged in ADR-134 §2.7 as
requiring Rayon parallelism or G=2K super-res reduction.

Measured Φ conditioning: κ(Φ) ≈ 1.00 identically across all tiers.
ADR-134 §2.3 was corrected — the C6 advantage is statistical SNR gain
(√(242/52) ≈ 2.16×) from more independent measurements, not improved
conditioning.

Witness: bit-deterministic SHA-256 over CirEstimator output on the
synthetic ADR-028 reference signal (100 frames, top-5 taps, 1e-6
quantization). Hash committed to expected_cir_features.sha256;
verify-cir-proof.sh wires the check into the existing witness bundle.

CI: cargo test --features cir + verify-cir-proof.sh added as separate
steps under the Rust Workspace Tests job; regressions are unambiguously
attributable.

Files:
- ADR + WITNESS-LOG-028 row 34 + CLAUDE.md module count (14 → 15)
- src/ruvsense/cir.rs (~540 LOC) + lib.rs re-exports + multistatic.rs
  wire-up (reversible via `use_cir_gate=false`)
- 3 integration tests + Criterion bench + 3 deterministic fixtures
- cir_proof_runner binary + sha256 + verify-cir-proof.sh

Test rate: 395 pass / 6 ignored (P2 ISTA hyperparameter tuning; see
#[ignore] reasons) / 0 fail. cargo check clean; verify-cir-proof.sh
VERDICT: PASS.

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

* fix(signal): make CIR witness cross-platform-deterministic

The first witness (Windows-generated hash 89704bfd…) failed on Linux CI
with a different hash (b36741bf…). Root cause: hashing `re`/`im` parts of
top-5 taps at 1e-6 precision is too tight against libm differences in
sin/cos/sqrt across glibc, MSVC, and Apple-clang. The previous
"top-5 sorted by magnitude" form also suffered from rank instability when
taps are near-tied — libm jitter could shuffle the ordering even when the
algorithm is unchanged.

New canonical form: full per-tap quantised-magnitude profile in natural
index order, no sort.

  - 156 taps × 2 bytes (u16 le) per frame = 312 bytes/frame.
  - Quantisation 1e-2 — robust to ~1e-3 float drift while still tripping
    on real algorithmic changes (e.g., a 10× lambda shift moves magnitudes
    by >1e-2).
  - No top-K selection — eliminates the unstable magnitude-sort step.

Regenerated expected_cir_features.sha256 — new hash 120bd7b1…

If the next CI run still mismatches, the cause is structural (rustfft SIMD
code path selection or NeumannSolver internal ordering), not magnitudes,
and the witness needs further coarsening or to be made platform-tagged.

Co-Authored-By: claude-flow <ruv@ruv.net>
2026-05-28 16:24:37 -04:00

18 KiB
Raw Permalink Blame History

Claude Code Configuration — WiFi-DensePose + Claude Flow V3

Project: wifi-densepose

WiFi-based human pose estimation using Channel State Information (CSI). Dual codebase: Python v1 (v1/) and Rust port (v2/).

Key Rust Crates

Crate Description
wifi-densepose-core Core types, traits, error types, CSI frame primitives
wifi-densepose-signal SOTA signal processing + RuvSense multistatic sensing (15 modules)
wifi-densepose-nn Neural network inference (ONNX, PyTorch, Candle backends)
wifi-densepose-train Training pipeline with ruvector integration + ruview_metrics
wifi-densepose-mat Mass Casualty Assessment Tool — disaster survivor detection
wifi-densepose-hardware ESP32 aggregator, TDM protocol, channel hopping firmware
wifi-densepose-ruvector RuVector v2.0.4 integration + cross-viewpoint fusion (5 modules)
wifi-densepose-wasm WebAssembly bindings for browser deployment
wifi-densepose-cli CLI tool (wifi-densepose binary)
wifi-densepose-sensing-server Lightweight Axum server for WiFi sensing UI
wifi-densepose-wifiscan Multi-BSSID WiFi scanning (ADR-022)
wifi-densepose-vitals ESP32 CSI-grade vital sign extraction (ADR-021)
nvsim Deterministic NV-diamond magnetometer pipeline simulator (ADR-089) — standalone leaf, WASM-ready
vendor/rvcsi (submodule) rvCSI — edge RF sensing runtime (ADR-095/096): 9 crates (rvcsi-core/-dsp/-events/-adapter-file/-adapter-nexmon/-ruvector/-runtime/-node/-cli). Lives in its own repo (github.com/ruvnet/rvcsi), vendored here under vendor/rvcsi, published to crates.io as rvcsi-* 0.3.x and to npm as @ruv/rvcsi. Not a v2/ workspace member — depend on the published crates (or the submodule's crates/rvcsi-* paths). Normalized CsiFrame/CsiWindow/CsiEvent schema, validate-before-FFI, reusable DSP, typed confidence-scored events, the napi-c Nexmon shim (real nexmon_csi .pcap from a Raspberry Pi 5 / 4 / 3B+ — BCM43455c0), the napi-rs SDK, the rvcsi CLI, a Claude Code plugin.

RuvSense Modules (signal/src/ruvsense/)

Module Purpose
multiband.rs Multi-band CSI frame fusion, cross-channel coherence
phase_align.rs Iterative LO phase offset estimation, circular mean
multistatic.rs Attention-weighted fusion, geometric diversity
coherence.rs Z-score coherence scoring, DriftProfile
coherence_gate.rs Accept/PredictOnly/Reject/Recalibrate gate decisions
pose_tracker.rs 17-keypoint Kalman tracker with AETHER re-ID embeddings
field_model.rs SVD room eigenstructure, perturbation extraction
tomography.rs RF tomography, ISTA L1 solver, voxel grid
longitudinal.rs Welford stats, biomechanics drift detection
intention.rs Pre-movement lead signals (200-500ms)
cross_room.rs Environment fingerprinting, transition graph
gesture.rs DTW template matching gesture classifier
adversarial.rs Physically impossible signal detection, multi-link consistency
cir.rs ADR-134 CSI→CIR via ISTA L1 sparse recovery (NeumannSolver warm-start)

Cross-Viewpoint Fusion (ruvector/src/viewpoint/)

Module Purpose
attention.rs CrossViewpointAttention, GeometricBias, softmax with G_bias
geometry.rs GeometricDiversityIndex, Cramer-Rao bounds, Fisher Information
coherence.rs Phase phasor coherence, hysteresis gate
fusion.rs MultistaticArray aggregate root, domain events

RuVector v2.0.4 Integration (ADR-016 complete, ADR-017 proposed)

All 5 ruvector crates integrated in workspace:

  • ruvector-mincut → metrics.rs (DynamicPersonMatcher) + subcarrier_selection.rs
  • ruvector-attn-mincut → model.rs (apply_antenna_attention) + spectrogram.rs
  • ruvector-temporal-tensor → dataset.rs (CompressedCsiBuffer) + breathing.rs
  • ruvector-solver → subcarrier.rs (sparse interpolation 114→56) + triangulation.rs
  • ruvector-attention → model.rs (apply_spatial_attention) + bvp.rs

Architecture Decisions

43 ADRs in docs/adr/ (ADR-001 through ADR-043). Key ones:

  • ADR-014: SOTA signal processing (Accepted)
  • ADR-015: MM-Fi + Wi-Pose training datasets (Accepted)
  • ADR-016: RuVector training pipeline integration (Accepted — complete)
  • ADR-017: RuVector signal + MAT integration (Proposed — next target)
  • ADR-024: Contrastive CSI embedding / AETHER (Accepted)
  • ADR-027: Cross-environment domain generalization / MERIDIAN (Accepted)
  • ADR-028: ESP32 capability audit + witness verification (Accepted)
  • ADR-029: RuvSense multistatic sensing mode (Proposed)
  • ADR-030: RuvSense persistent field model (Proposed)
  • ADR-031: RuView sensing-first RF mode (Proposed)
  • ADR-032: Multistatic mesh security hardening (Proposed)

Supported Hardware

Device Port Chip Role Cost
ESP32-S3 (8MB flash) COM9 (ruvzen, was COM7) Xtensa dual-core WiFi CSI sensing node ~$9
ESP32-S3 SuperMini (4MB) — Xtensa dual-core WiFi CSI (compact) ~$6
ESP32-C6 + Seeed MR60BHA2 COM12 (ruvzen, was COM4) RISC-V + 60 GHz FMCW mmWave HR/BR/presence + WiFi CSI ~$15
HLK-LD2410 — 24 GHz FMCW Presence + distance ~$3

Not supported: ESP32 (original), ESP32-C3 — single-core, can't run CSI DSP pipeline.

Build & Test Commands (this repo)

# Rust — full workspace tests (1,031+ tests, ~2 min)
cd v2
cargo test --workspace --no-default-features

# Rust — single crate check (no GPU needed)
cargo check -p wifi-densepose-train --no-default-features

# Python — deterministic proof verification (SHA-256)
python archive/v1/data/proof/verify.py

# Python — test suite
cd archive/v1 && python -m pytest tests/ -x -q

ESP32 Firmware Build (Windows — Python subprocess required)

# Build 8MB firmware (real WiFi CSI mode, no mocks)
# See CLAUDE.local.md for the full Python subprocess command
# Key: must strip MSYSTEM env vars for ESP-IDF v5.4 on Git Bash

# Build 4MB firmware
cp sdkconfig.defaults.4mb sdkconfig.defaults
# then same build process

# Flash to COM7
# [python, idf_py, '-p', 'COM7', 'flash']

# Provision WiFi
python firmware/esp32-csi-node/provision.py --port COM7 \
  --ssid "YourWiFi" --password "secret" --target-ip 192.168.1.20

# Monitor serial
python -m serial.tools.miniterm COM7 115200

Firmware Release Process

  1. Build 8MB from sdkconfig.defaults.template (no mock)
  2. Build 4MB from sdkconfig.defaults.4mb (no mock)
  3. Save 6 binaries: esp32-csi-node.bin, bootloader.bin, partition-table.bin, ota_data_initial.bin, esp32-csi-node-4mb.bin, partition-table-4mb.bin
  4. Tag: git tag v0.X.Y-esp32 && git push origin v0.X.Y-esp32
  5. Release: gh release create v0.X.Y-esp32 <binaries> --title "..." --notes-file ...
  6. Verify on real hardware (COM7) before publishing
  7. CRITICAL: Always test with real WiFi CSI, not mock mode — mock missed the Kconfig threshold bug

Crate Publishing Order

Crates must be published in dependency order:

  1. wifi-densepose-core (no internal deps)
  2. wifi-densepose-vitals (no internal deps)
  3. wifi-densepose-wifiscan (no internal deps)
  4. wifi-densepose-hardware (no internal deps)
  5. wifi-densepose-signal (depends on core)
  6. wifi-densepose-nn (no internal deps, workspace only)
  7. wifi-densepose-ruvector (no internal deps, workspace only)
  8. wifi-densepose-train (depends on signal, nn)
  9. wifi-densepose-mat (depends on core, signal, nn)
  10. wifi-densepose-wasm (depends on mat)
  11. wifi-densepose-sensing-server (depends on wifiscan)
  12. wifi-densepose-cli (depends on mat)

Validation & Witness Verification (ADR-028)

After any significant code change, run the full validation:

# 1. Rust tests — must be 1,031+ passed, 0 failed
cd v2
cargo test --workspace --no-default-features

# 2. Python proof — must print VERDICT: PASS
cd ..
python archive/v1/data/proof/verify.py

# 3. Generate witness bundle (includes both above + firmware hashes)
bash scripts/generate-witness-bundle.sh

# 4. Self-verify the bundle — must be 7/7 PASS
cd dist/witness-bundle-ADR028-*/
bash VERIFY.sh

If the Python proof hash changes (e.g., numpy/scipy version update):

# Regenerate the expected hash, then verify it passes
python archive/v1/data/proof/verify.py --generate-hash
python archive/v1/data/proof/verify.py

Witness bundle contents (dist/witness-bundle-ADR028-<sha>.tar.gz):

  • WITNESS-LOG-028.md — 33-row attestation matrix with evidence per capability
  • ADR-028-esp32-capability-audit.md — Full audit findings
  • proof/verify.py + expected_features.sha256 — Deterministic pipeline proof
  • test-results/rust-workspace-tests.log — Full cargo test output
  • firmware-manifest/source-hashes.txt — SHA-256 of all 7 ESP32 firmware files
  • crate-manifest/versions.txt — All 15 crates with versions
  • VERIFY.sh — One-command self-verification for recipients

Key proof artifacts:

  • archive/v1/data/proof/verify.py — Trust Kill Switch: feeds reference signal through production pipeline, hashes output
  • archive/v1/data/proof/expected_features.sha256 — Published expected hash
  • archive/v1/data/proof/sample_csi_data.json — 1,000 synthetic CSI frames (seed=42)
  • docs/WITNESS-LOG-028.md — 11-step reproducible verification procedure
  • docs/adr/ADR-028-esp32-capability-audit.md — Complete audit record

Branch

Default branch: main Active feature branch: ruvsense-full-implementation (PR #77)

Behavioral Rules (Always Enforced)

  • Do what has been asked; nothing more, nothing less
  • NEVER create files unless they're absolutely necessary for achieving your goal
  • ALWAYS prefer editing an existing file to creating a new one
  • NEVER proactively create documentation files (*.md) or README files unless explicitly requested
  • NEVER save working files, text/mds, or tests to the root folder
  • Never continuously check status after spawning a swarm — wait for results
  • ALWAYS read a file before editing it
  • NEVER commit secrets, credentials, or .env files

File Organization

  • NEVER save to root folder — use the directories below
  • docs/adr/ — Architecture Decision Records (43 ADRs)
  • docs/ddd/ — Domain-Driven Design models
  • v2/crates/ — Rust workspace crates (15 crates)
  • v2/crates/wifi-densepose-signal/src/ruvsense/ — RuvSense multistatic modules (14 files)
  • v2/crates/wifi-densepose-ruvector/src/viewpoint/ — Cross-viewpoint fusion (5 files)
  • v2/crates/wifi-densepose-hardware/src/esp32/ — ESP32 TDM protocol
  • firmware/esp32-csi-node/main/ — ESP32 C firmware (channel hopping, NVS config, TDM)
  • archive/v1/src/ — Python source (core, hardware, services, api)
  • archive/v1/data/proof/ — Deterministic CSI proof bundles
  • .claude-flow/ — Claude Flow coordination state (committed for team sharing)
  • .claude/ — Claude Code settings, agents, memory (committed for team sharing)

Project Architecture

  • Follow Domain-Driven Design with bounded contexts
  • Keep files under 500 lines
  • Use typed interfaces for all public APIs
  • Prefer TDD London School (mock-first) for new code
  • Use event sourcing for state changes
  • Ensure input validation at system boundaries

Project Config

  • Topology: hierarchical-mesh
  • Max Agents: 15
  • Memory: hybrid
  • HNSW: Enabled
  • Neural: Enabled

Pre-Merge Checklist

Before merging any PR, verify each item applies and is addressed:

  1. Rust tests pass — cargo test --workspace --no-default-features (1,031+ passed, 0 failed)
  2. Python proof passes — python archive/v1/data/proof/verify.py (VERDICT: PASS)
  3. README.md — Update platform tables, crate descriptions, hardware tables, feature summaries if scope changed
  4. CLAUDE.md — Update crate table, ADR list, module tables, version if scope changed
  5. CHANGELOG.md — Add entry under [Unreleased] with what was added/fixed/changed
  6. User guide (docs/user-guide.md) — Update if new data sources, CLI flags, or setup steps were added
  7. ADR index — Update ADR count in README docs table if a new ADR was created
  8. Witness bundle — Regenerate if tests or proof hash changed: bash scripts/generate-witness-bundle.sh
  9. Docker Hub image — Only rebuild if Dockerfile, dependencies, or runtime behavior changed
  10. Crate publishing — Only needed if a crate is published to crates.io and its public API changed
  11. .gitignore — Add any new build artifacts or binaries
  12. Security audit — Run security review for new modules touching hardware/network boundaries

Build & Test

# Build
npm run build

# Test
npm test

# Lint
npm run lint
  • ALWAYS run tests after making code changes
  • ALWAYS verify build succeeds before committing

Security Rules

  • NEVER hardcode API keys, secrets, or credentials in source files
  • NEVER commit .env files or any file containing secrets
  • Always validate user input at system boundaries
  • Always sanitize file paths to prevent directory traversal
  • Run npx @claude-flow/cli@latest security scan after security-related changes

Concurrency: 1 MESSAGE = ALL RELATED OPERATIONS

  • All operations MUST be concurrent/parallel in a single message
  • Use Claude Code's Task tool for spawning agents, not just MCP
  • ALWAYS batch ALL todos in ONE TodoWrite call (5-10+ minimum)
  • ALWAYS spawn ALL agents in ONE message with full instructions via Task tool
  • ALWAYS batch ALL file reads/writes/edits in ONE message
  • ALWAYS batch ALL Bash commands in ONE message

Swarm Orchestration

  • MUST initialize the swarm using CLI tools when starting complex tasks
  • MUST spawn concurrent agents using Claude Code's Task tool
  • Never use CLI tools alone for execution — Task tool agents do the actual work
  • MUST call CLI tools AND Task tool in ONE message for complex work

3-Tier Model Routing (ADR-026)

Tier Handler Latency Cost Use Cases
1 Agent Booster (WASM) <1ms $0 Simple transforms (var→const, add types) — Skip LLM
2 Haiku ~500ms $0.0002 Simple tasks, low complexity (<30%)
3 Sonnet/Opus 2-5s $0.003-0.015 Complex reasoning, architecture, security (>30%)
  • Always check for [AGENT_BOOSTER_AVAILABLE] or [TASK_MODEL_RECOMMENDATION] before spawning agents
  • Use Edit tool directly when [AGENT_BOOSTER_AVAILABLE]

Swarm Configuration & Anti-Drift

  • ALWAYS use hierarchical topology for coding swarms
  • Keep maxAgents at 6-8 for tight coordination
  • Use specialized strategy for clear role boundaries
  • Use raft consensus for hive-mind (leader maintains authoritative state)
  • Run frequent checkpoints via post-task hooks
  • Keep shared memory namespace for all agents
npx @claude-flow/cli@latest swarm init --topology hierarchical --max-agents 8 --strategy specialized

Swarm Execution Rules

  • ALWAYS use run_in_background: true for all agent Task calls
  • ALWAYS put ALL agent Task calls in ONE message for parallel execution
  • After spawning, STOP — do NOT add more tool calls or check status
  • Never poll TaskOutput or check swarm status — trust agents to return
  • When agent results arrive, review ALL results before proceeding

V3 CLI Commands

Core Commands

Command Subcommands Description
init 4 Project initialization
agent 8 Agent lifecycle management
swarm 6 Multi-agent swarm coordination
memory 11 AgentDB memory with HNSW search
task 6 Task creation and lifecycle
session 7 Session state management
hooks 17 Self-learning hooks + 12 workers
hive-mind 6 Byzantine fault-tolerant consensus

Quick CLI Examples

npx @claude-flow/cli@latest init --wizard
npx @claude-flow/cli@latest agent spawn -t coder --name my-coder
npx @claude-flow/cli@latest swarm init --v3-mode
npx @claude-flow/cli@latest memory search --query "authentication patterns"
npx @claude-flow/cli@latest doctor --fix

Available Agents (60+ Types)

Core Development

coder, reviewer, tester, planner, researcher

Specialized

security-architect, security-auditor, memory-specialist, performance-engineer

Swarm Coordination

hierarchical-coordinator, mesh-coordinator, adaptive-coordinator

GitHub & Repository

pr-manager, code-review-swarm, issue-tracker, release-manager

SPARC Methodology

sparc-coord, sparc-coder, specification, pseudocode, architecture

Memory Commands Reference

# Store (REQUIRED: --key, --value; OPTIONAL: --namespace, --ttl, --tags)
npx @claude-flow/cli@latest memory store --key "pattern-auth" --value "JWT with refresh" --namespace patterns

# Search (REQUIRED: --query; OPTIONAL: --namespace, --limit, --threshold)
npx @claude-flow/cli@latest memory search --query "authentication patterns"

# List (OPTIONAL: --namespace, --limit)
npx @claude-flow/cli@latest memory list --namespace patterns --limit 10

# Retrieve (REQUIRED: --key; OPTIONAL: --namespace)
npx @claude-flow/cli@latest memory retrieve --key "pattern-auth" --namespace patterns

Quick Setup

claude mcp add claude-flow -- npx -y @claude-flow/cli@latest
npx @claude-flow/cli@latest daemon start
npx @claude-flow/cli@latest doctor --fix

Claude Code vs CLI Tools

  • Claude Code's Task tool handles ALL execution: agents, file ops, code generation, git
  • CLI tools handle coordination via Bash: swarm init, memory, hooks, routing
  • NEVER use CLI tools as a substitute for Task tool agents

Support

Reference in New Issue View Git Blame Copy Permalink