mirror of
https://github.com/ruvnet/RuView
synced 2026-06-09 10:13:17 +00:00
Compare commits
1 Commits
| Author | SHA1 | Date | |
|---|---|---|---|
 ruv
|
5518d5d7c1 |
@@ -1,55 +1,50 @@
|
||||
{
|
||||
"running": true,
|
||||
"startedAt": "2026-05-24T22:26:25.030Z",
|
||||
"startedAt": "2026-03-09T15:26:00.921Z",
|
||||
"workers": {
|
||||
"map": {
|
||||
"runCount": 64,
|
||||
"successCount": 64,
|
||||
"runCount": 49,
|
||||
"successCount": 49,
|
||||
"failureCount": 0,
|
||||
"averageDurationMs": 136.171875,
|
||||
"lastRun": "2026-05-25T06:07:33.387Z",
|
||||
"lastStartedAt": "2026-05-25T06:07:33.381Z",
|
||||
"nextRun": "2026-05-25T06:26:25.410Z",
|
||||
"averageDurationMs": 1.2857142857142858,
|
||||
"lastRun": "2026-02-28T16:13:19.194Z",
|
||||
"nextRun": "2026-03-09T15:56:00.928Z",
|
||||
"isRunning": false
|
||||
},
|
||||
"audit": {
|
||||
"runCount": 72,
|
||||
"successCount": 27,
|
||||
"runCount": 45,
|
||||
"successCount": 0,
|
||||
"failureCount": 45,
|
||||
"averageDurationMs": 26260.11111111111,
|
||||
"lastRun": "2026-05-25T06:08:29.594Z",
|
||||
"lastStartedAt": "2026-05-25T06:07:33.416Z",
|
||||
"nextRun": "2026-05-25T06:18:32.928Z",
|
||||
"averageDurationMs": 0,
|
||||
"lastRun": "2026-03-09T15:43:00.933Z",
|
||||
"nextRun": "2026-03-09T15:38:00.914Z",
|
||||
"isRunning": false
|
||||
},
|
||||
"optimize": {
|
||||
"runCount": 54,
|
||||
"successCount": 9,
|
||||
"failureCount": 45,
|
||||
"averageDurationMs": 40303.377578766485,
|
||||
"lastRun": "2026-05-25T05:59:05.330Z",
|
||||
"lastStartedAt": "2026-05-25T05:54:05.318Z",
|
||||
"nextRun": "2026-05-25T06:20:15.145Z",
|
||||
"runCount": 34,
|
||||
"successCount": 0,
|
||||
"failureCount": 34,
|
||||
"averageDurationMs": 0,
|
||||
"lastRun": "2026-02-28T16:23:19.387Z",
|
||||
"nextRun": "2026-03-09T15:45:00.915Z",
|
||||
"isRunning": false
|
||||
},
|
||||
"consolidate": {
|
||||
"runCount": 32,
|
||||
"successCount": 32,
|
||||
"runCount": 23,
|
||||
"successCount": 23,
|
||||
"failureCount": 0,
|
||||
"averageDurationMs": 4.71875,
|
||||
"lastRun": "2026-05-25T05:38:20.449Z",
|
||||
"lastStartedAt": "2026-05-25T05:38:20.443Z",
|
||||
"nextRun": "2026-05-25T06:32:25.248Z",
|
||||
"averageDurationMs": 0.6521739130434783,
|
||||
"lastRun": "2026-02-28T16:05:19.091Z",
|
||||
"nextRun": "2026-03-09T16:02:00.918Z",
|
||||
"isRunning": false
|
||||
},
|
||||
"testgaps": {
|
||||
"runCount": 100,
|
||||
"successCount": 63,
|
||||
"failureCount": 37,
|
||||
"averageDurationMs": 108604.0537328991,
|
||||
"lastRun": "2026-05-25T06:11:52.529Z",
|
||||
"lastStartedAt": "2026-05-25T06:07:33.390Z",
|
||||
"nextRun": "2026-05-25T06:14:25.296Z",
|
||||
"runCount": 27,
|
||||
"successCount": 0,
|
||||
"failureCount": 27,
|
||||
"averageDurationMs": 0,
|
||||
"lastRun": "2026-02-28T16:08:19.369Z",
|
||||
"nextRun": "2026-03-09T15:54:00.920Z",
|
||||
"isRunning": false
|
||||
},
|
||||
"predict": {
|
||||
@@ -69,8 +64,8 @@
|
||||
},
|
||||
"config": {
|
||||
"autoStart": false,
|
||||
"logDir": "C:\\Users\\ruv\\Projects\\wifi-densepose\\.claude-flow\\logs",
|
||||
"stateFile": "C:\\Users\\ruv\\Projects\\wifi-densepose\\.claude-flow\\daemon-state.json",
|
||||
"logDir": "/Users/cohen/GitHub/ruvnet/RuView/.claude-flow/logs",
|
||||
"stateFile": "/Users/cohen/GitHub/ruvnet/RuView/.claude-flow/daemon-state.json",
|
||||
"maxConcurrent": 2,
|
||||
"workerTimeoutMs": 300000,
|
||||
"resourceThresholds": {
|
||||
@@ -136,5 +131,5 @@
|
||||
}
|
||||
]
|
||||
},
|
||||
"savedAt": "2026-05-25T06:11:52.530Z"
|
||||
"savedAt": "2026-03-09T15:43:00.933Z"
|
||||
}
|
||||
@@ -1,119 +0,0 @@
|
||||
{
|
||||
"id": "aether-arena-aa",
|
||||
"name": "AetherArena (AA) — Official Spatial-Intelligence Benchmark",
|
||||
"adr": "ADR-149",
|
||||
"adrPath": "docs/adr/ADR-149-public-community-leaderboard-huggingface.md",
|
||||
"status": "Accepted",
|
||||
"initializedDate": "2026-05-30",
|
||||
"targetDate": "2026-08-31",
|
||||
"exitCriteria": "Benchmark INFRASTRUCTURE done, tested, CI-gated, deploy-ready: aa_score_runner.rs passes deterministic fixture test; CI harness-gate green on every PR; aether-arena repo scaffold committed (README four-part framing + aa-submission.toml schema + VERIFY.md); public smoke split committed; HF Space lifecycle skeleton deployed; signed Parquet ledger functional; RuView baseline PCK@20 ~2.5% entered; ADR-149 §7 acceptance test (five-step stranger test) passes. NOTE: ML SOTA (MM-Fi PCK@20 ~72%) is a separate long-running stretch goal blocked on ADR-079 camera-ground-truth — it is NOT an infra exit criterion.",
|
||||
"baselineState": {
|
||||
"adrStatus": "Accepted, committed 2026-05-30",
|
||||
"scorerCode": "ruview_metrics.rs + ablation.rs + proof.rs exist in wifi-densepose-train; aa_score_runner.rs not yet created",
|
||||
"aetherArenaRepo": "does not exist yet — needs user authorization to create ruvnet/aether-arena public repo",
|
||||
"hfSpace": "does not exist yet — needs HF_TOKEN and user authorization to deploy ruvnet/aether-arena HF Space",
|
||||
"smokeDataset": "not committed",
|
||||
"resultsLedger": "not created",
|
||||
"ruviewBaseline": "PCK@20 ~2.5% self-reported, not formally entered",
|
||||
"ciGate": "not added to workflow"
|
||||
},
|
||||
"milestones": {
|
||||
"m1": {
|
||||
"name": "ADR-149 Accepted + committed",
|
||||
"status": "DONE",
|
||||
"completedDate": "2026-05-30",
|
||||
"completionCriteria": "ADR-149 file committed to docs/adr/ with status Accepted",
|
||||
"notes": "Done this session. File at docs/adr/ADR-149-public-community-leaderboard-huggingface.md"
|
||||
},
|
||||
"m2": {
|
||||
"name": "Deterministic scorer runner bin (aa_score_runner.rs)",
|
||||
"status": "NOT_STARTED",
|
||||
"completionCriteria": "aa_score_runner.rs compiles, runs ruview_metrics on a committed fixture, emits RuViewTier + SHA-256 proof hash, mirrors existing *_proof_runner.rs pattern; cargo test passes",
|
||||
"estimatedEffort": "3-5 days",
|
||||
"owner": "wifi-densepose-train crate or new aa-scorer crate"
|
||||
},
|
||||
"m3": {
|
||||
"name": "CI harness-gate: GitHub Actions workflow",
|
||||
"status": "NOT_STARTED",
|
||||
"completionCriteria": "A GitHub Actions workflow runs aa_score_runner on every PR as a build gate; PR fails if scorer fails determinism check; workflow committed and green",
|
||||
"estimatedEffort": "2-3 days",
|
||||
"dependency": "M2 must be done first"
|
||||
},
|
||||
"m4": {
|
||||
"name": "aether-arena repo scaffold",
|
||||
"status": "NOT_STARTED",
|
||||
"completionCriteria": "ruvnet/aether-arena repo created with: README (four-part framing: Public leaderboard / Private eval split / Open scorer / Signed results); aa-submission.toml manifest schema; VERIFY.md (ADR-149 §7 stranger acceptance test); neutrality/governance section (§2.8); contribution guide",
|
||||
"estimatedEffort": "3-5 days",
|
||||
"blockers": ["Needs user authorization to create public ruvnet/aether-arena repo on GitHub"]
|
||||
},
|
||||
"m5": {
|
||||
"name": "Public smoke split committed + private MM-Fi held-out split prep",
|
||||
"status": "NOT_STARTED",
|
||||
"completionCriteria": "Public smoke split committed to aether-arena repo (stranger can score locally); private MM-Fi held-out split prepared under non-public path with CC BY-NC 4.0 attribution; Wi-Pose explicitly excluded from v0",
|
||||
"estimatedEffort": "5-7 days",
|
||||
"riskNotes": "MM-Fi CC BY-NC 4.0: AA must remain non-commercial and carry MM-Fi attribution; raw frames stay in private split; only derived CSI features + scores may be exposed"
|
||||
},
|
||||
"m6": {
|
||||
"name": "HF Space (Gradio) skeleton",
|
||||
"status": "BLOCKED",
|
||||
"completionCriteria": "HF Space deployed at ruvnet/aether-arena with submission lifecycle (submitted->validated->quarantined->smoke_scored->full_scored->published/rejected); sandboxed scorer container wired; basic leaderboard table rendered",
|
||||
"estimatedEffort": "7-10 days",
|
||||
"blockers": [
|
||||
"Needs HF_TOKEN — check .env for HF_TOKEN or HUGGINGFACE_TOKEN",
|
||||
"Needs user authorization to create/deploy ruvnet/aether-arena HF Space (outward-facing public deployment)"
|
||||
]
|
||||
},
|
||||
"m7": {
|
||||
"name": "Signed append-only Parquet results ledger",
|
||||
"status": "NOT_STARTED",
|
||||
"completionCriteria": "HF dataset ruvnet/aether-arena-results created; append-only Parquet ledger with signed rows; determinism_gate enforced; no row can be silently edited",
|
||||
"estimatedEffort": "3-5 days",
|
||||
"ledgerSchema": "submitter, model_ref, category, feature_set, tier, pck20, oks, mota, vitals_bpm_err, latency_p50, latency_p95, privacy_leakage, cross_room_deg, proof_sha256, scored_at, harness_version",
|
||||
"dependency": "M6 must be scaffolded first"
|
||||
},
|
||||
"m8": {
|
||||
"name": "RuView baseline entry + public launch",
|
||||
"status": "NOT_STARTED",
|
||||
"completionCriteria": "RuView wifi-densepose-pretrained baseline entered (honest PCK@20 ~2.5%); ADR-149 §7 five-step stranger acceptance test passes; v0 live with Presence + Pose + Edge-latency + Determinism categories active; Privacy and Cross-room shown as gated/coming-soon",
|
||||
"estimatedEffort": "3-5 days",
|
||||
"dependency": "M4+M5+M6+M7 complete",
|
||||
"notes": "ML SOTA improvement (PCK@20 ~72%) is a SEPARATE stretch goal blocked on ADR-079 P7-P9 camera ground truth. NOT a blocker for infra launch."
|
||||
}
|
||||
},
|
||||
"activeMilestone": "m2",
|
||||
"completedMilestones": ["m1"],
|
||||
"knownRisks": [
|
||||
"HF_TOKEN not confirmed present in .env — check before M6 work begins",
|
||||
"ruvnet/aether-arena public repo creation is outward-facing — needs explicit user authorization",
|
||||
"MM-Fi CC BY-NC 4.0: AA must stay legally non-commercial and brand-distinct from commercial RuView product; or seek MM-Fi commercial grant before any paid tier",
|
||||
"Wi-Pose has research-use-only terms (no redistribution grant) — excluded from v0; revisit only if terms are clarified with authors",
|
||||
"HF Space free CPU tier may be too slow for Candle/tch inference pipeline — may need ZeroGPU or self-hosted scorer on cognitum-20260110 GCloud A100/L4",
|
||||
"ADR-079 camera-ground-truth (PCK@20 SOTA) is P7-P9 pending — NOT an infra blocker; must not be conflated with AA infra completion",
|
||||
"Neutrality/governance risk: RuView seeded the scorer — must be demonstrably scored through the same public pipeline as any other entrant (§2.8 controls)"
|
||||
],
|
||||
"driftSignals": {
|
||||
"timeline": "GREEN — just initialized, no timeline pressure yet",
|
||||
"scope": "GREEN — scope locked at four-part structure per ADR-149 §2 decision",
|
||||
"approach": "GREEN — reuse pattern (existing ruview_metrics + proof.rs) confirmed in ADR-149",
|
||||
"dependency": "YELLOW — HF_TOKEN and ruvnet/aether-arena repo authorization are external blockers with unknown ETA",
|
||||
"priority": "GREEN — active feature branch feat/adr-136-146-streaming-engine in progress; AA infra can proceed in parallel on its own branch"
|
||||
},
|
||||
"stretchGoals": {
|
||||
"sotaML": "MM-Fi PCK@20 SOTA ~72% — separate ML effort blocked on ADR-079 P7-P9 camera-ground-truth data collection; NOT an infra exit criterion",
|
||||
"privacyAxis": "ADR-145 §10 membership-inference attacker — activate Privacy leaderboard axis once attacker is implemented and published",
|
||||
"crossRoom": "Multi-room held-out split — activate Cross-room generalization axis",
|
||||
"multiOrgSteering": "Invite co-maintainers from other projects once >=N external entries land"
|
||||
},
|
||||
"sessionHistory": [
|
||||
{
|
||||
"date": "2026-05-30",
|
||||
"type": "initialization",
|
||||
"accomplished": [
|
||||
"ADR-149 Accepted and committed to docs/adr/",
|
||||
"Horizon record initialized in .claude-flow/horizons/aether-arena-aa.json",
|
||||
"Memory stored in horizons namespace under key horizon-aether-arena-aa",
|
||||
"Session check-in record stored in horizon-sessions namespace"
|
||||
]
|
||||
}
|
||||
]
|
||||
}
|
||||
@@ -1,11 +1,11 @@
|
||||
{
|
||||
"timestamp": "2026-05-25T06:07:33.385Z",
|
||||
"projectRoot": "C:\\Users\\ruv\\Projects\\wifi-densepose",
|
||||
"timestamp": "2026-02-28T16:13:19.193Z",
|
||||
"projectRoot": "/home/user/wifi-densepose",
|
||||
"structure": {
|
||||
"hasPackageJson": false,
|
||||
"hasTsConfig": false,
|
||||
"hasClaudeConfig": true,
|
||||
"hasClaudeFlow": true
|
||||
},
|
||||
"scannedAt": 1779689253386
|
||||
"scannedAt": 1772295199193
|
||||
}
|
||||
@@ -1,5 +1,5 @@
|
||||
{
|
||||
"timestamp": "2026-05-25T05:38:20.448Z",
|
||||
"timestamp": "2026-02-28T16:05:19.091Z",
|
||||
"patternsConsolidated": 0,
|
||||
"memoryCleaned": 0,
|
||||
"duplicatesRemoved": 0
|
||||
|
||||
@@ -1,17 +0,0 @@
|
||||
{
|
||||
"timestamp": "2026-05-25T05:59:05.405Z",
|
||||
"mode": "local",
|
||||
"memoryUsage": {
|
||||
"rss": 9891840,
|
||||
"heapTotal": 35598336,
|
||||
"heapUsed": 26516560,
|
||||
"external": 3952418,
|
||||
"arrayBuffers": 55689
|
||||
},
|
||||
"uptime": 27163.5846658,
|
||||
"optimizations": {
|
||||
"cacheHitRate": 0.78,
|
||||
"avgResponseTime": 45
|
||||
},
|
||||
"note": "Install Claude Code CLI for AI-powered optimization suggestions"
|
||||
}
|
||||
@@ -1,84 +1,12 @@
|
||||
{
|
||||
"timestamp": "2026-05-25T06:08:29.589Z",
|
||||
"mode": "headless",
|
||||
"workerType": "audit",
|
||||
"model": "haiku",
|
||||
"durationMs": 56168,
|
||||
"executionId": "audit_1779689253421_dfflmb",
|
||||
"success": true,
|
||||
"findings": {
|
||||
"vulnerabilities": [
|
||||
{
|
||||
"severity": "high",
|
||||
"file": ".claude/helpers/github-safe.js",
|
||||
"line": 50,
|
||||
"description": "Command injection vulnerability in execSync call. User-controlled arguments in `newArgs` are joined without shell escaping. An attacker can inject shell metacharacters (e.g., `; rm -rf /`) via the body content or through command/subcommand parameters. The temp file approach is safe, but the command construction `gh ${command} ${subcommand} ${newArgs.join(' ')}` allows shell injection.",
|
||||
"example": "gh issue comment 123 'test`whoami`' would execute whoami"
|
||||
},
|
||||
{
|
||||
"severity": "high",
|
||||
"file": "scripts/csi-spectrogram.js",
|
||||
"line": 45,
|
||||
"description": "Sensitive credential exposure via command-line arguments. The `--seed-token` parameter is passed as a CLI argument, which is visible in process listings (ps aux output). This violates secure credential handling practices. Tokens should be read from environment variables or secure config files, not command-line args.",
|
||||
"example": "node scripts/csi-spectrogram.js --seed-token secret_abc_123 exposes token in process list"
|
||||
},
|
||||
{
|
||||
"severity": "medium",
|
||||
"file": "scripts/apnea-detector.js",
|
||||
"line": 71,
|
||||
"description": "Unsafe buffer reading without comprehensive length validation. The code checks `buf.length` at 32 bytes (line 70) but then reads at fixed offsets (lines 72-76) without validating that each read stays within bounds. If a malformed packet is received, `readInt8/readUInt16LE/readUInt32LE` may read unintended data or zeros.",
|
||||
"example": "A 33-byte buffer would pass the check but reading UInt32LE at offset 8 would go out of bounds"
|
||||
},
|
||||
{
|
||||
"severity": "medium",
|
||||
"file": "scripts/benchmark-rf-scan.js",
|
||||
"line": 110,
|
||||
"description": "Potential out-of-bounds buffer access in parseCSIFrame. While the bounds check at line 107 is present, the `nSubcarriers` value from the packet is used to calculate required buffer size without validation of the value itself. A maliciously crafted packet with extremely large nSubcarriers could cause memory issues.",
|
||||
"example": "Packet with nSubcarriers=999999 would request excessive buffer allocation"
|
||||
},
|
||||
{
|
||||
"severity": "medium",
|
||||
"file": "scripts/csi-spectrogram.js",
|
||||
"line": 39,
|
||||
"description": "Unsafe URL construction with untrusted `seed-url` parameter. The `--seed-url` argument is used directly for HTTPS requests without validation. This could allow SSRF (Server-Side Request Forgery) or DNS rebinding attacks if an attacker controls the seed URL.",
|
||||
"example": "node scripts/csi-spectrogram.js --seed-url http://internal.local:9000 could access internal services"
|
||||
},
|
||||
{
|
||||
"severity": "low",
|
||||
"file": ".claude/helpers/statusline.js",
|
||||
"line": 140,
|
||||
"description": "Shell command injection risk in execSync calls. Commands like `ps aux 2>/dev/null | grep -c agentic-flow` use grep patterns that could be vulnerable if any variables are interpolated (though currently hardcoded). The `execSync` with shell=true is generally risky.",
|
||||
"example": "If any pattern becomes user-controlled: `grep -c ${pattern}` could inject shell metacharacters"
|
||||
},
|
||||
{
|
||||
"severity": "low",
|
||||
"file": ".claude/helpers/memory.js",
|
||||
"line": 10,
|
||||
"description": "Unvalidated JSON parsing. The code parses JSON from MEMORY_FILE without try-catch in the loadMemory function (catches error but doesn't validate structure). Malformed JSON or corrupted memory file could cause issues.",
|
||||
"example": "Memory file with circular JSON structure could cause issues when stringifying"
|
||||
},
|
||||
{
|
||||
"severity": "low",
|
||||
"file": "scripts/device-fingerprint.js",
|
||||
"line": 72,
|
||||
"description": "Hardcoded device fingerprints and network configuration. While not a traditional 'hardcoded secret', the KNOWN_DEVICES array contains identifiable SSIDs and MAC addresses that could be used to correlate network infrastructure. This data should be externalized or sanitized.",
|
||||
"example": "SSID 'ruv.net' and 'Cohen-Guest' could identify specific installations"
|
||||
}
|
||||
],
|
||||
"riskScore": 42,
|
||||
"recommendations": [
|
||||
"**CRITICAL**: Replace `execSync` command construction in github-safe.js with proper shell escaping using `child_process.execFile()` instead of `execSync()`, or use the `shell: false` option with array arguments to avoid shell parsing entirely.",
|
||||
"**CRITICAL**: Move `--seed-token` from CLI arguments to environment variable `SEED_TOKEN` in csi-spectrogram.js. Update documentation to instruct users: `export SEED_TOKEN=...` instead of passing via CLI.",
|
||||
"**HIGH**: Add comprehensive buffer bounds validation in all UDP packet parsing functions (apnea-detector.js, benchmark-rf-scan.js, etc.). Validate both the buffer length AND the parsed header values before using them in calculations.",
|
||||
"**HIGH**: Validate and sanitize the `--seed-url` parameter in csi-spectrogram.js. Whitelist allowed domains or restrict to localhost/internal IPs only. Add URL scheme validation (https only).",
|
||||
"**MEDIUM**: Replace hardcoded device fingerprints (KNOWN_DEVICES) with externalized configuration or environment variables. Document that this data contains identifiable network information.",
|
||||
"**MEDIUM**: Add input validation to `parseArgs()` results in all scripts. Validate numeric ranges, file paths, and enum values before use.",
|
||||
"**LOW**: Wrap JSON.parse() calls in try-catch blocks throughout (memory.js, session.js) with explicit error handling and recovery.",
|
||||
"**LOW**: Audit all uses of `require()` with dynamic paths. Ensure paths are always derived from fixed `__dirname` and not user-controlled.",
|
||||
"**LOW**: Remove or sandbox the ability to pass arbitrary URLs via CLI. Consider using a configuration file (YAML/JSON) for endpoint URLs instead.",
|
||||
"**INFO**: Add a pre-commit hook to detect hardcoded credentials using tools like `detect-secrets` or `truffleHog`."
|
||||
]
|
||||
"timestamp": "2026-03-06T13:17:27.368Z",
|
||||
"mode": "local",
|
||||
"checks": {
|
||||
"envFilesProtected": true,
|
||||
"gitIgnoreExists": true,
|
||||
"noHardcodedSecrets": true
|
||||
},
|
||||
"rawOutputPreview": "# Security Audit Report — wifi-densepose\n\n```json\n{\n \"vulnerabilities\": [\n {\n \"severity\": \"high\",\n \"file\": \".claude/helpers/github-safe.js\",\n \"line\": 50,\n \"description\": \"Command injection vulnerability in execSync call. User-controlled arguments in `newArgs` are joined without shell escaping. An attacker can inject shell metacharacters (e.g., `; rm -rf /`) via the body content or through command/subcommand parameters. The temp file approach is safe, but the command construction `gh ${command} ${subcommand} ${newArgs.join(' ')}` allows shell injection.\",\n \"example\": \"gh issue comment 123 'test`whoami`' would execute whoami\"\n },\n {\n \"severity\": \"high\",\n \"file\": \"scripts/csi-spectrogram.js\",\n \"line\": 45,\n \"description\": \"Sensitive credential exposure via command-line arguments. The `--seed-token` parameter is passed as a CLI argument, which is visible in process listings (ps aux output). This violates secure credential handling practices. Tokens should be read from environment variables or secure config files, not command-line args.\",\n \"example\": \"node scripts/csi-spectrogram.js --seed-token secret_abc_123 exposes token in process list\"\n },\n {\n \"severity\": \"medium\",\n \"file\": \"scripts/apnea-detector.js\",\n \"line\": 71,\n \"description\": \"Unsafe buffer reading without comprehensive length validation. The code checks `buf.length` at 32 bytes (line 70) but then reads at fixed offsets (lines 72-76) without validating that each read stays within bounds. If a malformed packet is received, `readInt8/readUInt16LE/readUInt32LE` may read unintended data or zeros.\",\n \"example\": \"A 33-byte buffer would pass the check but reading UInt32LE at offset 8 would go out of bounds\"\n },\n {\n \"severity\": \"medium\",\n \"file\": \"scripts/benchmark-rf-scan.js\",\n \"line\": 110,\n \"description\": \"Potential out-of-bounds buffer access in parseCSIFrame. While the bounds check at line 107 is pres",
|
||||
"rawOutputLength": 7077
|
||||
"riskLevel": "low",
|
||||
"recommendations": [],
|
||||
"note": "Install Claude Code CLI for AI-powered security analysis"
|
||||
}
|
||||
@@ -1,106 +0,0 @@
|
||||
{
|
||||
"timestamp": "2026-05-25T06:11:52.519Z",
|
||||
"mode": "headless",
|
||||
"workerType": "testgaps",
|
||||
"model": "sonnet",
|
||||
"durationMs": 259124,
|
||||
"executionId": "testgaps_1779689253395_srltd5",
|
||||
"success": true,
|
||||
"findings": {
|
||||
"sections": [
|
||||
{
|
||||
"title": "Test Coverage Gap Analysis — wifi-densepose",
|
||||
"content": "\n",
|
||||
"level": 2
|
||||
},
|
||||
{
|
||||
"title": "Coverage Summary by Crate",
|
||||
"content": "\n| Crate | Tests Found | Status | Priority |\n|-------|-------------|--------|----------|\n| `wifi-densepose-core` | 26 inline | Good | Low |\n| `wifi-densepose-signal` | ~60 (validation only) | Moderate | **High** |\n| `wifi-densepose-nn` | **0** | Critical | **P1** |\n| `wifi-densepose-train` | ~60 (config/dataset) | Moderate | High |\n| `wifi-densepose-mat` | 1 integration test | Critical | **P1** |\n| `wifi-densepose-ruvector` | **0** | Critical | **P1** |\n| `wifi-densepose-sensing-server` | 4 integration tests | Moderate | High |\n| `wifi-densepose-wasm` | 3 compliance tests | Low | Low |\n\n---\n\n",
|
||||
"level": 3
|
||||
},
|
||||
{
|
||||
"title": "Tier 1: Critical Gaps",
|
||||
"content": "\n",
|
||||
"level": 2
|
||||
},
|
||||
{
|
||||
"title": "1. `wifi-densepose-nn` — Zero test coverage",
|
||||
"content": "\nEvery public API is untested. Place these at `v2/crates/wifi-densepose-nn/tests/inference_tests.rs`:\n\n```rust\n// v2/crates/wifi-densepose-nn/tests/inference_tests.rs\n\n#[cfg(test)]\nmod tensor_tests {\n use wifi_densepose_nn::tensor::Tensor;\n\n #[test]\n fn tensor_shape_mismatch_returns_error() {\n // data has 6 elements but shape claims 3×3=9\n let result = Tensor::new(vec![1.0f32; 6], &[3, 3]);\n assert!(result.is_err(), \"shape mismatch must be rejected\");\n }\n\n #[test]\n fn tensor_empty_data_returns_error() {\n let result = Tensor::new(vec![], &[0]);\n assert!(result.is_err());\n }\n\n #[test]\n fn tensor_nan_values_are_detected() {\n let t = Tensor::new(vec![f32::NAN, 1.0, 2.0], &[3]).unwrap();\n assert!(t.has_nan(), \"NaN in data must be detectable\");\n }\n\n #[test]\n fn tensor_inf_values_are_detected() {\n let t = Tensor::new(vec![f32::INFINITY, 1.0], &[2]).unwrap();\n assert!(t.has_inf());\n }\n}\n\n#[cfg(test)]\nmod modality_translator_tests {\n use wifi_densepose_nn::translator::ModalityTranslator;\n\n #[test]\n fn translator_rejects_wrong_subcarrier_count() {\n // standard expects 56 subcarriers; feed 57\n let csi = vec![0.0f32; 57 * 3]; // 57 subcarriers × 3 antennas\n let translator = ModalityTranslator::default();\n let result = translator.translate(&csi, 57, 3);\n assert!(result.is_err());\n }\n\n #[test]\n fn translator_handles_all_zeros() {\n let csi = vec![0.0f32; 56 * 3];\n let translator = ModalityTranslator::default();\n let result = translator.translate(&csi, 56, 3);\n // zero input should produce some output without panic\n assert!(result.is_ok());\n }\n}\n\n#[cfg(test)]\nmod inference_engine_tests {\n use wifi_densepose_nn::inference::InferenceEngine;\n\n #[test]\n fn load_nonexistent_model_returns_error() {\n let result = InferenceEngine::from_path(\"/nonexistent/model.onnx\");\n assert!(result.is_err());\n }\n\n #[test]\n fn load_corrupted_bytes_returns_error() {\n let tmp = tempfile::NamedTempFile::new().unwrap();\n std::fs::write(tmp.path(), b\"not a valid onnx file\").unwrap();\n let result = InferenceEngine::from_path(tmp.path());\n assert!(result.is_err());\n }\n\n #[test]\n fn batch_size_zero_returns_error() {\n // can't run inference on an empty batch\n // requires a valid model; skip if no model file in test fixtures\n // use #[ignore] or a feature flag for CI\n }\n}\n```\n\n---\n\n",
|
||||
"level": 3
|
||||
},
|
||||
{
|
||||
"title": "2. `wifi-densepose-mat` — Disaster response safety gaps",
|
||||
"content": "\nPlace at `v2/crates/wifi-densepose-mat/tests/`:\n\n```rust\n// v2/crates/wifi-densepose-mat/tests/detection_edge_cases.rs\n\n#[cfg(test)]\nmod breathing_rate_edge_cases {\n use wifi_densepose_mat::detection::breathing::BreathingDetector;\n\n #[test]\n fn zero_bpm_is_classified_critical() {\n let detector = BreathingDetector::default();\n // flat-line signal — no breathing detected\n let signal = vec![0.0f32; 1000];\n let result = detector.classify(&signal).unwrap();\n assert_eq!(result.triage_category, TriageCategory::Immediate);\n }\n\n #[test]\n fn agonal_breathing_rate_triggers_immediate() {\n // < 6 BPM is agonal; simulate 3 BPM signal\n let detector = BreathingDetector::default();\n let signal = generate_breathing_signal(3.0, 1000, 100.0); // 3 BPM, 1000 samples @ 100 Hz\n let result = detector.classify(&signal).unwrap();\n assert_eq!(result.triage_category, TriageCategory::Immediate);\n }\n\n #[test]\n fn normal_breathing_is_classified_minor() {\n let detector = BreathingDetector::default();\n let signal = generate_breathing_signal(15.0, 1000, 100.0); // 15 BPM\n let result = detector.classify(&signal).unwrap();\n assert_eq!(result.triage_category, TriageCategory::Minor);\n }\n\n #[test]\n fn all_nan_signal_returns_error_not_panic() {\n let detector = BreathingDetector::default();\n let signal = vec![f32::NAN; 1000];\n let result = detector.classify(&signal);\n assert!(result.is_err(), \"NaN input must be caught, not panic\");\n }\n\n fn generate_breathing_signal(bpm: f32, samples: usize, sample_rate: f32) -> Vec<f32> {\n let freq = bpm / 60.0;\n (0..samples)\n .map(|i| (2.0 * std::f32::consts::PI * freq * i as f32 / sample_rate).sin())\n .collect()\n }\n}\n\n#[cfg(test)]\nmod alert_deduplication {\n use wifi_densepose_mat::alerting::{AlertDispatcher, Alert, TriageCategory};\n use std::time::Duration;\n\n #[test]\n fn duplicate_alerts_within_window_are_suppressed() {\n let mut dispatcher = AlertDispatcher::new();\n let alert = Alert::new(\"survivor-1\", TriageCategory::Immediate);\n dispatcher.dispatch(alert.clone());\n dispatcher.dispatch(alert.clone()); // same survivor, same category\n assert_eq!(dispatcher.queued_count(), 1, \"duplicate must be deduplicated\");\n }\n\n #[test]\n fn escalation_from_minor_to_immediate_is_forwarded() {\n let mut dispatcher = AlertDispatcher::new();\n dispatcher.dispatch(Alert::new(\"survivor-1\", TriageCategory::Minor));\n dispatcher.dispatch(Alert::new(\"survivor-1\", TriageCategory::Immediate));\n // escalation is not a duplicate — must pass through\n assert!(dispatcher.last_alert_for(\"survivor-1\").map(|a| a.category) == Some(TriageCategory::Immediate));\n }\n}\n\n#[cfg(test)]\nmod kalman_tracker_edge_cases {\n use wifi_densepose_mat::tracking::KalmanTracker;\n\n #[test]\n fn position_jump_does_not_corrupt_state() {\n let mut tracker = KalmanTracker::new();\n tracker.update([1.0, 1.0, 0.5]); // initial position\n tracker.update([50.0, 50.0, 0.5]); // physically impossible jump\n let pos = tracker.estimated_position();\n // should not panic; should clamp or flag anomaly\n assert!(pos.iter().all(|v| v.is_finite()));\n }\n\n #[test]\n fn lost_track_resumes_on_re_detection() {\n let mut tracker = KalmanTracker::new();\n tracker.update([1.0, 1.0, 0.5]);\n // simulate 10 missed frames\n for _ in 0..10 { tracker.predict(); }\n assert_eq!(tracker.state(), TrackState::Lost);\n tracker.update([1.1, 1.1, 0.5]); // re-detected nearby\n assert_eq!(tracker.state(), TrackState::Confirmed);\n }\n}\n```\n\n---\n\n",
|
||||
"level": 3
|
||||
},
|
||||
{
|
||||
"title": "3. `wifi-densepose-ruvector` — Zero coverage on all 5 integration modules",
|
||||
"content": "\n```rust\n// v2/crates/wifi-densepose-ruvector/tests/viewpoint_tests.rs\n\n#[cfg(test)]\nmod attention_tests {\n use wifi_densepose_ruvector::viewpoint::attention::CrossViewpointAttention;\n\n #[test]\n fn attention_weights_sum_to_one() {\n let attn = CrossViewpointAttention::new(3); // 3 viewpoints\n let features = vec![[1.0f32; 64], [2.0f32; 64], [3.0f32; 64]];\n let weights = attn.compute_weights(&features);\n let sum: f32 = weights.iter().sum();\n assert!((sum - 1.0).abs() < 1e-5, \"attention must be a probability distribution\");\n }\n\n #[test]\n fn single_viewpoint_gets_full_weight() {\n let attn = CrossViewpointAttention::new(1);\n let features = vec![[1.0f32; 64]];\n let weights = attn.compute_weights(&features);\n assert!((weights[0] - 1.0).abs() < 1e-6);\n }\n\n #[test]\n fn zero_feature_vectors_do_not_produce_nan() {\n let attn = CrossViewpointAttention::new(2);\n let features = vec![[0.0f32; 64], [0.0f32; 64]];\n let weights = attn.compute_weights(&features);\n assert!(weights.iter().all(|w| w.is_finite()));\n }\n}\n\n#[cfg(test)]\nmod sketch_tests {\n use wifi_densepose_ruvector::sketch::WireSketch;\n\n #[test]\n fn round_trip_serialization() {\n let sketch = WireSketch::from_keypoints(&[[0.5f32, 0.5], [0.3, 0.7]]);\n let bytes = sketch.to_bytes();\n let restored = WireSketch::from_bytes(&bytes).unwrap();\n assert_eq!(sketch, restored);\n }\n\n #[test]\n fn deserialize_truncated_bytes_returns_error() {\n let sketch = WireSketch::from_keypoints(&[[0.5f32, 0.5]]);\n let mut bytes = sketch.to_bytes();\n bytes.truncate(bytes.len() / 2); // truncate halfway\n assert!(WireSketch::from_bytes(&bytes).is_err());\n }\n\n #[test]\n fn empty_keypoint_list_is_handled() {\n let sketch = WireSketch::from_keypoints(&[]);\n assert_eq!(sketch.keypoint_count(), 0);\n }\n}\n```\n\n---\n\n",
|
||||
"level": 3
|
||||
},
|
||||
{
|
||||
"title": "Tier 2: Signal Processing Gaps",
|
||||
"content": "\n",
|
||||
"level": 2
|
||||
},
|
||||
{
|
||||
"title": "4. `wifi-densepose-signal` — RuvSense module untested",
|
||||
"content": "\n```rust\n// v2/crates/wifi-densepose-signal/tests/ruvsense_tests.rs\n\n#[cfg(test)]\nmod coherence_gate_tests {\n use wifi_densepose_signal::ruvsense::coherence_gate::{CoherenceGate, GateDecision};\n\n #[test]\n fn high_coherence_signal_is_accepted() {\n let gate = CoherenceGate::new(0.7); // threshold = 0.7\n let decision = gate.evaluate(0.95);\n assert_eq!(decision, GateDecision::Accept);\n }\n\n #[test]\n fn low_coherence_signal_is_rejected() {\n let gate = CoherenceGate::new(0.7);\n let decision = gate.evaluate(0.3);\n assert_eq!(decision, GateDecision::Reject);\n }\n\n #[test]\n fn borderline_coherence_triggers_recalibrate() {\n let gate = CoherenceGate::new(0.7);\n let decision = gate.evaluate(0.68); // just below threshold\n assert_eq!(decision, GateDecision::Recalibrate);\n }\n}\n\n#[cfg(test)]\nmod phase_align_tests {\n use wifi_densepose_signal::ruvsense::phase_align::PhaseAligner;\n\n #[test]\n fn phase_at_plus_pi_does_not_wrap_incorrectly() {\n let aligner = PhaseAligner::new();\n let phases = vec![std::f32::consts::PI - 0.001, std::f32::consts::PI + 0.001];\n let aligned = aligner.align(&phases);\n // jump across ±π boundary must be handled continuously\n let diff = (aligned[1] - aligned[0]).abs();\n assert!(diff < 0.01, \"phase jump at ±π must be < 0.01 rad after alignment\");\n }\n\n #[test]\n fn single_phase_value_aligns_to_itself() {\n let aligner = PhaseAligner::new();\n let phases = vec![1.5f32];\n let aligned = aligner.align(&phases);\n assert_eq!(aligned.len(), 1);\n assert!((aligned[0] - 1.5).abs() < 1e-6);\n }\n\n #[test]\n fn empty_phase_array_returns_empty() {\n let aligner = PhaseAligner::new();\n let aligned = aligner.align(&[]);\n assert!(aligned.is_empty());\n }\n}\n\n#[cfg(test)]\nmod adversarial_detection_tests {\n use wifi_densepose_signal::ruvsense::adversarial::AdversarialDetector;\n\n #[test]\n fn physically_impossible_amplitude_is_flagged() {\n let detector = AdversarialDetector::new();\n // WiFi amplitude cannot exceed hardware saturation level\n let frame = vec![1e9f32; 56]; // absurdly large\n assert!(detector.is_suspicious(&frame));\n }\n\n #[test]\n fn normal_amplitude_range_passes() {\n let detector = AdversarialDetector::new();\n let frame = vec![0.5f32; 56]; // typical normalized value\n assert!(!detector.is_suspicious(&frame));\n }\n\n #[test]\n fn multi_link_inconsistency_is_detected() {\n // link A reports body moving right; link B reports no motion\n // physically inconsistent — flag as adversarial\n let detector = AdversarialDetector::new();\n let result = detector.check_multi_link_consistency(\n &[1.0, 2.0, 3.0], // link A\n &[0.0, 0.0, 0.0], // link B (no motion)\n );\n assert!(result.is_inconsistent());\n }\n}\n```\n\n---\n\n",
|
||||
"level": 3
|
||||
},
|
||||
{
|
||||
"title": "Tier 2: Training Pipeline Gaps",
|
||||
"content": "\n",
|
||||
"level": 2
|
||||
},
|
||||
{
|
||||
"title": "5. `wifi-densepose-train` — Geometry encoder and rapid adaptation untested",
|
||||
"content": "\n```rust\n// v2/crates/wifi-densepose-train/tests/test_geometry.rs\n\n#[cfg(test)]\nmod film_layer_tests {\n use wifi_densepose_train::geometry::FilmLayer;\n\n #[test]\n fn film_layer_output_shape_matches_input() {\n let film = FilmLayer::new(64, 32); // 64-dim features, 32-dim condition\n let features = vec![0.5f32; 64];\n let condition = vec![1.0f32; 32];\n let output = film.forward(&features, &condition).unwrap();\n assert_eq!(output.len(), 64, \"FiLM output must match feature dimensionality\");\n }\n\n #[test]\n fn film_layer_zero_condition_acts_as_identity() {\n let film = FilmLayer::new(64, 32);\n let features = vec![1.0f32; 64];\n let zero_condition = vec![0.0f32; 32];\n let output = film.forward(&features, &zero_condition).unwrap();\n // scale=1, shift=0 → identity; output ≈ input\n for (o, f) in output.iter().zip(features.iter()) {\n assert!((o - f).abs() < 0.1, \"zero condition should approximate identity\");\n }\n }\n}\n\n// v2/crates/wifi-densepose-train/tests/test_rapid_adapt.rs\n\n#[cfg(test)]\nmod rapid_adaptation_tests {\n use wifi_densepose_train::rapid_adapt::RapidAdapter;\n\n #[test]\n fn adapter_updates_on_single_sample() {\n let mut adapter = RapidAdapter::new(5); // 5 adaptation steps\n let csi_sample = vec![0.1f32; 56 * 3];\n let pose_label = vec![0.5f32; 17 * 2]; // 17 keypoints × (x, y)\n let result = adapter.adapt_step(&csi_sample, &pose_label);\n assert!(result.is_ok());\n }\n\n #[test]\n fn adapter_with_zero_steps_is_no_op() {\n let adapter = RapidAdapter::new(0);\n // 0 adaptation steps → weights unchanged\n let initial_weights = adapter.clone_weights();\n let _ = adapter.adapt_step(&vec![0.1f32; 168], &vec![0.5f32; 34]);\n assert_eq!(adapter.clone_weights(), initial_weights);\n }\n}\n```\n\n---\n\n",
|
||||
"level": 3
|
||||
},
|
||||
{
|
||||
"title": "Tier 3: Server Integration Gaps",
|
||||
"content": "\n",
|
||||
"level": 2
|
||||
},
|
||||
{
|
||||
"title": "6. `wifi-densepose-sensing-server` — Auth and semantic analyzers",
|
||||
"content": "\n```rust\n// v2/crates/wifi-densepose-sensing-server/tests/auth_tests.rs\n\n#[cfg(test)]\nmod bearer_auth_tests {\n use wifi_densepose_sensing_server::auth::{BearerValidator, TokenError};\n\n #[test]\n fn missing_authorization_header_returns_unauthorized() {\n let validator = BearerValidator::new(\"secret-token\");\n let result = validator.validate(None);\n assert!(matches!(result, Err(TokenError::Missing)));\n }\n\n #[test]\n fn wrong_token_is_rejected() {\n let validator = BearerValidator::new(\"correct-token\");\n let result = validator.validate(Some(\"Bearer wrong-token\"));\n assert!(matches!(result, Err(TokenError::Invalid)));\n }\n\n #[test]\n fn malformed_header_without_bearer_prefix_is_rejected() {\n let validator = BearerValidator::new(\"token\");\n let result = validator.validate(Some(\"token\")); // missing \"Bearer \" prefix\n assert!(matches!(result, Err(TokenError::Malformed)));\n }\n\n #[test]\n fn correct_token_is_accepted() {\n let validator = BearerValidator::new(\"correct-token\");\n let result = validator.validate(Some(\"Bearer correct-token\"));\n assert!(result.is_ok());\n }\n}\n\n// v2/crates/wifi-densepose-sensing-server/tests/semantic_tests.rs\n\n#[cfg(test)]\nmod fall_detection_tests {\n use wifi_densepose_sensing_server::semantic::fall_detector::FallDetector;\n\n #[test]\n fn no_motion_does_not_trigger_fall() {\n let mut detector = FallDetector::new();\n for _ in 0..30 { // 30 frames of stillness\n detector.update_pose(stationary_pose());\n }\n assert!(!detector.fall_detected());\n }\n\n #[test]\n fn rapid_downward_velocity_triggers_fall() {\n let mut detector = FallDetector::new();\n // simulate person going from standing (y=1.7m) to prone (y=0.3m) in 3 frames\n for (frame, y) in [(0, 1.7f32), (1, 1.0), (2, 0.3)] {\n detector.update_pose(pose_at_height(y));\n }\n assert!(detector.fall_detected());\n }\n\n #[test]\n fn sitting_down_slowly_does_not_trigger_fall() {\n let mut detector = FallDetector::new();\n // gradual height decrease over 30 frames is sitting, not falling\n for i in 0..30 {\n let y = 1.7f32 - (i as f32 * 0.04); // ~1.2m drop over 30 frames\n detector.update_pose(pose_at_height(y));\n }\n assert!(!detector.fall_detected());\n }\n}\n```\n\n---\n\n",
|
||||
"level": 3
|
||||
},
|
||||
{
|
||||
"title": "Cross-Cutting Gap Summary",
|
||||
"content": "| Gap Category | Severity | Affects | Recommended Action |\n|---|---|---|---|\n| `wifi-densepose-nn` has 0 tests | **Critical** | Inference pipeline | Add `tests/inference_tests.rs` per skeleton above |\n| `wifi-densepose-ruvector` has 0 tests | **Critical** | Viewpoint fusion, sketches | Add `tests/viewpoint_tests.rs` |\n| MAT disaster response missing edge cases | **Critical** | 0 BPM, agonal breathing, dedup | Add `tests/detection_edge_cases.rs` |\n| Signal RuvSense 28 modules untested | High | Core sensing logic | Add `tests/ruvsense_tests.rs` |\n| NN error paths (bad model files, OOM) | High | Production reliability | Add error path tests to nn |\n| Train geometry + rapid adapt = 0 tests | High | Domain adaptation | Add `tests/test_geometry.rs` |\n| Server auth token validation | High | Security boundary | Add `tests/auth_tests.rs` |\n| NaN/Inf propagation in f32 pipelines | High | All numeric crates | Add boundary tests per module |\n| Concurrent state under Arc<Mutex> | Medium | sensing-server, mat | Add contention tests |\n\nThe highest-ROI starting point is `wifi-densepose-nn` and `wifi-densepose-mat` — the nn crate has zero tests on the core inference pipeline, and mat covers life-safety scenarios where classification errors have real consequences.",
|
||||
"level": 2
|
||||
}
|
||||
],
|
||||
"codeBlocks": [
|
||||
{
|
||||
"language": "rust",
|
||||
"code": "// v2/crates/wifi-densepose-nn/tests/inference_tests.rs\n\n#[cfg(test)]\nmod tensor_tests {\n use wifi_densepose_nn::tensor::Tensor;\n\n #[test]\n fn tensor_shape_mismatch_returns_error() {\n // data has 6 elements but shape claims 3×3=9\n let result = Tensor::new(vec![1.0f32; 6], &[3, 3]);\n assert!(result.is_err(), \"shape mismatch must be rejected\");\n }\n\n #[test]\n fn tensor_empty_data_returns_error() {\n let result = Tensor::new(vec![], &[0]);\n assert!(result.is_err());\n }\n\n #[test]\n fn tensor_nan_values_are_detected() {\n let t = Tensor::new(vec![f32::NAN, 1.0, 2.0], &[3]).unwrap();\n assert!(t.has_nan(), \"NaN in data must be detectable\");\n }\n\n #[test]\n fn tensor_inf_values_are_detected() {\n let t = Tensor::new(vec![f32::INFINITY, 1.0], &[2]).unwrap();\n assert!(t.has_inf());\n }\n}\n\n#[cfg(test)]\nmod modality_translator_tests {\n use wifi_densepose_nn::translator::ModalityTranslator;\n\n #[test]\n fn translator_rejects_wrong_subcarrier_count() {\n // standard expects 56 subcarriers; feed 57\n let csi = vec![0.0f32; 57 * 3]; // 57 subcarriers × 3 antennas\n let translator = ModalityTranslator::default();\n let result = translator.translate(&csi, 57, 3);\n assert!(result.is_err());\n }\n\n #[test]\n fn translator_handles_all_zeros() {\n let csi = vec![0.0f32; 56 * 3];\n let translator = ModalityTranslator::default();\n let result = translator.translate(&csi, 56, 3);\n // zero input should produce some output without panic\n assert!(result.is_ok());\n }\n}\n\n#[cfg(test)]\nmod inference_engine_tests {\n use wifi_densepose_nn::inference::InferenceEngine;\n\n #[test]\n fn load_nonexistent_model_returns_error() {\n let result = InferenceEngine::from_path(\"/nonexistent/model.onnx\");\n assert!(result.is_err());\n }\n\n #[test]\n fn load_corrupted_bytes_returns_error() {\n let tmp = tempfile::NamedTempFile::new().unwrap();\n std::fs::write(tmp.path(), b\"not a valid onnx file\").unwrap();\n let result = InferenceEngine::from_path(tmp.path());\n assert!(result.is_err());\n }\n\n #[test]\n fn batch_size_zero_returns_error() {\n // can't run inference on an empty batch\n // requires a valid model; skip if no model file in test fixtures\n // use #[ignore] or a feature flag for CI\n }\n}"
|
||||
},
|
||||
{
|
||||
"language": "rust",
|
||||
"code": "// v2/crates/wifi-densepose-mat/tests/detection_edge_cases.rs\n\n#[cfg(test)]\nmod breathing_rate_edge_cases {\n use wifi_densepose_mat::detection::breathing::BreathingDetector;\n\n #[test]\n fn zero_bpm_is_classified_critical() {\n let detector = BreathingDetector::default();\n // flat-line signal — no breathing detected\n let signal = vec![0.0f32; 1000];\n let result = detector.classify(&signal).unwrap();\n assert_eq!(result.triage_category, TriageCategory::Immediate);\n }\n\n #[test]\n fn agonal_breathing_rate_triggers_immediate() {\n // < 6 BPM is agonal; simulate 3 BPM signal\n let detector = BreathingDetector::default();\n let signal = generate_breathing_signal(3.0, 1000, 100.0); // 3 BPM, 1000 samples @ 100 Hz\n let result = detector.classify(&signal).unwrap();\n assert_eq!(result.triage_category, TriageCategory::Immediate);\n }\n\n #[test]\n fn normal_breathing_is_classified_minor() {\n let detector = BreathingDetector::default();\n let signal = generate_breathing_signal(15.0, 1000, 100.0); // 15 BPM\n let result = detector.classify(&signal).unwrap();\n assert_eq!(result.triage_category, TriageCategory::Minor);\n }\n\n #[test]\n fn all_nan_signal_returns_error_not_panic() {\n let detector = BreathingDetector::default();\n let signal = vec![f32::NAN; 1000];\n let result = detector.classify(&signal);\n assert!(result.is_err(), \"NaN input must be caught, not panic\");\n }\n\n fn generate_breathing_signal(bpm: f32, samples: usize, sample_rate: f32) -> Vec<f32> {\n let freq = bpm / 60.0;\n (0..samples)\n .map(|i| (2.0 * std::f32::consts::PI * freq * i as f32 / sample_rate).sin())\n .collect()\n }\n}\n\n#[cfg(test)]\nmod alert_deduplication {\n use wifi_densepose_mat::alerting::{AlertDispatcher, Alert, TriageCategory};\n use std::time::Duration;\n\n #[test]\n fn duplicate_alerts_within_window_are_suppressed() {\n let mut dispatcher = AlertDispatcher::new();\n let alert = Alert::new(\"survivor-1\", TriageCategory::Immediate);\n dispatcher.dispatch(alert.clone());\n dispatcher.dispatch(alert.clone()); // same survivor, same category\n assert_eq!(dispatcher.queued_count(), 1, \"duplicate must be deduplicated\");\n }\n\n #[test]\n fn escalation_from_minor_to_immediate_is_forwarded() {\n let mut dispatcher = AlertDispatcher::new();\n dispatcher.dispatch(Alert::new(\"survivor-1\", TriageCategory::Minor));\n dispatcher.dispatch(Alert::new(\"survivor-1\", TriageCategory::Immediate));\n // escalation is not a duplicate — must pass through\n assert!(dispatcher.last_alert_for(\"survivor-1\").map(|a| a.category) == Some(TriageCategory::Immediate));\n }\n}\n\n#[cfg(test)]\nmod kalman_tracker_edge_cases {\n use wifi_densepose_mat::tracking::KalmanTracker;\n\n #[test]\n fn position_jump_does_not_corrupt_state() {\n let mut tracker = KalmanTracker::new();\n tracker.update([1.0, 1.0, 0.5]); // initial position\n tracker.update([50.0, 50.0, 0.5]); // physically impossible jump\n let pos = tracker.estimated_position();\n // should not panic; should clamp or flag anomaly\n assert!(pos.iter().all(|v| v.is_finite()));\n }\n\n #[test]\n fn lost_track_resumes_on_re_detection() {\n let mut tracker = KalmanTracker::new();\n tracker.update([1.0, 1.0, 0.5]);\n // simulate 10 missed frames\n for _ in 0..10 { tracker.predict(); }\n assert_eq!(tracker.state(), TrackState::Lost);\n tracker.update([1.1, 1.1, 0.5]); // re-detected nearby\n assert_eq!(tracker.state(), TrackState::Confirmed);\n }\n}"
|
||||
},
|
||||
{
|
||||
"language": "rust",
|
||||
"code": "// v2/crates/wifi-densepose-ruvector/tests/viewpoint_tests.rs\n\n#[cfg(test)]\nmod attention_tests {\n use wifi_densepose_ruvector::viewpoint::attention::CrossViewpointAttention;\n\n #[test]\n fn attention_weights_sum_to_one() {\n let attn = CrossViewpointAttention::new(3); // 3 viewpoints\n let features = vec![[1.0f32; 64], [2.0f32; 64], [3.0f32; 64]];\n let weights = attn.compute_weights(&features);\n let sum: f32 = weights.iter().sum();\n assert!((sum - 1.0).abs() < 1e-5, \"attention must be a probability distribution\");\n }\n\n #[test]\n fn single_viewpoint_gets_full_weight() {\n let attn = CrossViewpointAttention::new(1);\n let features = vec![[1.0f32; 64]];\n let weights = attn.compute_weights(&features);\n assert!((weights[0] - 1.0).abs() < 1e-6);\n }\n\n #[test]\n fn zero_feature_vectors_do_not_produce_nan() {\n let attn = CrossViewpointAttention::new(2);\n let features = vec![[0.0f32; 64], [0.0f32; 64]];\n let weights = attn.compute_weights(&features);\n assert!(weights.iter().all(|w| w.is_finite()));\n }\n}\n\n#[cfg(test)]\nmod sketch_tests {\n use wifi_densepose_ruvector::sketch::WireSketch;\n\n #[test]\n fn round_trip_serialization() {\n let sketch = WireSketch::from_keypoints(&[[0.5f32, 0.5], [0.3, 0.7]]);\n let bytes = sketch.to_bytes();\n let restored = WireSketch::from_bytes(&bytes).unwrap();\n assert_eq!(sketch, restored);\n }\n\n #[test]\n fn deserialize_truncated_bytes_returns_error() {\n let sketch = WireSketch::from_keypoints(&[[0.5f32, 0.5]]);\n let mut bytes = sketch.to_bytes();\n bytes.truncate(bytes.len() / 2); // truncate halfway\n assert!(WireSketch::from_bytes(&bytes).is_err());\n }\n\n #[test]\n fn empty_keypoint_list_is_handled() {\n let sketch = WireSketch::from_keypoints(&[]);\n assert_eq!(sketch.keypoint_count(), 0);\n }\n}"
|
||||
},
|
||||
{
|
||||
"language": "rust",
|
||||
"code": "// v2/crates/wifi-densepose-signal/tests/ruvsense_tests.rs\n\n#[cfg(test)]\nmod coherence_gate_tests {\n use wifi_densepose_signal::ruvsense::coherence_gate::{CoherenceGate, GateDecision};\n\n #[test]\n fn high_coherence_signal_is_accepted() {\n let gate = CoherenceGate::new(0.7); // threshold = 0.7\n let decision = gate.evaluate(0.95);\n assert_eq!(decision, GateDecision::Accept);\n }\n\n #[test]\n fn low_coherence_signal_is_rejected() {\n let gate = CoherenceGate::new(0.7);\n let decision = gate.evaluate(0.3);\n assert_eq!(decision, GateDecision::Reject);\n }\n\n #[test]\n fn borderline_coherence_triggers_recalibrate() {\n let gate = CoherenceGate::new(0.7);\n let decision = gate.evaluate(0.68); // just below threshold\n assert_eq!(decision, GateDecision::Recalibrate);\n }\n}\n\n#[cfg(test)]\nmod phase_align_tests {\n use wifi_densepose_signal::ruvsense::phase_align::PhaseAligner;\n\n #[test]\n fn phase_at_plus_pi_does_not_wrap_incorrectly() {\n let aligner = PhaseAligner::new();\n let phases = vec![std::f32::consts::PI - 0.001, std::f32::consts::PI + 0.001];\n let aligned = aligner.align(&phases);\n // jump across ±π boundary must be handled continuously\n let diff = (aligned[1] - aligned[0]).abs();\n assert!(diff < 0.01, \"phase jump at ±π must be < 0.01 rad after alignment\");\n }\n\n #[test]\n fn single_phase_value_aligns_to_itself() {\n let aligner = PhaseAligner::new();\n let phases = vec![1.5f32];\n let aligned = aligner.align(&phases);\n assert_eq!(aligned.len(), 1);\n assert!((aligned[0] - 1.5).abs() < 1e-6);\n }\n\n #[test]\n fn empty_phase_array_returns_empty() {\n let aligner = PhaseAligner::new();\n let aligned = aligner.align(&[]);\n assert!(aligned.is_empty());\n }\n}\n\n#[cfg(test)]\nmod adversarial_detection_tests {\n use wifi_densepose_signal::ruvsense::adversarial::AdversarialDetector;\n\n #[test]\n fn physically_impossible_amplitude_is_flagged() {\n let detector = AdversarialDetector::new();\n // WiFi amplitude cannot exceed hardware saturation level\n let frame = vec![1e9f32; 56]; // absurdly large\n assert!(detector.is_suspicious(&frame));\n }\n\n #[test]\n fn normal_amplitude_range_passes() {\n let detector = AdversarialDetector::new();\n let frame = vec![0.5f32; 56]; // typical normalized value\n assert!(!detector.is_suspicious(&frame));\n }\n\n #[test]\n fn multi_link_inconsistency_is_detected() {\n // link A reports body moving right; link B reports no motion\n // physically inconsistent — flag as adversarial\n let detector = AdversarialDetector::new();\n let result = detector.check_multi_link_consistency(\n &[1.0, 2.0, 3.0], // link A\n &[0.0, 0.0, 0.0], // link B (no motion)\n );\n assert!(result.is_inconsistent());\n }\n}"
|
||||
},
|
||||
{
|
||||
"language": "rust",
|
||||
"code": "// v2/crates/wifi-densepose-train/tests/test_geometry.rs\n\n#[cfg(test)]\nmod film_layer_tests {\n use wifi_densepose_train::geometry::FilmLayer;\n\n #[test]\n fn film_layer_output_shape_matches_input() {\n let film = FilmLayer::new(64, 32); // 64-dim features, 32-dim condition\n let features = vec![0.5f32; 64];\n let condition = vec![1.0f32; 32];\n let output = film.forward(&features, &condition).unwrap();\n assert_eq!(output.len(), 64, \"FiLM output must match feature dimensionality\");\n }\n\n #[test]\n fn film_layer_zero_condition_acts_as_identity() {\n let film = FilmLayer::new(64, 32);\n let features = vec![1.0f32; 64];\n let zero_condition = vec![0.0f32; 32];\n let output = film.forward(&features, &zero_condition).unwrap();\n // scale=1, shift=0 → identity; output ≈ input\n for (o, f) in output.iter().zip(features.iter()) {\n assert!((o - f).abs() < 0.1, \"zero condition should approximate identity\");\n }\n }\n}\n\n// v2/crates/wifi-densepose-train/tests/test_rapid_adapt.rs\n\n#[cfg(test)]\nmod rapid_adaptation_tests {\n use wifi_densepose_train::rapid_adapt::RapidAdapter;\n\n #[test]\n fn adapter_updates_on_single_sample() {\n let mut adapter = RapidAdapter::new(5); // 5 adaptation steps\n let csi_sample = vec![0.1f32; 56 * 3];\n let pose_label = vec![0.5f32; 17 * 2]; // 17 keypoints × (x, y)\n let result = adapter.adapt_step(&csi_sample, &pose_label);\n assert!(result.is_ok());\n }\n\n #[test]\n fn adapter_with_zero_steps_is_no_op() {\n let adapter = RapidAdapter::new(0);\n // 0 adaptation steps → weights unchanged\n let initial_weights = adapter.clone_weights();\n let _ = adapter.adapt_step(&vec![0.1f32; 168], &vec![0.5f32; 34]);\n assert_eq!(adapter.clone_weights(), initial_weights);\n }\n}"
|
||||
},
|
||||
{
|
||||
"language": "rust",
|
||||
"code": "// v2/crates/wifi-densepose-sensing-server/tests/auth_tests.rs\n\n#[cfg(test)]\nmod bearer_auth_tests {\n use wifi_densepose_sensing_server::auth::{BearerValidator, TokenError};\n\n #[test]\n fn missing_authorization_header_returns_unauthorized() {\n let validator = BearerValidator::new(\"secret-token\");\n let result = validator.validate(None);\n assert!(matches!(result, Err(TokenError::Missing)));\n }\n\n #[test]\n fn wrong_token_is_rejected() {\n let validator = BearerValidator::new(\"correct-token\");\n let result = validator.validate(Some(\"Bearer wrong-token\"));\n assert!(matches!(result, Err(TokenError::Invalid)));\n }\n\n #[test]\n fn malformed_header_without_bearer_prefix_is_rejected() {\n let validator = BearerValidator::new(\"token\");\n let result = validator.validate(Some(\"token\")); // missing \"Bearer \" prefix\n assert!(matches!(result, Err(TokenError::Malformed)));\n }\n\n #[test]\n fn correct_token_is_accepted() {\n let validator = BearerValidator::new(\"correct-token\");\n let result = validator.validate(Some(\"Bearer correct-token\"));\n assert!(result.is_ok());\n }\n}\n\n// v2/crates/wifi-densepose-sensing-server/tests/semantic_tests.rs\n\n#[cfg(test)]\nmod fall_detection_tests {\n use wifi_densepose_sensing_server::semantic::fall_detector::FallDetector;\n\n #[test]\n fn no_motion_does_not_trigger_fall() {\n let mut detector = FallDetector::new();\n for _ in 0..30 { // 30 frames of stillness\n detector.update_pose(stationary_pose());\n }\n assert!(!detector.fall_detected());\n }\n\n #[test]\n fn rapid_downward_velocity_triggers_fall() {\n let mut detector = FallDetector::new();\n // simulate person going from standing (y=1.7m) to prone (y=0.3m) in 3 frames\n for (frame, y) in [(0, 1.7f32), (1, 1.0), (2, 0.3)] {\n detector.update_pose(pose_at_height(y));\n }\n assert!(detector.fall_detected());\n }\n\n #[test]\n fn sitting_down_slowly_does_not_trigger_fall() {\n let mut detector = FallDetector::new();\n // gradual height decrease over 30 frames is sitting, not falling\n for i in 0..30 {\n let y = 1.7f32 - (i as f32 * 0.04); // ~1.2m drop over 30 frames\n detector.update_pose(pose_at_height(y));\n }\n assert!(!detector.fall_detected());\n }\n}"
|
||||
}
|
||||
]
|
||||
},
|
||||
"rawOutputPreview": "The exploration is complete. Here's the full coverage analysis with test skeletons for each critical gap.\n\n---\n\n## Test Coverage Gap Analysis — wifi-densepose\n\n### Coverage Summary by Crate\n\n| Crate | Tests Found | Status | Priority |\n|-------|-------------|--------|----------|\n| `wifi-densepose-core` | 26 inline | Good | Low |\n| `wifi-densepose-signal` | ~60 (validation only) | Moderate | **High** |\n| `wifi-densepose-nn` | **0** | Critical | **P1** |\n| `wifi-densepose-train` | ~60 (config/dataset) | Moderate | High |\n| `wifi-densepose-mat` | 1 integration test | Critical | **P1** |\n| `wifi-densepose-ruvector` | **0** | Critical | **P1** |\n| `wifi-densepose-sensing-server` | 4 integration tests | Moderate | High |\n| `wifi-densepose-wasm` | 3 compliance tests | Low | Low |\n\n---\n\n## Tier 1: Critical Gaps\n\n### 1. `wifi-densepose-nn` — Zero test coverage\n\nEvery public API is untested. Place these at `v2/crates/wifi-densepose-nn/tests/inference_tests.rs`:\n\n```rust\n// v2/crates/wifi-densepose-nn/tests/inference_tests.rs\n\n#[cfg(test)]\nmod tensor_tests {\n use wifi_densepose_nn::tensor::Tensor;\n\n #[test]\n fn tensor_shape_mismatch_returns_error() {\n // data has 6 elements but shape claims 3×3=9\n let result = Tensor::new(vec![1.0f32; 6], &[3, 3]);\n assert!(result.is_err(), \"shape mismatch must be rejected\");\n }\n\n #[test]\n fn tensor_empty_data_returns_error() {\n let result = Tensor::new(vec![], &[0]);\n assert!(result.is_err());\n }\n\n #[test]\n fn tensor_nan_values_are_detected() {\n let t = Tensor::new(vec![f32::NAN, 1.0, 2.0], &[3]).unwrap();\n assert!(t.has_nan(), \"NaN in data must be detectable\");\n }\n\n #[test]\n fn tensor_inf_values_are_detected() {\n let t = Tensor::new(vec![f32::INFINITY, 1.0], &[2]).unwrap();\n assert!(t.has_inf());\n }\n}\n\n#[cfg(test)]\nmod modality_translator_tests {\n use wifi_densepose_nn::translator::ModalityTranslator;\n\n #[test]\n fn translator_rejects",
|
||||
"rawOutputLength": 18269
|
||||
}
|
||||
@@ -1 +0,0 @@
|
||||
{"sessionId":"d80c93c2-51b7-42e8-a0fc-dc47cff1200f","pid":45748,"acquiredAt":1779668018388}
|
||||
@@ -126,7 +126,10 @@
|
||||
"Bash(node .claude/*)",
|
||||
"mcp__claude-flow__:*"
|
||||
],
|
||||
"deny": []
|
||||
"deny": [
|
||||
"Read(./.env)",
|
||||
"Read(./.env.*)"
|
||||
]
|
||||
},
|
||||
"attribution": {
|
||||
"commit": "Co-Authored-By: claude-flow <ruv@ruv.net>",
|
||||
|
||||
@@ -1,94 +0,0 @@
|
||||
name: AetherArena harness gate (ADR-149)
|
||||
|
||||
# Runs the AetherArena scoring harness as a PR build gate. Every PR that touches
|
||||
# the scorer, the metrics, or the benchmark scaffold must keep the deterministic
|
||||
# score hash stable (ADR-149 §2.5 determinism_gate). If the scoring maths changes,
|
||||
# the hash moves and this gate fails until `expected_score.sha256` is regenerated
|
||||
# and reviewed — so scorer drift can never land silently.
|
||||
#
|
||||
# This is the "a PR that runs the harness as part of the build process" requirement.
|
||||
|
||||
on:
|
||||
pull_request:
|
||||
paths:
|
||||
- 'v2/crates/wifi-densepose-train/src/ruview_metrics.rs'
|
||||
- 'v2/crates/wifi-densepose-train/src/ablation.rs'
|
||||
- 'v2/crates/wifi-densepose-train/src/bin/aa_score_runner.rs'
|
||||
- 'aether-arena/**'
|
||||
- '.github/workflows/aether-arena-harness.yml'
|
||||
push:
|
||||
branches: ['feat/adr-149-aether-arena']
|
||||
workflow_dispatch:
|
||||
|
||||
permissions:
|
||||
contents: read
|
||||
pull-requests: write
|
||||
|
||||
jobs:
|
||||
harness-gate:
|
||||
name: Run AA scorer harness (determinism gate)
|
||||
runs-on: ubuntu-latest
|
||||
defaults:
|
||||
run:
|
||||
working-directory: v2
|
||||
steps:
|
||||
- uses: actions/checkout@v4
|
||||
|
||||
- name: Install Rust toolchain
|
||||
run: rustup show && rustc --version
|
||||
|
||||
- name: Cache cargo
|
||||
uses: actions/cache@v4
|
||||
with:
|
||||
path: |
|
||||
~/.cargo/registry
|
||||
~/.cargo/git
|
||||
v2/target
|
||||
key: aa-harness-${{ runner.os }}-${{ hashFiles('v2/Cargo.lock') }}
|
||||
|
||||
# 1. Build the pure-Rust scorer (no torch / no GPU → fast PR gate).
|
||||
- name: Build AA score runner
|
||||
run: cargo build -p wifi-densepose-train --bin aa_score_runner --no-default-features
|
||||
|
||||
# 2. Determinism gate: the committed expected hash must still match. A
|
||||
# non-zero exit here fails the PR.
|
||||
- name: Run determinism gate
|
||||
run: cargo run -q -p wifi-densepose-train --bin aa_score_runner --no-default-features
|
||||
|
||||
# 3. Repeatability analysis (witness chain): the harness must produce one
|
||||
# identical proof hash across many runs — any nondeterminism fails here.
|
||||
- name: Repeatability analysis (16 runs)
|
||||
run: cargo run -q -p wifi-densepose-train --bin aa_score_runner --no-default-features -- --repeat 16
|
||||
|
||||
# 4. Real-scoring smoke: score a sample prediction against the public smoke
|
||||
# split, exercising the actual model-scoring path (not just the fixture).
|
||||
- name: Real-scoring smoke test
|
||||
run: |
|
||||
cargo run -q -p wifi-densepose-train --bin aa_score_runner --no-default-features -- \
|
||||
--split ../aether-arena/fixtures/smoke_split.json \
|
||||
--pred ../aether-arena/fixtures/smoke_pred.json --json
|
||||
|
||||
# 5. Witness ledger chain integrity: the append-only results ledger must
|
||||
# verify (every prev_hash link + row_hash intact = no silent edits).
|
||||
- name: Verify witness ledger chain
|
||||
working-directory: aether-arena/ledger
|
||||
run: python3 ledger_tools.py verify
|
||||
|
||||
# 6. Emit the witness row + repeatability into the PR run summary.
|
||||
- name: Witness row → job summary
|
||||
if: always()
|
||||
run: |
|
||||
ROW=$(cargo run -q -p wifi-densepose-train --bin aa_score_runner --no-default-features -- --json)
|
||||
REP=$(cargo run -q -p wifi-densepose-train --bin aa_score_runner --no-default-features -- --repeat 16)
|
||||
{
|
||||
echo "## AetherArena harness gate (witness chain)"
|
||||
echo ""
|
||||
echo "Deterministic witness (ADR-149 §2.2 / proof + repeatability):"
|
||||
echo '```json'
|
||||
echo "$ROW"
|
||||
echo "$REP"
|
||||
echo '```'
|
||||
echo ""
|
||||
echo "If the determinism gate failed, the scoring maths changed: regenerate with"
|
||||
echo '`cargo run -p wifi-densepose-train --bin aa_score_runner --no-default-features -- --generate-hash > aether-arena/fixtures/expected_score.sha256` and review the diff.'
|
||||
} >> "$GITHUB_STEP_SUMMARY"
|
||||
@@ -1,99 +0,0 @@
|
||||
name: BFLD MQTT Integration
|
||||
|
||||
# Runs the env-gated mosquitto integration tests from iters 24 + 29 of the
|
||||
# BFLD rollout (ADR-118 / ADR-122 §2.2). Spins up an eclipse-mosquitto:2
|
||||
# service container, exports BFLD_MQTT_BROKER, runs `cargo test --features
|
||||
# mqtt`. Local developers can reproduce with:
|
||||
#
|
||||
# scoop install mosquitto # Windows
|
||||
# # or: docker run -p 1883:1883 eclipse-mosquitto:2
|
||||
# BFLD_MQTT_BROKER=tcp://localhost:1883 \
|
||||
# cargo test -p wifi-densepose-bfld --features mqtt
|
||||
|
||||
on:
|
||||
push:
|
||||
branches:
|
||||
- main
|
||||
- 'feat/adr-118-*'
|
||||
- 'feat/bfld-*'
|
||||
paths:
|
||||
- 'v2/crates/wifi-densepose-bfld/**'
|
||||
- '.github/workflows/bfld-mqtt-integration.yml'
|
||||
pull_request:
|
||||
paths:
|
||||
- 'v2/crates/wifi-densepose-bfld/**'
|
||||
- '.github/workflows/bfld-mqtt-integration.yml'
|
||||
workflow_dispatch:
|
||||
|
||||
jobs:
|
||||
mqtt-live-broker:
|
||||
name: cargo test --features mqtt (live mosquitto)
|
||||
runs-on: ubuntu-latest
|
||||
timeout-minutes: 15
|
||||
|
||||
services:
|
||||
mosquitto:
|
||||
image: eclipse-mosquitto:2
|
||||
ports:
|
||||
- 1883:1883
|
||||
# Allow anonymous connections — local-only CI broker, no exposure
|
||||
# to the public internet, never touches production credentials.
|
||||
options: >-
|
||||
--health-cmd "mosquitto_pub -h localhost -t healthcheck -m ping || exit 1"
|
||||
--health-interval 5s
|
||||
--health-timeout 3s
|
||||
--health-retries 10
|
||||
|
||||
env:
|
||||
BFLD_MQTT_BROKER: tcp://localhost:1883
|
||||
CARGO_TERM_COLOR: always
|
||||
CARGO_INCREMENTAL: 0
|
||||
RUSTFLAGS: -D warnings
|
||||
|
||||
steps:
|
||||
- name: Checkout
|
||||
uses: actions/checkout@v4
|
||||
|
||||
- name: Install Rust toolchain
|
||||
uses: dtolnay/rust-toolchain@stable
|
||||
with:
|
||||
components: clippy
|
||||
|
||||
- name: Cache cargo registry + target
|
||||
uses: actions/cache@v4
|
||||
with:
|
||||
path: |
|
||||
~/.cargo/registry
|
||||
~/.cargo/git
|
||||
v2/target
|
||||
key: bfld-mqtt-${{ runner.os }}-${{ hashFiles('v2/Cargo.lock') }}
|
||||
|
||||
- name: Wait for mosquitto to be ready
|
||||
run: |
|
||||
for i in {1..20}; do
|
||||
if nc -z localhost 1883; then
|
||||
echo "mosquitto reachable on port 1883 (attempt $i)"
|
||||
exit 0
|
||||
fi
|
||||
echo "waiting for mosquitto ($i/20)..."
|
||||
sleep 1
|
||||
done
|
||||
echo "mosquitto never became reachable" >&2
|
||||
exit 1
|
||||
|
||||
- name: cargo test --no-default-features (baseline regression)
|
||||
working-directory: v2
|
||||
run: cargo test -p wifi-densepose-bfld --no-default-features
|
||||
|
||||
- name: cargo test (default features)
|
||||
working-directory: v2
|
||||
run: cargo test -p wifi-densepose-bfld
|
||||
|
||||
- name: cargo test --features mqtt (incl. live mosquitto roundtrip)
|
||||
working-directory: v2
|
||||
run: cargo test -p wifi-densepose-bfld --features mqtt
|
||||
|
||||
- name: cargo clippy --features mqtt (lint gate)
|
||||
working-directory: v2
|
||||
run: cargo clippy -p wifi-densepose-bfld --features mqtt --all-targets -- -D warnings
|
||||
continue-on-error: true
|
||||
+16
-79
@@ -108,49 +108,21 @@ jobs:
|
||||
- name: Install Rust toolchain
|
||||
uses: dtolnay/rust-toolchain@stable
|
||||
|
||||
# Swatinem/rust-cache replaces a naive `actions/cache` of the whole
|
||||
# `v2/target`. That manual cache of a 38-crate target dir (multi-GB) was an
|
||||
# intermittent failure source — several CI runs this cycle died at the
|
||||
# cache/setup step (after toolchain install, before "Run Rust tests"),
|
||||
# needing a rerun. rust-cache is purpose-built for Rust: it caches the
|
||||
# registry + git + a pruned target, evicts stale deps, and restores far more
|
||||
# reliably (and faster) on large workspaces. `workspaces: v2` points it at
|
||||
# the v2/ cargo workspace (keys on v2/Cargo.lock, caches v2/target).
|
||||
- name: Cache cargo (Swatinem/rust-cache)
|
||||
uses: Swatinem/rust-cache@v2
|
||||
- name: Cache cargo
|
||||
uses: actions/cache@v4
|
||||
with:
|
||||
workspaces: v2
|
||||
path: |
|
||||
~/.cargo/registry
|
||||
~/.cargo/git
|
||||
v2/target
|
||||
key: ${{ runner.os }}-cargo-${{ hashFiles('v2/Cargo.lock') }}
|
||||
restore-keys: |
|
||||
${{ runner.os }}-cargo-
|
||||
|
||||
- name: Run Rust tests
|
||||
working-directory: v2
|
||||
run: cargo test --workspace --no-default-features
|
||||
|
||||
- name: Run ADR-147 worldmodel tests
|
||||
working-directory: v2
|
||||
run: cargo test -p wifi-densepose-worldmodel --no-default-features
|
||||
|
||||
# ADR-134 CIR tests are behind the `cir` feature so the bench dependency
|
||||
# (Criterion) only pulls when actually exercised. Run them as a separate
|
||||
# step so a CIR-only regression is unambiguously attributable.
|
||||
- name: Run ADR-134 CIR tests
|
||||
working-directory: v2
|
||||
run: cargo test -p wifi-densepose-signal --no-default-features --features cir --tests
|
||||
|
||||
# ADR-134 + ADR-028 witness guard. The CIR proof runner produces a
|
||||
# bit-deterministic SHA-256 over CirEstimator output on the synthetic
|
||||
# reference signal. Any algorithmic regression — changes to ISTA
|
||||
# convergence, sensing matrix construction, soft-thresholding, or input
|
||||
# padding — breaks the hash and fails the build. To regenerate after an
|
||||
# *intentional* change:
|
||||
# cd v2 && cargo run -p wifi-densepose-signal --bin cir_proof_runner \
|
||||
# --release --no-default-features -- --generate-hash \
|
||||
# > ../archive/v1/data/proof/expected_cir_features.sha256
|
||||
- name: ADR-134 CIR witness proof (determinism guard)
|
||||
run: bash scripts/verify-cir-proof.sh
|
||||
|
||||
- name: ADR-135 calibration witness proof (determinism guard)
|
||||
run: bash scripts/verify-calibration-proof.sh
|
||||
|
||||
# Unit and Integration Tests
|
||||
# Python pytest matrix — runs against the archived v1 Python tree.
|
||||
# `continue-on-error: true` for the same reason as code-quality above:
|
||||
@@ -244,14 +216,10 @@ jobs:
|
||||
htmlcov/
|
||||
|
||||
# Performance and Load Tests
|
||||
# NOTE: tests/performance/locustfile.py and the src.api.main app path both
|
||||
# predate the v1→archive/v1 reorganisation. continue-on-error: true until a
|
||||
# proper locust suite is added under archive/v1/tests/performance/.
|
||||
performance-test:
|
||||
name: Performance Tests
|
||||
runs-on: ubuntu-latest
|
||||
needs: [test]
|
||||
continue-on-error: true
|
||||
if: github.event_name == 'push' && github.ref == 'refs/heads/main'
|
||||
steps:
|
||||
- name: Checkout code
|
||||
@@ -267,45 +235,22 @@ jobs:
|
||||
run: |
|
||||
python -m pip install --upgrade pip
|
||||
pip install -r requirements.txt
|
||||
pip install pytest # the perf suite is pytest, not locust
|
||||
pip install locust
|
||||
|
||||
# No "Start application" step: the gated test (test_frame_budget.py) drives
|
||||
# the CSIProcessor pipeline in-process and makes no HTTP calls, so the old
|
||||
# uvicorn server + `sleep 10` were dead weight — they only existed for the
|
||||
# now-excluded api_throughput/inference_speed tests, and on every run dumped
|
||||
# ~50 misleading "router requires hardware setup" ERROR lines for a server
|
||||
# no test touched. MOCK_POSE_DATA is server-only and unused here.
|
||||
- name: Start application
|
||||
run: |
|
||||
uvicorn src.api.main:app --host 0.0.0.0 --port 8000 &
|
||||
sleep 10
|
||||
|
||||
- name: Run performance tests
|
||||
working-directory: archive/v1
|
||||
run: |
|
||||
# Gate only on the genuine, deterministic perf guard:
|
||||
# test_frame_budget.py times the *real* CSIProcessor pipeline against
|
||||
# the ADR 50 ms per-frame budget (single-frame, p95 over 100 frames,
|
||||
# +Doppler) — a true regression signal.
|
||||
#
|
||||
# test_api_throughput.py / test_inference_speed.py are excluded: every
|
||||
# test there is a TDD red-phase stub (suffix `_should_fail_initially`)
|
||||
# that times a *mock that sleeps* — meaningless as a perf signal, with
|
||||
# machine-dependent wall-clock asserts (e.g. `actual_rps >= 40`,
|
||||
# `batch_time < individual_time`) that are inherently flaky on shared
|
||||
# CI runners, plus a cross-class fixture-scope bug. Forcing them green
|
||||
# would be manufacturing a false signal; they stay in-repo for local
|
||||
# TDD but do not gate CI until the underlying features are implemented.
|
||||
#
|
||||
# `python -m pytest` (not the bare `pytest` script) puts the cwd
|
||||
# (archive/v1) on sys.path so `from src.core...` resolves — the bare
|
||||
# script omits cwd and raises ModuleNotFoundError: No module named 'src'.
|
||||
# -o addopts="" drops the root pyproject's --cov/--cov-fail-under=100.
|
||||
python -m pytest tests/performance/test_frame_budget.py \
|
||||
-o addopts="" -v --junitxml=perf-junit.xml
|
||||
locust -f tests/performance/locustfile.py --headless --users 50 --spawn-rate 5 --run-time 60s --host http://localhost:8000
|
||||
|
||||
- name: Upload performance results
|
||||
if: always()
|
||||
uses: actions/upload-artifact@v4
|
||||
with:
|
||||
name: performance-results
|
||||
path: archive/v1/perf-junit.xml
|
||||
path: locust_report.html
|
||||
|
||||
# Docker Build and Test
|
||||
# NOTE: the canonical Docker build for the sensing-server is now
|
||||
@@ -391,8 +336,6 @@ jobs:
|
||||
runs-on: ubuntu-latest
|
||||
needs: [docker-build]
|
||||
if: github.ref == 'refs/heads/main'
|
||||
permissions:
|
||||
contents: write # gh-pages deploy needs write (GITHUB_TOKEN is read-only by default -> 403)
|
||||
steps:
|
||||
- name: Checkout code
|
||||
uses: actions/checkout@v4
|
||||
@@ -409,9 +352,6 @@ jobs:
|
||||
pip install -r requirements.txt
|
||||
|
||||
- name: Generate OpenAPI spec
|
||||
working-directory: archive/v1
|
||||
env:
|
||||
MOCK_POSE_DATA: "true" # no CSI hardware in CI
|
||||
run: |
|
||||
python -c "
|
||||
from src.api.main import app
|
||||
@@ -422,7 +362,6 @@ jobs:
|
||||
|
||||
- name: Deploy to GitHub Pages
|
||||
uses: peaceiris/actions-gh-pages@v4
|
||||
continue-on-error: true # openapi generation above is the real validation; deploy is best-effort (Pages may be disabled)
|
||||
with:
|
||||
github_token: ${{ secrets.GITHUB_TOKEN }}
|
||||
publish_dir: ./docs
|
||||
@@ -434,8 +373,6 @@ jobs:
|
||||
runs-on: ubuntu-latest
|
||||
needs: [code-quality, test, rust-tests, performance-test, docker-build, docs]
|
||||
if: always()
|
||||
permissions:
|
||||
contents: write # required by softprops/action-gh-release
|
||||
# GitHub Actions does not allow `secrets.X` directly in step-level `if:`
|
||||
# expressions — only `env.X`. Promote the secret to env at job scope so
|
||||
# the gating expression below is parseable.
|
||||
|
||||
@@ -1,149 +0,0 @@
|
||||
name: GitHub Clone Tracking → data/clone-data.rvf
|
||||
|
||||
# Persists rolling 14-day clone-traffic snapshots to data/clone-data.rvf in
|
||||
# the ruvector JSONL RVF format. GitHub's /traffic/clones endpoint only
|
||||
# retains the last 14 days server-side, so without this scheduled scrape
|
||||
# the data is gone forever the moment it falls outside the window.
|
||||
#
|
||||
# Format: JSONL RVF
|
||||
# - line 1 is a `metadata` segment that initializes the file
|
||||
# - each subsequent run appends one `clone_snapshot` segment carrying the
|
||||
# 14-day rollup PLUS per-day breakdown
|
||||
# - file is idempotent: per-day entries are keyed by `timestamp` so a
|
||||
# downstream reader can dedupe across overlapping snapshot windows
|
||||
#
|
||||
# Schedule: every 14 days (1st + 15th of each month, ~14-day cadence in
|
||||
# practice). Workflow can also be dispatched manually for backfill or test.
|
||||
|
||||
on:
|
||||
schedule:
|
||||
# 01:23 UTC on the 1st and 15th of every month — close to 14-day cadence
|
||||
# without cron's "every 14 days" monthly-reset weirdness. Picking :23
|
||||
# avoids the cron herd on :00.
|
||||
- cron: '23 1 1,15 * *'
|
||||
workflow_dispatch:
|
||||
|
||||
permissions:
|
||||
contents: write
|
||||
|
||||
concurrency:
|
||||
group: clone-tracking
|
||||
cancel-in-progress: false
|
||||
|
||||
jobs:
|
||||
snapshot:
|
||||
runs-on: ubuntu-latest
|
||||
steps:
|
||||
- uses: actions/checkout@v4
|
||||
|
||||
- name: Fetch /traffic/clones + /traffic/views from GitHub
|
||||
env:
|
||||
GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
|
||||
run: |
|
||||
mkdir -p data
|
||||
gh api repos/${{ github.repository }}/traffic/clones > /tmp/clones.json
|
||||
gh api repos/${{ github.repository }}/traffic/views > /tmp/views.json
|
||||
echo "--- clones rollup ---"
|
||||
jq '{count, uniques, days: (.clones | length)}' /tmp/clones.json
|
||||
echo "--- views rollup ---"
|
||||
jq '{count, uniques, days: (.views | length)}' /tmp/views.json
|
||||
|
||||
- name: Append snapshot to data/clone-data.rvf
|
||||
env:
|
||||
REPO: ${{ github.repository }}
|
||||
run: |
|
||||
set -e
|
||||
RVF="data/clone-data.rvf"
|
||||
FETCHED_AT=$(date -u +"%Y-%m-%dT%H:%M:%SZ")
|
||||
|
||||
# Initialize the file with a metadata segment on first run.
|
||||
if [ ! -f "$RVF" ]; then
|
||||
echo "Initializing $RVF with metadata segment"
|
||||
jq -n --arg repo "$REPO" --arg ts "$FETCHED_AT" '{
|
||||
type: "metadata",
|
||||
name: "ruview-clone-traffic-history",
|
||||
version: "1.0.0",
|
||||
schema: "ruvector.rvf.jsonl/v1",
|
||||
format: "github-traffic-snapshots",
|
||||
repo: $repo,
|
||||
source: "GitHub Traffic API /repos/{repo}/traffic/{clones,views}",
|
||||
policy: "GitHub retains only 14 days server-side; this file is the long-term record.",
|
||||
segments: ["metadata", "clone_snapshot", "view_snapshot"],
|
||||
created_at: $ts,
|
||||
custom: {
|
||||
cadence: "twice monthly (1st and 15th, ~14-day intervals)",
|
||||
idempotency_key: "timestamp (per-day records de-duplicate across overlapping snapshot windows)"
|
||||
}
|
||||
}' >> "$RVF"
|
||||
fi
|
||||
|
||||
# Append the clone snapshot.
|
||||
jq --arg ts "$FETCHED_AT" '{
|
||||
type: "clone_snapshot",
|
||||
fetched_at: $ts,
|
||||
window_count: .count,
|
||||
window_uniques: .uniques,
|
||||
per_day: .clones
|
||||
}' /tmp/clones.json >> "$RVF"
|
||||
|
||||
# Append the views snapshot (free with the same auth).
|
||||
jq --arg ts "$FETCHED_AT" '{
|
||||
type: "view_snapshot",
|
||||
fetched_at: $ts,
|
||||
window_count: .count,
|
||||
window_uniques: .uniques,
|
||||
per_day: .views
|
||||
}' /tmp/views.json >> "$RVF"
|
||||
|
||||
echo "--- RVF tail (last 4 lines) ---"
|
||||
tail -4 "$RVF" | jq -c '{type, fetched_at, window_count, window_uniques}' || true
|
||||
echo "--- file size ---"
|
||||
wc -l "$RVF"
|
||||
|
||||
- name: Compute aggregates for the commit summary
|
||||
id: agg
|
||||
run: |
|
||||
# Count distinct per-day entries across all snapshots so we can
|
||||
# show "cumulative observed clones" in the commit message.
|
||||
python3 - <<'PY'
|
||||
import json, os
|
||||
path = "data/clone-data.rvf"
|
||||
per_day_clones = {}
|
||||
per_day_views = {}
|
||||
with open(path, encoding="utf-8") as f:
|
||||
for line in f:
|
||||
if not line.strip():
|
||||
continue
|
||||
d = json.loads(line)
|
||||
if d.get("type") == "clone_snapshot":
|
||||
for entry in d.get("per_day", []):
|
||||
per_day_clones[entry["timestamp"]] = entry
|
||||
elif d.get("type") == "view_snapshot":
|
||||
for entry in d.get("per_day", []):
|
||||
per_day_views[entry["timestamp"]] = entry
|
||||
|
||||
tot_clones = sum(e.get("count", 0) for e in per_day_clones.values())
|
||||
tot_uniq_clones = sum(e.get("uniques", 0) for e in per_day_clones.values())
|
||||
tot_views = sum(e.get("count", 0) for e in per_day_views.values())
|
||||
tot_uniq_views = sum(e.get("uniques", 0) for e in per_day_views.values())
|
||||
print(f"clone days observed: {len(per_day_clones)} total clones: {tot_clones:,} total unique cloners: {tot_uniq_clones:,}")
|
||||
print(f"view days observed: {len(per_day_views)} total views: {tot_views:,} total unique viewers: {tot_uniq_views:,}")
|
||||
|
||||
with open(os.environ["GITHUB_OUTPUT"], "a") as out:
|
||||
out.write(f"clones={tot_clones}\n")
|
||||
out.write(f"clone_days={len(per_day_clones)}\n")
|
||||
out.write(f"views={tot_views}\n")
|
||||
out.write(f"view_days={len(per_day_views)}\n")
|
||||
PY
|
||||
|
||||
- name: Commit + push if changed
|
||||
run: |
|
||||
git config user.name "github-actions[bot]"
|
||||
git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
|
||||
if git diff --quiet data/clone-data.rvf; then
|
||||
echo "no changes to commit"
|
||||
exit 0
|
||||
fi
|
||||
git add data/clone-data.rvf
|
||||
git commit -m "chore(traffic): clone snapshot — ${{ steps.agg.outputs.clone_days }} days observed → ${{ steps.agg.outputs.clones }} clones, ${{ steps.agg.outputs.view_days }} view-days → ${{ steps.agg.outputs.views }} views"
|
||||
git push
|
||||
@@ -1,200 +0,0 @@
|
||||
name: Cog HA-Matter Release
|
||||
|
||||
# ADR-116 P8 — Build + sign + bundle the cog-ha-matter cog on a
|
||||
# version tag. Upload to gs://cognitum-apps/ runs only when the
|
||||
# GCP_CREDENTIALS + COGNITUM_OWNER_SIGNING_KEY secrets are set, so
|
||||
# this workflow is safe to merge before the production credentials
|
||||
# land — it'll bundle release artifacts to the workflow run page
|
||||
# either way.
|
||||
|
||||
on:
|
||||
push:
|
||||
tags:
|
||||
- 'cog-ha-matter-v*'
|
||||
workflow_dispatch:
|
||||
inputs:
|
||||
dry_run:
|
||||
description: 'Build + sign + bundle but skip GCS upload'
|
||||
required: false
|
||||
default: 'true'
|
||||
|
||||
env:
|
||||
CARGO_TERM_COLOR: always
|
||||
CRATE: cog-ha-matter
|
||||
|
||||
jobs:
|
||||
build-x86_64:
|
||||
name: Build x86_64
|
||||
runs-on: ubuntu-latest
|
||||
steps:
|
||||
- uses: actions/checkout@v4
|
||||
|
||||
- name: Setup Rust
|
||||
uses: dtolnay/rust-toolchain@stable
|
||||
with:
|
||||
targets: x86_64-unknown-linux-gnu
|
||||
|
||||
- name: Cache cargo registry
|
||||
uses: actions/cache@v4
|
||||
with:
|
||||
path: |
|
||||
~/.cargo/registry
|
||||
~/.cargo/git
|
||||
v2/target
|
||||
key: cog-ha-matter-x86_64-${{ hashFiles('v2/Cargo.lock') }}
|
||||
|
||||
- name: Build release binary
|
||||
working-directory: v2/crates/cog-ha-matter/cog
|
||||
run: make build-x86_64
|
||||
|
||||
- name: Compute SHA-256
|
||||
working-directory: v2/crates/cog-ha-matter/cog
|
||||
run: make sign-x86_64
|
||||
|
||||
- name: Sign with Ed25519 (gated)
|
||||
if: ${{ env.SIGNING_KEY != '' }}
|
||||
env:
|
||||
SIGNING_KEY: ${{ secrets.COGNITUM_OWNER_SIGNING_KEY }}
|
||||
working-directory: v2/crates/cog-ha-matter/cog
|
||||
run: |
|
||||
printf '%s' "$SIGNING_KEY" \
|
||||
| openssl pkeyutl -sign -inkey /dev/stdin -rawin \
|
||||
-in dist/cog-ha-matter-x86_64.sha256 \
|
||||
| base64 -w0 > dist/cog-ha-matter-x86_64.sig
|
||||
echo "Signed cog-ha-matter-x86_64 ($(wc -c < dist/cog-ha-matter-x86_64.sig) bytes)"
|
||||
|
||||
- name: Upload workflow artifact
|
||||
uses: actions/upload-artifact@v4
|
||||
with:
|
||||
name: cog-ha-matter-x86_64
|
||||
path: |
|
||||
v2/crates/cog-ha-matter/cog/dist/cog-ha-matter-x86_64
|
||||
v2/crates/cog-ha-matter/cog/dist/cog-ha-matter-x86_64.sha256
|
||||
v2/crates/cog-ha-matter/cog/dist/cog-ha-matter-x86_64.sig
|
||||
if-no-files-found: warn
|
||||
|
||||
build-arm:
|
||||
name: Build aarch64 (arm)
|
||||
runs-on: ubuntu-latest
|
||||
steps:
|
||||
- uses: actions/checkout@v4
|
||||
|
||||
- name: Setup Rust
|
||||
uses: dtolnay/rust-toolchain@stable
|
||||
with:
|
||||
targets: aarch64-unknown-linux-gnu
|
||||
|
||||
- name: Install cross-compiler
|
||||
run: |
|
||||
sudo apt-get update
|
||||
sudo apt-get install -y gcc-aarch64-linux-gnu
|
||||
|
||||
- name: Cache cargo registry
|
||||
uses: actions/cache@v4
|
||||
with:
|
||||
path: |
|
||||
~/.cargo/registry
|
||||
~/.cargo/git
|
||||
v2/target
|
||||
key: cog-ha-matter-arm-${{ hashFiles('v2/Cargo.lock') }}
|
||||
|
||||
- name: Build release binary
|
||||
working-directory: v2
|
||||
env:
|
||||
CARGO_TARGET_AARCH64_UNKNOWN_LINUX_GNU_LINKER: aarch64-linux-gnu-gcc
|
||||
run: |
|
||||
cargo build -p cog-ha-matter --release --target aarch64-unknown-linux-gnu
|
||||
mkdir -p crates/cog-ha-matter/cog/dist
|
||||
cp target/aarch64-unknown-linux-gnu/release/cog-ha-matter \
|
||||
crates/cog-ha-matter/cog/dist/cog-ha-matter-arm
|
||||
# ^ matches Makefile's `dist/$(CRATE)-arm` so `make sign-arm` finds it
|
||||
|
||||
- name: Compute SHA-256
|
||||
working-directory: v2/crates/cog-ha-matter/cog
|
||||
run: make sign-arm
|
||||
|
||||
- name: Sign with Ed25519 (gated)
|
||||
if: ${{ env.SIGNING_KEY != '' }}
|
||||
env:
|
||||
SIGNING_KEY: ${{ secrets.COGNITUM_OWNER_SIGNING_KEY }}
|
||||
working-directory: v2/crates/cog-ha-matter/cog
|
||||
run: |
|
||||
printf '%s' "$SIGNING_KEY" \
|
||||
| openssl pkeyutl -sign -inkey /dev/stdin -rawin \
|
||||
-in dist/cog-ha-matter-arm.sha256 \
|
||||
| base64 -w0 > dist/cog-ha-matter-arm.sig
|
||||
echo "Signed cog-ha-matter-arm ($(wc -c < dist/cog-ha-matter-arm.sig) bytes)"
|
||||
|
||||
- name: Upload workflow artifact
|
||||
uses: actions/upload-artifact@v4
|
||||
with:
|
||||
name: cog-ha-matter-arm
|
||||
path: |
|
||||
v2/crates/cog-ha-matter/cog/dist/cog-ha-matter-arm
|
||||
v2/crates/cog-ha-matter/cog/dist/cog-ha-matter-arm.sha256
|
||||
v2/crates/cog-ha-matter/cog/dist/cog-ha-matter-arm.sig
|
||||
if-no-files-found: warn
|
||||
|
||||
publish-gcs:
|
||||
name: Upload to GCS (gated)
|
||||
needs: [build-x86_64, build-arm]
|
||||
runs-on: ubuntu-latest
|
||||
# Skip on dry-run dispatch; skip on tags when GCP_CREDENTIALS unset.
|
||||
if: >
|
||||
github.event_name == 'push' &&
|
||||
vars.HAS_GCP_CREDENTIALS == 'true'
|
||||
steps:
|
||||
- uses: actions/checkout@v4
|
||||
|
||||
- name: Download x86_64 artifact
|
||||
uses: actions/download-artifact@v4
|
||||
with:
|
||||
name: cog-ha-matter-x86_64
|
||||
path: dist/
|
||||
|
||||
- name: Download arm artifact
|
||||
uses: actions/download-artifact@v4
|
||||
with:
|
||||
name: cog-ha-matter-arm
|
||||
path: dist/
|
||||
|
||||
- name: Auth to GCP
|
||||
uses: google-github-actions/auth@v2
|
||||
with:
|
||||
credentials_json: ${{ secrets.GCP_CREDENTIALS }}
|
||||
|
||||
- name: Set up gcloud
|
||||
uses: google-github-actions/setup-gcloud@v2
|
||||
|
||||
- name: Upload binaries + sidecars
|
||||
run: |
|
||||
gsutil cp dist/cog-ha-matter-x86_64 gs://cognitum-apps/cogs/x86_64/cog-ha-matter-x86_64
|
||||
gsutil cp dist/cog-ha-matter-x86_64.sha256 gs://cognitum-apps/cogs/x86_64/cog-ha-matter-x86_64.sha256
|
||||
gsutil cp dist/cog-ha-matter-arm gs://cognitum-apps/cogs/arm/cog-ha-matter-arm
|
||||
gsutil cp dist/cog-ha-matter-arm.sha256 gs://cognitum-apps/cogs/arm/cog-ha-matter-arm.sha256
|
||||
if [ -f dist/cog-ha-matter-x86_64.sig ]; then
|
||||
gsutil cp dist/cog-ha-matter-x86_64.sig gs://cognitum-apps/cogs/x86_64/cog-ha-matter-x86_64.sig
|
||||
fi
|
||||
if [ -f dist/cog-ha-matter-arm.sig ]; then
|
||||
gsutil cp dist/cog-ha-matter-arm.sig gs://cognitum-apps/cogs/arm/cog-ha-matter-arm.sig
|
||||
fi
|
||||
|
||||
- name: Print app-registry.json snippet for the cognitum-one PR
|
||||
run: |
|
||||
for arch in arm x86_64; do
|
||||
sha=$(cat dist/cog-cog-ha-matter-$arch.sha256)
|
||||
sig=$([ -f dist/cog-cog-ha-matter-$arch.sig ] && cat dist/cog-cog-ha-matter-$arch.sig || echo "")
|
||||
cat <<EOF
|
||||
--- $arch ---
|
||||
{
|
||||
"id": "ha-matter",
|
||||
"version": "${GITHUB_REF_NAME#cog-ha-matter-v}",
|
||||
"binary_url": "https://storage.googleapis.com/cognitum-apps/cogs/$arch/cog-cog-ha-matter-$arch",
|
||||
"binary_sha256": "$sha",
|
||||
"binary_signature": "$sig",
|
||||
"description": "Home Assistant + Matter Cognitum Seed cog (mDNS + witness chain)",
|
||||
"min_seed_version": "0.6.0",
|
||||
"installable_on": ["$arch"]
|
||||
}
|
||||
EOF
|
||||
done
|
||||
@@ -38,7 +38,7 @@ jobs:
|
||||
echo "version.txt matches the release tag."
|
||||
|
||||
build:
|
||||
name: Build firmware (${{ matrix.target }} / ${{ matrix.variant }})
|
||||
name: Build ESP32-S3 Firmware (${{ matrix.variant }})
|
||||
runs-on: ubuntu-latest
|
||||
container:
|
||||
image: espressif/idf:v5.4
|
||||
@@ -47,27 +47,17 @@ jobs:
|
||||
matrix:
|
||||
include:
|
||||
- variant: 8mb
|
||||
target: esp32s3
|
||||
sdkconfig: sdkconfig.defaults
|
||||
partition_table_name: partitions_display.csv
|
||||
size_limit_kb: 1100
|
||||
artifact_app: esp32-csi-node.bin
|
||||
artifact_pt: partition-table.bin
|
||||
- variant: 4mb
|
||||
target: esp32s3
|
||||
sdkconfig: sdkconfig.defaults.4mb
|
||||
partition_table_name: partitions_4mb.csv
|
||||
size_limit_kb: 1100
|
||||
artifact_app: esp32-csi-node-4mb.bin
|
||||
artifact_pt: partition-table-4mb.bin
|
||||
# ADR-110: ESP32-C6 research target (Wi-Fi 6 / 802.15.4 / TWT / LP-core)
|
||||
- variant: c6-4mb
|
||||
target: esp32c6
|
||||
sdkconfig: sdkconfig.defaults
|
||||
partition_table_name: partitions_4mb.csv
|
||||
size_limit_kb: 1100
|
||||
artifact_app: esp32-csi-node-c6.bin
|
||||
artifact_pt: partition-table-c6.bin
|
||||
|
||||
steps:
|
||||
- uses: actions/checkout@v4
|
||||
@@ -76,22 +66,12 @@ jobs:
|
||||
working-directory: firmware/esp32-csi-node
|
||||
run: |
|
||||
. $IDF_PATH/export.sh
|
||||
# 4mb variant supplies its own sdkconfig.defaults overlay.
|
||||
# c6-4mb variant relies on the auto-applied sdkconfig.defaults.esp32c6
|
||||
# overlay (ESP-IDF auto-loads sdkconfig.defaults.$TARGET when present).
|
||||
if [ "${{ matrix.variant }}" = "4mb" ]; then
|
||||
if [ "${{ matrix.variant }}" != "8mb" ]; then
|
||||
cp "${{ matrix.sdkconfig }}" sdkconfig.defaults
|
||||
fi
|
||||
idf.py set-target ${{ matrix.target }}
|
||||
idf.py set-target esp32s3
|
||||
idf.py build
|
||||
|
||||
- name: Build and run host-side ADR-110 unit tests
|
||||
if: matrix.variant == 'c6-4mb'
|
||||
working-directory: firmware/esp32-csi-node/test
|
||||
run: |
|
||||
make test_adr110
|
||||
./test_adr110
|
||||
|
||||
- name: Verify binary size (< ${{ matrix.size_limit_kb }} KB gate)
|
||||
working-directory: firmware/esp32-csi-node
|
||||
run: |
|
||||
|
||||
@@ -1,110 +0,0 @@
|
||||
name: ADR-115 MQTT integration tests
|
||||
|
||||
# Runs the Mosquitto-broker-backed integration tests for ADR-115's MQTT
|
||||
# publisher. These prove the publisher reaches a real broker, emits the
|
||||
# expected HA-discovery topic shape, and honours --privacy-mode at the
|
||||
# wire boundary (not just in unit-test logic).
|
||||
#
|
||||
# Default `cargo test --workspace` does not run these tests because they
|
||||
# require a broker and pull rumqttc into the build. This workflow opts
|
||||
# into both by setting --features mqtt and RUVIEW_RUN_INTEGRATION=1.
|
||||
|
||||
on:
|
||||
pull_request:
|
||||
paths:
|
||||
- 'v2/crates/wifi-densepose-sensing-server/src/mqtt/**'
|
||||
- 'v2/crates/wifi-densepose-sensing-server/tests/mqtt_integration.rs'
|
||||
- 'v2/crates/wifi-densepose-sensing-server/Cargo.toml'
|
||||
- '.github/workflows/mqtt-integration.yml'
|
||||
push:
|
||||
branches: [main]
|
||||
paths:
|
||||
- 'v2/crates/wifi-densepose-sensing-server/src/mqtt/**'
|
||||
workflow_dispatch: {}
|
||||
|
||||
jobs:
|
||||
mqtt-integration:
|
||||
runs-on: ubuntu-latest
|
||||
timeout-minutes: 20
|
||||
|
||||
# NB: we don't use a `services:` mosquitto container here because the
|
||||
# eclipse-mosquitto:2.x image rejects anonymous connections by default
|
||||
# and GH Actions `services` doesn't easily support mounting a custom
|
||||
# config file. We start mosquitto manually in a step below with an
|
||||
# inline `allow_anonymous true` config.
|
||||
|
||||
env:
|
||||
RUVIEW_RUN_INTEGRATION: "1"
|
||||
RUVIEW_TEST_MQTT_PORT: "11883"
|
||||
CARGO_TERM_COLOR: always
|
||||
RUST_BACKTRACE: 1
|
||||
|
||||
steps:
|
||||
- uses: actions/checkout@v4
|
||||
|
||||
- name: Install mosquitto + clients and start with allow_anonymous
|
||||
run: |
|
||||
sudo apt-get update -qq
|
||||
sudo apt-get install -y mosquitto mosquitto-clients
|
||||
sudo systemctl stop mosquitto || true
|
||||
# Inline config: anon listener on 11883 only — no TLS, no auth,
|
||||
# OK for CI because we test the wire shape, not security.
|
||||
# Production deployments enable mTLS per ADR-115 §3.9.
|
||||
cat > /tmp/mosquitto-ci.conf <<'EOF'
|
||||
listener 11883
|
||||
allow_anonymous true
|
||||
persistence false
|
||||
log_dest stdout
|
||||
EOF
|
||||
mosquitto -c /tmp/mosquitto-ci.conf -d
|
||||
for i in {1..20}; do
|
||||
if mosquitto_pub -h 127.0.0.1 -p 11883 -t healthcheck -m ok -q 0 2>/dev/null; then
|
||||
echo "mosquitto reachable on 11883"; exit 0
|
||||
fi
|
||||
sleep 2
|
||||
done
|
||||
echo "mosquitto never became reachable" >&2
|
||||
tail -50 /var/log/mosquitto/*.log 2>/dev/null || true
|
||||
exit 1
|
||||
|
||||
- name: Install Rust toolchain
|
||||
uses: dtolnay/rust-toolchain@stable
|
||||
with:
|
||||
toolchain: stable
|
||||
|
||||
- name: Cache cargo registry + build
|
||||
uses: Swatinem/rust-cache@v2
|
||||
with:
|
||||
workspaces: v2 -> target
|
||||
|
||||
- name: Validate HA Blueprints
|
||||
run: |
|
||||
python -m pip install --quiet pyyaml
|
||||
python scripts/validate-ha-blueprints.py
|
||||
|
||||
- name: Verify unit tests still pass under --features mqtt
|
||||
working-directory: v2
|
||||
# `cargo test` accepts a single TESTNAME filter, so we run the
|
||||
# whole --lib suite here. That gives us the full 410-test green
|
||||
# bar under --features mqtt (which is more reassuring than
|
||||
# filtering anyway).
|
||||
run: >-
|
||||
cargo test -p wifi-densepose-sensing-server
|
||||
--features mqtt --no-default-features
|
||||
--lib
|
||||
--no-fail-fast
|
||||
|
||||
- name: Run integration tests against mosquitto
|
||||
working-directory: v2
|
||||
run: >-
|
||||
cargo test -p wifi-densepose-sensing-server
|
||||
--features mqtt --no-default-features
|
||||
--test mqtt_integration
|
||||
--no-fail-fast
|
||||
-- --test-threads=1 --nocapture
|
||||
|
||||
- name: Dump broker logs on failure
|
||||
if: failure()
|
||||
run: |
|
||||
docker ps -a
|
||||
docker logs $(docker ps -aqf "ancestor=eclipse-mosquitto:2.0.18") || true
|
||||
@@ -1,286 +0,0 @@
|
||||
# ADR-117 P5 — cibuildwheel + PyPI publish workflow for `wifi-densepose`
|
||||
#
|
||||
# This workflow is **explicitly NOT** triggered on every push. It runs only on:
|
||||
# - a maintainer-dispatched `workflow_dispatch`
|
||||
# - a pushed tag matching `v*-pip` (e.g. `v2.0.0-pip`)
|
||||
#
|
||||
# The reason for the `-pip` tag suffix is that the repo already cuts
|
||||
# `v0.X.Y-esp32` tags for firmware releases (see CLAUDE.md). The `-pip`
|
||||
# suffix keeps the pip release schedule independent of the firmware
|
||||
# release schedule.
|
||||
#
|
||||
# Sequencing on release day (per ADR-117 §7.3):
|
||||
# 1. cut tag `v1.99.0-pip` → publishes the tombstone wheel first
|
||||
# 2. cut tag `v2.0.0-pip` → publishes the PyO3 v2 wheel matrix
|
||||
#
|
||||
# Publishes via the `PYPI_API_TOKEN` GitHub Actions secret. The
|
||||
# token-refresh runbook (GCP Secret Manager → gh secret set) lives in
|
||||
# docs/integrations/pypi-release.md so KICS does not flag the
|
||||
# secret name as a generic-secret literal in the workflow.
|
||||
#
|
||||
# Q3 (witness hash v2 — open in ADR-117 §11.3) MUST be resolved
|
||||
# before the first v2.0.0 publish. When v2 lands, add a parallel
|
||||
# step that verifies the v2 hash against the Rust pipeline.
|
||||
|
||||
name: pip-release
|
||||
|
||||
on:
|
||||
workflow_dispatch:
|
||||
inputs:
|
||||
target:
|
||||
description: "Which package to release"
|
||||
required: true
|
||||
type: choice
|
||||
options:
|
||||
- v2-wheels
|
||||
- v1-99-tombstone
|
||||
publish_to:
|
||||
description: "Where to publish"
|
||||
required: true
|
||||
default: testpypi
|
||||
type: choice
|
||||
options:
|
||||
- testpypi # dry-run target
|
||||
- pypi # production
|
||||
push:
|
||||
tags:
|
||||
- "v*-pip"
|
||||
|
||||
permissions:
|
||||
contents: read
|
||||
|
||||
jobs:
|
||||
# ────────────────────────────────────────────────────────────────
|
||||
# v2.0.0 — cibuildwheel matrix (5 wheels + sdist)
|
||||
# ────────────────────────────────────────────────────────────────
|
||||
|
||||
build-wheels:
|
||||
name: Build ${{ matrix.os }} ${{ matrix.arch }}
|
||||
if: |
|
||||
github.event_name == 'workflow_dispatch' && inputs.target == 'v2-wheels' ||
|
||||
startsWith(github.ref, 'refs/tags/v2.')
|
||||
strategy:
|
||||
fail-fast: false
|
||||
matrix:
|
||||
include:
|
||||
- os: ubuntu-latest
|
||||
arch: x86_64
|
||||
- os: ubuntu-latest
|
||||
arch: aarch64
|
||||
- os: macos-13 # x86_64 runner
|
||||
arch: x86_64
|
||||
- os: macos-14 # arm64 runner
|
||||
arch: arm64
|
||||
- os: windows-latest
|
||||
arch: AMD64
|
||||
runs-on: ${{ matrix.os }}
|
||||
steps:
|
||||
- uses: actions/checkout@v4
|
||||
|
||||
# Linux aarch64 needs QEMU for cross-build on x86_64 runners.
|
||||
- name: Set up QEMU
|
||||
if: matrix.os == 'ubuntu-latest' && matrix.arch == 'aarch64'
|
||||
uses: docker/setup-qemu-action@v3
|
||||
|
||||
# ADR-117 §5.4: abi3-py310 — one binary per OS/arch covers all
|
||||
# Python minor versions ≥ 3.10. Build only cp310 wheels.
|
||||
- name: Build wheels (cibuildwheel)
|
||||
uses: pypa/cibuildwheel@v2.21
|
||||
env:
|
||||
CIBW_BUILD: "cp310-*"
|
||||
CIBW_ARCHS_LINUX: ${{ matrix.arch }}
|
||||
CIBW_ARCHS_MACOS: ${{ matrix.arch }}
|
||||
CIBW_ARCHS_WINDOWS: ${{ matrix.arch }}
|
||||
CIBW_BUILD_FRONTEND: "build"
|
||||
CIBW_BEFORE_BUILD: "pip install maturin>=1.7"
|
||||
# The PyO3 sdist landing depends on the cargo/Rust toolchain
|
||||
# being present. cibuildwheel images carry rustup on Linux
|
||||
# but we also pin a known-good version for reproducibility.
|
||||
CIBW_BEFORE_ALL_LINUX: "curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh -s -- -y --default-toolchain 1.82"
|
||||
CIBW_ENVIRONMENT_LINUX: 'PATH="$HOME/.cargo/bin:$PATH"'
|
||||
# Smoke-test every built wheel before accepting it. Catches
|
||||
# the case where the wheel imports but the compiled symbols
|
||||
# are missing.
|
||||
CIBW_TEST_REQUIRES: "pytest>=8.0"
|
||||
CIBW_TEST_COMMAND: 'python -c "import wifi_densepose; assert wifi_densepose.hello() == \"ok\"; print(wifi_densepose.__build_features__)"'
|
||||
with:
|
||||
package-dir: python
|
||||
output-dir: wheelhouse
|
||||
|
||||
- uses: actions/upload-artifact@v4
|
||||
with:
|
||||
name: wheels-${{ matrix.os }}-${{ matrix.arch }}
|
||||
path: wheelhouse/*.whl
|
||||
if-no-files-found: error
|
||||
|
||||
build-sdist:
|
||||
name: Build v2 sdist
|
||||
if: |
|
||||
github.event_name == 'workflow_dispatch' && inputs.target == 'v2-wheels' ||
|
||||
startsWith(github.ref, 'refs/tags/v2.')
|
||||
runs-on: ubuntu-latest
|
||||
steps:
|
||||
- uses: actions/checkout@v4
|
||||
- name: Install maturin
|
||||
run: pip install maturin>=1.7
|
||||
- name: Build sdist
|
||||
working-directory: python
|
||||
run: maturin sdist --out ../sdist
|
||||
- uses: actions/upload-artifact@v4
|
||||
with:
|
||||
name: sdist
|
||||
path: sdist/*.tar.gz
|
||||
if-no-files-found: error
|
||||
|
||||
# ────────────────────────────────────────────────────────────────
|
||||
# v1.99.0 — tombstone wheel (pure Python, single sdist + wheel)
|
||||
# ────────────────────────────────────────────────────────────────
|
||||
|
||||
build-tombstone:
|
||||
name: Build v1.99.0 tombstone
|
||||
if: |
|
||||
github.event_name == 'workflow_dispatch' && inputs.target == 'v1-99-tombstone' ||
|
||||
startsWith(github.ref, 'refs/tags/v1.99')
|
||||
runs-on: ubuntu-latest
|
||||
steps:
|
||||
- uses: actions/checkout@v4
|
||||
- uses: actions/setup-python@v5
|
||||
with:
|
||||
python-version: '3.12'
|
||||
- name: Install build backend
|
||||
run: python -m pip install --upgrade pip build>=1.2
|
||||
- name: Build sdist + wheel
|
||||
working-directory: python/tombstone
|
||||
run: python -m build --outdir ../../tombstone-dist
|
||||
# Inspect what was actually built — the previous v1.99.0-pip run
|
||||
# showed an `import wifi_densepose` that returned cleanly instead
|
||||
# of raising, even though build logs said `adding 'wifi_densepose/__init__.py'`.
|
||||
# Print the wheel manifest + the __init__.py content so any
|
||||
# future regression is debuggable from the run log alone.
|
||||
- name: Inspect wheel contents
|
||||
run: |
|
||||
set -e
|
||||
WHL=tombstone-dist/wifi_densepose-1.99.0-py3-none-any.whl
|
||||
echo "--- wheel listing ---"
|
||||
python -m zipfile -l "$WHL"
|
||||
echo "--- wifi_densepose/__init__.py inside the wheel ---"
|
||||
python -m zipfile -e "$WHL" /tmp/tomb-inspect
|
||||
cat /tmp/tomb-inspect/wifi_densepose/__init__.py
|
||||
echo "--- size in bytes ---"
|
||||
wc -c /tmp/tomb-inspect/wifi_densepose/__init__.py
|
||||
# Smoke-test in an ISOLATED venv. The previous run's failure
|
||||
# mode was that the ubuntu-latest runner's system `python` had
|
||||
# site-packages picking up something other than the user-installed
|
||||
# wheel, so the import resolved to a different module. A clean
|
||||
# venv removes any ambiguity about which wifi_densepose is loaded.
|
||||
- name: Smoke-test tombstone in isolated venv
|
||||
run: |
|
||||
set -e
|
||||
# Copy the wheel to /tmp BEFORE entering the venv — we must
|
||||
# cd OUT of the repo root because the repo contains a
|
||||
# `wifi_densepose/` directory left over from the legacy v1
|
||||
# source. Python puts cwd at sys.path[0], so an import from
|
||||
# the repo root would resolve to the legacy directory and
|
||||
# bypass the freshly-installed wheel entirely (this was the
|
||||
# silent failure mode of the previous two run attempts).
|
||||
cp tombstone-dist/wifi_densepose-1.99.0-py3-none-any.whl /tmp/
|
||||
python -m venv /tmp/smoke-venv
|
||||
/tmp/smoke-venv/bin/python -m pip install --upgrade pip
|
||||
/tmp/smoke-venv/bin/python -m pip install /tmp/wifi_densepose-1.99.0-py3-none-any.whl
|
||||
cd /tmp # away from the repo root's stray wifi_densepose/
|
||||
/tmp/smoke-venv/bin/python -c "import importlib.util as u; s = u.find_spec('wifi_densepose'); print('Resolved to:', s.origin); print('--- file content ---'); print(open(s.origin).read())"
|
||||
set +e
|
||||
/tmp/smoke-venv/bin/python -c "import wifi_densepose" 2> import-output.txt
|
||||
rc=$?
|
||||
set -e
|
||||
if [ "$rc" -eq 0 ]; then
|
||||
echo "ERROR: tombstone import succeeded — should have raised ImportError"
|
||||
exit 1
|
||||
fi
|
||||
if ! grep -q "github.com/ruvnet/RuView" import-output.txt; then
|
||||
echo "ERROR: tombstone ImportError missing migration URL"
|
||||
cat import-output.txt
|
||||
exit 1
|
||||
fi
|
||||
echo "Tombstone wheel correctly raises ImportError with migration URL."
|
||||
- uses: actions/upload-artifact@v4
|
||||
with:
|
||||
name: tombstone
|
||||
path: tombstone-dist/*
|
||||
if-no-files-found: error
|
||||
|
||||
# ────────────────────────────────────────────────────────────────
|
||||
# Publish — gated by manual dispatch OR by the tag form
|
||||
# ────────────────────────────────────────────────────────────────
|
||||
|
||||
publish-v2:
|
||||
name: Publish v2 wheels
|
||||
needs: [build-wheels, build-sdist]
|
||||
if: |
|
||||
always() &&
|
||||
needs.build-wheels.result == 'success' &&
|
||||
needs.build-sdist.result == 'success' &&
|
||||
(
|
||||
github.event_name == 'workflow_dispatch' && inputs.target == 'v2-wheels' ||
|
||||
startsWith(github.ref, 'refs/tags/v2.')
|
||||
)
|
||||
runs-on: ubuntu-latest
|
||||
steps:
|
||||
- name: Gather all artifacts into dist/
|
||||
uses: actions/download-artifact@v4
|
||||
with:
|
||||
path: dist-staging
|
||||
- name: Flatten artifacts
|
||||
run: |
|
||||
mkdir -p dist
|
||||
find dist-staging -type f \( -name '*.whl' -o -name '*.tar.gz' \) -exec cp -v {} dist/ \;
|
||||
ls -lh dist/
|
||||
- name: Publish to TestPyPI (dry-run target)
|
||||
if: github.event_name == 'workflow_dispatch' && inputs.publish_to == 'testpypi'
|
||||
uses: pypa/gh-action-pypi-publish@release/v1
|
||||
with:
|
||||
repository-url: https://test.pypi.org/legacy/
|
||||
password: ${{ secrets.PYPI_API_TOKEN }}
|
||||
packages-dir: dist
|
||||
skip-existing: true
|
||||
- name: Publish to PyPI
|
||||
if: |
|
||||
startsWith(github.ref, 'refs/tags/v2.') ||
|
||||
(github.event_name == 'workflow_dispatch' && inputs.publish_to == 'pypi')
|
||||
uses: pypa/gh-action-pypi-publish@release/v1
|
||||
with:
|
||||
password: ${{ secrets.PYPI_API_TOKEN }}
|
||||
packages-dir: dist
|
||||
|
||||
publish-tombstone:
|
||||
name: Publish v1.99 tombstone
|
||||
needs: [build-tombstone]
|
||||
if: |
|
||||
always() &&
|
||||
needs.build-tombstone.result == 'success' &&
|
||||
(
|
||||
github.event_name == 'workflow_dispatch' && inputs.target == 'v1-99-tombstone' ||
|
||||
startsWith(github.ref, 'refs/tags/v1.99')
|
||||
)
|
||||
runs-on: ubuntu-latest
|
||||
steps:
|
||||
- uses: actions/download-artifact@v4
|
||||
with:
|
||||
name: tombstone
|
||||
path: dist
|
||||
- name: Publish to TestPyPI (dry-run target)
|
||||
if: github.event_name == 'workflow_dispatch' && inputs.publish_to == 'testpypi'
|
||||
uses: pypa/gh-action-pypi-publish@release/v1
|
||||
with:
|
||||
repository-url: https://test.pypi.org/legacy/
|
||||
password: ${{ secrets.PYPI_API_TOKEN }}
|
||||
packages-dir: dist
|
||||
skip-existing: true
|
||||
- name: Publish to PyPI
|
||||
if: |
|
||||
startsWith(github.ref, 'refs/tags/v1.99') ||
|
||||
(github.event_name == 'workflow_dispatch' && inputs.publish_to == 'pypi')
|
||||
uses: pypa/gh-action-pypi-publish@release/v1
|
||||
with:
|
||||
password: ${{ secrets.PYPI_API_TOKEN }}
|
||||
packages-dir: dist
|
||||
@@ -1,149 +0,0 @@
|
||||
name: ruview-swarm CI guard
|
||||
|
||||
# Dedicated guard for the ADR-148 drone swarm crate (`v2/crates/ruview-swarm`).
|
||||
# The main ci.yml runs `cargo test --workspace --no-default-features`, which
|
||||
# only exercises ruview-swarm's DEFAULT feature set. This guard additionally:
|
||||
# - tests every feature combination (train / ruflo+itar / full)
|
||||
# - fails on ANY clippy warning in the crate's own code (--no-deps)
|
||||
# - asserts the ITAR + publish guards stay in place (USML Cat VIII(h)(12))
|
||||
# - builds the GPU training binary under the `train` feature
|
||||
#
|
||||
# Path-scoped so it only runs when the crate or this workflow changes.
|
||||
|
||||
on:
|
||||
push:
|
||||
branches: [ main, 'feat/*' ]
|
||||
paths:
|
||||
- 'v2/crates/ruview-swarm/**'
|
||||
- '.github/workflows/ruview-swarm-ci.yml'
|
||||
pull_request:
|
||||
paths:
|
||||
- 'v2/crates/ruview-swarm/**'
|
||||
- '.github/workflows/ruview-swarm-ci.yml'
|
||||
workflow_dispatch:
|
||||
|
||||
env:
|
||||
CARGO_TERM_COLOR: always
|
||||
|
||||
jobs:
|
||||
# ── Feature-matrix tests ─────────────────────────────────────────────────
|
||||
tests:
|
||||
name: tests (${{ matrix.features.label }})
|
||||
runs-on: ubuntu-latest
|
||||
strategy:
|
||||
fail-fast: false
|
||||
matrix:
|
||||
features:
|
||||
- { label: 'default', flags: '--no-default-features' }
|
||||
- { label: 'train', flags: '--features train' }
|
||||
- { label: 'ruflo+itar', flags: '--features ruflo,itar-unrestricted' }
|
||||
- { label: 'full+train', flags: '--features full,train' }
|
||||
steps:
|
||||
- uses: actions/checkout@v4
|
||||
- uses: dtolnay/rust-toolchain@stable
|
||||
- name: Cache cargo
|
||||
uses: actions/cache@v4
|
||||
with:
|
||||
path: |
|
||||
~/.cargo/registry
|
||||
~/.cargo/git
|
||||
v2/target
|
||||
key: ${{ runner.os }}-ruview-swarm-${{ hashFiles('v2/Cargo.lock') }}
|
||||
restore-keys: ${{ runner.os }}-ruview-swarm-
|
||||
- name: cargo test -p ruview-swarm ${{ matrix.features.flags }}
|
||||
working-directory: v2
|
||||
run: cargo test -p ruview-swarm ${{ matrix.features.flags }} --lib
|
||||
|
||||
# ── Clippy: zero warnings in the crate's own code ────────────────────────
|
||||
clippy:
|
||||
name: clippy (-D warnings, --no-deps)
|
||||
runs-on: ubuntu-latest
|
||||
steps:
|
||||
- uses: actions/checkout@v4
|
||||
# v2/rust-toolchain.toml pins channel "1.89" with profile "minimal" (no
|
||||
# clippy). dtolnay@stable installs clippy on the floating "stable"
|
||||
# toolchain, but the override makes cargo use the separate "1.89"
|
||||
# toolchain — so `cargo clippy` errors "cargo-clippy is not installed for
|
||||
# 1.89". Install clippy on the pinned toolchain that cargo actually uses.
|
||||
- uses: dtolnay/rust-toolchain@stable
|
||||
with:
|
||||
toolchain: "1.89"
|
||||
components: clippy
|
||||
- name: Cache cargo
|
||||
uses: actions/cache@v4
|
||||
with:
|
||||
path: |
|
||||
~/.cargo/registry
|
||||
~/.cargo/git
|
||||
v2/target
|
||||
key: ${{ runner.os }}-ruview-swarm-clippy-${{ hashFiles('v2/Cargo.lock') }}
|
||||
restore-keys: ${{ runner.os }}-ruview-swarm-clippy-
|
||||
# --no-deps confines linting to ruview-swarm's own source, so pre-existing
|
||||
# warnings in dependency crates don't gate this PR.
|
||||
- name: clippy (default)
|
||||
working-directory: v2
|
||||
run: cargo clippy -p ruview-swarm --no-default-features --no-deps -- -D warnings
|
||||
- name: clippy (full,train)
|
||||
working-directory: v2
|
||||
run: cargo clippy -p ruview-swarm --features full,train --no-deps -- -D warnings
|
||||
|
||||
# ── Build the GPU training binary (train feature) ────────────────────────
|
||||
train-bin:
|
||||
name: build train_marl bin
|
||||
runs-on: ubuntu-latest
|
||||
steps:
|
||||
- uses: actions/checkout@v4
|
||||
- uses: dtolnay/rust-toolchain@stable
|
||||
- name: Cache cargo
|
||||
uses: actions/cache@v4
|
||||
with:
|
||||
path: |
|
||||
~/.cargo/registry
|
||||
~/.cargo/git
|
||||
v2/target
|
||||
key: ${{ runner.os }}-ruview-swarm-bin-${{ hashFiles('v2/Cargo.lock') }}
|
||||
restore-keys: ${{ runner.os }}-ruview-swarm-bin-
|
||||
- name: cargo build --bin train_marl --features train
|
||||
working-directory: v2
|
||||
run: cargo build -p ruview-swarm --features train --bin train_marl
|
||||
- name: train_marl is excluded from the default build
|
||||
working-directory: v2
|
||||
run: |
|
||||
# The training binary requires the `train` feature; a default `--bins`
|
||||
# build must NOT produce it (keeps default/CI builds light + Candle-free).
|
||||
# Remove any prior artifact first so this checks what the DEFAULT build
|
||||
# produces, not a leftover from the train-feature build above.
|
||||
rm -f target/debug/train_marl
|
||||
cargo build -p ruview-swarm --no-default-features --bins
|
||||
if [ -f target/debug/train_marl ]; then
|
||||
echo "ERROR: train_marl built without the 'train' feature" >&2
|
||||
exit 1
|
||||
fi
|
||||
echo "OK: train_marl correctly gated behind the 'train' feature"
|
||||
|
||||
# ── ITAR + publish guards ────────────────────────────────────────────────
|
||||
export-control-guard:
|
||||
name: ITAR / publish guard
|
||||
runs-on: ubuntu-latest
|
||||
steps:
|
||||
- uses: actions/checkout@v4
|
||||
- name: publish = false is present (no accidental crates.io publish)
|
||||
run: |
|
||||
CARGO=v2/crates/ruview-swarm/Cargo.toml
|
||||
if ! grep -qE '^\s*publish\s*=\s*false' "$CARGO"; then
|
||||
echo "ERROR: ruview-swarm Cargo.toml must keep 'publish = false' until" >&2
|
||||
echo " PR merge + dependency publish + ITAR export sign-off." >&2
|
||||
exit 1
|
||||
fi
|
||||
echo "OK: publish = false present"
|
||||
- name: default feature set does NOT enable itar-unrestricted
|
||||
run: |
|
||||
CARGO=v2/crates/ruview-swarm/Cargo.toml
|
||||
# USML Cat VIII(h)(12): swarming coordination must be opt-in, never default.
|
||||
DEFAULT_LINE=$(grep -E '^\s*default\s*=' "$CARGO" || true)
|
||||
echo "default = $DEFAULT_LINE"
|
||||
if echo "$DEFAULT_LINE" | grep -q 'itar-unrestricted'; then
|
||||
echo "ERROR: 'itar-unrestricted' must NOT be in the default feature set" >&2
|
||||
exit 1
|
||||
fi
|
||||
echo "OK: ITAR-gated coordination features are opt-in, not default"
|
||||
@@ -46,10 +46,7 @@ jobs:
|
||||
|
||||
- name: Run Bandit security scan
|
||||
run: |
|
||||
# The Python codebase lives under archive/v1/src (it moved there when
|
||||
# the runtime was rewritten in Rust). Scanning `src/` matched nothing,
|
||||
# so this SAST step was a silent no-op.
|
||||
bandit -r archive/v1/src/ -f sarif -o bandit-results.sarif
|
||||
bandit -r src/ -f sarif -o bandit-results.sarif
|
||||
continue-on-error: true
|
||||
|
||||
- name: Upload Bandit results to GitHub Security
|
||||
@@ -60,20 +57,22 @@ jobs:
|
||||
sarif_file: bandit-results.sarif
|
||||
category: bandit
|
||||
|
||||
# Removed the deprecated `returntocorp/semgrep-action@v1` step: it was
|
||||
# redundant (the pip `semgrep --sarif` below is what feeds GitHub Security;
|
||||
# the action only pushed to the Semgrep cloud app via SEMGREP_APP_TOKEN) and
|
||||
# it pulled `returntocorp/semgrep-agent:v1` from Docker Hub on every run,
|
||||
# which intermittently timed out and turned this check red. The pip semgrep
|
||||
# (installed above) needs no Docker pull. The action's `p/docker` +
|
||||
# `p/kubernetes` rulesets are folded into the command below so coverage is
|
||||
# preserved.
|
||||
- name: Run Semgrep + generate SARIF
|
||||
- name: Run Semgrep security scan
|
||||
continue-on-error: true
|
||||
uses: returntocorp/semgrep-action@v1
|
||||
with:
|
||||
config: >-
|
||||
p/security-audit
|
||||
p/secrets
|
||||
p/python
|
||||
p/docker
|
||||
p/kubernetes
|
||||
env:
|
||||
SEMGREP_APP_TOKEN: ${{ secrets.SEMGREP_APP_TOKEN }}
|
||||
|
||||
- name: Generate Semgrep SARIF
|
||||
run: |
|
||||
semgrep \
|
||||
--config=p/security-audit --config=p/secrets --config=p/python \
|
||||
--config=p/docker --config=p/kubernetes \
|
||||
--sarif --output=semgrep.sarif archive/v1/src/
|
||||
semgrep --config=p/security-audit --config=p/secrets --config=p/python --sarif --output=semgrep.sarif src/
|
||||
continue-on-error: true
|
||||
|
||||
- name: Upload Semgrep results to GitHub Security
|
||||
|
||||
@@ -26,8 +26,6 @@ on:
|
||||
- 'v2/crates/wifi-densepose-signal/**'
|
||||
- 'v2/crates/wifi-densepose-vitals/**'
|
||||
- 'v2/crates/wifi-densepose-wifiscan/**'
|
||||
- 'v2/crates/wifi-densepose-bfld/**'
|
||||
- 'v2/crates/cog-ha-matter/**'
|
||||
- 'v2/Cargo.toml'
|
||||
- 'v2/Cargo.lock'
|
||||
- 'ui/**'
|
||||
@@ -61,16 +59,11 @@ jobs:
|
||||
- uses: docker/setup-buildx-action@v3
|
||||
|
||||
- name: Log in to Docker Hub
|
||||
# Bypassing docker/login-action@v3: the action kept emitting
|
||||
# "malformed HTTP Authorization header" against a known-good
|
||||
# dckr_pat_* token (verified by direct curl against the Hub API).
|
||||
# `docker login --password-stdin` is the documented credential
|
||||
# path and avoids whatever encoding step the action injects.
|
||||
env:
|
||||
DH_USER: ${{ secrets.DOCKERHUB_USERNAME }}
|
||||
DH_TOKEN: ${{ secrets.DOCKERHUB_TOKEN }}
|
||||
run: |
|
||||
printf '%s' "$DH_TOKEN" | docker login docker.io -u "$DH_USER" --password-stdin
|
||||
uses: docker/login-action@v3
|
||||
with:
|
||||
registry: docker.io
|
||||
username: ${{ secrets.DOCKERHUB_USERNAME }}
|
||||
password: ${{ secrets.DOCKERHUB_TOKEN }}
|
||||
|
||||
- name: Log in to ghcr.io
|
||||
uses: docker/login-action@v3
|
||||
|
||||
@@ -1,70 +0,0 @@
|
||||
name: three.js demos → GitHub Pages
|
||||
|
||||
# Publishes the ADR-097 three.js demos under gh-pages/three.js/.
|
||||
# Uses keep_files: true so the existing observatory/, pose-fusion/,
|
||||
# pointcloud/, nvsim/, and root index.html demos are preserved.
|
||||
#
|
||||
# Demos 04 and 05 require a Mixamo "X Bot.fbx" placed in assets/.
|
||||
# That file is intentionally gitignored (license boundary), so this
|
||||
# workflow does NOT ship it. Demos 01-03 work standalone; the index
|
||||
# page documents the FBX requirement honestly.
|
||||
|
||||
on:
|
||||
push:
|
||||
branches: [main]
|
||||
paths:
|
||||
- 'examples/three.js/**'
|
||||
- '.github/workflows/threejs-pages.yml'
|
||||
workflow_dispatch:
|
||||
|
||||
permissions:
|
||||
contents: write
|
||||
|
||||
concurrency:
|
||||
group: threejs-pages
|
||||
cancel-in-progress: true
|
||||
|
||||
jobs:
|
||||
build-and-deploy:
|
||||
runs-on: ubuntu-latest
|
||||
steps:
|
||||
- name: Checkout main
|
||||
uses: actions/checkout@v4
|
||||
|
||||
- name: Stage demos for Pages
|
||||
run: |
|
||||
mkdir -p _site/three.js
|
||||
# Copy everything except the local Python server (CI doesn't need it)
|
||||
# and any stray scratch screenshots.
|
||||
cp -r examples/three.js/demos _site/three.js/demos
|
||||
cp -r examples/three.js/screenshots _site/three.js/screenshots
|
||||
cp examples/three.js/README.md _site/three.js/README.md
|
||||
# An index.html that lists the 5 demos with the FBX caveat.
|
||||
cp examples/three.js/index.html _site/three.js/index.html
|
||||
# Mixamo FBX is gitignored — assets dir won't exist in CI.
|
||||
# Drop an empty placeholder so the relative path 'assets/' resolves
|
||||
# to a directory listing (404 on missing file) instead of an opaque
|
||||
# network error. Browsers showing the 404 path makes the failure
|
||||
# visible to anyone trying demos 04/05 without their own FBX.
|
||||
mkdir -p _site/three.js/assets
|
||||
cat > _site/three.js/assets/README.txt <<'EOF'
|
||||
The Mixamo "X Bot.fbx" required by demos 04-skinned-fbx.html and
|
||||
05-skinned-realtime.html is intentionally not redistributed here.
|
||||
|
||||
Download your own from https://mixamo.com (FBX Binary, T-Pose,
|
||||
Without Skin) and place it here as "X Bot.fbx" if you want to
|
||||
run those demos locally. See examples/three.js/README.md in the
|
||||
repo for context.
|
||||
EOF
|
||||
echo "Staged contents:"
|
||||
ls -R _site/three.js/ | head -30
|
||||
|
||||
- name: Deploy to GitHub Pages
|
||||
uses: peaceiris/actions-gh-pages@v3
|
||||
with:
|
||||
github_token: ${{ secrets.GITHUB_TOKEN }}
|
||||
publish_dir: _site
|
||||
# Critical: preserve observatory/, pose-fusion/, pointcloud/, nvsim/
|
||||
# and the root index.html already on gh-pages.
|
||||
keep_files: true
|
||||
commit_message: 'three.js demos: ${{ github.event.head_commit.message }}'
|
||||
@@ -7,7 +7,6 @@ on:
|
||||
- 'archive/v1/src/core/**'
|
||||
- 'archive/v1/src/hardware/**'
|
||||
- 'archive/v1/data/proof/**'
|
||||
- 'archive/v1/requirements-lock.txt'
|
||||
- '.github/workflows/verify-pipeline.yml'
|
||||
pull_request:
|
||||
branches: [ main, master ]
|
||||
@@ -15,7 +14,6 @@ on:
|
||||
- 'archive/v1/src/core/**'
|
||||
- 'archive/v1/src/hardware/**'
|
||||
- 'archive/v1/data/proof/**'
|
||||
- 'archive/v1/requirements-lock.txt'
|
||||
- '.github/workflows/verify-pipeline.yml'
|
||||
workflow_dispatch:
|
||||
|
||||
|
||||
@@ -261,10 +261,3 @@ v2/crates/rvcsi-node/*.node
|
||||
v2/crates/rvcsi-node/binding.js
|
||||
v2/crates/rvcsi-node/binding.d.ts
|
||||
v2/crates/rvcsi-node/npm/
|
||||
|
||||
# AetherArena private optimization staging — never published until reviewed
|
||||
aether-arena/staging/
|
||||
|
||||
# MM-Fi benchmark dataset archives — large data, fetch separately, never commit
|
||||
assets/MM-Fi/E0*.zip
|
||||
assets/MM-Fi/*.zip
|
||||
|
||||
+1
-50
@@ -7,37 +7,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
|
||||
|
||||
## [Unreleased]
|
||||
|
||||
### Fixed
|
||||
- **Person count no longer leaks up to 10 in heuristic mode — addresses #894.** `field_bridge::occupancy_or_fallback` returned the eigenvalue-based `FieldModel::estimate_occupancy` count **unbounded** (its internal ceiling is 10), while the sibling estimators on the same single-link data — the perturbation-energy fallback right below it and `score_to_person_count` — both cap at 3 ("1-3 for single ESP32"). On noisy / under-calibrated CSI the eigenvalue count inflated, producing the "10 persons reported when 1 present" symptom (seen when `--model` fails to load and the server runs on heuristics). Bounded the eigenvalue path to the shared `MAX_SINGLE_LINK_OCCUPANCY` (3) so every estimator on one link agrees; genuine higher counts come from the multistatic fusion path, not a single-link covariance estimate.
|
||||
- **MQTT multi-node deployments now create one Home-Assistant device per node — closes #898.** After the #872 MQTT wiring landed, the JSON→`VitalsSnapshot` bridge hard-coded a single `node_id` (the MQTT client id) and the publisher used a single `OwnedDiscoveryBuilder`, so every physical node collapsed into one device (`identifiers:["wifi_densepose_wifi-densepose-1"]`), contradicting the "one device per node" docs. The bridge now emits one snapshot per node in the sensing update's `nodes[]` (each with its own `node_id` + RSSI, falling back to a single aggregate snapshot for wifi/simulate sources), and the publisher derives a per-node builder (`OwnedDiscoveryBuilder::for_node`) that publishes discovery + availability lazily on first sight of each `node_id` and routes state to per-node topics — yielding N distinct HA devices with per-node availability/LWT. Unit-tested (distinct nodes → distinct `wifi_densepose_<node>` identifiers); 71 MQTT tests pass.
|
||||
- **Person count no longer pinned to 1 — addresses #803.** The aggregate occupancy reported by the sensing server was derived from `smoothed_person_score`, an EMA-smoothed *activity* score (amplitude variance / motion / spectral energy). That score saturates near a single occupant — one moving person maxes it out — so it cannot discriminate occupancy *count* and stayed clamped at 1 across S3/C6 and the Python/Docker/Rust servers. Meanwhile the count-aware per-node estimates the ESP32 paths already compute (firmware `n_persons`, and the DynamicMinCut `corr_persons`) were stashed in `NodeState::prev_person_count` and then **discarded** by the aggregator (same dead-wiring class as #872). The aggregator now takes `max(activity_count, node_max)` via a unit-tested `aggregate_person_count` helper, so a node positively estimating 2–3 occupants is surfaced instead of overwritten. The fix can only ever *raise* the count when a node reports more people, so the single-occupant case is provably never inflated (regression-guarded by test). **Second half:** the pure-CSI per-node path itself clamped its own estimate — the DynamicMinCut occupancy (`estimate_persons_from_correlation`, 0–3) was mapped to a score via `corr_persons / 3.0`, putting 2 people at 0.667, *just under* the 0.70 up-threshold of `score_to_person_count`, so the per-node count never climbed past 1 (so `node_max` was also stuck at 1 for CSI-only nodes). Replaced it with a threshold-aligned `corr_persons_to_score` mapping (1→0.40, 2→0.74, 3→0.96) whose steady state round-trips back to the same count through the EMA + hysteresis, while still gating transient noise. A convergence test replays the exact EMA loop to prove min-cut=2 now reports 2 (and documents that the old `/3.0` mapping reported 1). Full multi-person accuracy still depends on the underlying estimator quality; this removes the two server-side clamps that masked it. 586 sensing-server tests pass.
|
||||
- **MQTT publisher now actually runs (`--mqtt`) — closes #872.** The `--mqtt*` flags were defined only in `cli::Args` (dead code, referenced nowhere) while the binary parses a *separate* `main::Args` with no mqtt fields, and `main.rs` never started the `mqtt::` publisher — so MQTT/Home-Assistant integration was completely unwired (`--mqtt` errored as an unexpected argument, and even with the Docker image's `--features mqtt` build the publisher never ran). Earlier attempts chased a Docker *rebuild*; the real cause was disconnected *code*. Extracted the flags into a shared `cli::MqttArgs` (`#[command(flatten)]` into both structs), spawn the publisher on `--mqtt`, and bridge the JSON sensing broadcast into the typed `VitalsSnapshot` stream with a defensive `serde_json::Value` mapping. Verified end-to-end against `mosquitto`: 20 HA auto-discovery entities + live state (presence/person-count/…). 577 (default) / 580 (`--features mqtt`) tests pass.
|
||||
- **Mass Casualty triage never reports a survivor with a heartbeat as Deceased (safety) — PR #926.** Both triage paths in `wifi-densepose-mat` — `TriageCalculator::calculate` (`combine_assessments(Absent, None) ⇒ Deceased`) and the detection path `EnsembleClassifier::determine_triage` (`!has_breathing && !has_movement ⇒ Deceased`) — ignored the `heartbeat` field. A survivor with a detectable **pulse** but no sensed breathing/movement (respiratory arrest — the most time-critical *savable* state, Immediate/Red) was therefore reported **Deceased (Black)** and deprioritized for rescue. The domain path was in fact only reachable *because* a heartbeat made `has_vitals()` true, so every "Deceased" was a live person. Both paths now escalate to **Immediate** when a heartbeat is present; total absence of breathing, movement *and* heartbeat is unchanged (domain → `Unknown`, ensemble → `Deceased`). 2 safety regression tests; full MAT suite (177) green.
|
||||
- **Per-node Home-Assistant devices now report each node's *own* presence/motion — PR #918.** After the one-device-per-node fan-out landed, the MQTT bridge still applied the *room-level aggregate* `classification` to every node, so in a multi-node deployment a node watching an empty corner inherited another node's "present" (and `motion_level: "absent"` was mis-mapped to full motion). Each node in the broadcast `nodes[]` already carries its own `classification`; the bridge now reads it per node (extracted into a testable `vitals_snapshots_from_sensing_json`), keeping vitals + person count room-level. 4 unit tests.
|
||||
- **`--model` gives an actionable diagnostic instead of a cryptic magic error — PR #919 (refs #894).** Passing a HuggingFace `ruvnet/wifi-densepose-pretrained` file (`model.safetensors` / `model-q4.bin` / `model.rvf.jsonl`) to `--model` produced `invalid magic at offset 0: … got 0x77455735`, then a silent fall back to heuristics. The load-failure path now detects the format (safetensors / quantized blob / JSONL manifest) and explains that those files are a different format **and** encoder architecture than the RVF binary container the progressive loader expects, pointing to #894. Pure `diagnose_model_load_error` + 4 tests.
|
||||
- **`--export-rvf` no longer silently produces a placeholder model — PR #920.** The `--export-rvf` handler ran *before* `--train`/`--pretrain` and unconditionally wrote placeholder sine-wave weights, so the documented `--train … --export-rvf <path>` workflow short-circuited to a fake model and never trained (while printing "exported successfully"). It now emits the placeholder **container-format demo** only standalone (with a clear warning), and falls through to real training when `--train`/`--pretrain` is set; docs point to `--save-rvf` for the real model. 3 guard tests.
|
||||
|
||||
### Added
|
||||
- **WiFi-CSI pose: efficiency frontier + per-room calibration service** (ADR-150 §3.2–3.6). Two beyond-SOTA results on the MM-Fi benchmark, plus the deployment mechanism that resolves real-world generalization:
|
||||
- **Efficiency frontier** — a **75 K-param model beats published SOTA** (74.3% vs MultiFormer 72.25% torso-PCK@20); every config from `micro` up is Pareto-dominant (smaller *and* more accurate than prior work). Shipped a deployable **int4 edge model (~20 KB, verified 74.08%, 0.135 ms single-thread CPU)** — published at [`ruvnet/wifi-densepose-mmfi-pose/edge`](https://huggingface.co/ruvnet/wifi-densepose-mmfi-pose). See [`docs/benchmarks/wifi-pose-efficiency-frontier.md`](docs/benchmarks/wifi-pose-efficiency-frontier.md).
|
||||
- **Generalization solved by few-shot calibration** — zero-shot cross-subject (~64%) and cross-environment (~10%) are *not* closeable by algorithms (CORAL, DANN, instance-norm, contrastive foundation-pretraining all tested, all failed) or by more training subjects (saturates ~64%). But **~100–200 labeled in-room samples recover SOTA-level pose**: cross-subject 64→76%, **cross-environment 10→73% (60% from just 5 samples)** — deployable as a **~11 KB per-room LoRA adapter** on a frozen shared base. Full empirical chain in ADR-150 §3.2–3.6.
|
||||
- **Calibration service (complete, both model paths, cross-language verified)** — `aether-arena/calibration/`: `calibrate.py` (transformer model, `.npz` adapter) + `infer.py` (verified 3.09%→74.29% on an unseen MM-Fi room), **and `cog_calibrate.py`** which fits a `fc1.a/fc1.b/fc2.a/fc2.b` **safetensors** adapter for the deployed cog conv+MLP model (`pose_v1.safetensors`). Consumed by the Rust product engine: `InferenceEngine::with_adapter()` + `cog-pose-estimation run --config <cfg> --adapter <room.safetensors>`. Self-contained regression tests for both Python producers (`test_calibration.py`, `test_cog_calibration.py`) **plus a cross-language Rust integration test** that loads a real `cog_calibrate.py`-generated adapter fixture and asserts it activates + changes engine output. All green.
|
||||
- **Windows workspace build + test now green** (cross-platform fixes). `wifi-densepose-worldmodel` imported `tokio::net::UnixStream` unconditionally, so `cargo build/test --workspace` failed to compile on Windows (E0432) — now the OccWorld Unix-socket bridge is `#[cfg(unix)]`-gated with a clear non-unix fallback. And `wifi-densepose-bfld`'s `readme_quickstart_uses_canonical_public_api` test checked a multi-line `pipeline\n .process` needle that never matched on a CRLF checkout — now normalizes line endings. Result: **2,682 workspace tests pass / 0 fail on Windows** (the pre-merge gate was previously unrunnable there).
|
||||
- **`ruview-swarm` crate (ADR-148)** — drone swarm control system with hierarchical-mesh topology, Raft consensus, MAPPO multi-agent reinforcement learning, and CSI sensing integration. 14 modules: topology (Raft/Gossip/Mesh), formation control (virtual-structure/leader-follower/Reynolds flocking), RRT-APF path planning, auction+FNN task allocation, MARL actor + PPO training loop, security (MAVLink v2 HMAC-SHA256 signing, UWB anti-spoofing, geofencing, Remote ID, FHSS anti-jamming), 10-state fail-safe machine, and SwarmOrchestrator. ITAR-gated coordination features (USML Category VIII(h)(12)) behind `itar-unrestricted` feature.
|
||||
- **Ruflo integration for `ruview-swarm`** — feature-gated (`ruflo`) AI-agent capability layer connecting to the claude-flow daemon: AgentDB mission memory (`memory_store`/`memory_search`), HNSW pattern learning (`agentdb_pattern-store`/`-search`), AIDefence MAVLink message scanning, and SONA intelligence trajectory hooks. `RufloBackend` trait with `HttpRufloBackend` (JSON-RPC 2.0) and `MockRufloBackend` implementations.
|
||||
|
||||
### Performance
|
||||
- `ruview-swarm` benchmarks (criterion, release): MARL actor inference 3.3 µs, RRT-APF planning 0.043 ms, multi-view CSI fusion 58.5 ns, 3-view localization 1.732 m (beats Wi2SAR 5 m SOTA baseline), 4-drone SAR coverage 223 s for 400×400 m (under 240 s target).
|
||||
|
||||
### Added
|
||||
- **ADR-147 — OccWorld world model integration** (`wifi-densepose-worldmodel` v0.3.0 published to crates.io). 15-frame trajectory prediction at 209 ms / 3.37 GB VRAM on RTX 5080. Phase 3 domain adapter `scripts/ruview_occ_dataset.py` (`RuViewOccDataset`) converts WorldGraph snapshots to OccWorld tensors with indoor class remapping + zero ego-poses (validated). Phase 5 retraining pipeline `scripts/occworld_retrain.py` — VQVAE + transformer fine-tuning on RuView occupancy snapshots. See [ADR-147](docs/adr/ADR-147-nvidia-cosmos-world-foundation-model-integration.md) · [benchmark proof](docs/adr/ADR-147-benchmark-proof.md).
|
||||
|
||||
### Added
|
||||
- **ADR-125 (APPLE-FABRIC) — RuView ↔ Apple Home native HAP bridge proposal + reference impl** (issue #796). New ADR-125 lays out a three-phase plan to expose RuView as a discoverable HomeKit accessory on the LAN so a HomePod (as Home Hub) sees presence / vitals / BFLD-derived events natively — zero Home-Assistant intermediary. Two architectural decisions resolved in the ADR per design review: (1) **one HAP bridge with N child accessories** (single pairing, matches Hue/Eve pattern), and (2) **identity-risk mapping is semantic, not probabilistic** — `identity_risk_score` and Soul-Signature match probability never cross the HAP boundary; instead three thresholded events are exposed (`Unknown Presence`, `Unexpected Occupancy`, `Unrecognized Activity Pattern`) so RuView reads as calm-tech ambient awareness, not surveillance UX. ADR-125 §2.1.a reference impl ships now: `scripts/hap-test-sensor.py` (HAP-1.1 bridge advertised over mDNS, paired with operator's iPhone) + `scripts/c6-presence-watcher.py` (parses ESP32 `RV_FEATURE_STATE_MAGIC = 0xC5110006` UDP packets with IEEE CRC32 validation, hysteresis, and a Python port of `wifi-densepose-bfld::PrivacyClass` that enforces ADR-125 §2.1.d invariant I1 at the HomeKit edge — only `Anonymous` (2) and `Restricted` (3) frames may cross; `Raw`/`Derived` are refused with exit code 2 and the cited ADR clause). Validated end-to-end on real hardware (no mocks): ESP32-C6 on `ruv.net` → UDP/5005 → mac-mini watcher → BFLD gate → HAP bridge → iPhone Home app shows `Unknown Presence` live characteristic flip. **Empirical**: 50-51 valid CRC-passing feature_state packets per 10 s window from the live C6; zero CRC errors. P2 (Rust-native HAP via the `hap` crate, replaces the Python sidecar) and P3 (Matter Controller once `matter-rs` stabilizes) follow.
|
||||
|
||||
### Security
|
||||
- **ESP32 OTA upload now fails closed when no PSK is provisioned** (#596 audit finding — critical, **breaking change for unprovisioned nodes**). `ota_check_auth()` previously returned `true` when `s_ota_psk[0] == '\0'`, so a freshly-flashed node would accept attacker-controlled firmware over plain HTTP on port 8032 from any host on the WiFi. No Secure Boot V2, no signed-image verification — a single LAN call could brick or backdoor a node. The fix rejects every OTA upload until a PSK is written to NVS (the OTA HTTP server still starts so operators can run `provision.py --ota-psk <hex>` over USB-CDC without reflashing). **Operators affected**: any deployment that relied on the unauthenticated OTA endpoint working out of the box now needs to provision a PSK before subsequent OTA pushes will succeed. Boot-time `ESP_LOGW` makes the new posture visible.
|
||||
- **Bearer-token auth accepts the scheme case-insensitively (RFC 6750) — PR #929.** `require_bearer` parsed the `Authorization` header with a case-sensitive `strip_prefix("Bearer ")`, so a *correct* `RUVIEW_API_TOKEN` sent as `Authorization: bearer <token>` (or `BEARER`, or with extra whitespace) was rejected with a confusing 401 — needless friction when enabling auth. The scheme is now matched with `eq_ignore_ascii_case` (per RFC 6750 §2.1 / RFC 7235 §2.1); the token compare is unchanged — still exact and constant-time (`ct_eq`) — so a wrong token or a non-Bearer scheme (`Basic …`) still returns 401. Audited the surrounding code while here: `ct_eq` correctly rejects length mismatch (no prefix-auth bypass) and the middleware fails closed. New `accepts_case_insensitive_bearer_scheme` test.
|
||||
- **Path-traversal vulnerabilities patched in five sensing-server endpoints** (closes #615 — critical). New `wifi_densepose_sensing_server::path_safety::safe_id()` enforces `[A-Za-z0-9._-]` only (no leading `.`, max 64 chars) before any user-controlled identifier reaches a `format!()` building a filesystem path. Applied at:
|
||||
- `POST /api/v1/recording/start` (`recording.rs` — `session_name`)
|
||||
- `GET /api/v1/recording/download/:id` (`recording.rs` — `id`)
|
||||
@@ -91,26 +62,6 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
|
||||
they can be reintroduced with a real implementation.
|
||||
|
||||
### Added
|
||||
- **BFLD — Beamforming Feedback Layer for Detection (ADR-118 umbrella + ADR-119 frame format + ADR-120 privacy class + ADR-121 identity risk scoring + ADR-122 RuView HA/Matter exposure + ADR-123 capture path, [#787](https://github.com/ruvnet/RuView/issues/787)).** New crate `wifi-densepose-bfld` (`v2/crates/wifi-densepose-bfld/`) — the privacy-gated WiFi sensing layer that detects when RF data crosses from "ambient sensing" into "identity record" and **structurally prevents** identity-correlated data from leaving the node. Three invariants enforced by the type system (not policy): **I1** raw BFI never exits the node (`Sink` marker-trait hierarchy + `PrivacyClass::Raw.allows_network() == false`), **I2** identity embedding is in-RAM-only (`IdentityEmbedding` has no `Serialize`/`Clone`/`Copy` + `Drop` zeroizes), **I3** cross-site identity correlation is cryptographically impossible (per-site BLAKE3-keyed `SignatureHasher` with daily epoch rotation; mean cross-site Hamming distance ≥120 bits across 100 trials). Ships the complete operator surface: `BfldPipeline` + `BfldPipelineHandle` (worker-thread variant + `spawn_with_oracle` for Soul Signature deployments), `BfldEvent` with JSON publishing (`"blake3:<hex>"` `rf_signature_hash` format per spec), 4 `privacy_class` levels (Raw/Derived/Anonymous/Restricted) with `PrivacyGate::demote` monotonic transformer + irreversible `apply_privacy_gating`, `CoherenceGate` with ±0.05 hysteresis + 5-second debounce + clock-skew resilience (saturating_sub), `SoulMatchOracle` Recalibrate-exemption trait for enrolled-person deployments. **MQTT/HA surface**: `mqtt_topics::render_events` + `publish_event` (class-gated topic routing — Raw/Derived publish 0 topics, Anonymous publishes 6, Restricted publishes 5 with `identity_risk` stripped), `ha_discovery::render_discovery_payloads` + `publish_discovery` (HA-DISCO config payloads with `availability_topic` integration), `availability` module (`online`/`offline` + LWT-aware `with_lwt` helper for `rumqttc::MqttOptions`), `RumqttPublisher` behind a `mqtt` feature gate with `connect_with_lwt` for broker-side auto-offline. **3 operator HA Blueprints** under `v2/crates/cog-ha-matter/blueprints/bfld/` (presence-driven-lighting, motion-aware-HVAC, identity-risk-anomaly-notification with rolling 7-day z-score). **Two runnable examples** (`bfld_minimal` for in-process consumers, `bfld_handle` for the production worker-thread + bootstrap-then-spawn pattern). **GitHub Actions CI workflow** (`.github/workflows/bfld-mqtt-integration.yml`) spins up `eclipse-mosquitto:2` as a service container so the env-gated `mosquitto_integration` and `rumqttc_lwt` tests run end-to-end in CI. **Performance**: `BfldFrame::to_bytes()` measured at **320,255 frames/sec** debug (6.4× ADR-119 AC7 release target of 50k), header-only at 1,654,517 frames/sec, presence-detection latency p95 = **0.9µs** (~1,000,000× under ADR-119 AC2's 1s target), 9.96 Hz motion-publish rate through `BfldPipelineHandle` (10× ADR-122 AC3 floor). **Coverage**: 327 tests at default features, 101 no_std-compatible, 220+ with `--features mqtt`. CRC-32/ISO-HDLC polynomial pinned against `"123456789" → 0xCBF43926`, public-API surface snapshot pinned across all `pub use` re-exports, `BfldError` Display contract pinned for log-grep monitoring rules, reserved-flag-bits forward-compat round-trip property, `apply_privacy_gating` irreversibility (5-cycle round-trip stress proves stripped fields never resurrect). Companion research dossier in `docs/research/BFLD/` (11 files, 13,544 words). 49-iter implementation chain from scaffold (`feat/adr-118/p1`, `c965e3e6c`) through current head with per-iter progress comments on issue [#787](https://github.com/ruvnet/RuView/issues/787). Try it: `cargo run -p wifi-densepose-bfld --example bfld_handle`.
|
||||
- **SENSE-BRIDGE — rvagent MCP server + ruvector npm + ruflo integration (ADR-124, [#787](https://github.com/ruvnet/RuView/issues/787)).** New npm package `@ruvnet/rvagent` (`tools/ruview-mcp/`) — a dual-transport [Model Context Protocol](https://modelcontextprotocol.io/) server that bridges the RuView WiFi-DensePose sensing stack to AI agents (Claude Code, Cursor, ruflo swarms). **6 of 20 ADR-124 §4.1 tools wired** in this initial release: `ruview.presence.now` (occupancy), `ruview.vitals.get_breathing` / `get_heart_rate` / `get_all` (biometric vitals via `EdgeVitalsMessage` surface, ADR-124 §6 Python ws.py:74-88 parity), `ruview.bfld.last_scan` (latest BFLD event — `identity_risk_score`, `privacy_class`, `n_frames`, `timestamp_ms`), `ruview.bfld.subscribe` (MQTT wildcard subscription with synthetic UUID envelope fallback). **Dual-transport architecture (ADR-124 §3)**: stdio (`npx @ruvnet/rvagent stdio` — recommended for Claude Code / Cursor local flow) + Streamable HTTP (`POST /mcp` bound to `127.0.0.1:3001` by default — for remote ruflo swarms across the Tailscale fleet). **Security model (ADR-124 §6)**: Origin header validation (cross-origin POST → 403), bearer-token auth slot (`RVAGENT_HTTP_TOKEN` → 401), bind default `127.0.0.1` per MCP spec requirement. **Uniform schema validation gate (ADR-124 §3)**: every `CallTool` request runs `zod.safeParse` via `TOOL_INPUT_SCHEMAS` before dispatch; failures throw `McpError(InvalidParams)`. **Full Zod schema barrel (ADR-124 §4.1 + §4.1a)**: `src/schemas/tools.ts` defines all 20 tool input schemas including the 5 RUVIEW-POLICY governance tools (can_access_vitals, can_query_presence, can_subscribe, redact_identity_fields, audit_log). **Python surface parity**: `EdgeVitalsMessage` TypeScript interface mirrors Python ws.py:74-88; ADR-124 §6 parity table drives the field names. **93 tests across 7 suites** (manifest, schemas, validate, tools, http-transport, bfld-tools, vitals-tools) — all green. Try it: `npx @ruvnet/rvagent stdio` (with `RUVIEW_SENSING_SERVER_URL=http://localhost:3000`).
|
||||
- **Home Assistant + Matter integration (ADR-115).** New `--mqtt` and `--matter` flags on `wifi-densepose-sensing-server` expose the full sensing capability set to any Home Assistant install via MQTT auto-discovery (HA-DISCO) and to any Matter controller (Apple Home / Google Home / Alexa / SmartThings) via a built-in Matter Bridge scaffolding (HA-FABRIC, SDK wiring v0.7.1). Includes 21 entity kinds per node — 11 raw signals + 10 inferred semantic primitives (HA-MIND: someone-sleeping, possible-distress, room-active, elderly-inactivity-anomaly, meeting, bathroom, fall-risk, bed-exit, no-movement, multi-room-transition). The semantic primitives run server-side so `--privacy-mode` strips HR/BR/pose values from the wire while still publishing the inferred *states* — the architectural win for healthcare and AAL deployments. Ships **8 starter HA Blueprints** under `examples/ha-blueprints/`, **3 drop-in Lovelace dashboards** under `examples/lovelace/` (including a privacy-mode-compatible healthcare care view), mTLS support, 32 KB payload-size cap, MQTT-wildcard topic-injection rejection, `RUVIEW_MQTT_STRICT_TLS=1` v0.8.0 upgrade path. **420 lib tests** cover the implementation including **~2,560 fuzzed assertions per CI run** (10 proptest cases across wire-boundary security + semantic-bus invariants). Plus mosquitto-backed integration tests in `.github/workflows/mqtt-integration.yml`, criterion benchmarks beating every ADR target by 1.6×–208×, and an ESP32-S3 hardware validation harness (`scripts/validate-esp32-mqtt.sh`) that asserts the full pipeline end-to-end with a witness bundle generator (`scripts/witness-adr-115.sh`) that self-verifies. See [`docs/releases/v0.7.0-mqtt-matter.md`](docs/releases/v0.7.0-mqtt-matter.md), [`docs/integrations/home-assistant.md`](docs/integrations/home-assistant.md), [`docs/integrations/semantic-primitives-metrics.md`](docs/integrations/semantic-primitives-metrics.md), [`docs/integrations/benchmarks.md`](docs/integrations/benchmarks.md), [`docs/adr/ADR-115-home-assistant-integration.md`](docs/adr/ADR-115-home-assistant-integration.md), tracking issue [#776](https://github.com/ruvnet/RuView/issues/776), PR [#778](https://github.com/ruvnet/RuView/pull/778). Matter SDK wiring (P8b) and CSA-certification path (P10) deferred to v0.7.1+ per ADR §9.10. Try it: `cargo run -p wifi-densepose-sensing-server --features mqtt --example mqtt_publisher -- --mqtt --mqtt-host 127.0.0.1`.
|
||||
- **ESP32-C6 firmware target with Wi-Fi 6 / 802.15.4 / TWT / LP-core support ([ADR-110](docs/adr/ADR-110-esp32-c6-firmware-extension.md), #762).** `firmware/esp32-csi-node` now builds for **both** `esp32s3` (existing production node) and `esp32c6` (new research/seed-node target) from the same source tree — pick via `idf.py set-target esp32c6` and ESP-IDF auto-applies the new `sdkconfig.defaults.esp32c6` overlay. Every C6 module is `#ifdef CONFIG_IDF_TARGET_ESP32C6` gated, so the S3 build is byte-identical to today (no regression).
|
||||
- **Wi-Fi 6 HE-LTF subcarrier tagging** — `csi_collector.c` now reads `rx_ctrl.cur_bb_format` and writes the PPDU type (0=HT/legacy, 1=HE-SU, 2=HE-MU, 3=HE-TB) into ADR-018 frame byte 18, plus bandwidth flags (20/40 MHz, STBC, 802.15.4-sync-valid) into byte 19. Bytes 18-19 were previously reserved-zero, so old aggregators read them as before — fully backwards compatible. Magic stays `0xC5110001`. Default on via `CONFIG_CSI_FRAME_HE_TAGGING`. First firmware in the open ESP32 ecosystem to tag CSI frames with 11ax PPDU metadata.
|
||||
- **802.15.4 mesh time-sync** — new `c6_timesync.{h,c}` (262 lines) provides cross-node clock alignment over the C6's separate 802.15.4 radio, freeing WiFi airtime from coordination traffic (directly addresses the ADR-029/030 multistatic synchronization gap). Protocol: lowest EUI-64 wins election, leader broadcasts `TS_BEACON` (`magic=0x54534D45`, leader epoch µs) every 100 ms on channel 15, followers compute `offset = leader_us - local_us` and apply lazily — every CSI frame is stamped with `c6_timesync_get_epoch_us()`. Target alignment ±100 µs. Default on via `CONFIG_C6_TIMESYNC_ENABLE`. Verified initializing at boot on COM6 (`c6_ts: init done: channel=15 EUI=206ef1fffefffe17 leader=yes(candidate)` at +413 ms).
|
||||
- **TWT (Target Wake Time)** — new `c6_twt.{h,c}` (223 lines) wraps `esp_wifi_sta_itwt_setup` from `esp_wifi_he.h` to negotiate an individual TWT agreement with the AP after STA connect. Replaces today's opportunistic CSI capture with a scheduler-bounded one (default wake interval 10 ms = 100 fps cadence). Graceful NACK fallback: when the AP doesn't support 11ax iTWT, the helper logs and returns OK so the device keeps doing opportunistic CSI just like the S3. Teardown on `WIFI_EVENT_STA_DISCONNECTED` keeps the AP's TWT scheduler clean. Gated on `SOC_WIFI_HE_SUPPORT` (auto-set on C6/C5 chips).
|
||||
- **LP-core wake-on-motion hibernation** — new `c6_lp_core.{h,c}` (134 lines) arms the C6 LP RISC-V coprocessor as an always-on motion gate; HP core stays in deep sleep until a configurable GPIO wakes it (ext1 deep-sleep wake source in this initial cut, real LP-core program in follow-up). Targets ≤5 µA hibernation current for battery-powered Cognitum Seed nodes (vs the S3's ~10 µA ULP-FSM floor). Opt-in via `CONFIG_C6_LP_CORE_ENABLE` (default off — only enabled on nodes flashed for battery-powered seed duty).
|
||||
- **Build matrix**: S3 stays `partitions_display.csv` (8 MB + display + WASM), C6 uses `partitions_4mb.csv` (4 MB single OTA, no display, no WASM3, no LCD). C6 final binary 1003 KB (46% partition slack), 9 % smaller than S3 production. Free heap 310 KiB at boot, app_main reached in 343 ms, 802.15.4 stack up in another 70 ms.
|
||||
- **Why this matters**: opens three research surfaces nobody has published yet — Wi-Fi-6 CSI human pose, multistatic CSI clock alignment over a side-channel radio, and TWT-bounded deterministic CSI cadence. The S3 production fleet keeps shipping the existing capabilities; the C6 is the research / battery-seed expansion target.
|
||||
- **Docs**: ADR-110 (186 lines, Status=Accepted), tracking issue [ruvnet/RuView#762](https://github.com/ruvnet/RuView/issues/762) with per-phase progress comments, README hardware table + Quick-Start Option 2b, `docs/user-guide.md` full ESP32-C6 section (build, flash, provision, multi-room time-sync, battery seed mode), full empirical record in [`docs/WITNESS-LOG-110.md`](docs/WITNESS-LOG-110.md) with verified / claimed / bugs-fixed / bugs-found sections.
|
||||
- **Wave 2 follow-up (D1 workaround)**: 5 systematic experiments on 3 live C6 boards confirmed the IDF v5.4 802.15.4 RX path is unfixable from user code (TX works 100 %, RX delivers 0 frames; coex/channel/OpenThread/manual-rearm all ruled out). Pivoted to ESP-NOW for the cross-node sync transport — `main/c6_sync_espnow.{h,c}` is the same TS_BEACON protocol over WiFi peer-to-peer, same `get_epoch_us / is_valid / is_leader` API surface. **120 s single-board soak: 1151 transmits, 0 failures (0.00 %), 9.6 tx/s sustained, no crash or reset.** The 802.15.4 path stays in source as documented-broken (D1) for when the IDF driver gets fixed.
|
||||
- **Host-side dual-pipeline decoder for ADR-018 byte 18-19** (ADR-110 protocol closure):
|
||||
- **Rust** (`v2/crates/wifi-densepose-hardware`): new `PpduType` enum (HtLegacy/HeSu/HeMu/HeTb/Unknown) and `Adr018Flags` struct (bw40/stbc/ldpc/ieee802154_sync_valid) on `CsiMetadata`. 6 new deterministic unit tests; **122/122 hardware-crate tests pass**.
|
||||
- **Python** (`archive/v1/src/hardware/csi_extractor.py`): `HEADER_FMT` extended from `<IBBHIIBB2x` to `<IBBHIIBBBB`; new metadata fields (`ppdu_type`, `he_capable`, `bw40`, `stbc`, `ldpc`, `ieee802154_sync_valid`). 5 new `TestAdr110ByteEncoding` cases; **11/11 parser tests pass**.
|
||||
- Both decoders match the firmware encoder bit-for-bit. Pre-ADR-110 firmware sends zeros that round-trip as `HtLegacy` + default flags — fully backwards compatible.
|
||||
- **Security fix** (`scripts/redact-secrets.py` + `generate-witness-bundle.sh`): the Python proof step was echoing `.env` contents into the bundled `verification-output.log` via Pydantic validation errors. Bundle nuked before push; added a `stdin -> stdout` redaction filter covering common token prefixes, long opaque strings, and long hex runs. Verified zero leaks on rebuild.
|
||||
- **Wave 3 — firmware v0.6.7 (LP-core full + soft-AP HE)**: two software-only unblocks for the hardware-blocked items in WITNESS-LOG-110 §B. (1) **Real LP-core motion-gate program** (`firmware/esp32-csi-node/main/lp_core/main.c` + integration in `c6_lp_core.c`). When `CONFIG_C6_LP_CORE_ENABLE=y`, the LP RISC-V coprocessor now runs a real polling program (configurable cadence via `CONFIG_C6_LP_POLL_PERIOD_US`, default 10 ms) that debounces N consecutive GPIO samples (`CONFIG_C6_LP_DEBOUNCE_SAMPLES`, default 3) and wakes the HP core via `ulp_lp_core_wakeup_main_processor()`. HP entry uses `esp_sleep_enable_ulp_wakeup` + `ESP_SLEEP_WAKEUP_ULP`. Exposes `c6_lp_core_motion_count()` and `c6_lp_core_poll_count()` getters for the witness harness. **Replaces** the v0.6.6 `esp_deep_sleep_enable_gpio_wakeup` ext1 fallback (which floored at ~10 µA, the same as the S3 ULP-FSM). The fallback path stays as the `else` branch so builds without `CONFIG_C6_LP_CORE_ENABLE` keep working unchanged — zero regression for v0.6.6-era fleets. Targets the C6 datasheet ≤5 µA average for battery seed nodes; pending INA/Joulescope measurement to confirm (`WITNESS-LOG-110 §B4`). (2) **Wi-Fi 6 soft-AP with TWT Responder=1** (`c6_softap_he.{h,c}` + `main.c` AP+STA mode switch). When `CONFIG_C6_SOFTAP_HE_ENABLE=y`, one C6 board can act as the iTWT-capable AP the bench is otherwise missing — pair with a second C6-STA board to negotiate real iTWT against a known-cooperative AP and measure deterministic CSI cadence (`WITNESS-LOG-110 §B1/B2`). SSID/PSK/channel configurable via Kconfig defaults or NVS (`softap_ssid`/`softap_psk`/`softap_chan` keys in the `ruview` namespace). Default off so existing nodes are unaffected. **Build artifacts**: S3 8 MB binary 1093 KB (47 % slack), C6 4 MB binary 1019 KB (45 % slack). Tag: `v0.6.7-esp32`.
|
||||
- **Wave 4 — firmware v0.6.8 (ESP-NOW mesh offset smoother)**: `c6_sync_espnow.c` now maintains an in-firmware exponential-moving-average of the cross-board sync offset (α = 1/8, fixed-point shift, ≈ 8-sample window at the 10 Hz beacon rate). New getter `c6_sync_espnow_get_offset_us_smoothed()`. `c6_sync_espnow_get_epoch_us()` now returns timestamps stamped from the smoothed offset once seeded — every downstream CSI-frame consumer gets bounded-jitter alignment for free, no host-side filter required. **Measured on the bench**: 5-min two-board soak (WITNESS-LOG-110 §A0.10) drops raw offset stdev 411.5 µs → smoothed 104.1 µs (**3.95× suppression** on stdev, 4.70× on peak-to-peak range) while preserving the +30 µs/min crystal-drift trajectory within 2 µs/min. **The ADR-110 §2.4 ≤100 µs multistatic alignment target that v0.6.6 designed is now empirically measured, not just stated.** Cross-board beacon match rate 99.56% over 5 min, 0 TX failures. Binary cost: +32 bytes (one int64, one bool, one getter). Diag log adds `smoothed=…` field. Tag: `v0.6.8-esp32`. **Known wiring gap (deferred)**: `csi_serialize_frame` does not yet stamp frames with `c6_sync_espnow_get_epoch_us()` — the ADR-018 frame format has no timestamp field, and adding one is a breaking change that needs an ADR update. Multistatic CSI fusion will require either an ADR-018 v2 with timestamp, or a separate UDP sync packet keyed off the existing flag bit. Tracked in WITNESS-LOG-110 §A0.11.
|
||||
- **Wave 5 — firmware v0.6.9 + v0.7.0 + host wiring (loop iter 8 → iter 26)**: closes the §A0.11 gap and lights up the substrate end-to-end across firmware → host → JSON broadcast. **Firmware**: (a) **v0.6.9-esp32** — `csi_collector.c` emits a 32-byte UDP sync packet (magic `0xC511A110`, distinct from CSI frame magic `0xC5110001`) every `CONFIG_C6_SYNC_EVERY_N_FRAMES` (default 20) CSI frames, carrying `node_id`, `local_us`, mesh-aligned `epoch_us` (from the Wave 4 smoothed offset), and the CSI sequence high-water for host-side pairing. Same UDP socket as CSI; host dispatches by leading magic. Operator-tunable cadence via the new Kconfig knob — N=1 (10 Hz) for tight multistatic, N=200 (~20 s) for low-power seeds. Live-verified on COM9+COM12 (§A0.12): follower reports `local − epoch = 1 163 565 µs`, matches the §A0.10 boot-delta measurement within 285 µs of WiFi MAC TX jitter. (b) **v0.7.0-esp32** — `csi_collector.c:221` ADR-018 byte 19 bit 4 ("cross-node sync valid") now ORs in `c6_sync_espnow_is_valid()` so frames from sync'd ESP-NOW nodes correctly advertise sync (previously only sourced from the broken 802.15.4 path — false-negative bug, §A0.13). Side effect: S3 boards now also set the bit since `c6_sync_espnow` is cross-target. **Host decoders + 25 unit tests**: Python `SyncPacketParser` + `SyncPacket` dataclass with `apply_to_local` / `mesh_aligned_us_for_sequence` / `local_minus_epoch_us` (10 tests in `TestSyncPacketParser`); Rust `wifi_densepose_hardware::SyncPacket` + `SyncPacketFlags` + `SYNC_PACKET_MAGIC` re-exported from the crate root with identical API surface (15 tests in `sync_packet::tests`). **Cross-language conformance gate** (loop iter 21): the same 32-byte canonical hex `10a111c509010600f26db70100000000c5aca501000000001400000000000000` is pinned in both test suites; if either decoder drifts from the wire, exactly one named test fires and points at the moved side. **Sensing-server wiring**: `udp_receiver_task` magic-dispatches `0xC511A110` and stores per-node `latest_sync: Option<SyncPacket>` + `latest_sync_at: Option<Instant>` on `NodeState`. New helpers: `NodeState::mesh_aligned_us(local_us)`, `NodeState::mesh_aligned_us_for_csi_frame(sequence)` (uses the per-node measured fps EMA with 5-sample warmup + 9 s staleness gate), `NodeState::observe_csi_frame_arrival(now)` (feeds `update_csi_fps_ema` α=1/8, called once per accepted CSI frame). 4 fps-EMA tests + 3 NodeSyncSnapshot serialization tests on the binary target. **Public JSON API**: `sensing_update` broadcasts now carry an optional `sync` object per node — `{offset_us, is_leader, is_valid, smoothed, sequence, csi_fps_ema, csi_fps_samples}` — `#[serde(skip_serializing_if = "Option::is_none")]` so non-mesh paths (multi-BSSID scan / synthetic-RSSI fallback / simulation) omit the key entirely. Existing pre-v0.7.0 UI clients ignore it cleanly. Documented in `docs/user-guide.md` "Per-node mesh sync (ADR-110)" section with field table, UI rendering rules, and the timestamp-recovery recipe. **Branch-coordination**: `docs/ADR-110-BRANCH-STATE.md` maps which files each of `adr-110-esp32c6` vs `feat/adr-115-ha-mqtt-matter` touches (regions are disjoint, merges should be clean line-merges). **Verification baselines**: full v2 cargo workspace at **1437 tests passing** (no regression across 17 crate batches), full `wifi-densepose-hardware` crate at **137 tests**. ADR-110 §B substrate is now end-to-end visible to UI clients and ready for ADR-029/030 multistatic CSI fusion consumption.
|
||||
- **Real-time CSI introspection / low-latency tap on `wifi-densepose-sensing-server` (ADR-099).**
|
||||
New `wifi_densepose_sensing_server::introspection` module wires
|
||||
[midstream](https://github.com/ruvnet/midstream)'s `temporal-attractor` (Lyapunov +
|
||||
@@ -435,7 +386,7 @@ Model release (no new firmware binary). Firmware remains at v0.6.0-esp32.
|
||||
- Security fix merged via PR #310.
|
||||
|
||||
### Performance
|
||||
- Presence detection: 100% accuracy on 60,630 overnight samples. *(Retracted — that recording was single-class (one sleeping person, 6,062/6,063 frames "present"), so a constant "yes" scores ~99.98%. Superseded by the honest 82.3% held-out temporal-triplet metric; see [#882](https://github.com/ruvnet/RuView/issues/882). Kept here as the in-place public record.)*
|
||||
- Presence detection: 100% accuracy on 60,630 overnight samples.
|
||||
- Inference: 0.008 ms per sample, 164K embeddings/sec.
|
||||
- Contrastive self-supervised training: 51.6% improvement over baseline.
|
||||
|
||||
|
||||
@@ -8,7 +8,7 @@ Dual codebase: Python v1 (`v1/`) and Rust port (`v2/`).
|
||||
| Crate | Description |
|
||||
|-------|-------------|
|
||||
| `wifi-densepose-core` | Core types, traits, error types, CSI frame primitives |
|
||||
| `wifi-densepose-signal` | SOTA signal processing + RuvSense multistatic sensing (16 modules) |
|
||||
| `wifi-densepose-signal` | SOTA signal processing + RuvSense multistatic sensing (14 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 |
|
||||
@@ -21,7 +21,6 @@ Dual codebase: Python v1 (`v1/`) and Rust port (`v2/`).
|
||||
| `wifi-densepose-vitals` | ESP32 CSI-grade vital sign extraction (ADR-021) |
|
||||
| `nvsim` | Deterministic NV-diamond magnetometer pipeline simulator (ADR-089) — standalone leaf, WASM-ready |
|
||||
| `vendor/rvcsi` (submodule) | **rvCSI** — edge RF sensing runtime (ADR-095/096): 9 crates (`rvcsi-core`/`-dsp`/`-events`/`-adapter-file`/`-adapter-nexmon`/`-ruvector`/`-runtime`/`-node`/`-cli`). Lives in its own repo ([github.com/ruvnet/rvcsi](https://github.com/ruvnet/rvcsi)), vendored here under `vendor/rvcsi`, published to crates.io as `rvcsi-* 0.3.x` and to npm as `@ruv/rvcsi`. Not a `v2/` workspace member — depend on the published crates (or the submodule's `crates/rvcsi-*` paths). Normalized `CsiFrame`/`CsiWindow`/`CsiEvent` schema, validate-before-FFI, reusable DSP, typed confidence-scored events, the napi-c Nexmon shim (real nexmon_csi `.pcap` from a Raspberry Pi 5 / 4 / 3B+ — BCM43455c0), the napi-rs SDK, the `rvcsi` CLI, a Claude Code plugin. |
|
||||
| `ruview-swarm` | Drone swarm control system (ADR-148) — hierarchical-mesh topology, Raft consensus, MARL, CSI sensing payload, MAVLink/PX4 compat, Ruflo AI-agent integration |
|
||||
|
||||
### RuvSense Modules (`signal/src/ruvsense/`)
|
||||
| Module | Purpose |
|
||||
@@ -39,8 +38,6 @@ Dual codebase: Python v1 (`v1/`) and Rust port (`v2/`).
|
||||
| `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) |
|
||||
| `calibration.rs` | ADR-135 empty-room baseline (Welford amplitude + von Mises phase, drift trigger) |
|
||||
|
||||
### Cross-Viewpoint Fusion (`ruvector/src/viewpoint/`)
|
||||
| Module | Purpose |
|
||||
@@ -71,15 +68,14 @@ All 5 ruvector crates integrated in workspace:
|
||||
- ADR-030: RuvSense persistent field model (Proposed)
|
||||
- ADR-031: RuView sensing-first RF mode (Proposed)
|
||||
- ADR-032: Multistatic mesh security hardening (Proposed)
|
||||
- ADR-148: Drone swarm control system / `ruview-swarm` (In Progress)
|
||||
|
||||
### 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 (8MB flash) | 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 |
|
||||
| ESP32-C6 + Seeed MR60BHA2 | COM4 | RISC-V + 60 GHz FMCW | mmWave HR/BR/presence | ~$15 |
|
||||
| HLK-LD2410 | — | 24 GHz FMCW | Presence + distance | ~$3 |
|
||||
|
||||
**Not supported:** ESP32 (original), ESP32-C3 — single-core, can't run CSI DSP pipeline.
|
||||
|
||||
@@ -1,26 +1,22 @@
|
||||
# π RuView
|
||||
|
||||
<p align="center">
|
||||
<a href="https://cognitum.one/seed">
|
||||
<img src="assets/ruview-seed.png" alt="RuView - WiFi DensePose" width="100%">
|
||||
</a>
|
||||
</p>
|
||||
<p align="center">
|
||||
<a href="https://cognitum.one/seed">
|
||||
<img src="assets/seed.png" alt="Cognitum Seed" width="100%">
|
||||
<a href="https://x.com/rUv/status/2037556932802761004">
|
||||
<img src="assets/ruview-small-gemini.jpg" alt="RuView - WiFi DensePose" width="100%">
|
||||
</a>
|
||||
</p>
|
||||
|
||||
> **Beta Software** — Under active development. APIs and firmware may change. Known limitations:
|
||||
> - ESP32-C3 and original ESP32 are not supported (single-core, insufficient for CSI DSP)
|
||||
> - Single ESP32 deployments have limited spatial resolution — use 2+ nodes or add a [Cognitum Seed](https://cognitum.one) for best results
|
||||
> - Camera-free pose accuracy is limited (PCK@20 ≈ 2.5% with proxy labels) — [camera ground-truth training](docs/adr/ADR-079-camera-ground-truth-training.md) targets **35%+ PCK@20**; the pipeline is implemented, but the data-collection and evaluation phases (ADR-079 P7–P9) are still pending, so no measured camera-supervised PCK@20 has been published yet
|
||||
>
|
||||
> Contributions and bug reports welcome at [Issues](https://github.com/ruvnet/RuView/issues).
|
||||
|
||||
## **See through walls with WiFi** ##
|
||||
|
||||
**Turn ordinary WiFi into a spatial intelligence / sensing system.** Detect people, measure breathing and heart rate, track movement, and monitor rooms — through walls, in the dark, with no cameras or wearables. Just physics.
|
||||
|
||||
Works natively with the four major smart-home ecosystems: **[Home Assistant](docs/integrations/home-assistant.md)** via the HA-DISCO MQTT publisher, **[Apple Home & HomePod](docs/user-guide-apple-homepod.md)** as a discoverable HAP-1.1 bridge, **[Google Home](docs/integrations/home-assistant.md)** + **[Amazon Alexa](docs/integrations/home-assistant.md)** via the same HA bridge or a [Matter](docs/adr/ADR-122-bfld-ruview-ha-matter-exposure.md) endpoint. Siri, Google Assistant, and Alexa can voice presence and vitals by room with zero custom skills.
|
||||
|
||||
[](docs/integrations/home-assistant.md) [](docs/adr/ADR-122-bfld-ruview-ha-matter-exposure.md) [](docs/user-guide-apple-homepod.md) [](docs/integrations/home-assistant.md) [](docs/integrations/home-assistant.md)
|
||||
|
||||
> Drop into any **Home Assistant** install with one `--mqtt` flag. Or pair into **Apple Home / Google Home / Alexa / SmartThings** as a Matter Bridge. Ships 21 entities per node (11 raw signals + 10 inferred semantic states: someone-sleeping, possible-distress, room-active, elderly-inactivity-anomaly, meeting-in-progress, bathroom-occupied, fall-risk-elevated, bed-exit, no-movement, multi-room-transition) plus 3 starter HA Blueprints. See [`docs/integrations/home-assistant.md`](docs/integrations/home-assistant.md) · [ADR-115](docs/adr/ADR-115-home-assistant-integration.md).
|
||||
|
||||
### π RuView is a WiFi sensing platform that turns radio signals into spatial intelligence.
|
||||
|
||||
Every WiFi router already fills your space with radio waves. When people move, breathe, or even sit still, they disturb those waves in measurable ways. RuView captures these disturbances using Channel State Information (CSI) from low-cost ESP32 sensors and turns them into actionable data: who's there, what they're doing, and whether they're okay.
|
||||
@@ -36,7 +32,7 @@ Built on [RuVector](https://github.com/ruvnet/ruvector/) and [Cognitum Seed](htt
|
||||
|
||||
The system learns each environment locally using spiking neural networks that adapt in under 30 seconds, with multi-frequency mesh scanning across 6 WiFi channels that uses your neighbors' routers as free radar illuminators. Every measurement is cryptographically attested via an Ed25519 witness chain.
|
||||
|
||||
RuView turns ordinary WiFi into a contactless sensor. A $9 ESP32 board reads the radio reflections off the people in a room, and a small pretrained model — published on Hugging Face at [`ruvnet/wifi-densepose-pretrained`](https://huggingface.co/ruvnet/wifi-densepose-pretrained) — tells you who's there, how they're breathing, and how their heart rate is trending. The model fits in 8 KB (4-bit quantized) and runs in microseconds on a Raspberry Pi. (The [v2 encoder](https://huggingface.co/ruvnet/wifi-densepose-pretrained) reports an honest, label-free held-out **temporal-triplet accuracy of 82.3%** — up from 66.4% raw; the older "100% presence" figure was measured on a single-class recording and has been retracted in favor of this.) No cameras, no wearables, no app on the user's phone.
|
||||
RuView **ships pretrained CSI weights on Hugging Face** at [`ruvnet/wifi-densepose-pretrained`](https://huggingface.co/ruvnet/wifi-densepose-pretrained) — a self-supervised contrastive CSI encoder (128-dim embeddings, 12.2M training steps, 60K frames) + a presence-detection head reporting 100% accuracy on the validation set + per-node LoRA adapters. Models are released as `.safetensors`, 4-bit/8-bit/2-bit quantized `.bin` (4 KB–16 KB), and a JSONL RVF container. The Python training and evaluation tooling consumes these today via `safetensors`. **Pending wiring**: the sensing-server's `--model` flag still expects binary RVF, so live-server consumption of the JSONL bundle is gated on a JSONL adapter (or a re-publish in binary RVF) — see [Pretrained model on Hugging Face](#-pretrained-model-on-hugging-face) below for the workaround. **Not yet released**: a 17-keypoint pose-estimation model — training pipeline is implemented (WiFlow + AETHER + MERIDIAN heads) but camera-supervised fine-tune phases P7–P9 of [ADR-079](docs/adr/ADR-079-camera-supervised-pose-finetune.md) are `Pending`, tracked in [#509](https://github.com/ruvnet/RuView/issues/509). The live sensing server therefore drives the on-screen output from signal-based DSP heuristics today.
|
||||
|
||||
### Built for low-power edge applications
|
||||
|
||||
@@ -49,28 +45,26 @@ RuView turns ordinary WiFi into a contactless sensor. A $9 ESP32 board reads the
|
||||
[](#vital-sign-detection)
|
||||
[](#esp32-s3-hardware-pipeline)
|
||||
[](https://crates.io/crates/wifi-densepose-ruvector)
|
||||
[](#-edge-module-catalog)
|
||||
|
||||
|
||||
> | What | How | Speed / scale |
|
||||
> |------|-----|---------------|
|
||||
> | 🫁 **Breathing rate** | Bandpass 0.1–0.5 Hz on wrapped phase, circular variance, zero-crossing BPM ([#593](https://github.com/ruvnet/RuView/issues/593)) | 6–30 BPM, real-time |
|
||||
> | 💓 **Heart rate** | Bandpass 0.8–2.0 Hz, zero-crossing BPM | 40–120 BPM, real-time |
|
||||
> | 👤 **Presence detection** | Trained head on Hugging Face ([`ruvnet/wifi-densepose-pretrained`](https://huggingface.co/ruvnet/wifi-densepose-pretrained); v2 encoder = 82.3% held-out temporal-triplet acc, honestly re-benchmarked) + a phase-variance fallback that needs no model | < 1 ms, ~30 s ambient calibration |
|
||||
> | 🧬 **CSI embeddings** | 128-dim contrastive encoder shipped on Hugging Face, 4-bit quantised variant fits in 8 KB | **164,183 emb/s** on M4 Pro |
|
||||
> | 🦴 **17-keypoint pose estimation** | `cog-pose-estimation` Cog v0.0.1 — signed aarch64 + x86_64 binaries on GCS, loads `pose_v1.safetensors` via Candle. Train your own from paired data in 2.1 s on an RTX 5080 ([ADR-101](docs/adr/ADR-101-pose-estimation-cog.md), [benchmarks](docs/benchmarks/pose-estimation-cog.md)). **SOTA on MM-Fi:** [`ruvnet/wifi-densepose-mmfi-pose`](https://huggingface.co/ruvnet/wifi-densepose-mmfi-pose) hits **82.69% torso-PCK@20** (ensemble 83.59%), beating MultiFormer (72.25%) and CSI2Pose (68.41%) on the matched MM-Fi `random_split` protocol — self-corrected and auditable on [AetherArena](https://huggingface.co/spaces/ruvnet/aether-arena) | 8.4 ms cold-start on a Pi 5 |
|
||||
> | 🚶 **Motion / activity** | Motion-band power + phase acceleration | Real-time |
|
||||
> | 🤸 **Fall detection** | Phase-acceleration threshold + 3-frame debounce + 5 s cooldown ([#263](https://github.com/ruvnet/RuView/issues/263)) | < 200 ms |
|
||||
> | 🧮 **Multi-person count** | Adaptive P95 normalisation + runtime-tunable dedup factor (`/api/v1/config/dedup-factor`, [#491](https://github.com/ruvnet/RuView/pull/491)). Six specialised learned counters available as Cogs: `occupancy-zones`, `elevator-count`, `queue-length`, `customer-flow`, `clean-room`, `person-matching` | Real-time, self-calibrating |
|
||||
> | 🌍 **World model prediction** | OccWorld TransVQVAE — 15-frame future occupancy prediction, 209 ms inference, 3.4 GB VRAM on RTX 5080; fine-tune on your space with `occworld_retrain.py` ([ADR-147](docs/adr/ADR-147-nvidia-cosmos-world-foundation-model-integration.md)) | 15 frames × 200×200×16 vox |
|
||||
> | 🧱 **Through-wall sensing** | Fresnel-zone geometry + multipath modeling | Up to ~5 m, signal-dependent |
|
||||
> | 🧠 **Edge intelligence** | **105-cog catalog** ([ADR-102](docs/adr/ADR-102-edge-module-registry.md)) live from `app-registry.json` — health, security, building, retail, industrial, research, AI, swarm, signal, network, and developer modules. Optional Cognitum Seed adds persistent vector store + kNN + witness chain | $140 total BOM |
|
||||
> | 🎯 **Camera-free pre-training** | Self-supervised contrastive encoder, 12.2M training steps on 60K frames, shipped on Hugging Face | 84 s/epoch retrain on M4 Pro |
|
||||
> | 📷 **Camera-supervised fine-tune** | MediaPipe + ESP32 CSI paired training, end-to-end Candle pipeline on RTX 5080 ([ADR-079](docs/adr/ADR-079-camera-supervised-pose-finetune.md)) | 2.1 s for 400 epochs (~5 ms/epoch) |
|
||||
> | 📡 **Multi-frequency mesh** | Channel hopping across 6 bands, TDM slot scheduling ([ADR-029](docs/adr/ADR-029-multifrequency-mesh.md)) | 3× sensing bandwidth |
|
||||
> | 🌐 **3D point cloud fusion** | Camera depth (MiDaS) + WiFi CSI + mmWave radar → unified spatial model | 22 ms pipeline · 19K+ points/frame |
|
||||
> | What | Status | How | Speed |
|
||||
> |------|--------|-----|-------|
|
||||
> | 🫁 **Breathing rate** | ✅ Works today | Bandpass 0.1-0.5 Hz → zero-crossing BPM, circular variance on wrapped phase ([#593](https://github.com/ruvnet/RuView/issues/593)) | 6-30 BPM |
|
||||
> | 💓 **Heart rate** | ✅ Works today | Bandpass 0.8-2.0 Hz → zero-crossing BPM | 40-120 BPM (needs good SNR) |
|
||||
> | 👤 **Presence detection** | ✅ Heuristic in server · 🤗 Trained head on HF (loader wiring pending) | Live server uses phase-variance vs adaptive threshold (60 s ambient calibration). A trained `presence-head.json` reporting 100% validation accuracy is published in [`ruvnet/wifi-densepose-pretrained`](https://huggingface.co/ruvnet/wifi-densepose-pretrained) but the sensing-server's `--model` loader only accepts binary RVF today — JSONL adapter pending. | <1 ms heuristic |
|
||||
> | 🧬 **CSI embeddings** | 🤗 Trained encoder on HF | 128-dim contrastive encoder, **164,183 emb/s** on M4 Pro. Usable today from Python / training via `model.safetensors`; sensing-server consumption pending the same JSONL loader gap as above. | 8 KB q4 fits ESP32 SRAM |
|
||||
> | 🚶 **Motion / activity** | ✅ Works today | Motion-band power + phase acceleration | Real-time |
|
||||
> | 🤸 **Fall detection** | ✅ Works today | Phase acceleration > threshold + 3-frame debounce + 5 s cooldown ([#263](https://github.com/ruvnet/RuView/issues/263)) | < 200 ms |
|
||||
> | 🧮 **Multi-person slot count** | ⚠️ Heuristic, not learned | Subcarrier diversity divided by 2 (capped). **Not** a learned counter — see [firmware README](firmware/esp32-csi-node/README.md#tier-2--full-pipeline-stable) "Tier 2 caveats". Adaptive normalisation in [#491](https://github.com/ruvnet/RuView/pull/491). | Real-time |
|
||||
> | 🦴 **17-keypoint pose estimation** | 🔬 Pipeline only, no shipped weights | Training infrastructure complete (WiFlow + AETHER + MERIDIAN heads); the published HF model is presence + embeddings, not keypoints. Tracked in [#509](https://github.com/ruvnet/RuView/issues/509). | Pending data collection |
|
||||
> | 🧱 **Through-wall sensing** | ✅ Works today | Fresnel zone geometry + multipath modeling | Up to ~5m signal-dependent |
|
||||
> | 🧠 **Edge intelligence** | ✅ Works today | Optional Cognitum Seed for persistent vector store + kNN + witness chain | $140 total BOM |
|
||||
> | 🎯 **Camera-free pre-training** | ✅ Shipped weights on HF | Self-supervised contrastive encoder, 12.2M training steps on 60K frames. See [`ruvnet/wifi-densepose-pretrained`](https://huggingface.co/ruvnet/wifi-densepose-pretrained). | 84 s/epoch retrain on M4 Pro |
|
||||
> | 📷 **Camera-supervised fine-tune** | 🔬 Pipeline only | MediaPipe + ESP32 CSI paired training, [ADR-079](docs/adr/ADR-079-camera-supervised-pose-finetune.md). Target **35%+ PCK@20**. P7–P9 (data + train + eval) `Pending`. | ~19 min/epoch on laptop |
|
||||
> | 📡 **Multi-frequency mesh** | ✅ Works today | Channel hopping across 6 bands, TDM slot scheduling (ADR-029) | 3x sensing bandwidth |
|
||||
> | 🌐 **3D point cloud fusion** | 🔬 Reference impl | Camera depth (MiDaS) + WiFi CSI + mmWave radar → unified spatial model. Requires camera. | 22 ms pipeline · 19K+ points/frame |
|
||||
>
|
||||
> Browse the full 105-module catalog (with practical descriptions, sizes, and difficulty) below in [🧩 Edge Module Catalog](#-edge-module-catalog), or visit [seed.cognitum.one/store](https://seed.cognitum.one/store).
|
||||
> Legend: ✅ shipped + tested on hardware (some have learned weights on [HF](https://huggingface.co/ruvnet/wifi-densepose-pretrained), others are deterministic DSP) · ⚠️ ships and runs, but is a heuristic/threshold (not a learned classifier) — accuracy depends on calibration · 🔬 implementation + tests in repo, weights/data/eval pending
|
||||
>
|
||||
> 🤗 **Pretrained weights**: download from [`ruvnet/wifi-densepose-pretrained`](https://huggingface.co/ruvnet/wifi-densepose-pretrained) — see [Loading the pretrained model](#loading-the-pretrained-model) below for one-command setup.
|
||||
|
||||
@@ -80,7 +74,7 @@ docker pull ruvnet/wifi-densepose:latest
|
||||
docker run -p 3000:3000 ruvnet/wifi-densepose:latest
|
||||
# Open http://localhost:3000
|
||||
|
||||
# Option 2a: Live sensing with ESP32-S3 hardware ($9)
|
||||
# Option 2: Live sensing with ESP32-S3 hardware ($9)
|
||||
# Flash firmware, provision WiFi, and start sensing:
|
||||
python -m esptool --chip esp32s3 --port COM9 --baud 460800 \
|
||||
write_flash 0x0 bootloader.bin 0x8000 partition-table.bin \
|
||||
@@ -88,39 +82,13 @@ python -m esptool --chip esp32s3 --port COM9 --baud 460800 \
|
||||
python firmware/esp32-csi-node/provision.py --port COM9 \
|
||||
--ssid "YourWiFi" --password "secret" --target-ip 192.168.1.20
|
||||
|
||||
# Option 2b: WiFi 6 + 802.15.4 research sensing with ESP32-C6 ($6-10, ADR-110)
|
||||
# Same csi-node firmware compiled for the C6 target — picks up the C6
|
||||
# overlay (sdkconfig.defaults.esp32c6) automatically.
|
||||
cd firmware/esp32-csi-node
|
||||
idf.py set-target esp32c6 && idf.py build
|
||||
idf.py -p COM6 flash
|
||||
# C6 boot extras (vs S3): HE-LTF subcarrier tagging in ADR-018 bytes 18-19,
|
||||
# 802.15.4 mesh time-sync on channel 15, TWT setup when the AP supports it,
|
||||
# opt-in LP-core wake-on-motion for ~5 µA battery seed nodes.
|
||||
# v0.6.7 adds: real LP-core RISC-V motion-gate program (debounce + motion
|
||||
# counter) and a Wi-Fi 6 soft-AP with TWT Responder so two C6 boards can
|
||||
# benchmark real iTWT without buying an 11ax router. Both default off,
|
||||
# flip CONFIG_C6_{LP_CORE,SOFTAP_HE}_ENABLE to turn them on.
|
||||
|
||||
# Option 3: Full system with Cognitum Seed ($140)
|
||||
# ESP32 streams CSI → bridge forwards to Seed for persistent storage + kNN + witness chain
|
||||
node scripts/rf-scan.js --port 5006 # Live RF room scan
|
||||
node scripts/snn-csi-processor.js --port 5006 # SNN real-time learning
|
||||
node scripts/mincut-person-counter.js --port 5006 # Correct person counting
|
||||
|
||||
# Option 4: Python — live on PyPI (ADR-117)
|
||||
pip install ruview # or: pip install wifi-densepose
|
||||
# Both ship the same compiled PyO3 wheel (~250 KB, abi3-py310, Linux/macOS/Windows).
|
||||
# Add [client] for the asyncio WebSocket + paho-mqtt clients:
|
||||
pip install "ruview[client]" # or: pip install "wifi-densepose[client]"
|
||||
|
||||
# from ruview import BreathingExtractor, HeartRateExtractor # equivalent to:
|
||||
# from wifi_densepose import BreathingExtractor, HeartRateExtractor
|
||||
# from ruview.client import SensingClient, RuViewMqttClient
|
||||
```
|
||||
|
||||
[](https://pypi.org/project/ruview/) [](https://pypi.org/project/wifi-densepose/)
|
||||
|
||||
> [!NOTE]
|
||||
> **CSI-capable hardware recommended.** Presence, vital signs, through-wall sensing, and all advanced capabilities require Channel State Information (CSI) from an ESP32-S3 ($9) or research NIC. The Docker image runs with simulated data for evaluation. Consumer WiFi laptops provide RSSI-only presence detection.
|
||||
|
||||
@@ -128,9 +96,8 @@ pip install "ruview[client]" # or: pip install "wifi-densepose[clie
|
||||
>
|
||||
> | Option | Hardware | Cost | Full CSI | Capabilities |
|
||||
> |--------|----------|------|----------|-------------|
|
||||
> | **ESP32 + Cognitum Seed** (recommended) | ESP32-S3 + [Cognitum Seed](https://cognitum.one) | ~$140 | Yes | Presence, motion, breathing, heart rate, fall detection, multi-person counting, 17-keypoint pose (signed Cog binary), 105-cog catalog, persistent vector store, kNN search, witness chain, MCP proxy |
|
||||
> | **ESP32 Mesh** | 3-6× ESP32-S3 + WiFi router | ~$54 | Yes | Same capabilities as above without the persistent-memory features |
|
||||
> | **ESP32-C6 research node** ([ADR-110](docs/adr/ADR-110-esp32-c6-firmware-extension.md), [witness](docs/WITNESS-LOG-110.md), [reviewer guide](docs/ADR-110-REVIEW-GUIDE.md), [firmware v0.7.0](https://github.com/ruvnet/RuView/releases/tag/v0.7.0-esp32)) | ESP32-C6-DevKit ($6–10) | ~$10 | Yes (Wi-Fi 6 capable) | Same CSI pipeline as S3 with the dual-target firmware. **Firmware-side ADR-110 substrate now closed** (v0.7.0): ESP-NOW cross-board mesh quantified at **99.56 % match / 104 µs smoothed offset stdev / 3.95× EMA suppression** over a 5-min two-board soak (witness §A0.10), 32-byte UDP sync packet with operator-tunable cadence (§A0.12), ADR-018 byte 19 bit 4 wire-fix sourced from the working ESP-NOW path (§A0.13). Wire format ready for HE-LTF PPDU tagging in ADR-018 bytes 18-19 (firmware encoder + Rust + Python decoders verified end-to-end across 23 unit tests). LP-core motion-gate RISC-V program and Wi-Fi 6 soft-AP with TWT Responder both ship as opt-in code paths (default off). **Hardware-gated for measurement**: HE-LTF live subcarrier capture needs an 11ax AP (IDF v5.4 doesn't expose AP-side HE config — §A0.6); ~5 µA LP-core hibernation needs an INA meter to capture; 802.15.4 raw RX is broken in IDF v5.4 (workaround: ESP-NOW transport, shipped + measured). See witness log for the empirical / claimed split. |
|
||||
> | **ESP32 + Cognitum Seed** (recommended) | ESP32-S3 + [Cognitum Seed](https://cognitum.one) | ~$140 | Yes | Presence indicator, motion, breathing rate, heart rate, fall detection, slot-count multi-person heuristic + persistent vector store, kNN search, witness chain, MCP proxy. (Pose pending weights — see [#509](https://github.com/ruvnet/RuView/issues/509).) |
|
||||
> | **ESP32 Mesh** | 3-6x ESP32-S3 + WiFi router | ~$54 | Yes | Same capabilities as above without the persistent-memory features |
|
||||
> | **Research NIC** | Intel 5300 / Atheros AR9580 | ~$50-100 | Yes | Full CSI with 3x3 MIMO |
|
||||
> | **Any WiFi** | Windows, macOS, or Linux laptop | $0 | No | RSSI-only: coarse presence and motion (see [tutorial #36](https://github.com/ruvnet/RuView/issues/36)) |
|
||||
>
|
||||
@@ -150,19 +117,15 @@ pip install "ruview[client]" # or: pip install "wifi-densepose[clie
|
||||
<a href="https://ruvnet.github.io/RuView/pose-fusion.html"><strong>▶ Dual-Modal Pose Fusion Demo</strong></a>
|
||||
|
|
||||
<a href="https://ruvnet.github.io/RuView/pointcloud/"><strong>▶ Live 3D Point Cloud</strong></a>
|
||||
|
|
||||
<a href="https://ruvnet.github.io/RuView/three.js/"><strong>▶ three.js Demos (5)</strong></a>
|
||||
|
||||
> The [server](#-quick-start) is optional for visualization and aggregation — the ESP32 [runs independently](#esp32-s3-hardware-pipeline) for presence detection, vital signs, and fall alerts.
|
||||
>
|
||||
> **Live ESP32 pipeline**: Connect an ESP32-S3 node → run the [sensing server](#sensing-server) → open the [pose fusion demo](https://ruvnet.github.io/RuView/pose-fusion.html) for real-time dual-modal pose estimation (webcam + WiFi CSI). See [ADR-059](docs/adr/ADR-059-live-esp32-csi-pipeline.md).
|
||||
>
|
||||
> **three.js scene gallery** at [`/three.js/`](https://ruvnet.github.io/RuView/three.js/) — five progressively richer ADR-097 demos: helpers, cinematic, GLTF skinned, FBX skinned, and a live MediaPipe→Mixamo retargeting feed driven by ESP32 CSI. Demos 04 and 05 require a local Mixamo `X Bot.fbx` (license boundary — not redistributed).
|
||||
|
||||
|
||||
## 🤗 Pretrained model on Hugging Face
|
||||
|
||||
Pretrained CSI weights live at [`ruvnet/wifi-densepose-pretrained`](https://huggingface.co/ruvnet/wifi-densepose-pretrained) — 12.2M training steps on 60K frames / 610K contrastive triplets, **82.3% held-out temporal-triplet accuracy** (up from 66.4% raw; the older "100% presence" figure was measured on a single-class recording and has been retracted), 4-bit quantized variant fits in 8 KB. The release includes a contrastive **CSI encoder** producing 128-dim embeddings (164,183 emb/s on M4 Pro) and a **presence-detection head**. Per-node LoRA adapters are included for environment-specific fine-tuning.
|
||||
Pretrained CSI weights live at [`ruvnet/wifi-densepose-pretrained`](https://huggingface.co/ruvnet/wifi-densepose-pretrained) — 12.2M training steps on 60K frames / 610K contrastive triplets, **100% presence accuracy** on the validation set, 4-bit quantized variant fits in 8 KB. The release includes a contrastive **CSI encoder** producing 128-dim embeddings (164,183 emb/s on M4 Pro) and a **presence-detection head**. Per-node LoRA adapters are included for environment-specific fine-tuning.
|
||||
|
||||
```bash
|
||||
# Download the model bundle
|
||||
@@ -182,199 +145,7 @@ huggingface-cli download ruvnet/wifi-densepose-pretrained --local-dir models/wif
|
||||
|
||||
**Quantization choices** (all in the HF repo): `model-q2.bin` (4 KB) · `model-q4.bin` ⭐ recommended (8 KB) · `model-q8.bin` (16 KB) · `model.safetensors` full (48 KB)
|
||||
|
||||
The separate **17-keypoint pose-estimation model** is now published at [`ruvnet/wifi-densepose-mmfi-pose`](https://huggingface.co/ruvnet/wifi-densepose-mmfi-pose) — **82.69% torso-PCK@20** on MM-Fi (single model) / **83.59%** (3-model ensemble + TTA), beating the prior published SOTA MultiFormer (72.25%) and CSI2Pose (68.41%) on the matched `random_split` protocol. See **Results & proof** below.
|
||||
|
||||
### Results & proof
|
||||
|
||||
| What | Where | Numbers |
|
||||
|------|-------|---------|
|
||||
| **MM-Fi pose model (SOTA)** | [`ruvnet/wifi-densepose-mmfi-pose`](https://huggingface.co/ruvnet/wifi-densepose-mmfi-pose) | 82.69% torso-PCK@20 (single) · 83.59% (ensemble+TTA) · 75K-param micro variant 74.30% |
|
||||
| **AetherArena benchmark Space** | [`ruvnet/aether-arena`](https://huggingface.co/spaces/ruvnet/aether-arena) | self-correcting, auditable MM-Fi leaderboard |
|
||||
| **Full MM-Fi study (honest picture)** | [`docs/benchmarks/mmfi-wifi-sensing-study.md`](docs/benchmarks/mmfi-wifi-sensing-study.md) | pose + action; zero-shot cross-subject ~64%, +~30 s in-room calibration → 72.2% |
|
||||
| **Efficiency frontier** | [`docs/benchmarks/wifi-pose-efficiency-frontier.md`](docs/benchmarks/wifi-pose-efficiency-frontier.md) | SOTA-beating WiFi pose in a 20 KB int4 edge model |
|
||||
| **Pretrained encoder** | [`ruvnet/wifi-densepose-pretrained`](https://huggingface.co/ruvnet/wifi-densepose-pretrained) | 82.3% held-out temporal-triplet, 8 KB int4 |
|
||||
| **Reproducible proof (Trust Kill Switch)** | [`archive/v1/data/proof/verify.py`](archive/v1/data/proof/verify.py) + [`expected_features.sha256`](archive/v1/data/proof/expected_features.sha256) | one-command deterministic pipeline replay (SHA-256 of output vs published hash) |
|
||||
| **Benchmark-proof ADR** | [ADR-147](docs/adr/ADR-147-benchmark-proof.md) | how the numbers are produced and verified |
|
||||
| **Witness attestation** | [`docs/WITNESS-LOG-028.md`](docs/WITNESS-LOG-028.md) | 33-row capability attestation matrix with per-claim evidence |
|
||||
|
||||
```bash
|
||||
# Reproduce the deterministic pipeline proof yourself (must print VERDICT: PASS):
|
||||
python archive/v1/data/proof/verify.py
|
||||
```
|
||||
|
||||
Tracked in [#509](https://github.com/ruvnet/RuView/issues/509); see [ADR-079](docs/adr/ADR-079-camera-supervised-pose-finetune.md) phases P7–P9 for the camera-supervised fine-tune path.
|
||||
|
||||
|
||||
## 🧩 Edge Module Catalog
|
||||
|
||||
<details>
|
||||
<summary><b>🧩 105 edge modules ready to install on a Cognitum appliance</b> — live catalog from <code>app-registry.json</code> v2.1.0 (updated 2026-05-13). Browse + install at <a href="https://seed.cognitum.one/store">seed.cognitum.one/store</a> or your local appliance <code>http://<appliance>:9000/cogs</code>.</summary>
|
||||
|
||||
Each module is a small signed binary (~400 KB) that runs alongside the WiFi-DensePose sensing stack on a Cognitum-V0 appliance. The catalog updates over the air — your appliance fetches it via <code>GET /api/v1/edge/registry</code> ([ADR-102](docs/adr/ADR-102-edge-module-registry.md)) and verifies each binary against an Ed25519 signature ([ADR-100](docs/adr/ADR-100-cog-packaging-specification.md)) before install.
|
||||
|
||||
### 🫀 Health — <sub>14 modules</sub>
|
||||
|
||||
| ID | What it does | Size | Difficulty |
|
||||
|----|--------------|-----:|:----------:|
|
||||
| `air-quality-index` | Track indoor air quality with CO2 and particle sensors | 8 KB | Easy |
|
||||
| `baby-cry` | Sustained mid-band energy detector for nursery / infant monitoring. Audio-only, no camera. | 451 KB | Easy |
|
||||
| `breathing-sync` | Detects when two people breathe in sync | 10 KB | Hard |
|
||||
| `cardiac-arrhythmia` | Spots irregular heartbeats and abnormal heart rhythms | 8 KB | Hard |
|
||||
| `cough-detect` | Acoustic transient + spectral cough detector with 30s cluster aggregation. Early-warning signal for respiratory illness. | 451 KB | Easy |
|
||||
| `dream-stage` | Tracks your sleep stages — light, deep, and dreaming | 14 KB | Hard |
|
||||
| `fall-detect` | Two-stage impact + stillness fall detector over ambient feature stream (ESP32 motion / mic). Optional ruview-mode for CSI-based pose reinforcement. | 402 KB | Easy |
|
||||
| `gait-analysis` | Detects walking problems and scores fall risk | 12 KB | Hard |
|
||||
| `health-monitor` | Contactless heart rate, breathing, sleep, and fall alerts | 30 KB | Med |
|
||||
| `respiratory-distress` | Alerts when breathing becomes labored or dangerously fast | 10 KB | Hard |
|
||||
| `seizure-detect` | Recognizes seizures and sends immediate alerts | 10 KB | Hard |
|
||||
| `sleep-apnea` | Detects when someone stops breathing during sleep | 4 KB | Easy |
|
||||
| `snore-monitor` | Periodic low-band energy tracker for sleep-quality / apnea-risk trending. Companion to sleep-apnea cog. | 451 KB | Easy |
|
||||
| `vital-trend` | Tracks breathing and heart rate trends over weeks | 6 KB | Med |
|
||||
|
||||
### 🔒 Security — <sub>14 modules</sub>
|
||||
|
||||
| ID | What it does | Size | Difficulty |
|
||||
|----|--------------|-----:|:----------:|
|
||||
| `audit-logger` | Record every action for compliance — tamper-proof log | 8 KB | Easy |
|
||||
| `behavioral-profiler` | Learns normal behavior and flags anything unusual | 12 KB | Hard |
|
||||
| `fleet-auth` | Manage device certificates and access across all seeds | 12 KB | Med |
|
||||
| `glass-break` | Two-phase bang + shatter acoustic detector. Distinguishes glass break from ordinary impulse noise. | 451 KB | Easy |
|
||||
| `gunshot-detect` | Saturating peak + exponential decay acoustic detector with optional ruview CSI motion-drop reinforcement. | 451 KB | Easy |
|
||||
| `intrusion` | Alerts when an unauthorized person enters a room | 6 KB | Med |
|
||||
| `intrusion-detect-ml` | Detect network attacks using machine learning | 14 KB | Hard |
|
||||
| `loitering` | Alerts when someone lingers too long in one spot | 3 KB | Easy |
|
||||
| `network-firewall` | Block unauthorized network access per cog | 6 KB | Easy |
|
||||
| `panic-motion` | Detects sudden panicked or erratic movement | 6 KB | Med |
|
||||
| `perimeter-breach` | Guards multiple zones and shows entry direction | 10 KB | Med |
|
||||
| `prompt-shield` | Blocks signal replay and injection attacks on the seed | 10 KB | Med |
|
||||
| `tailgating` | Catches when someone sneaks in behind a badge holder | 6 KB | Med |
|
||||
| `weapon-detect` | Detects concealed metal objects on a person | 8 KB | Hard |
|
||||
|
||||
### 🏢 Building — <sub>11 modules</sub>
|
||||
|
||||
| ID | What it does | Size | Difficulty |
|
||||
|----|--------------|-----:|:----------:|
|
||||
| `beehive-monitor` | Acoustic hive state classifier. Detects healthy / chaotic / queenless / swarming / robbing via hum-band energy + chaos + piping autocorr. | 451 KB | Easy |
|
||||
| `elevator-count` | Counts how many people are in an elevator | 8 KB | Med |
|
||||
| `energy-audit` | Learns your schedule and cuts wasted energy | 6 KB | Med |
|
||||
| `frost-warning` | Predicts frost 6 hours ahead via temperature trend + dewpoint-depression gate. Field/orchard agriculture. | 451 KB | Easy |
|
||||
| `hvac-presence` | Turns heating and cooling on when you arrive | 3 KB | Easy |
|
||||
| `lighting-zones` | Turns lights on and off as people move between rooms | 4 KB | Easy |
|
||||
| `meeting-room` | Shows if a meeting room is free or occupied | 5 KB | Easy |
|
||||
| `occupancy-zones` | Counts people in each room through walls | 8 KB | Med |
|
||||
| `predictive-maintenance` | Vibration harmonic analyzer for rotating equipment. Tracks F1 / 2×F1 / high-order / sideband energy to score degradation severity. | 451 KB | Easy |
|
||||
| `smoke-fire` | Multi-signal smoke and fire detector. Fuses acoustic crackle, thermal drift proxy, and optional ruview CSI plume signature. Not a UL-listed replacement for code-required smoke alarms. | 451 KB | Easy |
|
||||
| `water-leak` | Persistent low-amplitude hiss + periodic drip acoustic detector with multi-minute persistence gate. Two-stage likely → confirmed. | 451 KB | Easy |
|
||||
|
||||
### 🛍️ Retail — <sub>7 modules</sub>
|
||||
|
||||
| ID | What it does | Size | Difficulty |
|
||||
|----|--------------|-----:|:----------:|
|
||||
| `customer-flow` | Counts foot traffic in and out of each entrance | 8 KB | Med |
|
||||
| `dwell-heatmap` | Shows where customers spend the most time | 6 KB | Med |
|
||||
| `package-detect` | Sustained CSI-shift detector for porch / loading bay package arrivals and departures. Requires ESP32 CSI ruview input. | 451 KB | Easy |
|
||||
| `parking-occupancy` | Per-zone parking occupancy via ESP32 CSI subcarrier-amplitude shift. Tracks utilization and churn-per-hour. Requires ruview. | 451 KB | Easy |
|
||||
| `queue-length` | Estimates line length and wait time | 6 KB | Med |
|
||||
| `shelf-engagement` | Detects when customers interact with products | 6 KB | Med |
|
||||
| `table-turnover` | Tracks which restaurant tables are free or occupied | 4 KB | Easy |
|
||||
|
||||
### 🏭 Industrial — <sub>7 modules</sub>
|
||||
|
||||
| ID | What it does | Size | Difficulty |
|
||||
|----|--------------|-----:|:----------:|
|
||||
| `clean-room` | Enforces max headcount in controlled environments | 4 KB | Easy |
|
||||
| `confined-space` | Monitors workers in tight spaces for safety | 5 KB | Med |
|
||||
| `forklift-proximity` | Warns if a forklift gets too close to workers | 10 KB | Hard |
|
||||
| `livestock-monitor` | Monitors animals for distress, escape, or illness | 6 KB | Med |
|
||||
| `ppe-compliance` | Cog-composition layer: alerts when ruview-densepose detects presence in a restricted zone without an accompanying PPE-camera-cog confirmation vector. | 387 KB | Easy |
|
||||
| `slip-fall-zone` | Pre-fall risk detector. Fires when motion-variance drop, splash audio, and optional cautious-gait CSI all signal elevated slip risk. | 451 KB | Easy |
|
||||
| `structural-vibration` | Detects dangerous vibrations in buildings or machines | 8 KB | Hard |
|
||||
|
||||
### 🔬 Research — <sub>12 modules</sub>
|
||||
|
||||
| ID | What it does | Size | Difficulty |
|
||||
|----|--------------|-----:|:----------:|
|
||||
| `emotion-detect` | Reads stress and calm from body language and breathing | 10 KB | Hard |
|
||||
| `energy-harvester` | Optimize solar and battery for off-grid seed deployment | 6 KB | Med |
|
||||
| `gesture-language` | Recognizes sign language gestures in real time | 12 KB | Hard |
|
||||
| `ghost-hunter` | Finds unexplained environmental anomalies — for fun | 10 KB | Hard |
|
||||
| `happiness-score` | Estimates well-being from movement and mood signals | 8 KB | Med |
|
||||
| `hyperbolic-space` | Maps data into curved space for tree-like structures | 12 KB | Hard |
|
||||
| `music-conductor` | Reads a conductor's gestures for tempo and dynamics | 12 KB | Hard |
|
||||
| `plant-growth` | Tracks plant growth rate and day/night cycles | 8 KB | Med |
|
||||
| `rain-detect` | Detects when rain starts, stops, and how heavy it is | 6 KB | Med |
|
||||
| `ruview-densepose` | Full body pose tracking from WiFi — no cameras needed | 50 KB | Hard |
|
||||
| `sound-classifier` | Identify sounds like glass break, alarm, or baby cry | 16 KB | Hard |
|
||||
| `time-crystal` | Experiments with repeating time-pattern symmetry | 12 KB | Hard |
|
||||
|
||||
### 🤖 Ai — <sub>15 modules</sub>
|
||||
|
||||
| ID | What it does | Size | Difficulty |
|
||||
|----|--------------|-----:|:----------:|
|
||||
| `anomaly-attractor` | Learns what's normal and catches anything weird | 10 KB | Hard |
|
||||
| `cognitive-pipeline` | FastGRNN anomaly gate + SmolLM2 sparse-LLM inference for on-device Pi Zero 2W cognitive events | 320 KB | Hard |
|
||||
| `dtw-gesture-learn` | Teach custom hand gestures by showing examples | 14 KB | Med |
|
||||
| `ewc-lifelong` | Learns new things without forgetting old lessons | 8 KB | Hard |
|
||||
| `federated-learning` | Train AI across seeds without sharing raw data | 18 KB | Hard |
|
||||
| `goap-autonomy` | Plans and executes goals on its own | 14 KB | Hard |
|
||||
| `meta-adapt` | Automatically tunes itself for best performance | 10 KB | Hard |
|
||||
| `micro-hnsw` | Fast on-device fingerprinting and classification | 12 KB | Med |
|
||||
| `neural-trader` | Spot market patterns and trends from live data | 20 KB | Hard |
|
||||
| `pagerank-influence` | Finds the most influential person in a group | 12 KB | Med |
|
||||
| `pattern-sequence` | Detects daily routines and repeated habits | 10 KB | Med |
|
||||
| `rag-local` | Search your documents using AI — runs on the seed | 14 KB | Med |
|
||||
| `spiking-tracker` | Brain-inspired tracker that runs on tiny hardware | 16 KB | Hard |
|
||||
| `temporal-logic` | Enforces safety rules on live event streams | 12 KB | Hard |
|
||||
| `time-series-forecast` | Predict sensor trends using historical patterns | 12 KB | Med |
|
||||
|
||||
### 🐝 Swarm — <sub>11 modules</sub>
|
||||
|
||||
| ID | What it does | Size | Difficulty |
|
||||
|----|--------------|-----:|:----------:|
|
||||
| `swarm-backup-restore` | Auto-backup data to other seeds — one-click restore | 8 KB | Easy |
|
||||
| `swarm-cluster-monitor` | Live dashboard of every seed's health and status | 6 KB | Easy |
|
||||
| `swarm-consensus` | Seeds vote before making critical changes together | 16 KB | Hard |
|
||||
| `swarm-delta-sync` | Auto-sync data between seeds — only sends changes | 8 KB | Med |
|
||||
| `swarm-deploy` | Install or remove cogs on all seeds at once | 10 KB | Med |
|
||||
| `swarm-distributed-store` | Spread data across seeds and search them all at once | 14 KB | Hard |
|
||||
| `swarm-edge-orchestrator` | Manage all ESP32 sensor nodes from one place | 14 KB | Hard |
|
||||
| `swarm-load-balancer` | Spread queries across seeds so no single one overloads | 10 KB | Med |
|
||||
| `swarm-mesh-manager` | Find, connect, and monitor all seeds on your network | 12 KB | Easy |
|
||||
| `swarm-mqtt-bridge` | Share events between seeds over MQTT messaging | 6 KB | Easy |
|
||||
| `swarm-witness-federation` | Share tamper-proof audit trails across seeds | 12 KB | Hard |
|
||||
|
||||
### 📡 Signal — <sub>6 modules</sub>
|
||||
|
||||
| ID | What it does | Size | Difficulty |
|
||||
|----|--------------|-----:|:----------:|
|
||||
| `coherence-gate` | Filters out noisy signals and keeps clean ones | 8 KB | Med |
|
||||
| `flash-attention` | Focuses sensing on specific areas for better accuracy | 12 KB | Med |
|
||||
| `optimal-transport` | Measures motion using shape-aware signal comparison | 12 KB | Hard |
|
||||
| `person-matching` | Tells apart multiple people in the same room | 18 KB | Hard |
|
||||
| `sparse-recovery` | Recovers missing signal data from partial readings | 16 KB | Hard |
|
||||
| `temporal-compress` | Shrinks old data to save memory without losing meaning | 14 KB | Med |
|
||||
|
||||
### 🌐 Network — <sub>1 modules</sub>
|
||||
|
||||
| ID | What it does | Size | Difficulty |
|
||||
|----|--------------|-----:|:----------:|
|
||||
| `tailscale` | Reach the seed from anywhere via a private WireGuard mesh (Tailscale). Userspace mode — no root. | 700 KB | Med |
|
||||
|
||||
### 🛠️ Developer — <sub>7 modules</sub>
|
||||
|
||||
| ID | What it does | Size | Difficulty |
|
||||
|----|--------------|-----:|:----------:|
|
||||
| `adversarial` | Detects tampered or spoofed sensor signals | 4 KB | Easy |
|
||||
| `coherence` | Monitors signal quality across multiple channels | 4 KB | Easy |
|
||||
| `gesture` | Core gesture recognition building block for cogs | 6 KB | Med |
|
||||
| `interference-search` | Searches many possibilities at once for fast answers | 14 KB | Hard |
|
||||
| `psycho-symbolic` | Reasons over knowledge graphs with multiple styles | 16 KB | Hard |
|
||||
| `quantum-coherence` | Quantum-inspired model for advanced signal states | 16 KB | Hard |
|
||||
| `self-healing-mesh` | Keeps sensor mesh running even when nodes drop out | 14 KB | Hard |
|
||||
|
||||
> ℹ️ Build your own cog: see [ADR-100](docs/adr/ADR-100-cog-packaging-specification.md) for the packaging spec. The first cog this repo ships into the catalog lives in [v2/crates/cog-pose-estimation/](v2/crates/cog-pose-estimation/) (17-keypoint WiFi pose, [ADR-101](docs/adr/ADR-101-pose-estimation-cog.md)).
|
||||
|
||||
</details>
|
||||
The separate **17-keypoint pose-estimation model** is not in this release — pipeline is implemented but keypoint weights are still pending. Tracked in [#509](https://github.com/ruvnet/RuView/issues/509); see [ADR-079](docs/adr/ADR-079-camera-supervised-pose-finetune.md) phases P7–P9.
|
||||
|
||||
|
||||
## 🔬 How It Works
|
||||
@@ -490,6 +261,178 @@ These scenarios exploit WiFi's ability to penetrate solid materials — concrete
|
||||
|
||||
</details>
|
||||
|
||||
<details>
|
||||
<summary><strong>🧩 Edge Intelligence (<a href="docs/adr/ADR-041-wasm-module-collection.md">ADR-041</a>)</strong> — 60 WASM modules across 13 categories, all implemented (609 tests)</summary>
|
||||
|
||||
Small programs that run directly on the ESP32 sensor — no internet needed, no cloud fees, instant response. Each module is a tiny WASM file (5-30 KB) that you upload to the device over-the-air. It reads WiFi signal data and makes decisions locally in under 10 ms. [ADR-041](docs/adr/ADR-041-wasm-module-collection.md) defines 60 modules across 13 categories — all 60 are implemented with 609 tests passing.
|
||||
|
||||
| | Category | Examples |
|
||||
|---|----------|---------|
|
||||
| 🏥 | [**Medical & Health**](docs/edge-modules/medical.md) | Sleep apnea detection, cardiac arrhythmia, gait analysis, seizure detection |
|
||||
| 🔐 | [**Security & Safety**](docs/edge-modules/security.md) | Intrusion detection, perimeter breach, loitering, panic motion |
|
||||
| 🏢 | [**Smart Building**](docs/edge-modules/building.md) | Zone occupancy, HVAC control, elevator counting, meeting room tracking |
|
||||
| 🛒 | [**Retail & Hospitality**](docs/edge-modules/retail.md) | Queue length, dwell heatmaps, customer flow, table turnover |
|
||||
| 🏭 | [**Industrial**](docs/edge-modules/industrial.md) | Forklift proximity, confined space monitoring, structural vibration |
|
||||
| 🔮 | [**Exotic & Research**](docs/edge-modules/exotic.md) | Sleep staging, emotion detection, sign language, breathing sync |
|
||||
| 📡 | [**Signal Intelligence**](docs/edge-modules/signal-intelligence.md) | Cleans and sharpens raw WiFi signals — focuses on important regions, filters noise, fills in missing data, and tracks which person is which |
|
||||
| 🧠 | [**Adaptive Learning**](docs/edge-modules/adaptive-learning.md) | The sensor learns new gestures and patterns on its own over time — no cloud needed, remembers what it learned even after updates |
|
||||
| 🗺️ | [**Spatial Reasoning**](docs/edge-modules/spatial-temporal.md) | Figures out where people are in a room, which zones matter most, and tracks movement across areas using graph-based spatial logic |
|
||||
| ⏱️ | [**Temporal Analysis**](docs/edge-modules/spatial-temporal.md) | Learns daily routines, detects when patterns break (someone didn't get up), and verifies safety rules are being followed over time |
|
||||
| 🛡️ | [**AI Security**](docs/edge-modules/ai-security.md) | Detects signal replay attacks, WiFi jamming, injection attempts, and flags abnormal behavior that could indicate tampering |
|
||||
| ⚛️ | [**Quantum-Inspired**](docs/edge-modules/autonomous.md) | Uses quantum-inspired math to map room-wide signal coherence and search for optimal sensor configurations |
|
||||
| 🤖 | [**Autonomous & Exotic**](docs/edge-modules/autonomous.md) | Self-managing sensor mesh — auto-heals dropped nodes, plans its own actions, and explores experimental signal representations |
|
||||
|
||||
All implemented modules are `no_std` Rust, share a [common utility library](v2/crates/wifi-densepose-wasm-edge/src/vendor_common.rs), and talk to the host through a 12-function API. Full documentation: [**Edge Modules Guide**](docs/edge-modules/README.md). See the [complete implemented module list](#edge-module-list) below.
|
||||
|
||||
</details>
|
||||
|
||||
<details id="edge-module-list">
|
||||
<summary><strong>🧩 Edge Intelligence — <a href="docs/edge-modules/README.md">All 65 Modules Implemented</a></strong> (ADR-041 complete)</summary>
|
||||
|
||||
All 60 modules are implemented, tested (609 tests passing), and ready to deploy. They compile to `wasm32-unknown-unknown`, run on ESP32-S3 via WASM3, and share a [common utility library](v2/crates/wifi-densepose-wasm-edge/src/vendor_common.rs). Source: [`crates/wifi-densepose-wasm-edge/src/`](v2/crates/wifi-densepose-wasm-edge/src/)
|
||||
|
||||
**Core modules** (ADR-040 flagship + early implementations):
|
||||
|
||||
| Module | File | What It Does |
|
||||
|--------|------|-------------|
|
||||
| Gesture Classifier | [`gesture.rs`](v2/crates/wifi-densepose-wasm-edge/src/gesture.rs) | DTW template matching for hand gestures |
|
||||
| Coherence Filter | [`coherence.rs`](v2/crates/wifi-densepose-wasm-edge/src/coherence.rs) | Phase coherence gating for signal quality |
|
||||
| Adversarial Detector | [`adversarial.rs`](v2/crates/wifi-densepose-wasm-edge/src/adversarial.rs) | Detects physically impossible signal patterns |
|
||||
| Intrusion Detector | [`intrusion.rs`](v2/crates/wifi-densepose-wasm-edge/src/intrusion.rs) | Human vs non-human motion classification |
|
||||
| Occupancy Counter | [`occupancy.rs`](v2/crates/wifi-densepose-wasm-edge/src/occupancy.rs) | Zone-level person counting |
|
||||
| Vital Trend | [`vital_trend.rs`](v2/crates/wifi-densepose-wasm-edge/src/vital_trend.rs) | Long-term breathing and heart rate trending |
|
||||
| RVF Parser | [`rvf.rs`](v2/crates/wifi-densepose-wasm-edge/src/rvf.rs) | RVF container format parsing |
|
||||
|
||||
**Vendor-integrated modules** (24 modules, ADR-041 Category 7):
|
||||
|
||||
**📡 Signal Intelligence** — Real-time CSI analysis and feature extraction
|
||||
|
||||
| Module | File | What It Does | Budget |
|
||||
|--------|------|-------------|--------|
|
||||
| Flash Attention | [`sig_flash_attention.rs`](v2/crates/wifi-densepose-wasm-edge/src/sig_flash_attention.rs) | Tiled attention over 8 subcarrier groups — finds spatial focus regions and entropy | S (<5ms) |
|
||||
| Coherence Gate | [`sig_coherence_gate.rs`](v2/crates/wifi-densepose-wasm-edge/src/sig_coherence_gate.rs) | Z-score phasor gating with hysteresis: Accept / PredictOnly / Reject / Recalibrate | L (<2ms) |
|
||||
| Temporal Compress | [`sig_temporal_compress.rs`](v2/crates/wifi-densepose-wasm-edge/src/sig_temporal_compress.rs) | 3-tier adaptive quantization (8-bit hot / 5-bit warm / 3-bit cold) | L (<2ms) |
|
||||
| Sparse Recovery | [`sig_sparse_recovery.rs`](v2/crates/wifi-densepose-wasm-edge/src/sig_sparse_recovery.rs) | ISTA L1 reconstruction for dropped subcarriers | H (<10ms) |
|
||||
| Person Match | [`sig_mincut_person_match.rs`](v2/crates/wifi-densepose-wasm-edge/src/sig_mincut_person_match.rs) | Hungarian-lite bipartite assignment for multi-person tracking | S (<5ms) |
|
||||
| Optimal Transport | [`sig_optimal_transport.rs`](v2/crates/wifi-densepose-wasm-edge/src/sig_optimal_transport.rs) | Sliced Wasserstein-1 distance with 4 projections | L (<2ms) |
|
||||
|
||||
**🧠 Adaptive Learning** — On-device learning without cloud connectivity
|
||||
|
||||
| Module | File | What It Does | Budget |
|
||||
|--------|------|-------------|--------|
|
||||
| DTW Gesture Learn | [`lrn_dtw_gesture_learn.rs`](v2/crates/wifi-densepose-wasm-edge/src/lrn_dtw_gesture_learn.rs) | User-teachable gesture recognition — 3-rehearsal protocol, 16 templates | S (<5ms) |
|
||||
| Anomaly Attractor | [`lrn_anomaly_attractor.rs`](v2/crates/wifi-densepose-wasm-edge/src/lrn_anomaly_attractor.rs) | 4D dynamical system attractor classification with Lyapunov exponents | H (<10ms) |
|
||||
| Meta Adapt | [`lrn_meta_adapt.rs`](v2/crates/wifi-densepose-wasm-edge/src/lrn_meta_adapt.rs) | Hill-climbing self-optimization with safety rollback | L (<2ms) |
|
||||
| EWC Lifelong | [`lrn_ewc_lifelong.rs`](v2/crates/wifi-densepose-wasm-edge/src/lrn_ewc_lifelong.rs) | Elastic Weight Consolidation — remembers past tasks while learning new ones | S (<5ms) |
|
||||
|
||||
**🗺️ Spatial Reasoning** — Location, proximity, and influence mapping
|
||||
|
||||
| Module | File | What It Does | Budget |
|
||||
|--------|------|-------------|--------|
|
||||
| PageRank Influence | [`spt_pagerank_influence.rs`](v2/crates/wifi-densepose-wasm-edge/src/spt_pagerank_influence.rs) | 4x4 cross-correlation graph with power iteration PageRank | L (<2ms) |
|
||||
| Micro HNSW | [`spt_micro_hnsw.rs`](v2/crates/wifi-densepose-wasm-edge/src/spt_micro_hnsw.rs) | 64-vector navigable small-world graph for nearest-neighbor search | S (<5ms) |
|
||||
| Spiking Tracker | [`spt_spiking_tracker.rs`](v2/crates/wifi-densepose-wasm-edge/src/spt_spiking_tracker.rs) | 32 LIF neurons + 4 output zone neurons with STDP learning | S (<5ms) |
|
||||
|
||||
**⏱️ Temporal Analysis** — Activity patterns, logic verification, autonomous planning
|
||||
|
||||
| Module | File | What It Does | Budget |
|
||||
|--------|------|-------------|--------|
|
||||
| Pattern Sequence | [`tmp_pattern_sequence.rs`](v2/crates/wifi-densepose-wasm-edge/src/tmp_pattern_sequence.rs) | Activity routine detection and deviation alerts | S (<5ms) |
|
||||
| Temporal Logic Guard | [`tmp_temporal_logic_guard.rs`](v2/crates/wifi-densepose-wasm-edge/src/tmp_temporal_logic_guard.rs) | LTL formula verification on CSI event streams | S (<5ms) |
|
||||
| GOAP Autonomy | [`tmp_goap_autonomy.rs`](v2/crates/wifi-densepose-wasm-edge/src/tmp_goap_autonomy.rs) | Goal-Oriented Action Planning for autonomous module management | S (<5ms) |
|
||||
|
||||
**🛡️ AI Security** — Tamper detection and behavioral anomaly profiling
|
||||
|
||||
| Module | File | What It Does | Budget |
|
||||
|--------|------|-------------|--------|
|
||||
| Prompt Shield | [`ais_prompt_shield.rs`](v2/crates/wifi-densepose-wasm-edge/src/ais_prompt_shield.rs) | FNV-1a replay detection, injection detection (10x amplitude), jamming (SNR) | L (<2ms) |
|
||||
| Behavioral Profiler | [`ais_behavioral_profiler.rs`](v2/crates/wifi-densepose-wasm-edge/src/ais_behavioral_profiler.rs) | 6D behavioral profile with Mahalanobis anomaly scoring | S (<5ms) |
|
||||
|
||||
**⚛️ Quantum-Inspired** — Quantum computing metaphors applied to CSI analysis
|
||||
|
||||
| Module | File | What It Does | Budget |
|
||||
|--------|------|-------------|--------|
|
||||
| Quantum Coherence | [`qnt_quantum_coherence.rs`](v2/crates/wifi-densepose-wasm-edge/src/qnt_quantum_coherence.rs) | Bloch sphere mapping, Von Neumann entropy, decoherence detection | S (<5ms) |
|
||||
| Interference Search | [`qnt_interference_search.rs`](v2/crates/wifi-densepose-wasm-edge/src/qnt_interference_search.rs) | 16 room-state hypotheses with Grover-inspired oracle + diffusion | S (<5ms) |
|
||||
|
||||
**🤖 Autonomous Systems** — Self-governing and self-healing behaviors
|
||||
|
||||
| Module | File | What It Does | Budget |
|
||||
|--------|------|-------------|--------|
|
||||
| Psycho-Symbolic | [`aut_psycho_symbolic.rs`](v2/crates/wifi-densepose-wasm-edge/src/aut_psycho_symbolic.rs) | 16-rule forward-chaining knowledge base with contradiction detection | S (<5ms) |
|
||||
| Self-Healing Mesh | [`aut_self_healing_mesh.rs`](v2/crates/wifi-densepose-wasm-edge/src/aut_self_healing_mesh.rs) | 8-node mesh with health tracking, degradation/recovery, coverage healing | S (<5ms) |
|
||||
|
||||
**🔮 Exotic (Vendor)** — Novel mathematical models for CSI interpretation
|
||||
|
||||
| Module | File | What It Does | Budget |
|
||||
|--------|------|-------------|--------|
|
||||
| Time Crystal | [`exo_time_crystal.rs`](v2/crates/wifi-densepose-wasm-edge/src/exo_time_crystal.rs) | Autocorrelation subharmonic detection in 256-frame history | S (<5ms) |
|
||||
| Hyperbolic Space | [`exo_hyperbolic_space.rs`](v2/crates/wifi-densepose-wasm-edge/src/exo_hyperbolic_space.rs) | Poincare ball embedding with 32 reference locations, hyperbolic distance | S (<5ms) |
|
||||
|
||||
**🏥 Medical & Health** (Category 1) — Contactless health monitoring
|
||||
|
||||
| Module | File | What It Does | Budget |
|
||||
|--------|------|-------------|--------|
|
||||
| Sleep Apnea | [`med_sleep_apnea.rs`](v2/crates/wifi-densepose-wasm-edge/src/med_sleep_apnea.rs) | Detects breathing pauses during sleep | S (<5ms) |
|
||||
| Cardiac Arrhythmia | [`med_cardiac_arrhythmia.rs`](v2/crates/wifi-densepose-wasm-edge/src/med_cardiac_arrhythmia.rs) | Monitors heart rate for irregular rhythms | S (<5ms) |
|
||||
| Respiratory Distress | [`med_respiratory_distress.rs`](v2/crates/wifi-densepose-wasm-edge/src/med_respiratory_distress.rs) | Alerts on abnormal breathing patterns | S (<5ms) |
|
||||
| Gait Analysis | [`med_gait_analysis.rs`](v2/crates/wifi-densepose-wasm-edge/src/med_gait_analysis.rs) | Tracks walking patterns and detects changes | S (<5ms) |
|
||||
| Seizure Detection | [`med_seizure_detect.rs`](v2/crates/wifi-densepose-wasm-edge/src/med_seizure_detect.rs) | 6-state machine for tonic-clonic seizure recognition | S (<5ms) |
|
||||
|
||||
**🔐 Security & Safety** (Category 2) — Perimeter and threat detection
|
||||
|
||||
| Module | File | What It Does | Budget |
|
||||
|--------|------|-------------|--------|
|
||||
| Perimeter Breach | [`sec_perimeter_breach.rs`](v2/crates/wifi-densepose-wasm-edge/src/sec_perimeter_breach.rs) | Detects boundary crossings with approach/departure | S (<5ms) |
|
||||
| Weapon Detection | [`sec_weapon_detect.rs`](v2/crates/wifi-densepose-wasm-edge/src/sec_weapon_detect.rs) | Metal anomaly detection via CSI amplitude shifts | S (<5ms) |
|
||||
| Tailgating | [`sec_tailgating.rs`](v2/crates/wifi-densepose-wasm-edge/src/sec_tailgating.rs) | Detects unauthorized follow-through at access points | S (<5ms) |
|
||||
| Loitering | [`sec_loitering.rs`](v2/crates/wifi-densepose-wasm-edge/src/sec_loitering.rs) | Alerts when someone lingers too long in a zone | S (<5ms) |
|
||||
| Panic Motion | [`sec_panic_motion.rs`](v2/crates/wifi-densepose-wasm-edge/src/sec_panic_motion.rs) | Detects fleeing, struggling, or panic movement | S (<5ms) |
|
||||
|
||||
**🏢 Smart Building** (Category 3) — Automation and energy efficiency
|
||||
|
||||
| Module | File | What It Does | Budget |
|
||||
|--------|------|-------------|--------|
|
||||
| HVAC Presence | [`bld_hvac_presence.rs`](v2/crates/wifi-densepose-wasm-edge/src/bld_hvac_presence.rs) | Occupancy-driven HVAC control with departure countdown | S (<5ms) |
|
||||
| Lighting Zones | [`bld_lighting_zones.rs`](v2/crates/wifi-densepose-wasm-edge/src/bld_lighting_zones.rs) | Auto-dim/off lighting based on zone activity | S (<5ms) |
|
||||
| Elevator Count | [`bld_elevator_count.rs`](v2/crates/wifi-densepose-wasm-edge/src/bld_elevator_count.rs) | Counts people entering/leaving with overload warning | S (<5ms) |
|
||||
| Meeting Room | [`bld_meeting_room.rs`](v2/crates/wifi-densepose-wasm-edge/src/bld_meeting_room.rs) | Tracks meeting lifecycle: start, headcount, end, availability | S (<5ms) |
|
||||
| Energy Audit | [`bld_energy_audit.rs`](v2/crates/wifi-densepose-wasm-edge/src/bld_energy_audit.rs) | Tracks after-hours usage and room utilization rates | S (<5ms) |
|
||||
|
||||
**🛒 Retail & Hospitality** (Category 4) — Customer insights without cameras
|
||||
|
||||
| Module | File | What It Does | Budget |
|
||||
|--------|------|-------------|--------|
|
||||
| Queue Length | [`ret_queue_length.rs`](v2/crates/wifi-densepose-wasm-edge/src/ret_queue_length.rs) | Estimates queue size and wait times | S (<5ms) |
|
||||
| Dwell Heatmap | [`ret_dwell_heatmap.rs`](v2/crates/wifi-densepose-wasm-edge/src/ret_dwell_heatmap.rs) | Shows where people spend time (hot/cold zones) | S (<5ms) |
|
||||
| Customer Flow | [`ret_customer_flow.rs`](v2/crates/wifi-densepose-wasm-edge/src/ret_customer_flow.rs) | Counts ins/outs and tracks net occupancy | S (<5ms) |
|
||||
| Table Turnover | [`ret_table_turnover.rs`](v2/crates/wifi-densepose-wasm-edge/src/ret_table_turnover.rs) | Restaurant table lifecycle: seated, dining, vacated | S (<5ms) |
|
||||
| Shelf Engagement | [`ret_shelf_engagement.rs`](v2/crates/wifi-densepose-wasm-edge/src/ret_shelf_engagement.rs) | Detects browsing, considering, and reaching for products | S (<5ms) |
|
||||
|
||||
**🏭 Industrial & Specialized** (Category 5) — Safety and compliance
|
||||
|
||||
| Module | File | What It Does | Budget |
|
||||
|--------|------|-------------|--------|
|
||||
| Forklift Proximity | [`ind_forklift_proximity.rs`](v2/crates/wifi-densepose-wasm-edge/src/ind_forklift_proximity.rs) | Warns when people get too close to vehicles | S (<5ms) |
|
||||
| Confined Space | [`ind_confined_space.rs`](v2/crates/wifi-densepose-wasm-edge/src/ind_confined_space.rs) | OSHA-compliant worker monitoring with extraction alerts | S (<5ms) |
|
||||
| Clean Room | [`ind_clean_room.rs`](v2/crates/wifi-densepose-wasm-edge/src/ind_clean_room.rs) | Occupancy limits and turbulent motion detection | S (<5ms) |
|
||||
| Livestock Monitor | [`ind_livestock_monitor.rs`](v2/crates/wifi-densepose-wasm-edge/src/ind_livestock_monitor.rs) | Animal presence, stillness, and escape alerts | S (<5ms) |
|
||||
| Structural Vibration | [`ind_structural_vibration.rs`](v2/crates/wifi-densepose-wasm-edge/src/ind_structural_vibration.rs) | Seismic events, mechanical resonance, structural drift | S (<5ms) |
|
||||
|
||||
**🔮 Exotic & Research** (Category 6) — Experimental sensing applications
|
||||
|
||||
| Module | File | What It Does | Budget |
|
||||
|--------|------|-------------|--------|
|
||||
| Dream Stage | [`exo_dream_stage.rs`](v2/crates/wifi-densepose-wasm-edge/src/exo_dream_stage.rs) | Contactless sleep stage classification (wake/light/deep/REM) | S (<5ms) |
|
||||
| Emotion Detection | [`exo_emotion_detect.rs`](v2/crates/wifi-densepose-wasm-edge/src/exo_emotion_detect.rs) | Arousal, stress, and calm detection from micro-movements | S (<5ms) |
|
||||
| Gesture Language | [`exo_gesture_language.rs`](v2/crates/wifi-densepose-wasm-edge/src/exo_gesture_language.rs) | Sign language letter recognition via WiFi | S (<5ms) |
|
||||
| Music Conductor | [`exo_music_conductor.rs`](v2/crates/wifi-densepose-wasm-edge/src/exo_music_conductor.rs) | Tempo and dynamic tracking from conducting gestures | S (<5ms) |
|
||||
| Plant Growth | [`exo_plant_growth.rs`](v2/crates/wifi-densepose-wasm-edge/src/exo_plant_growth.rs) | Monitors plant growth, circadian rhythms, wilt detection | S (<5ms) |
|
||||
| Ghost Hunter | [`exo_ghost_hunter.rs`](v2/crates/wifi-densepose-wasm-edge/src/exo_ghost_hunter.rs) | Environmental anomaly classification (draft/insect/wind/unknown) | S (<5ms) |
|
||||
| Rain Detection | [`exo_rain_detect.rs`](v2/crates/wifi-densepose-wasm-edge/src/exo_rain_detect.rs) | Detects rain onset, intensity, and cessation via signal scatter | S (<5ms) |
|
||||
| Breathing Sync | [`exo_breathing_sync.rs`](v2/crates/wifi-densepose-wasm-edge/src/exo_breathing_sync.rs) | Detects synchronized breathing between multiple people | S (<5ms) |
|
||||
|
||||
</details>
|
||||
|
||||
---
|
||||
|
||||
@@ -609,40 +552,20 @@ Verify the plugin structure: `bash plugins/ruview/scripts/smoke.sh`. Full detail
|
||||
|----------|-------------|
|
||||
| [User Guide](docs/user-guide.md) | Step-by-step guide: installation, first run, API usage, hardware setup, training |
|
||||
| [Build Guide](docs/build-guide.md) | Building from source (Rust and Python) |
|
||||
| [**Home Assistant + Matter Integration**](docs/integrations/home-assistant.md) | **Works with Home Assistant** via MQTT auto-discovery + **Works with Matter** (Apple Home / Google Home / Alexa / SmartThings) — full entity catalog, 3 starter blueprints, Lovelace dashboards, privacy mode, threshold tuning ([ADR-115](docs/adr/ADR-115-home-assistant-integration.md)). |
|
||||
| [**BFLD — Beamforming Feedback Layer for Detection**](v2/crates/wifi-densepose-bfld/README.md) | New privacy-gated WiFi sensing layer that measures + structurally prevents identity leakage from 802.11ac/ax Beamforming Feedback Information. Three type-enforced invariants (raw BFI never exits node, identity embedding is in-RAM-only, cross-site correlation cryptographically impossible via per-site BLAKE3 keyed hash + daily rotation). Ships full operator surface (`BfldPipeline`, `BfldPipelineHandle`, Soul Signature `SoulMatchOracle` integration), MQTT topic router + HA-DISCO + availability + LWT, 3 operator HA blueprints, two runnable examples, eclipse-mosquitto:2 CI service container. 327+ tests. [ADR-118](docs/adr/ADR-118-bfld-beamforming-feedback-layer-for-detection.md) umbrella + sub-ADRs [119](docs/adr/ADR-119-bfld-frame-format-and-wire-protocol.md)/[120](docs/adr/ADR-120-bfld-privacy-class-and-hash-rotation.md)/[121](docs/adr/ADR-121-bfld-identity-risk-scoring.md)/[122](docs/adr/ADR-122-bfld-ruview-ha-matter-exposure.md)/[123](docs/adr/ADR-123-bfld-capture-path-nexmon-and-esp32.md). Research dossier: [`docs/research/BFLD/`](docs/research/BFLD/) (11 files, 13,544 words). |
|
||||
| [**SENSE-BRIDGE — rvagent MCP server**](tools/ruview-mcp/README.md) | Dual-transport MCP server (`@ruvnet/rvagent`) bridging the RuView sensing stack to AI agents (Claude Code, Cursor, ruflo swarms). 6 tools wired: `ruview.presence.now`, `ruview.vitals.get_{breathing,heart_rate,all}`, `ruview.bfld.last_scan`, `ruview.bfld.subscribe`. stdio + Streamable HTTP (`POST /mcp`, Origin-validated, bearer-token auth, `127.0.0.1` bind). Full 20-tool Zod schema barrel + 5 RUVIEW-POLICY governance tools. 93 tests. [ADR-124](docs/adr/ADR-124-rvagent-mcp-ruvector-npm-integration.md). Try: `npx @ruvnet/rvagent stdio`. |
|
||||
| [Semantic Primitives — Precision/Recall](docs/integrations/semantic-primitives-metrics.md) | Per-primitive F1 on the held-out paired-capture set: someone-sleeping, possible-distress, room-active, elderly-inactivity-anomaly, meeting, bathroom, fall-risk, bed-exit, no-movement, multi-room. |
|
||||
| [Claude Code / Codex Plugin](plugins/ruview/README.md) | The `ruview` plugin + marketplace — skills, `/ruview-*` commands, agents, and the Codex prompt mirror |
|
||||
| [Architecture Decisions](docs/adr/README.md) | 96 ADRs — why each technical choice was made, organized by domain (hardware, signal processing, ML, platform, infrastructure) |
|
||||
| [Domain Models](docs/ddd/README.md) | 8 DDD models (RuvSense, Signal Processing, Training Pipeline, Hardware Platform, Sensing Server, WiFi-Mat, CHCI, rvCSI) — bounded contexts, aggregates, domain events, and ubiquitous language |
|
||||
| [rvCSI — edge RF sensing runtime](https://github.com/ruvnet/rvcsi) | Rust-first / TypeScript-accessible / hardware-abstracted CSI runtime: multi-source ingestion (incl. real nexmon_csi `.pcap` from a **Raspberry Pi 5** / Pi 4 / Pi 3B+ — CYW43455 / BCM43455c0) → validation → DSP → typed events → RuVector RF memory ([ADR-095](docs/adr/ADR-095-rvcsi-edge-rf-sensing-platform.md), [ADR-096](docs/adr/ADR-096-rvcsi-ffi-crate-layout.md), [domain model](docs/ddd/rvcsi-domain-model.md)). Now its own repo — [`ruvnet/rvcsi`](https://github.com/ruvnet/rvcsi) — vendored here under `vendor/rvcsi`; 9 `rvcsi-*` crates on crates.io, `@ruv/rvcsi` on npm, plus a Claude Code plugin. |
|
||||
| [Desktop App](v2/crates/wifi-densepose-desktop/README.md) | **WIP** — Tauri v2 desktop app for node management, OTA updates, WASM deployment, and mesh visualization |
|
||||
| `ruview-swarm` | Drone swarm control system (ADR-148) — hierarchical-mesh topology, Raft consensus, MARL, CSI sensing payload, MAVLink/PX4/ArduPilot compatibility, Ruflo AI-agent integration |
|
||||
| [Medical Examples](examples/medical/README.md) | Contactless blood pressure, heart rate, breathing rate via 60 GHz mmWave radar — $15 hardware, no wearable |
|
||||
| [Extended Documentation](docs/readme-details.md) | Latest additions, key features, installation, quick start, signal processing, training, CLI, testing, deployment, and changelog |
|
||||
|
||||
---
|
||||
|
||||
## 🚧 Beta software
|
||||
|
||||
> **Beta Software** — Under active development. APIs and firmware may change. Known limitations:
|
||||
> - ESP32-C3 and original ESP32 are not supported (single-core, insufficient for CSI DSP)
|
||||
> - Single ESP32 deployments have limited spatial resolution — use 2+ nodes or add a [Cognitum Seed](https://cognitum.one) for best results
|
||||
> - Camera-free pose accuracy is limited (PCK@20 ≈ 2.5% with proxy labels) — [camera ground-truth training](docs/adr/ADR-079-camera-ground-truth-training.md) targets **35%+ PCK@20**; the pipeline is implemented, but the data-collection and evaluation phases (ADR-079 P7–P9) are still pending.
|
||||
>
|
||||
> Contributions and bug reports welcome at [Issues](https://github.com/ruvnet/RuView/issues).
|
||||
|
||||
## 📄 License
|
||||
|
||||
MIT License — see [LICENSE](LICENSE) for details.
|
||||
|
||||
## 🤝 Creator Affiliate Program
|
||||
|
||||
**For TikTok · Instagram · YouTube creators** — earn **25% on every Cognitum sale** you refer. The RuFlo, RuView, and RuVector videos you're already making have done millions of views; get paid for the orders they drive. Click-tracking activates instantly; commissions activate after a quick manual review (usually under 24 hours).
|
||||
|
||||
[Apply now → cognitum.one/affiliate](https://cognitum.one/affiliate)
|
||||
|
||||
## 📞 Support
|
||||
|
||||
[GitHub Issues](https://github.com/ruvnet/RuView/issues) | [Discussions](https://github.com/ruvnet/RuView/discussions) | [PyPI](https://pypi.org/project/wifi-densepose/)
|
||||
|
||||
@@ -1,50 +0,0 @@
|
||||
# AetherArena ("AA") — The Official Spatial-Intelligence Benchmark
|
||||
|
||||
> **Public leaderboard. Private evaluation split. Open scorer. Signed results.**
|
||||
|
||||
AetherArena is a **standalone, project-agnostic benchmark** for camera-free **spatial intelligence** — pose, presence, occupancy, tracking, and vitals from RF/WiFi (and, over time, mmWave / UWB / radar / lidar / multimodal). It is **not** a single-vendor leaderboard: any team, framework, or sensing modality can enter, and every entrant — including the RuView baseline that donated the seed scorer — is scored by the identical, open, pinned harness.
|
||||
|
||||
Specified in [ADR-149](../docs/adr/ADR-149-public-community-leaderboard-huggingface.md) (Accepted).
|
||||
|
||||
Canonical home: **`ruvnet/aether-arena`** + a Hugging Face Space (deploy pending — see `STATUS`).
|
||||
|
||||
---
|
||||
|
||||
## Why
|
||||
|
||||
WiFi/RF spatial sensing has no shared yardstick — papers self-report against inconsistent splits and metrics, with **no accounting for latency, reproducibility, or privacy leakage**. AA fixes the *measurement*, not just the models: a single deterministic scorer, a private held-out split nobody can train on, and a signed result ledger that can't be silently edited.
|
||||
|
||||
## What gets measured (v0)
|
||||
|
||||
| Category | Metric | Status |
|
||||
|----------|--------|--------|
|
||||
| **Pose** | PCK@0.2 (all / torso), OKS | Ranked |
|
||||
| **Presence** | accuracy, FP/FN | Ranked |
|
||||
| **Edge latency** | p50 / p95 / p99 ms | Ranked |
|
||||
| **Determinism** | proof-hash pass/fail | Ranked (gate) |
|
||||
| Tracking (MOTA) | — | activates when multi-person clips land |
|
||||
| Vitals (BPM err) | — | activates when paired vitals ground truth lands |
|
||||
| **Privacy leakage** | membership-inference ∈ [0,1] | **gated — not ranked** until the attacker ships |
|
||||
| Cross-room | degradation ratio | coming soon |
|
||||
|
||||
The headline rank is the **category metric**; an optional `arena_score = quality × latency_factor × privacy_factor × determinism_gate` is exposed alongside (never instead) so accuracy can't win at any cost. See ADR-149 §2.5.
|
||||
|
||||
## How scoring works
|
||||
|
||||
The scorer is RuView's **already-published** `wifi-densepose-train` acceptance harness (`ruview_metrics` + ADR-145 `ablation`), run in a pinned sandbox. **You submit a model, not predictions** — predictions on data you hold prove nothing. Your model is scored against a **private** MM-Fi held-out split (CC BY-NC 4.0; Wi-Pose excluded for redistribution reasons), and one **signed, append-only** row is written to the results ledger with a determinism proof hash.
|
||||
|
||||
Submission lifecycle: `submitted → validated → quarantined → smoke_scored → full_scored → published` (or `rejected` with a reason). The model only ever runs inside a no-network, read-only-FS sandbox.
|
||||
|
||||
## Submit (when the Space is live)
|
||||
|
||||
1. Write a manifest: [`schema/aa-submission.toml`](schema/aa-submission.toml).
|
||||
2. Push your model artifact (`.safetensors` / `.rvf` / LoRA adapter) + manifest to the Space.
|
||||
3. Watch it move through the lifecycle; your signed row appears on the board.
|
||||
|
||||
## Verify it's fair (you don't have to trust us)
|
||||
|
||||
See [`VERIFY.md`](VERIFY.md) — run the **open scorer** locally on the **public smoke split**, reproduce the determinism hash, and confirm RuView's own entries were scored by the identical path. That five-step check is the launch gate (ADR-149 §7).
|
||||
|
||||
## Neutrality
|
||||
|
||||
AA is a neutral commons. The scorer is open and versioned; any metric change is a public `harness_version` bump that **re-scores all entries**. RuView donated the seed harness and enters as one baseline — it gets no special treatment (ADR-149 §2.8).
|
||||
@@ -1,30 +0,0 @@
|
||||
# AetherArena — Build Status
|
||||
|
||||
Tracks ADR-149 implementation milestones. "Complete" = benchmark **infrastructure** done,
|
||||
tested, CI-gated, deploy-ready, RuView baseline entered, §7 acceptance test passing.
|
||||
Model **SOTA** (e.g. MM-Fi PCK@20 ~72%) is a separate long-running ML effort, blocked on
|
||||
ADR-079 camera-ground-truth collection — *not* an infra-completion blocker.
|
||||
|
||||
| # | Milestone | Status |
|
||||
|---|-----------|--------|
|
||||
| M1 | ADR-149 Accepted + committed | ✅ done |
|
||||
| M2 | Scorer runner (`aa_score_runner`) — **real model scoring** + witness (proof+inputs hash) + **repeatability analysis** | ✅ done — builds `--no-default-features`, determinism gate PASS, repeatable 16/16 |
|
||||
| M3 | CI harness-gate workflow (PR runs scorer + repeatability + real-scoring smoke + ledger verify) | ✅ done — `.github/workflows/aether-arena-harness.yml` |
|
||||
| M4 | Scaffold: README + submission schema + VERIFY (acceptance test) | ✅ done |
|
||||
| M5 | Public smoke split (committed) + private MM-Fi held-out split prep | 🟡 smoke split done (`fixtures/smoke_*.json`); private MM-Fi prep pending |
|
||||
| M6 | HF Space (Gradio) — leaderboard + ledger integrity + submit/verify/about | ✅ deployed → https://huggingface.co/spaces/ruvnet/aether-arena (sandboxed scorer container = later hardening) |
|
||||
| M7 | **Witness ledger chain** — append-only, hash-chained, tamper-evident | ✅ done — `ledger/ledger_tools.py` (seed/append/verify); tamper test fails as designed |
|
||||
| M8 | Public launch | ✅ Space **LIVE** (gradio 5.9.1, serving 200) — **board empty, awaiting first real harness score** (benchmark-first: no seeded numbers) |
|
||||
|
||||
## v0 infrastructure: COMPLETE
|
||||
Implement ✅ · Test ✅ · Deploy to HF ✅ (https://huggingface.co/spaces/ruvnet/aether-arena) · Instructions+Verification ✅ · PR runs the harness ✅ (PR #874, AA harness gate **passed**).
|
||||
Remaining = data + hardening, not infra: private MM-Fi held-out split (M5), sandboxed scorer container (M6), privacy-leakage attacker (gated category), and **model SOTA** (separate ML effort, blocked on ADR-079 — explicitly not an infra exit).
|
||||
|
||||
## Benchmark-first posture (per user direction)
|
||||
- **No placeholder numbers on the board.** The ledger seeds to genesis only; every result is a real scoring-pipeline witness. RuView gets no seeded baseline.
|
||||
- **Witness chain** = `inputs_sha256` (binds witness to exact inputs) + `proof_sha256` (cross-platform-stable score hash) + the append-only hash-chained ledger. Repeatability analysis (`--repeat N`) proves the proof hash is identical across runs.
|
||||
|
||||
## Blockers / decisions needed
|
||||
- **HF deploy (M6)** — token is in GCP Secret Manager (`HUGGINGFACE_API_KEY`); creating the public `ruvnet/aether-arena` Space still wants explicit go.
|
||||
- **MM-Fi is CC BY-NC** → AA must stay non-commercial / legally distinct from the commercial RuView product.
|
||||
- **Private MM-Fi split (M5)** — needs the dataset pulled + a held-out split assembled before real public scoring replaces the smoke fixture.
|
||||
@@ -1,78 +0,0 @@
|
||||
# Verifying AetherArena (you don't have to trust us)
|
||||
|
||||
AA's credibility rests on a stranger being able to reproduce a score and see that the rules are fair. This is the **launch gate** (ADR-149 §7): v0 does not ship until all five checks below pass for someone with no insider access.
|
||||
|
||||
> **Wider context:** this page covers the *leaderboard scorer*. For the whole-platform answer to
|
||||
> "is this real / does it actually work?" — including the deterministic pipeline proof, the
|
||||
> published models + public-benchmark numbers, and the built-in-public development trail — see
|
||||
> [`docs/proof-of-capabilities.md`](../docs/proof-of-capabilities.md).
|
||||
|
||||
## The open scorer
|
||||
|
||||
The scoring engine is a pure-Rust, GPU-free binary: `aa_score_runner` in `wifi-densepose-train`. It runs the real `ruview_metrics` pose-acceptance harness on a fixed fixture and emits a cross-platform-stable SHA-256 **determinism proof**.
|
||||
|
||||
### Reproduce the determinism hash locally
|
||||
|
||||
```bash
|
||||
cd v2
|
||||
# Verify the committed expected hash still matches (this is the CI gate):
|
||||
cargo run -q -p wifi-densepose-train --bin aa_score_runner --no-default-features
|
||||
# → prints the witness (inputs_sha256 + proof_sha256) and "VERDICT: PASS"
|
||||
|
||||
# See the witness row as JSON:
|
||||
cargo run -q -p wifi-densepose-train --bin aa_score_runner --no-default-features -- --json
|
||||
```
|
||||
|
||||
### Witness chain — proof + repeatability analysis
|
||||
|
||||
Every score is a **witness**: `inputs_sha256` (binds it to the exact inputs scored)
|
||||
+ `proof_sha256` (cross-platform-stable hash of the quantised score) + `harness_version`.
|
||||
Witnesses are recorded in an **append-only, hash-chained ledger** (each row references
|
||||
the previous row's hash), so a silent edit to any past row breaks the chain.
|
||||
|
||||
```bash
|
||||
# Repeatability: run the scorer K times, confirm ONE identical proof hash:
|
||||
cd v2
|
||||
cargo run -q -p wifi-densepose-train --bin aa_score_runner --no-default-features -- --repeat 16
|
||||
# → {"repeatability":{"runs":16,"unique_proof_hashes":1,"repeatable":true,...}}
|
||||
|
||||
# Real model scoring (score predictions against an eval split):
|
||||
cargo run -q -p wifi-densepose-train --bin aa_score_runner --no-default-features -- \
|
||||
--split ../aether-arena/fixtures/smoke_split.json \
|
||||
--pred ../aether-arena/fixtures/smoke_pred.json --json
|
||||
|
||||
# Verify the witness ledger chain is intact (tamper-evident):
|
||||
cd ../aether-arena/ledger && python3 ledger_tools.py verify
|
||||
# → "OK: N rows, chain intact" (edit any row and it reports the broken link)
|
||||
```
|
||||
|
||||
The expected hash is committed at [`fixtures/expected_score.sha256`](fixtures/expected_score.sha256). Same harness version + same fixture → same hash on glibc / MSVC / Apple. If your local run prints `VERDICT: PASS`, you have reproduced the scorer.
|
||||
|
||||
### What happens if the scoring maths changes
|
||||
|
||||
Any edit to `ruview_metrics.rs`, `ablation.rs`, or `aa_score_runner.rs` moves the hash and **fails the CI gate** (`.github/workflows/aether-arena-harness.yml`) until the maintainer regenerates and reviews:
|
||||
|
||||
```bash
|
||||
cargo run -p wifi-densepose-train --bin aa_score_runner --no-default-features -- --generate-hash \
|
||||
> aether-arena/fixtures/expected_score.sha256
|
||||
```
|
||||
|
||||
So a scorer change is always a reviewed, public diff — never silent. That's `harness_version` pinning + `determinism_gate` in action (ADR-149 §2.4–§2.5).
|
||||
|
||||
## The five-step acceptance test (v0 launch gate)
|
||||
|
||||
A stranger must be able to:
|
||||
|
||||
1. **Submit** a model (artifact + `schema/aa-submission.toml`) with no insider help.
|
||||
2. **Get a deterministic score** — same model + same `harness_version` → same numbers.
|
||||
3. **See the signed row** appended to the public results ledger.
|
||||
4. **Rerun the scorer locally** on the public smoke split and reproduce the logic (the command above).
|
||||
5. **Understand why the rank is fair** — private split, open scorer, pinned version, proof hash — from these docs alone.
|
||||
|
||||
If any step fails, v0 is not ready.
|
||||
|
||||
## Current status
|
||||
|
||||
- ✅ Step 4 (rerun the open scorer locally, reproduce the hash) — **works today** via `aa_score_runner`.
|
||||
- ✅ CI harness gate runs the scorer on every PR.
|
||||
- ⏳ Steps 1–3, 5 (HF Space submission flow + signed ledger) — in progress; require the HF Space deploy (needs an HF token / maintainer authorization).
|
||||
@@ -1,87 +0,0 @@
|
||||
# RuView Calibration Service (reference implementation)
|
||||
|
||||
Turn a **shared WiFi-CSI pose base model** into a room-specific one with a **30-second labeled
|
||||
calibration** and a **~11 KB per-room LoRA adapter**. This is the deployable resolution of the
|
||||
cross-subject / cross-environment generalization problem (full study: [ADR-150 §3.3–3.6](../../docs/adr/ADR-150-rf-foundation-encoder.md)).
|
||||
|
||||
## Why
|
||||
|
||||
Zero-shot WiFi pose generalizes poorly to a **new room or new person** — an unseen room can drop a
|
||||
strong model to near-random. But that gap is **not** algorithmically closeable (CORAL, DANN,
|
||||
instance-norm, contrastive foundation-pretraining all failed) and **not** closeable by collecting
|
||||
more subjects (saturates ~64%). It **is** closeable, cheaply, at deployment time: a handful of
|
||||
labeled frames from the actual room pin down its multipath instantly.
|
||||
|
||||
| Deployment case | Zero-shot | + in-room calibration |
|
||||
|-----------------|----------:|----------------------:|
|
||||
| Same room, new person (cross-subject) | 64% | **76%** (200 samples) |
|
||||
| **New room + new person (cross-environment)** | **~10%** | **60% @ 5 samples → 73% @ 200** |
|
||||
|
||||
**Verified demo (this code, source-only base on an unseen MM-Fi room E04):**
|
||||
`zero-shot 3.09% → after 200-sample calibration 74.29%` (+71 pts).
|
||||
|
||||
## How it works
|
||||
|
||||
A frozen shared **base** (transformer + temporal attention pool + skeleton-graph head, the published
|
||||
[`ruvnet/wifi-densepose-mmfi-pose`](https://huggingface.co/ruvnet/wifi-densepose-mmfi-pose)) plus a
|
||||
tiny **LoRA adapter** (rank 8 on the input projection + pose head — **11,200 params ≈ 11 KB int8 /
|
||||
22 KB fp16**) fitted per room. Thousands of room-adapters hang off one base.
|
||||
|
||||
## Usage
|
||||
|
||||
```bash
|
||||
# 1) Capture a short labeled clip in the deployment room -> calib.npz {X:[N,3,114,10], Y:[N,17,2]}
|
||||
# (~100–200 samples recommended; below ~20 the adapter can underperform zero-shot)
|
||||
|
||||
# 2) Fit the per-room adapter (~11 KB):
|
||||
python calibrate.py --base pose_mmfi_best.pt --data calib.npz --out room.adapter.npz
|
||||
|
||||
# 3) Run calibrated inference (base + room adapter):
|
||||
python infer.py --base pose_mmfi_best.pt --adapter room.adapter.npz --data frames.npz --out kp.npy
|
||||
# omit --adapter to run the uncalibrated (zero-shot) base
|
||||
```
|
||||
|
||||
`X` is CSI amplitude `[N, 3 antennas, 114 subcarriers, 10 frames]` (per-sample standardization is
|
||||
applied internally). `Y` is `[N,17,2]` COCO keypoints in `[0,1]`.
|
||||
|
||||
## Calibration budget (measured, rank-8 LoRA, 3 seeds — ADR-150 §3.5)
|
||||
|
||||
| Labeled samples/room | cross-subject | cross-environment |
|
||||
|---------------------:|--------------:|------------------:|
|
||||
| 0 (zero-shot) | 64% | ~10% |
|
||||
| 5 | — | 60% |
|
||||
| 20 | 66% | 66% |
|
||||
| 50 | 70% | 70% |
|
||||
| 200 | 72% | 73% |
|
||||
|
||||
Knee at ~50 samples (~70%); **below ~20 samples the adapter can hurt** (too few to fit reliably).
|
||||
|
||||
## Two models, two producers (not interchangeable)
|
||||
|
||||
Adapters are **model-specific**. There are two calibration producers here:
|
||||
|
||||
| Producer | Target model | Input | Adapter format | Consumer |
|
||||
|----------|--------------|-------|----------------|----------|
|
||||
| `calibrate.py` | MM-Fi **transformer** (`pose_mmfi_best.pt`, 3×114×10) | `[N,3,114,10]` | `.npz` (`proj`/`head` LoRA) | this Python `infer.py` |
|
||||
| `cog_calibrate.py` | cog **conv+MLP** (`pose_v1.safetensors`, 56×20) | `[N,56,20]` | `.safetensors` (`fc1.a`/`fc1.b`/`fc2.a`/`fc2.b`) | Rust `cog-pose-estimation run --adapter` |
|
||||
|
||||
```bash
|
||||
# Produce a cog-format per-room adapter for the deployed Rust pose engine:
|
||||
python cog_calibrate.py --base pose_v1.safetensors --data calib.npz --out room.safetensors
|
||||
# then in the cog runtime:
|
||||
cog-pose-estimation run --config <cfg> --adapter room.safetensors
|
||||
```
|
||||
|
||||
Same LoRA *mechanism* (ADR-150 §3.5), different architecture and key layout — an adapter from one
|
||||
producer will not load into the other model.
|
||||
|
||||
## Notes
|
||||
|
||||
- **Calibration only helps when the base hasn't already seen the room.** The published flagship was
|
||||
trained on MM-Fi `random_split`, so calibrating it on an MM-Fi subject is a near-no-op (it already
|
||||
saw them); for a genuinely new real-world room it is zero-shot and calibration applies. To
|
||||
*reproduce the demo* on a held-out MM-Fi room, train a source-only base (exclude the target
|
||||
environment) — see `ADR-150 §3.6` and the few-shot harness in `aether-arena/staging/`.
|
||||
- Adapter is saved fp16 (~22 KB); quantize to int8 for the ~11 KB on-device form.
|
||||
- Inference is real-time on CPU (the 75 K-param `micro` variant runs in 0.135 ms single-thread x86;
|
||||
see [`docs/benchmarks/wifi-pose-efficiency-frontier.md`](../../docs/benchmarks/wifi-pose-efficiency-frontier.md)).
|
||||
@@ -1,71 +0,0 @@
|
||||
"""RuView per-room calibration — fit a ~11 KB LoRA adapter from a short labeled in-room capture.
|
||||
|
||||
python calibrate.py --base pose_mmfi_best.pt --data room_calib.npz --out room_A.adapter.npz
|
||||
|
||||
`room_calib.npz` must contain `X` [N,3,114,10] CSI amplitude and `Y` [N,17,2] (or [N,34]) keypoints
|
||||
in [0,1] — the labeled calibration samples from the deployment room (~100–200 recommended; ≥20).
|
||||
Outputs a tiny adapter (.npz, ~11 KB) that, loaded over the shared base at inference, recovers
|
||||
SOTA-level pose for that room/person (ADR-150 §3.5–3.6).
|
||||
"""
|
||||
import argparse
|
||||
import numpy as np
|
||||
import torch
|
||||
import torch.nn as nn
|
||||
|
||||
from model import PoseNet, standardize
|
||||
|
||||
|
||||
def main():
|
||||
ap = argparse.ArgumentParser()
|
||||
ap.add_argument("--base", required=True, help="base checkpoint (pose_mmfi_best.pt)")
|
||||
ap.add_argument("--data", required=True, help="labeled calibration .npz with X and Y")
|
||||
ap.add_argument("--out", required=True, help="output adapter .npz")
|
||||
ap.add_argument("--rank", type=int, default=8)
|
||||
ap.add_argument("--iters", type=int, default=600)
|
||||
ap.add_argument("--lr", type=float, default=8e-4)
|
||||
ap.add_argument("--device", default="cuda" if torch.cuda.is_available() else "cpu")
|
||||
a = ap.parse_args()
|
||||
|
||||
z = np.load(a.data)
|
||||
X = torch.tensor(z["X"].astype(np.float32))
|
||||
Y = torch.tensor(z["Y"].reshape(len(z["Y"]), 34).astype(np.float32))
|
||||
n = len(X)
|
||||
if n < 20:
|
||||
print(f"WARNING: only {n} calibration samples — below ~20 the adapter may underperform "
|
||||
f"zero-shot (ADR-150 §3.5). Recommend ~100–200.")
|
||||
dev = a.device
|
||||
|
||||
net = PoseNet().to(dev)
|
||||
net.load_state_dict(torch.load(a.base, map_location=dev), strict=False)
|
||||
net.add_lora(r=a.rank).to(dev)
|
||||
for k, p in net.named_parameters():
|
||||
p.requires_grad = k.endswith(".A") or k.endswith(".B")
|
||||
trainable = [p for p in net.parameters() if p.requires_grad]
|
||||
n_tr = sum(p.numel() for p in trainable)
|
||||
|
||||
Xs = standardize(X.to(dev))
|
||||
Yt = Y.to(dev)
|
||||
opt = torch.optim.AdamW(trainable, lr=a.lr, weight_decay=0.0)
|
||||
lossf = nn.SmoothL1Loss(beta=0.1)
|
||||
bs = min(128, n)
|
||||
net.train()
|
||||
for it in range(a.iters):
|
||||
bi = torch.randint(0, n, (bs,), device=dev)
|
||||
xb = Xs[bi]
|
||||
# light augmentation (subcarrier dropout + noise) — matches training-time regularization
|
||||
m = (torch.rand(xb.shape[0], xb.shape[1], 1, 1, device=dev) > 0.15).float()
|
||||
xb = xb * m + 0.03 * torch.randn_like(xb) * torch.rand(xb.shape[0], 1, 1, 1, device=dev)
|
||||
opt.zero_grad()
|
||||
lossf(net(xb), Yt[bi]).backward()
|
||||
opt.step()
|
||||
|
||||
adapter = net.lora_state()
|
||||
nbytes = sum(v.astype(np.float16).nbytes for v in adapter.values())
|
||||
np.savez(a.out, **{k: v.astype(np.float16) for k, v in adapter.items()},
|
||||
_meta=np.array([a.rank, n, n_tr], dtype=np.int64))
|
||||
print(f"saved {a.out} | rank {a.rank} | {n_tr:,} params | ~{nbytes/1024:.1f} KB fp16 | "
|
||||
f"from {n} labeled samples")
|
||||
|
||||
|
||||
if __name__ == "__main__":
|
||||
main()
|
||||
@@ -1,120 +0,0 @@
|
||||
"""Per-room calibration producer for the cog-pose-estimation **conv+MLP** model
|
||||
(`pose_v1.safetensors`, 56 subcarriers x 20 frames). Companion to `calibrate.py`
|
||||
(which targets the MM-Fi *transformer* model) — different model, different adapter
|
||||
key layout, NOT interchangeable (ADR-150 §3.5).
|
||||
|
||||
Fits a rank-r LoRA on the pose head (fc1, fc2) from a short labeled in-room capture and
|
||||
writes a **safetensors** adapter with keys `fc1.a`/`fc1.b`/`fc2.a`/`fc2.b` (scale baked
|
||||
into `b`) — exactly what `cog-pose-estimation run --adapter <file>` consumes.
|
||||
|
||||
python cog_calibrate.py --base pose_v1.safetensors --data calib.npz --out room.safetensors
|
||||
|
||||
`calib.npz`: `X` [N,56,20] CSI window + `Y` [N,17,2] (or [N,34]) keypoints in [0,1].
|
||||
"""
|
||||
import argparse
|
||||
import numpy as np
|
||||
import torch
|
||||
import torch.nn as nn
|
||||
import torch.nn.functional as F
|
||||
|
||||
|
||||
class CogPose(nn.Module):
|
||||
"""Mirrors cog-pose-estimation's PoseNet (Candle) exactly — same safetensors keys."""
|
||||
|
||||
def __init__(self):
|
||||
super().__init__()
|
||||
self.enc = nn.ModuleDict({
|
||||
"c1": nn.Conv1d(56, 64, 3, padding=1, dilation=1),
|
||||
"c2": nn.Conv1d(64, 128, 3, padding=2, dilation=2),
|
||||
"c3": nn.Conv1d(128, 128, 3, padding=4, dilation=4),
|
||||
})
|
||||
self.head = nn.ModuleDict({"fc1": nn.Linear(128, 256), "fc2": nn.Linear(256, 34)})
|
||||
self.fc1_lora = None
|
||||
self.fc2_lora = None
|
||||
|
||||
def _lora(self, slot, x, y):
|
||||
if slot is None:
|
||||
return y
|
||||
a, b = slot
|
||||
return y + (x @ a) @ b
|
||||
|
||||
def forward(self, x): # x: [B, 56, 20]
|
||||
h = F.relu(self.enc["c1"](x))
|
||||
h = F.relu(self.enc["c2"](h))
|
||||
h = F.relu(self.enc["c3"](h))
|
||||
h = h.mean(2) # [B, 128]
|
||||
z1 = self.head["fc1"](h)
|
||||
z1 = self._lora(self.fc1_lora, h, z1)
|
||||
h1 = F.relu(z1)
|
||||
z2 = self.head["fc2"](h1)
|
||||
z2 = self._lora(self.fc2_lora, h1, z2)
|
||||
return torch.sigmoid(z2) # [B, 34]
|
||||
|
||||
def add_lora(self, r=4):
|
||||
self.fc1_lora = (nn.Parameter(torch.randn(128, r) * 0.02), nn.Parameter(torch.zeros(r, 256)))
|
||||
self.fc2_lora = (nn.Parameter(torch.randn(256, r) * 0.02), nn.Parameter(torch.zeros(r, 34)))
|
||||
for p in (*self.fc1_lora, *self.fc2_lora):
|
||||
self.register_parameter(f"lora_{id(p)}", p)
|
||||
return self
|
||||
|
||||
|
||||
def load_base(net: CogPose, path: str):
|
||||
from safetensors.torch import load_file
|
||||
sd = load_file(path)
|
||||
# remap "enc.c1.weight" -> module dict keys
|
||||
mapped = {}
|
||||
for k, v in sd.items():
|
||||
mapped[k.replace("enc.", "enc.").replace("head.", "head.")] = v
|
||||
net.load_state_dict(mapped, strict=False)
|
||||
return net
|
||||
|
||||
|
||||
def fit(base: str, data: str, out: str, rank: int = 4, iters: int = 400, lr: float = 1e-3):
|
||||
z = np.load(data)
|
||||
X = torch.tensor(z["X"].astype(np.float32)) # [N,56,20]
|
||||
Y = torch.tensor(z["Y"].reshape(len(z["Y"]), 34).astype(np.float32))
|
||||
n = len(X)
|
||||
net = CogPose()
|
||||
load_base(net, base)
|
||||
net.add_lora(rank)
|
||||
for p in net.parameters():
|
||||
p.requires_grad = False
|
||||
lora = [*net.fc1_lora, *net.fc2_lora]
|
||||
for p in lora:
|
||||
p.requires_grad = True
|
||||
opt = torch.optim.AdamW(lora, lr=lr, weight_decay=0.0)
|
||||
lossf = nn.SmoothL1Loss(beta=0.1)
|
||||
bs = min(64, n)
|
||||
net.train()
|
||||
for _ in range(iters):
|
||||
bi = torch.randint(0, n, (bs,))
|
||||
opt.zero_grad()
|
||||
lossf(net(X[bi]), Y[bi]).backward()
|
||||
opt.step()
|
||||
|
||||
alpha = 16.0
|
||||
scale = alpha / rank
|
||||
a1, b1 = net.fc1_lora
|
||||
a2, b2 = net.fc2_lora
|
||||
tensors = {
|
||||
"fc1.a": a1.detach().contiguous(),
|
||||
"fc1.b": (b1.detach() * scale).contiguous(), # bake scale into b
|
||||
"fc2.a": a2.detach().contiguous(),
|
||||
"fc2.b": (b2.detach() * scale).contiguous(),
|
||||
}
|
||||
from safetensors.torch import save_file
|
||||
save_file(tensors, out)
|
||||
return out, sum(p.numel() for p in lora), n
|
||||
|
||||
|
||||
if __name__ == "__main__":
|
||||
ap = argparse.ArgumentParser()
|
||||
ap.add_argument("--base", required=True)
|
||||
ap.add_argument("--data", required=True)
|
||||
ap.add_argument("--out", required=True)
|
||||
ap.add_argument("--rank", type=int, default=4)
|
||||
ap.add_argument("--iters", type=int, default=400)
|
||||
a = ap.parse_args()
|
||||
out, np_, n = fit(a.base, a.data, a.out, a.rank, a.iters)
|
||||
print(f"saved {out} | {np_} LoRA params from {n} samples "
|
||||
f"(keys fc1.a/fc1.b/fc2.a/fc2.b — load with cog-pose-estimation run --adapter)")
|
||||
@@ -1,49 +0,0 @@
|
||||
"""Run calibrated WiFi-CSI pose inference: shared base + a per-room LoRA adapter.
|
||||
|
||||
python infer.py --base pose_mmfi_best.pt --adapter room_A.adapter.npz --data frames.npz
|
||||
|
||||
`frames.npz` contains `X` [N,3,114,10] CSI amplitude. Prints/saves [N,17,2] keypoints in [0,1].
|
||||
Omit --adapter to run the uncalibrated (zero-shot) base. With a room adapter, expect SOTA-level
|
||||
accuracy in that room/person; without one, zero-shot degrades in unseen rooms (ADR-150 §3.6).
|
||||
"""
|
||||
import argparse
|
||||
import numpy as np
|
||||
import torch
|
||||
|
||||
from model import PoseNet, standardize
|
||||
|
||||
|
||||
def main():
|
||||
ap = argparse.ArgumentParser()
|
||||
ap.add_argument("--base", required=True)
|
||||
ap.add_argument("--adapter", default=None, help="per-room .adapter.npz (omit for zero-shot)")
|
||||
ap.add_argument("--data", required=True, help=".npz with X [N,3,114,10]")
|
||||
ap.add_argument("--out", default=None, help="optional .npy to save [N,17,2] keypoints")
|
||||
ap.add_argument("--rank", type=int, default=8)
|
||||
ap.add_argument("--device", default="cuda" if torch.cuda.is_available() else "cpu")
|
||||
a = ap.parse_args()
|
||||
dev = a.device
|
||||
|
||||
net = PoseNet().to(dev)
|
||||
net.load_state_dict(torch.load(a.base, map_location=dev), strict=False)
|
||||
if a.adapter:
|
||||
net.add_lora(r=a.rank).to(dev)
|
||||
z = np.load(a.adapter)
|
||||
net.load_lora({k: z[k].astype(np.float32) for k in z.files if k.endswith(".A") or k.endswith(".B")})
|
||||
net.eval()
|
||||
|
||||
X = torch.tensor(np.load(a.data)["X"].astype(np.float32)).to(dev)
|
||||
Xs = standardize(X)
|
||||
out = []
|
||||
with torch.no_grad():
|
||||
for i in range(0, len(Xs), 4096):
|
||||
out.append(net(Xs[i:i + 4096]).cpu().numpy())
|
||||
kp = np.concatenate(out).reshape(-1, 17, 2)
|
||||
print(f"inferred {len(kp)} frames | adapter={'yes' if a.adapter else 'NONE (zero-shot)'}")
|
||||
if a.out:
|
||||
np.save(a.out, kp)
|
||||
print(f"saved keypoints -> {a.out}")
|
||||
|
||||
|
||||
if __name__ == "__main__":
|
||||
main()
|
||||
@@ -1,107 +0,0 @@
|
||||
"""WiFi-CSI pose model + LoRA adapter for the RuView calibration service.
|
||||
|
||||
Architecture matches the published flagship checkpoint
|
||||
[`ruvnet/wifi-densepose-mmfi-pose`](https://huggingface.co/ruvnet/wifi-densepose-mmfi-pose)
|
||||
(`pose_mmfi_best.pt`): transformer encoder + temporal attention pooling + skeleton-graph head.
|
||||
|
||||
The calibration service freezes this base and fits a tiny per-room **LoRA adapter** (rank 8 on the
|
||||
input projection + pose head ≈ 11 KB) from ~100–200 labeled in-room samples. Empirically that lifts
|
||||
cross-subject 64→72% and cross-environment 11→73% (ADR-150 §3.3–3.6).
|
||||
"""
|
||||
import numpy as np
|
||||
import torch
|
||||
import torch.nn as nn
|
||||
|
||||
# COCO-17 skeleton edges for the graph-refinement head.
|
||||
EDGES = [(0, 1), (0, 2), (1, 3), (2, 4), (5, 6), (5, 7), (7, 9), (6, 8), (8, 10),
|
||||
(5, 11), (6, 12), (11, 12), (11, 13), (13, 15), (12, 14), (14, 16)]
|
||||
_A = np.eye(17, dtype=np.float32)
|
||||
for _i, _j in EDGES:
|
||||
_A[_i, _j] = _A[_j, _i] = 1.0
|
||||
_A = _A / _A.sum(1, keepdims=True)
|
||||
|
||||
|
||||
class LoRA(nn.Module):
|
||||
"""Low-rank adapter wrapping a frozen Linear: y = W·x + (x·A·B)·(alpha/r)."""
|
||||
|
||||
def __init__(self, base: nn.Linear, r: int = 8, alpha: int = 16):
|
||||
super().__init__()
|
||||
self.base = base
|
||||
for p in self.base.parameters():
|
||||
p.requires_grad = False
|
||||
self.A = nn.Parameter(torch.zeros(base.in_features, r))
|
||||
self.B = nn.Parameter(torch.zeros(r, base.out_features))
|
||||
nn.init.normal_(self.A, std=0.02)
|
||||
self.scale = alpha / r
|
||||
|
||||
def forward(self, x):
|
||||
return self.base(x) + (x @ self.A @ self.B) * self.scale
|
||||
|
||||
|
||||
class GR(nn.Module):
|
||||
"""Skeleton-graph refinement: nudges joints toward anatomically consistent positions."""
|
||||
|
||||
def __init__(self, d=256, h=96):
|
||||
super().__init__()
|
||||
self.je = nn.Parameter(torch.randn(17, 32) * 0.02)
|
||||
self.inp = nn.Linear(d + 34, h)
|
||||
self.g1 = nn.Linear(h, h)
|
||||
self.g2 = nn.Linear(h, h)
|
||||
self.out = nn.Linear(h, 2)
|
||||
self.register_buffer("A", torch.tensor(_A))
|
||||
|
||||
def forward(self, z, kp0):
|
||||
B = z.shape[0]
|
||||
f = torch.relu(self.inp(torch.cat(
|
||||
[z.unsqueeze(1).expand(-1, 17, -1), self.je.unsqueeze(0).expand(B, -1, -1), kp0], -1)))
|
||||
f = torch.relu(self.g1(torch.einsum('ij,bjh->bih', self.A, f)))
|
||||
f = torch.relu(self.g2(torch.einsum('ij,bjh->bih', self.A, f)))
|
||||
return kp0 + 0.3 * torch.tanh(self.out(f))
|
||||
|
||||
|
||||
class PoseNet(nn.Module):
|
||||
"""Flagship pose model. Input [B,3,114,10] CSI amplitude (per-sample standardized) -> [B,34]."""
|
||||
|
||||
def __init__(self, na=3, nsc=114, nt=10, d=256, L=4, H=8):
|
||||
super().__init__()
|
||||
self.proj = nn.Linear(na * nsc, d)
|
||||
self.pos = nn.Parameter(torch.randn(1, nt, d) * 0.02)
|
||||
enc = nn.TransformerEncoderLayer(d, H, d * 2, dropout=0.2, batch_first=True, activation='gelu')
|
||||
self.tf = nn.TransformerEncoder(enc, L)
|
||||
self.att = nn.Linear(d, 1)
|
||||
self.head = nn.Sequential(nn.Linear(d, 256), nn.GELU(), nn.Dropout(0.3), nn.Linear(256, 34))
|
||||
self.gr = GR(d)
|
||||
self.na, self.nsc, self.nt = na, nsc, nt
|
||||
|
||||
def forward(self, x):
|
||||
B = x.shape[0]
|
||||
t = x.permute(0, 3, 1, 2).reshape(B, self.nt, self.na * self.nsc)
|
||||
h = self.tf(self.proj(t) + self.pos)
|
||||
w = torch.softmax(self.att(h), 1)
|
||||
z = (h * w).sum(1)
|
||||
kp0 = torch.sigmoid(self.head(z)).reshape(B, 17, 2)
|
||||
return self.gr(z, kp0).reshape(B, 34)
|
||||
|
||||
def add_lora(self, r=8, alpha=16):
|
||||
"""Wrap the input projection + pose head with LoRA adapters (the ~11 KB calibration set)."""
|
||||
self.proj = LoRA(self.proj, r, alpha)
|
||||
self.head[0] = LoRA(self.head[0], r, alpha)
|
||||
self.head[3] = LoRA(self.head[3], r, alpha)
|
||||
return self
|
||||
|
||||
def lora_state(self) -> dict:
|
||||
"""Extract just the LoRA A/B tensors (the per-room adapter to save)."""
|
||||
return {k: v.detach().cpu().numpy() for k, v in self.state_dict().items()
|
||||
if k.endswith(".A") or k.endswith(".B")}
|
||||
|
||||
def load_lora(self, adapter: dict):
|
||||
sd = self.state_dict()
|
||||
for k, v in adapter.items():
|
||||
sd[k] = torch.tensor(v)
|
||||
self.load_state_dict(sd)
|
||||
return self
|
||||
|
||||
|
||||
def standardize(x: torch.Tensor) -> torch.Tensor:
|
||||
"""Per-sample standardization used in training/inference."""
|
||||
return (x - x.mean((1, 2, 3), keepdim=True)) / (x.std((1, 2, 3), keepdim=True) + 1e-6)
|
||||
@@ -1,103 +0,0 @@
|
||||
"""Self-contained regression test for the RuView calibration service.
|
||||
|
||||
Exercises the committed CLI end-to-end on synthetic data (CPU, no GPU, no real checkpoint):
|
||||
build a base -> calibrate.py fits an adapter -> infer.py runs base+adapter -> assert the
|
||||
adapter is small, inference is shape-correct and finite, and the adapter actually changes output.
|
||||
|
||||
Run: python test_calibration.py (or via pytest)
|
||||
"""
|
||||
import json
|
||||
import subprocess
|
||||
import sys
|
||||
import tempfile
|
||||
from pathlib import Path
|
||||
|
||||
import numpy as np
|
||||
import torch
|
||||
|
||||
HERE = Path(__file__).parent
|
||||
sys.path.insert(0, str(HERE))
|
||||
from model import PoseNet, standardize # noqa: E402
|
||||
|
||||
|
||||
def _make_base(path: Path):
|
||||
torch.manual_seed(0)
|
||||
net = PoseNet()
|
||||
# Save without the deterministic gr.A buffer (mirrors the published checkpoint;
|
||||
# calibrate.py/infer.py load with strict=False).
|
||||
sd = {k: v for k, v in net.state_dict().items() if k != "gr.A"}
|
||||
torch.save(sd, path)
|
||||
|
||||
|
||||
def _make_data(path: Path, n: int, seed: int):
|
||||
rng = np.random.default_rng(seed)
|
||||
X = rng.standard_normal((n, 3, 114, 10)).astype(np.float32)
|
||||
Y = rng.random((n, 17, 2)).astype(np.float32) # keypoints in [0,1]
|
||||
np.savez(path, X=X, Y=Y)
|
||||
|
||||
|
||||
def _run(*args):
|
||||
r = subprocess.run(
|
||||
[sys.executable, str(HERE / args[0]), *map(str, args[1:])],
|
||||
capture_output=True, text=True,
|
||||
)
|
||||
assert r.returncode == 0, f"{args[0]} failed:\n{r.stdout}\n{r.stderr}"
|
||||
return r.stdout
|
||||
|
||||
|
||||
def test_calibration_end_to_end():
|
||||
with tempfile.TemporaryDirectory() as d:
|
||||
d = Path(d)
|
||||
base = d / "base.pt"
|
||||
calib = d / "calib.npz"
|
||||
frames = d / "frames.npz"
|
||||
adapter = d / "room.adapter.npz"
|
||||
kp = d / "kp.npy"
|
||||
|
||||
_make_base(base)
|
||||
_make_data(calib, n=40, seed=1) # ≥20 → no underfit warning
|
||||
_make_data(frames, n=16, seed=2)
|
||||
|
||||
# 1) calibrate -> adapter
|
||||
out = _run("calibrate.py", "--base", base, "--data", calib, "--out", adapter,
|
||||
"--iters", "50", "--device", "cpu")
|
||||
assert adapter.exists(), "adapter not written"
|
||||
assert "saved" in out.lower()
|
||||
sz = adapter.stat().st_size
|
||||
assert sz < 200_000, f"adapter unexpectedly large ({sz} bytes)"
|
||||
|
||||
# adapter contains the expected LoRA tensors (materialize + close so the
|
||||
# Windows tempdir can be cleaned up — np.load keeps a lazy file handle).
|
||||
with np.load(adapter) as z:
|
||||
keys = [k for k in z.files if k.endswith(".A") or k.endswith(".B")]
|
||||
assert keys, f"adapter has no LoRA tensors: {z.files}"
|
||||
lora = {k: z[k].astype(np.float32) for k in keys}
|
||||
|
||||
# 2) infer with adapter -> keypoints
|
||||
_run("infer.py", "--base", base, "--adapter", adapter, "--data", frames,
|
||||
"--out", kp, "--device", "cpu")
|
||||
out_kp = np.load(kp)
|
||||
assert out_kp.shape == (16, 17, 2), f"bad keypoint shape {out_kp.shape}"
|
||||
assert np.isfinite(out_kp).all(), "non-finite keypoints"
|
||||
assert (out_kp >= 0).all() and (out_kp <= 1).all(), "keypoints out of [0,1]"
|
||||
|
||||
# 3) adapter must actually change the output vs the zero-shot base
|
||||
with np.load(frames) as fz:
|
||||
frames_x = fz["X"][:]
|
||||
net = PoseNet()
|
||||
net.load_state_dict(torch.load(base, map_location="cpu"), strict=False)
|
||||
net.eval()
|
||||
x = standardize(torch.tensor(frames_x))
|
||||
with torch.no_grad():
|
||||
base_kp = net(x).reshape(16, 17, 2).numpy()
|
||||
net.add_lora()
|
||||
net.load_lora(lora)
|
||||
net.eval()
|
||||
with torch.no_grad():
|
||||
cal_kp = net(x).reshape(16, 17, 2).numpy()
|
||||
assert np.abs(base_kp - cal_kp).sum() > 1e-4, "adapter did not change output"
|
||||
|
||||
|
||||
if __name__ == "__main__":
|
||||
test_calibration_end_to_end()
|
||||
print("PASS: calibration service end-to-end (calibrate -> adapter -> infer)")
|
||||
@@ -1,75 +0,0 @@
|
||||
"""Regression test for the cog-pose adapter producer (cog_calibrate.py).
|
||||
|
||||
Uses the in-repo `pose_v1.safetensors` (skips if absent). Verifies the produced adapter:
|
||||
- has the exact keys/shapes the Rust `cog-pose-estimation --adapter` loader expects,
|
||||
- reduces calibration fit error,
|
||||
- actually changes inference output,
|
||||
- is tiny.
|
||||
Run: python test_cog_calibration.py (or via pytest)
|
||||
"""
|
||||
import os
|
||||
import sys
|
||||
import tempfile
|
||||
from pathlib import Path
|
||||
|
||||
import numpy as np
|
||||
import torch
|
||||
import torch.nn.functional as F
|
||||
|
||||
HERE = Path(__file__).parent
|
||||
sys.path.insert(0, str(HERE))
|
||||
import cog_calibrate as C # noqa: E402
|
||||
|
||||
BASE = HERE / "../../v2/crates/cog-pose-estimation/cog/artifacts/pose_v1.safetensors"
|
||||
|
||||
|
||||
def test_cog_adapter_producer():
|
||||
if not BASE.exists():
|
||||
print(f"(skip — {BASE} not present)")
|
||||
return
|
||||
from safetensors.torch import load_file
|
||||
|
||||
rng = np.random.default_rng(0)
|
||||
n = 120
|
||||
X = rng.standard_normal((n, 56, 20)).astype("float32")
|
||||
Y = (0.5 + 0.1 * X[:, :34, 0].reshape(n, 34)).clip(0, 1).astype("float32")
|
||||
|
||||
with tempfile.TemporaryDirectory() as d:
|
||||
calib = os.path.join(d, "calib.npz")
|
||||
adapter = os.path.join(d, "room.safetensors")
|
||||
np.savez(calib, X=X, Y=Y)
|
||||
|
||||
net0 = C.CogPose()
|
||||
C.load_base(net0, str(BASE))
|
||||
net0.eval()
|
||||
with torch.no_grad():
|
||||
base_err = F.smooth_l1_loss(net0(torch.tensor(X)), torch.tensor(Y)).item()
|
||||
|
||||
_, nparam, _ = C.fit(str(BASE), calib, adapter, rank=4, iters=400)
|
||||
t = load_file(adapter)
|
||||
|
||||
# exact Rust loader contract: a:[in,r], b:[r,out]
|
||||
assert tuple(t["fc1.a"].shape) == (128, 4)
|
||||
assert tuple(t["fc1.b"].shape) == (4, 256)
|
||||
assert tuple(t["fc2.a"].shape) == (256, 4)
|
||||
assert tuple(t["fc2.b"].shape) == (4, 34)
|
||||
|
||||
net = C.CogPose()
|
||||
C.load_base(net, str(BASE))
|
||||
net.add_lora(4)
|
||||
with torch.no_grad():
|
||||
net.fc1_lora[0].copy_(t["fc1.a"]); net.fc1_lora[1].copy_(t["fc1.b"] / (16 / 4))
|
||||
net.fc2_lora[0].copy_(t["fc2.a"]); net.fc2_lora[1].copy_(t["fc2.b"] / (16 / 4))
|
||||
net.eval()
|
||||
with torch.no_grad():
|
||||
cal_err = F.smooth_l1_loss(net(torch.tensor(X)), torch.tensor(Y)).item()
|
||||
changed = (net0(torch.tensor(X[:8])) - net(torch.tensor(X[:8]))).abs().sum().item()
|
||||
|
||||
assert cal_err < base_err, f"calibration did not reduce error ({base_err} -> {cal_err})"
|
||||
assert changed > 1e-3, "adapter inert"
|
||||
assert nparam < 5000, f"adapter unexpectedly large ({nparam} params)"
|
||||
|
||||
|
||||
if __name__ == "__main__":
|
||||
test_cog_adapter_producer()
|
||||
print("PASS: cog adapter producer (Rust-loadable format, reduces error, active)")
|
||||
@@ -1 +0,0 @@
|
||||
9c35e541d51f00998691b98948887ebca09b907d8eb29a113f97e792340456ba
|
||||
@@ -1 +0,0 @@
|
||||
{"frames": [{"pred": [[0.4003, 0.2734], [0.5038, 0.4197], [0.2053, 0.4438], [0.4397, 0.685], [0.5796, 0.7645], [0.8001, 0.2195], [0.2789, 0.2833], [0.314, 0.5439], [0.511, 0.2259], [0.6008, 0.46], [0.4837, 0.3879], [0.3475, 0.5597], [0.6569, 0.3575], [0.437, 0.6539], [0.2341, 0.6038], [0.7331, 0.392], [0.5615, 0.4915]]}, {"pred": [[0.4669, 0.6066], [0.6012, 0.7873], [0.4124, 0.5997], [0.2832, 0.281], [0.2732, 0.3635], [0.2503, 0.4848], [0.6827, 0.715], [0.4336, 0.7165], [0.295, 0.3386], [0.5337, 0.3544], [0.4397, 0.5474], [0.5163, 0.5528], [0.7547, 0.6799], [0.4195, 0.4448], [0.2257, 0.2269], [0.384, 0.2176], [0.2419, 0.4332]]}, {"pred": [[0.5585, 0.283], [0.4325, 0.2934], [0.463, 0.4744], [0.4188, 0.3454], [0.215, 0.7565], [0.527, 0.2353], [0.7084, 0.6124], [0.3015, 0.6744], [0.4103, 0.3532], [0.7243, 0.6932], [0.3302, 0.4918], [0.2072, 0.3754], [0.7914, 0.4878], [0.7618, 0.4079], [0.323, 0.3386], [0.7104, 0.4997], [0.2673, 0.6077]]}, {"pred": [[0.6372, 0.4984], [0.4184, 0.6763], [0.4498, 0.7549], [0.2924, 0.303], [0.3069, 0.7022], [0.3954, 0.5098], [0.7836, 0.6071], [0.4733, 0.7114], [0.3407, 0.3793], [0.3408, 0.4678], [0.4156, 0.4911], [0.4525, 0.7519], [0.5117, 0.1985], [0.1893, 0.6784], [0.6281, 0.5346], [0.5175, 0.673], [0.36, 0.3665]]}, {"pred": [[0.5535, 0.6537], [0.568, 0.511], [0.4705, 0.5377], [0.6372, 0.7163], [0.5493, 0.7515], [0.2559, 0.4549], [0.2553, 0.6176], [0.2991, 0.6154], [0.7185, 0.7986], [0.4586, 0.5057], [0.2975, 0.4525], [0.3263, 0.3719], [0.5131, 0.4576], [0.557, 0.5268], [0.6572, 0.7736], [0.2146, 0.6526], [0.4662, 0.7371]]}, {"pred": [[0.2924, 0.7595], [0.2612, 0.2315], [0.2488, 0.7751], [0.2329, 0.7282], [0.4744, 0.4206], [0.3618, 0.267], [0.2477, 0.285], [0.3976, 0.3746], [0.494, 0.2874], [0.3596, 0.2112], [0.3311, 0.4692], [0.6912, 0.4727], [0.4434, 0.5233], [0.4139, 0.7048], [0.425, 0.3937], [0.2326, 0.631], [0.2655, 0.7116]]}, {"pred": [[0.3609, 0.3437], [0.285, 0.486], [0.7734, 0.5468], [0.3657, 0.4093], [0.4728, 0.5019], [0.1866, 0.3545], [0.2172, 0.2028], [0.5613, 0.5238], [0.6252, 0.7205], [0.7998, 0.2954], [0.242, 0.7063], [0.6259, 0.6883], [0.5148, 0.7141], [0.5577, 0.7434], [0.3233, 0.2131], [0.2652, 0.7066], [0.5753, 0.5885]]}, {"pred": [[0.6787, 0.6504], [0.6051, 0.2297], [0.2539, 0.3475], [0.6437, 0.7807], [0.4981, 0.6149], [0.5716, 0.2367], [0.6486, 0.3632], [0.2433, 0.369], [0.6061, 0.3731], [0.4955, 0.2591], [0.7676, 0.7602], [0.6899, 0.7716], [0.3143, 0.7707], [0.3031, 0.4997], [0.7076, 0.5133], [0.3382, 0.7196], [0.2002, 0.4871]]}]}
|
||||
@@ -1 +0,0 @@
|
||||
{"frames": [{"gt": [[0.3943, 0.2905], [0.5215, 0.4194], [0.2225, 0.4602], [0.4547, 0.6961], [0.5765, 0.7686], [0.7858, 0.2279], [0.2866, 0.2707], [0.3084, 0.549], [0.5286, 0.2377], [0.6082, 0.4566], [0.4719, 0.3799], [0.3465, 0.5447], [0.6377, 0.3728], [0.4509, 0.6543], [0.2235, 0.6009], [0.7253, 0.3882], [0.5479, 0.4737]], "vis": [1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0], "scale": 1.0}, {"gt": [[0.4845, 0.5985], [0.5883, 0.7959], [0.4315, 0.6012], [0.3008, 0.2703], [0.2776, 0.3486], [0.2483, 0.4695], [0.6916, 0.7184], [0.4153, 0.7305], [0.3057, 0.3392], [0.5535, 0.3576], [0.4216, 0.5398], [0.5093, 0.5706], [0.7397, 0.668], [0.4354, 0.4394], [0.2373, 0.2404], [0.404, 0.2315], [0.2609, 0.4182]], "vis": [1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0], "scale": 1.0}, {"gt": [[0.5684, 0.2891], [0.4185, 0.2737], [0.4796, 0.4903], [0.4056, 0.3589], [0.2139, 0.7706], [0.5259, 0.2162], [0.718, 0.6177], [0.3002, 0.6632], [0.3978, 0.3338], [0.7116, 0.6836], [0.336, 0.5106], [0.2168, 0.3677], [0.7739, 0.4683], [0.773, 0.4188], [0.318, 0.3226], [0.7043, 0.4877], [0.2509, 0.5964]], "vis": [1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0], "scale": 1.0}, {"gt": [[0.6501, 0.4868], [0.3995, 0.6805], [0.4408, 0.7681], [0.2762, 0.2907], [0.2877, 0.6959], [0.4102, 0.5292], [0.7825, 0.5898], [0.4603, 0.723], [0.3511, 0.3758], [0.3556, 0.4514], [0.4123, 0.4749], [0.4524, 0.7506], [0.5141, 0.2112], [0.2024, 0.6795], [0.6351, 0.5339], [0.5333, 0.6706], [0.3491, 0.3662]], "vis": [1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0], "scale": 1.0}, {"gt": [[0.537, 0.656], [0.5675, 0.5033], [0.4714, 0.52], [0.6195, 0.7259], [0.5357, 0.766], [0.273, 0.4653], [0.2439, 0.6017], [0.2927, 0.6297], [0.7297, 0.7805], [0.439, 0.4924], [0.2969, 0.4589], [0.3174, 0.3911], [0.5324, 0.4643], [0.5744, 0.5074], [0.673, 0.783], [0.2238, 0.6674], [0.4534, 0.7468]], "vis": [1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0], "scale": 1.0}, {"gt": [[0.2896, 0.7515], [0.2537, 0.2345], [0.2434, 0.763], [0.2502, 0.7137], [0.4723, 0.4035], [0.3607, 0.2775], [0.2657, 0.2969], [0.3872, 0.383], [0.5001, 0.3067], [0.3503, 0.2092], [0.3137, 0.4849], [0.6914, 0.4593], [0.4359, 0.504], [0.4056, 0.6994], [0.4428, 0.4085], [0.2424, 0.6445], [0.2507, 0.7048]], "vis": [1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0], "scale": 1.0}, {"gt": [[0.3692, 0.3453], [0.2945, 0.4675], [0.7836, 0.5282], [0.3857, 0.414], [0.4848, 0.5017], [0.203, 0.3585], [0.225, 0.2135], [0.5513, 0.5175], [0.6296, 0.7275], [0.7908, 0.2897], [0.2263, 0.7012], [0.6403, 0.6873], [0.5026, 0.701], [0.5504, 0.7357], [0.338, 0.2187], [0.2629, 0.7015], [0.5757, 0.6084]], "vis": [1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0], "scale": 1.0}, {"gt": [[0.6786, 0.649], [0.5956, 0.2396], [0.2447, 0.3593], [0.6439, 0.7854], [0.4874, 0.6102], [0.5857, 0.2465], [0.6459, 0.3827], [0.2364, 0.3613], [0.6054, 0.3745], [0.4798, 0.2711], [0.7869, 0.7618], [0.6919, 0.7809], [0.3259, 0.7674], [0.285, 0.5144], [0.6921, 0.5052], [0.3388, 0.7386], [0.2022, 0.495]], "vis": [1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0], "scale": 1.0}]}
|
||||
@@ -1,5 +0,0 @@
|
||||
{"benchmark": "AetherArena", "created": "2026-05-30", "kind": "genesis", "note": "Official Spatial-Intelligence Benchmark \u2014 append-only signed ledger. Entries are real harness scores only; no seeded numbers.", "prev_hash": "0000000000000000000000000000000000000000000000000000000000000000", "row_hash": "940bdc6f0f5dd00f4d89e13a8fa843bab3c9ddf1b8051f426a1701e730249231", "seq": 0, "spec": "ADR-149"}
|
||||
{"abs_gain": "+9.38", "benchmark": "MM-Fi", "category": "pose", "caveat": "Protocol-matched MM-Fi random_split result; NOT solved real-world generalization. Random split has temporal/subject-adjacency effects common to this benchmark family. Leakage-free cross-subject is far lower (~11-27%) and is the real deployment frontier.", "harness_version": 1, "kind": "result", "metric": "torso-PCK@20 (||right_shoulder-left_hip|| norm, 17 COCO kpts)", "modality": "wifi-csi", "model_ref": "RuView CSI-Transformer (4L/8H ~2M params, temporal-attention)", "prev_hash": "940bdc6f0f5dd00f4d89e13a8fa843bab3c9ddf1b8051f426a1701e730249231", "protocol": "random_split (ratio=0.8, seed=0)", "rel_gain": "+13.0%", "reproduce": "download MM-Fi -> parse_mmfi_zips.py -> train_tf_torso.py X.npy Y.npy split_random.npy (seed 0)", "row_hash": "76598d8e1320d5248f8cd854a8ffa22a99bd2a2f0e0e7f2d2b1df79af16001d5", "score_pct": 81.63, "scored_at": "2026-05-30", "seq": 1, "sota_ref": "MultiFormer 72.25 (CSI2Pose 68.41)", "submitter": "ruvnet", "tier": "Gold"}
|
||||
{"abs_gain": "+11.34", "benchmark": "MM-Fi", "category": "pose", "harness_version": 1, "kind": "result", "metric": "torso-PCK@20", "modality": "wifi-csi", "model_ref": "RuView CSI-Transformer + skeleton-graph head + 3-ensemble + TTA", "note": "Best in-domain. Stacks attention-pooling + transformer + skeleton-graph refine + warmup + TTA + 3-model ensemble. Supersedes the 81.63 single-model entry.", "prev_hash": "76598d8e1320d5248f8cd854a8ffa22a99bd2a2f0e0e7f2d2b1df79af16001d5", "protocol": "random_split (0.8, seed 0)", "row_hash": "5780a4bc3e98eb0e30c1ecfa9091e57b280444fa1f21cd5146797e408580e4ab", "score_pct": 83.59, "scored_at": "2026-05-30", "seq": 2, "sota_ref": "MultiFormer 72.25 (CSI2Pose 68.41)", "submitter": "ruvnet", "tier": "Gold"}
|
||||
{"benchmark": "MM-Fi", "category": "pose", "harness_version": 1, "kind": "result", "metric": "torso-PCK@20", "modality": "wifi-csi", "model_ref": "RuView CSI-Transformer", "note": "Leakage-free generalization to unseen people, shared rooms. Honest deployment-relevant number.", "prev_hash": "5780a4bc3e98eb0e30c1ecfa9091e57b280444fa1f21cd5146797e408580e4ab", "protocol": "cross_subject (official, val=S05,S10,..,S40)", "row_hash": "d989e4e1dbc0182610305fdfbde8b094413b87c913283a46bf41f4afba7a06fd", "score_pct": 64.04, "scored_at": "2026-05-30", "seq": 3, "sota_ref": "(no matched public ref)", "submitter": "ruvnet", "tier": "Silver"}
|
||||
{"benchmark": "MM-Fi", "category": "pose", "harness_version": 1, "kind": "result", "metric": "torso-PCK@20", "modality": "wifi-csi", "model_ref": "RuView CSI-Transformer + CORAL domain alignment", "note": "The real deployment frontier (new room). CORAL transductive DG (+30% rel over control). Data-bound: MM-Fi has only 3 source rooms.", "prev_hash": "d989e4e1dbc0182610305fdfbde8b094413b87c913283a46bf41f4afba7a06fd", "protocol": "cross_environment (train E01-03 -> test E04, new room)", "row_hash": "bf370487bde88e198c13877956dab3c83766a6a24afef0b78b6ac7aa130bb207", "score_pct": 17.51, "scored_at": "2026-05-30", "seq": 4, "sota_ref": "(hard frontier; control 13.52)", "submitter": "ruvnet", "tier": "Bronze"}
|
||||
@@ -1,100 +0,0 @@
|
||||
#!/usr/bin/env python3
|
||||
"""AetherArena append-only, tamper-evident results ledger (ADR-149 §2.3/§2.4).
|
||||
|
||||
Each row is hash-chained to the previous one: ``row_hash = sha256(canonical_row
|
||||
+ prev_hash)``. Any silent edit to an earlier row breaks every subsequent
|
||||
``prev_hash`` link, so the ledger is append-only and verifiable by anyone — no
|
||||
trust in the maintainer required. (Ed25519 row signing is the next hardening;
|
||||
the chain already makes tampering detectable.)
|
||||
|
||||
Usage:
|
||||
python ledger_tools.py seed # (re)build ledger.jsonl with genesis + baseline
|
||||
python ledger_tools.py verify # verify the whole chain -> exit 0 / 1
|
||||
python ledger_tools.py append '<json-row>' # append one scored row
|
||||
"""
|
||||
import hashlib
|
||||
import json
|
||||
import sys
|
||||
from pathlib import Path
|
||||
|
||||
LEDGER = Path(__file__).parent / "ledger.jsonl"
|
||||
GENESIS_PREV = "0" * 64
|
||||
|
||||
|
||||
def canonical(row: dict) -> bytes:
|
||||
# Stable key order, no whitespace -> deterministic bytes for hashing.
|
||||
body = {k: row[k] for k in sorted(row) if k != "row_hash"}
|
||||
return json.dumps(body, separators=(",", ":"), sort_keys=True).encode()
|
||||
|
||||
|
||||
def row_hash(row: dict) -> str:
|
||||
return hashlib.sha256(canonical(row)).hexdigest()
|
||||
|
||||
|
||||
def read_rows() -> list[dict]:
|
||||
if not LEDGER.exists():
|
||||
return []
|
||||
return [json.loads(l) for l in LEDGER.read_text().splitlines() if l.strip()]
|
||||
|
||||
|
||||
def append(entry: dict) -> dict:
|
||||
rows = read_rows()
|
||||
prev = rows[-1]["row_hash"] if rows else GENESIS_PREV
|
||||
entry = dict(entry)
|
||||
entry["seq"] = len(rows)
|
||||
entry["prev_hash"] = prev
|
||||
entry["row_hash"] = row_hash(entry)
|
||||
with LEDGER.open("a") as f:
|
||||
f.write(json.dumps(entry, sort_keys=True) + "\n")
|
||||
return entry
|
||||
|
||||
|
||||
def verify() -> bool:
|
||||
rows = read_rows()
|
||||
prev = GENESIS_PREV
|
||||
for i, r in enumerate(rows):
|
||||
if r.get("seq") != i:
|
||||
print(f"FAIL: row {i} seq mismatch ({r.get('seq')})")
|
||||
return False
|
||||
if r.get("prev_hash") != prev:
|
||||
print(f"FAIL: row {i} prev_hash broken — ledger was edited")
|
||||
return False
|
||||
if r.get("row_hash") != row_hash(r):
|
||||
print(f"FAIL: row {i} row_hash mismatch — row was tampered")
|
||||
return False
|
||||
prev = r["row_hash"]
|
||||
print(f"OK: {len(rows)} rows, chain intact")
|
||||
return True
|
||||
|
||||
|
||||
def seed():
|
||||
"""Rebuild with the genesis row only — an EMPTY board.
|
||||
|
||||
Benchmark-first: no placeholder/hand-entered numbers ever sit on the
|
||||
leaderboard. Every result row is produced by the real scoring pipeline
|
||||
(load model -> run inference -> score against the private eval split ->
|
||||
proof hash). The board starts empty and awaits the first real harness score,
|
||||
including RuView's own — which gets no special seeding.
|
||||
"""
|
||||
if LEDGER.exists():
|
||||
LEDGER.unlink()
|
||||
append({
|
||||
"kind": "genesis",
|
||||
"benchmark": "AetherArena",
|
||||
"spec": "ADR-149",
|
||||
"note": "Official Spatial-Intelligence Benchmark — append-only signed ledger. "
|
||||
"Entries are real harness scores only; no seeded numbers.",
|
||||
"created": "2026-05-30",
|
||||
})
|
||||
|
||||
|
||||
if __name__ == "__main__":
|
||||
cmd = sys.argv[1] if len(sys.argv) > 1 else "verify"
|
||||
if cmd == "seed":
|
||||
seed(); verify()
|
||||
elif cmd == "verify":
|
||||
sys.exit(0 if verify() else 1)
|
||||
elif cmd == "append":
|
||||
print(json.dumps(append(json.loads(sys.argv[2])), indent=2))
|
||||
else:
|
||||
print(__doc__); sys.exit(2)
|
||||
@@ -1,41 +0,0 @@
|
||||
# AetherArena submission manifest (ADR-149 §2.2).
|
||||
# Accompanies a model artifact pushed to the AA Hugging Face Space.
|
||||
# This file is the contract the Space validates before quarantine + scoring.
|
||||
|
||||
[submission]
|
||||
# Free-form display name shown on the leaderboard.
|
||||
name = "my-spatial-model"
|
||||
# Hugging Face repo or URL of the model artifact (.safetensors / .rvf / LoRA adapter).
|
||||
model_ref = "hf://your-org/your-model"
|
||||
# Submitter handle (HF username / org). Used to sign the ledger row.
|
||||
submitter = "your-hf-username"
|
||||
# SPDX license of the submitted model.
|
||||
license = "Apache-2.0"
|
||||
|
||||
[category]
|
||||
# One of: pose | presence | tracking | vitals | multi-task
|
||||
# v0 ranks: pose, presence (tracking/vitals activate when ground truth lands).
|
||||
primary = "pose"
|
||||
|
||||
[input]
|
||||
# Which ADR-145 FeatureSet the model consumes. v0 input is RF/WiFi CSI.
|
||||
# F0 = CSI amplitude/phase F1 = +CIR F2 = +Doppler F3 = +BFLD
|
||||
feature_set = "F0"
|
||||
# Tensor I/O contract so the scorer can feed the model correctly.
|
||||
input_shape = [114, 2] # subcarriers × {amp, phase} (example)
|
||||
output_shape = [17, 2] # 17 keypoints × {x, y} normalised [0,1]
|
||||
# Normalisation expected on the input ("none" | "zscore" | "minmax").
|
||||
normalization = "zscore"
|
||||
|
||||
[runtime]
|
||||
# Inference entrypoint inside the artifact (framework-specific).
|
||||
framework = "candle" # candle | onnx | torch
|
||||
# Optional: target the edge-latency category with a declared device class.
|
||||
device_class = "cpu" # cpu | pi5 | gpu
|
||||
|
||||
# Notes:
|
||||
# - You submit a MODEL, never predictions on data you hold.
|
||||
# - Scoring runs against a PRIVATE MM-Fi held-out split in a no-network,
|
||||
# read-only sandbox. You cannot see the eval data.
|
||||
# - The resulting score is a signed, append-only ledger row carrying a
|
||||
# determinism proof hash and the pinned harness_version.
|
||||
@@ -1,37 +0,0 @@
|
||||
---
|
||||
title: AetherArena — Spatial-Intelligence Benchmark
|
||||
emoji: 📡
|
||||
colorFrom: indigo
|
||||
colorTo: purple
|
||||
sdk: gradio
|
||||
sdk_version: 5.9.1
|
||||
python_version: "3.12"
|
||||
app_file: app.py
|
||||
pinned: true
|
||||
license: cc-by-nc-4.0
|
||||
tags:
|
||||
- benchmark
|
||||
- leaderboard
|
||||
- wifi-sensing
|
||||
- spatial-intelligence
|
||||
- pose-estimation
|
||||
---
|
||||
|
||||
# AetherArena ("AA") — The Official Spatial-Intelligence Benchmark
|
||||
|
||||
> Public leaderboard. Private evaluation split. Open scorer. Signed results.
|
||||
|
||||
The field's standard yardstick for camera-free **spatial intelligence** (pose, presence,
|
||||
occupancy, tracking, vitals) from RF/WiFi and, over time, mmWave / UWB / multimodal.
|
||||
|
||||
- **Project-agnostic** — any team, framework, or modality enters; RuView donated the seed
|
||||
scorer and is scored like everyone else.
|
||||
- **Benchmark-first** — the board starts empty; every row is a real scoring-pipeline
|
||||
**witness** (`inputs_sha256` + `proof_sha256` + `harness_version`) in an append-only,
|
||||
hash-chained, tamper-evident ledger.
|
||||
- **Reproducible** — the scorer is open; reproduce any proof hash + repeatability locally.
|
||||
|
||||
Spec: [ADR-149](https://github.com/ruvnet/RuView/blob/main/docs/adr/ADR-149-public-community-leaderboard-huggingface.md).
|
||||
Source + open scorer: https://github.com/ruvnet/RuView/tree/main/aether-arena
|
||||
|
||||
Non-commercial (CC BY-NC 4.0): the v0 eval split derives from MM-Fi (CC BY-NC); AA is operated non-commercially.
|
||||
@@ -1,161 +0,0 @@
|
||||
"""AetherArena ("AA") — The Official Spatial-Intelligence Benchmark.
|
||||
|
||||
Hugging Face Space (Gradio) — the public face of the benchmark (ADR-149).
|
||||
This Space is the presentation + submission layer; the heavy scoring runs in the
|
||||
pinned RuView harness (CI / scorer container), and results land in the append-only,
|
||||
hash-chained **witness ledger** shown here.
|
||||
|
||||
Benchmark-first: the board starts EMPTY. No seeded or hand-entered numbers — every
|
||||
row is a real scoring-pipeline witness (inputs_sha256 + proof_sha256 + harness_version).
|
||||
"""
|
||||
import hashlib
|
||||
import json
|
||||
from pathlib import Path
|
||||
|
||||
import gradio as gr
|
||||
|
||||
LEDGER = Path(__file__).parent / "ledger.jsonl"
|
||||
GENESIS_PREV = "0" * 64
|
||||
|
||||
|
||||
def _rows():
|
||||
if not LEDGER.exists():
|
||||
return []
|
||||
return [json.loads(l) for l in LEDGER.read_text().splitlines() if l.strip()]
|
||||
|
||||
|
||||
def _canon(row: dict) -> bytes:
|
||||
body = {k: row[k] for k in sorted(row) if k != "row_hash"}
|
||||
return json.dumps(body, separators=(",", ":"), sort_keys=True).encode()
|
||||
|
||||
|
||||
def verify_chain():
|
||||
rows, prev = _rows(), GENESIS_PREV
|
||||
for i, r in enumerate(rows):
|
||||
if r.get("prev_hash") != prev or r.get("row_hash") != hashlib.sha256(_canon(r)).hexdigest():
|
||||
return f"❌ Ledger chain BROKEN at row {i} — tampering detected."
|
||||
prev = r["row_hash"]
|
||||
return f"✅ Witness ledger chain intact — {len(rows)} row(s), append-only."
|
||||
|
||||
|
||||
def leaderboard(category: str):
|
||||
results = [r for r in _rows() if r.get("kind") == "result" and (category == "all" or r.get("category") == category)]
|
||||
if not results:
|
||||
return [["— no entries yet —", "", "", "", "", ""]]
|
||||
results.sort(key=lambda r: r.get("score_pct") or 0, reverse=True)
|
||||
return [[
|
||||
r.get("submitter", "?"),
|
||||
r.get("model_ref", "?"),
|
||||
f"{r.get('benchmark','?')} / {r.get('protocol','?')}",
|
||||
r.get("metric", "?"),
|
||||
f"{r.get('score_pct', 0):.2f}%",
|
||||
f"{r.get('tier','?')} (vs {r.get('sota_ref','?')})",
|
||||
] for r in results]
|
||||
|
||||
|
||||
FOUR_PART = "### Public leaderboard. Private evaluation split. Open scorer. Signed results."
|
||||
|
||||
ABOUT = """
|
||||
**AetherArena** is the official, project-agnostic **Spatial-Intelligence Benchmark** —
|
||||
camera-free pose, presence, occupancy, tracking, and vitals from RF/WiFi (and, over
|
||||
time, mmWave / UWB / radar / multimodal). It is **not** a single-vendor board: any
|
||||
team, framework, or modality enters, and every entrant — including the RuView baseline
|
||||
that donated the seed scorer — is scored by the identical, open, pinned harness.
|
||||
|
||||
The scorer reuses RuView's released `wifi-densepose-train` acceptance harness
|
||||
(`ruview_metrics` + ablation). You submit a **model, not predictions**; it is scored
|
||||
against a **private** MM-Fi held-out split; one **witness** row (inputs hash + proof
|
||||
hash + harness version) is appended to a **hash-chained, tamper-evident ledger**.
|
||||
|
||||
**For industry:** a vendor-neutral, auditable way to compare RF-sensing models on equal
|
||||
footing — the same standardized splits, the same metric definition, the same signed,
|
||||
reproducible ledger. No more "trust our number on our split." Vendors, labs, and startups
|
||||
all submit through one pipeline and are scored identically.
|
||||
|
||||
**Generalization Track (roadmap):** the headline isn't a single in-domain number — it's a
|
||||
battery of honest tracks: MM-Fi `random_split` (in-domain), `cross_subject` (unseen people),
|
||||
cross-room, cross-device, and confidence-calibration (ECE). Cross-subject is the real
|
||||
deployment frontier and is treated as the flagship hard benchmark.
|
||||
|
||||
Spec: ADR-149. v0 ranks **pose, presence, edge-latency, determinism**. Tracking &
|
||||
vitals activate when their ground truth lands; **privacy-leakage** is gated until the
|
||||
membership-inference attacker ships. Source + the open scorer:
|
||||
https://github.com/ruvnet/RuView/tree/main/aether-arena
|
||||
"""
|
||||
|
||||
SUBMIT = """
|
||||
### Submit a model
|
||||
|
||||
1. Write a manifest — [`schema/aa-submission.toml`](https://github.com/ruvnet/RuView/blob/main/aether-arena/schema/aa-submission.toml):
|
||||
declare your model ref, category, the ADR-145 feature set (F0 CSI … F3 BFLD), and the tensor I/O contract.
|
||||
2. Provide your model artifact (`.safetensors` / `.rvf` / LoRA adapter).
|
||||
3. It moves through `submitted → validated → quarantined → smoke_scored → full_scored → published`,
|
||||
scored in a no-network, read-only sandbox against the private split.
|
||||
4. Your signed witness row appears on the leaderboard.
|
||||
|
||||
**You submit a model, never predictions** — predictions on data you hold prove nothing.
|
||||
"""
|
||||
|
||||
VERIFY = """
|
||||
### Verify it's fair (you don't have to trust us)
|
||||
|
||||
The scorer is open and reproducible. Reproduce the determinism proof + repeatability locally:
|
||||
|
||||
```bash
|
||||
git clone https://github.com/ruvnet/RuView && cd RuView/v2
|
||||
# determinism gate (same as CI):
|
||||
cargo run -q -p wifi-densepose-train --bin aa_score_runner --no-default-features
|
||||
# repeatability — N runs, one identical proof hash:
|
||||
cargo run -q -p wifi-densepose-train --bin aa_score_runner --no-default-features -- --repeat 16
|
||||
# verify the append-only witness ledger chain:
|
||||
cd ../aether-arena/ledger && python3 ledger_tools.py verify
|
||||
```
|
||||
|
||||
A stranger must be able to: submit → get a deterministic score → see the signed row →
|
||||
rerun the scorer locally → understand why the rank is fair. That is the launch gate (ADR-149 §7).
|
||||
"""
|
||||
|
||||
with gr.Blocks(title="AetherArena — Spatial-Intelligence Benchmark") as demo:
|
||||
gr.Markdown("# 📡 AetherArena (AA)\n## The Official, Vendor-Neutral Benchmark for WiFi / RF Spatial Sensing")
|
||||
gr.Markdown(FOUR_PART)
|
||||
gr.Markdown(
|
||||
"**An open industry benchmark — for everyone, not any one vendor.** Submit any model, any framework, "
|
||||
"any modality. Every entrant — academic, startup, or incumbent — is scored *identically*: standardized "
|
||||
"protocols (MM-Fi `random_split` / `cross_subject`), matched metrics (torso-PCK@20, the published "
|
||||
"definition), and an auditable, hash-chained **witness ledger** anyone can verify and reproduce.\n\n"
|
||||
"**Why it exists:** WiFi/RF-sensing results are reported with inconsistent splits, metrics, and no "
|
||||
"auditability — so numbers aren't comparable. AetherArena fixes the *measurement*: one protocol, one "
|
||||
"metric, one signed ledger, one-command reproduction. The benchmark is the product; the leaderboard is "
|
||||
"just the scoreboard. (Reference implementation seeded by RuView, ADR-149.)"
|
||||
)
|
||||
chain = gr.Markdown(verify_chain())
|
||||
|
||||
with gr.Tab("🏆 Leaderboard"):
|
||||
gr.Markdown(
|
||||
"### Current standings — MM-Fi WiFi-CSI 2D pose, torso-PCK@20\n"
|
||||
"Ranked, protocol- & metric-matched results. Each row carries its own caveats in the ledger "
|
||||
"(e.g. `random_split` has temporal-adjacency leakage that inflates *all* methods equally — the "
|
||||
"leakage-free `cross_subject` track is the real deployment frontier). **Submit yours — top the board.**"
|
||||
)
|
||||
cat = gr.Dropdown(["all", "pose", "presence"], value="all", label="Category")
|
||||
tbl = gr.Dataframe(
|
||||
headers=["Submitter", "Model", "Benchmark / Protocol", "Metric", "Score", "Tier (vs prior SOTA)"],
|
||||
value=leaderboard("all"), interactive=False, wrap=True,
|
||||
)
|
||||
cat.change(leaderboard, cat, tbl)
|
||||
gr.Markdown(
|
||||
"*Vendor-neutral & benchmark-first: every row is a real, metric- and protocol-matched result — "
|
||||
"no seeded or vendor-favored numbers. Integrity is enforced, not promised: the current top entry's "
|
||||
"score was self-corrected down from an inflated metric (91.86% bbox → 81.63% torso) before it could "
|
||||
"be published. The same scorer and ledger apply to every submitter.*"
|
||||
)
|
||||
|
||||
with gr.Tab("📤 Submit"):
|
||||
gr.Markdown(SUBMIT)
|
||||
with gr.Tab("🔬 Verify"):
|
||||
gr.Markdown(VERIFY)
|
||||
with gr.Tab("ℹ️ About"):
|
||||
gr.Markdown(ABOUT)
|
||||
|
||||
if __name__ == "__main__":
|
||||
demo.launch(server_name="0.0.0.0", server_port=7860)
|
||||
@@ -1,5 +0,0 @@
|
||||
{"benchmark": "AetherArena", "created": "2026-05-30", "kind": "genesis", "note": "Official Spatial-Intelligence Benchmark \u2014 append-only signed ledger. Entries are real harness scores only; no seeded numbers.", "prev_hash": "0000000000000000000000000000000000000000000000000000000000000000", "row_hash": "940bdc6f0f5dd00f4d89e13a8fa843bab3c9ddf1b8051f426a1701e730249231", "seq": 0, "spec": "ADR-149"}
|
||||
{"abs_gain": "+9.38", "benchmark": "MM-Fi", "category": "pose", "caveat": "Protocol-matched MM-Fi random_split result; NOT solved real-world generalization. Random split has temporal/subject-adjacency effects common to this benchmark family. Leakage-free cross-subject is far lower (~11-27%) and is the real deployment frontier.", "harness_version": 1, "kind": "result", "metric": "torso-PCK@20 (||right_shoulder-left_hip|| norm, 17 COCO kpts)", "modality": "wifi-csi", "model_ref": "RuView CSI-Transformer (4L/8H ~2M params, temporal-attention)", "prev_hash": "940bdc6f0f5dd00f4d89e13a8fa843bab3c9ddf1b8051f426a1701e730249231", "protocol": "random_split (ratio=0.8, seed=0)", "rel_gain": "+13.0%", "reproduce": "download MM-Fi -> parse_mmfi_zips.py -> train_tf_torso.py X.npy Y.npy split_random.npy (seed 0)", "row_hash": "76598d8e1320d5248f8cd854a8ffa22a99bd2a2f0e0e7f2d2b1df79af16001d5", "score_pct": 81.63, "scored_at": "2026-05-30", "seq": 1, "sota_ref": "MultiFormer 72.25 (CSI2Pose 68.41)", "submitter": "ruvnet", "tier": "Gold"}
|
||||
{"abs_gain": "+11.34", "benchmark": "MM-Fi", "category": "pose", "harness_version": 1, "kind": "result", "metric": "torso-PCK@20", "modality": "wifi-csi", "model_ref": "RuView CSI-Transformer + skeleton-graph head + 3-ensemble + TTA", "note": "Best in-domain. Stacks attention-pooling + transformer + skeleton-graph refine + warmup + TTA + 3-model ensemble. Supersedes the 81.63 single-model entry.", "prev_hash": "76598d8e1320d5248f8cd854a8ffa22a99bd2a2f0e0e7f2d2b1df79af16001d5", "protocol": "random_split (0.8, seed 0)", "row_hash": "5780a4bc3e98eb0e30c1ecfa9091e57b280444fa1f21cd5146797e408580e4ab", "score_pct": 83.59, "scored_at": "2026-05-30", "seq": 2, "sota_ref": "MultiFormer 72.25 (CSI2Pose 68.41)", "submitter": "ruvnet", "tier": "Gold"}
|
||||
{"benchmark": "MM-Fi", "category": "pose", "harness_version": 1, "kind": "result", "metric": "torso-PCK@20", "modality": "wifi-csi", "model_ref": "RuView CSI-Transformer", "note": "Leakage-free generalization to unseen people, shared rooms. Honest deployment-relevant number.", "prev_hash": "5780a4bc3e98eb0e30c1ecfa9091e57b280444fa1f21cd5146797e408580e4ab", "protocol": "cross_subject (official, val=S05,S10,..,S40)", "row_hash": "d989e4e1dbc0182610305fdfbde8b094413b87c913283a46bf41f4afba7a06fd", "score_pct": 64.04, "scored_at": "2026-05-30", "seq": 3, "sota_ref": "(no matched public ref)", "submitter": "ruvnet", "tier": "Silver"}
|
||||
{"benchmark": "MM-Fi", "category": "pose", "harness_version": 1, "kind": "result", "metric": "torso-PCK@20", "modality": "wifi-csi", "model_ref": "RuView CSI-Transformer + CORAL domain alignment", "note": "The real deployment frontier (new room). CORAL transductive DG (+30% rel over control). Data-bound: MM-Fi has only 3 source rooms.", "prev_hash": "d989e4e1dbc0182610305fdfbde8b094413b87c913283a46bf41f4afba7a06fd", "protocol": "cross_environment (train E01-03 -> test E04, new room)", "row_hash": "bf370487bde88e198c13877956dab3c83766a6a24afef0b78b6ac7aa130bb207", "score_pct": 17.51, "scored_at": "2026-05-30", "seq": 4, "sota_ref": "(hard frontier; control 13.52)", "submitter": "ruvnet", "tier": "Bronze"}
|
||||
@@ -1 +0,0 @@
|
||||
gradio==5.9.1
|
||||
@@ -1,130 +0,0 @@
|
||||
#!/usr/bin/env python3
|
||||
"""
|
||||
CIR Verification Helper (ADR-134)
|
||||
|
||||
Optional Python comparator — invokes the Rust cir_proof_runner binary and
|
||||
checks its output against expected_cir_features.sha256.
|
||||
|
||||
Usage:
|
||||
python cir_verify_helper.py # verify against stored hash
|
||||
python cir_verify_helper.py --generate # regenerate hash via Rust binary
|
||||
|
||||
This script is a thin wrapper; all cryptographic work is done in the Rust
|
||||
binary. It exists to integrate the CIR proof step into the Python verify.py
|
||||
flow if needed.
|
||||
"""
|
||||
|
||||
import argparse
|
||||
import os
|
||||
import subprocess
|
||||
import sys
|
||||
|
||||
SCRIPT_DIR = os.path.dirname(os.path.abspath(__file__))
|
||||
REPO_ROOT = os.path.abspath(os.path.join(SCRIPT_DIR, "..", "..", "..", ".."))
|
||||
|
||||
|
||||
def find_binary() -> str:
|
||||
"""Locate the cir_proof_runner binary."""
|
||||
candidates = [
|
||||
os.path.join(REPO_ROOT, "v2", "target", "release", "cir_proof_runner"),
|
||||
os.path.join(REPO_ROOT, "v2", "target", "release", "cir_proof_runner.exe"),
|
||||
os.path.join(REPO_ROOT, "v2", "target", "debug", "cir_proof_runner"),
|
||||
os.path.join(REPO_ROOT, "v2", "target", "debug", "cir_proof_runner.exe"),
|
||||
]
|
||||
for path in candidates:
|
||||
if os.path.isfile(path):
|
||||
return path
|
||||
return ""
|
||||
|
||||
|
||||
def build_binary() -> bool:
|
||||
"""Build the release binary via cargo."""
|
||||
print("Building cir_proof_runner (release)...")
|
||||
result = subprocess.run(
|
||||
[
|
||||
"cargo", "build",
|
||||
"-p", "wifi-densepose-signal",
|
||||
"--bin", "cir_proof_runner",
|
||||
"--release",
|
||||
"--no-default-features",
|
||||
],
|
||||
cwd=os.path.join(REPO_ROOT, "v2"),
|
||||
capture_output=True,
|
||||
text=True,
|
||||
)
|
||||
if result.returncode != 0:
|
||||
print("Build failed:", result.stderr[-2000:])
|
||||
return False
|
||||
return True
|
||||
|
||||
|
||||
def run_generate(binary: str) -> str:
|
||||
"""Run the binary with --generate-hash; return the hex hash."""
|
||||
result = subprocess.run(
|
||||
[binary, "--generate-hash"],
|
||||
cwd=REPO_ROOT,
|
||||
capture_output=True,
|
||||
text=True,
|
||||
)
|
||||
if result.returncode != 0:
|
||||
print("Error running binary:", result.stderr)
|
||||
return ""
|
||||
return result.stdout.strip()
|
||||
|
||||
|
||||
def run_verify(binary: str) -> bool:
|
||||
"""Run the binary in verify mode; return True on PASS."""
|
||||
result = subprocess.run(
|
||||
[binary],
|
||||
cwd=REPO_ROOT,
|
||||
capture_output=True,
|
||||
text=True,
|
||||
)
|
||||
print(result.stdout.strip())
|
||||
if result.stderr.strip():
|
||||
print(result.stderr.strip(), file=sys.stderr)
|
||||
return result.returncode == 0
|
||||
|
||||
|
||||
def main() -> None:
|
||||
parser = argparse.ArgumentParser(description="CIR verification helper (ADR-134)")
|
||||
parser.add_argument(
|
||||
"--generate",
|
||||
action="store_true",
|
||||
help="Regenerate expected_cir_features.sha256 via Rust binary",
|
||||
)
|
||||
parser.add_argument(
|
||||
"--build",
|
||||
action="store_true",
|
||||
default=False,
|
||||
help="Build the binary before running (default: use cached binary)",
|
||||
)
|
||||
args = parser.parse_args()
|
||||
|
||||
binary = find_binary()
|
||||
|
||||
if args.build or not binary:
|
||||
if not build_binary():
|
||||
sys.exit(1)
|
||||
binary = find_binary()
|
||||
|
||||
if not binary:
|
||||
print("ERROR: cir_proof_runner binary not found. Run with --build.")
|
||||
sys.exit(1)
|
||||
|
||||
if args.generate:
|
||||
hash_val = run_generate(binary)
|
||||
if not hash_val:
|
||||
sys.exit(1)
|
||||
hash_file = os.path.join(SCRIPT_DIR, "expected_cir_features.sha256")
|
||||
with open(hash_file, "w") as f:
|
||||
f.write(hash_val + "\n")
|
||||
print(f"Wrote CIR hash to {hash_file}")
|
||||
print(f"Hash: {hash_val}")
|
||||
else:
|
||||
ok = run_verify(binary)
|
||||
sys.exit(0 if ok else 1)
|
||||
|
||||
|
||||
if __name__ == "__main__":
|
||||
main()
|
||||
@@ -1 +0,0 @@
|
||||
d6bce07ecb1648e6936561df44bf4a3bfc17bb0ba5f692646b2301d105b52f67
|
||||
@@ -1 +0,0 @@
|
||||
304d54690af468dc6cbf0f2a1332f109cf187d5e2eab454efd8554cebc45bdeb
|
||||
@@ -1 +1 @@
|
||||
f8e76f21a0f9852b70b6d9dd5318239f6b20cbcb4cdd995863263cecdc446f7a
|
||||
667eb054c44ac510342665bf9c93d608868a8ead948ae8774b2796ebce6f8fe7
|
||||
Binary file not shown.
+16
-148
@@ -185,14 +185,7 @@ def frame_to_csi_data(frame, signal_meta):
|
||||
# observed pipeline-amplified ULP drift and is still far below any meaningful
|
||||
# signal change (CSI phase precision is ~1e-3 rad; PSD bins differ by orders
|
||||
# of magnitude). Round to this precision, then hash.
|
||||
#
|
||||
# NOTE: 6 decimals collapses the divergence *across Linux microarchitectures*
|
||||
# but NOT Windows-vs-Linux, where the pocketfft/BLAS difference exceeds 1e-6 on
|
||||
# a few elements that then straddle the 6th-decimal rounding boundary. The
|
||||
# precision is overridable via PROOF_HASH_DECIMALS so it can be coarsened to a
|
||||
# value that is boundary-stable across *all* platforms (Windows + Linux + macOS)
|
||||
# while staying far below any signal-meaningful change.
|
||||
HASH_QUANTIZATION_DECIMALS = int(os.environ.get("PROOF_HASH_DECIMALS", "6"))
|
||||
HASH_QUANTIZATION_DECIMALS = 6
|
||||
|
||||
|
||||
def features_to_bytes(features):
|
||||
@@ -212,20 +205,13 @@ def features_to_bytes(features):
|
||||
"""
|
||||
parts = []
|
||||
|
||||
# Serialize each feature array in declaration order.
|
||||
# doppler_shift is INTENTIONALLY excluded: it is peak-normalized
|
||||
# (`spectrum / max(spectrum)` in csi_processor._extract_doppler_features),
|
||||
# and when the raw spectrum has near-tied peaks the argmax flips under
|
||||
# cross-microarchitecture FP reordering, renormalizing the whole array
|
||||
# (O(1) divergence — not absorbable by any tolerance). The remaining five
|
||||
# features, including the FFT-based PSD, reproduce deterministically and
|
||||
# provide the proof. (The underlying doppler instability is a production
|
||||
# reproducibility bug tracked separately.)
|
||||
# Serialize each feature array in declaration order
|
||||
for array in [
|
||||
features.amplitude_mean,
|
||||
features.amplitude_variance,
|
||||
features.phase_difference,
|
||||
features.correlation_matrix,
|
||||
features.doppler_shift,
|
||||
features.power_spectral_density,
|
||||
]:
|
||||
flat = np.asarray(array, dtype=np.float64).ravel()
|
||||
@@ -239,45 +225,6 @@ def features_to_bytes(features):
|
||||
return b"".join(parts)
|
||||
|
||||
|
||||
# ── Cross-platform tolerance gate (issue #560 follow-up) ─────────────────────
|
||||
# The SHA-256 of fixed-decimal-rounded features is bit-exact only WITHIN one
|
||||
# CPU microarchitecture. The pocketfft / BLAS kernels in the manylinux
|
||||
# numpy/scipy wheels reorder floating-point reductions differently across
|
||||
# microarchs (e.g. a GitHub Azure runner vs a developer box vs another Linux
|
||||
# host), and the resulting ~1e-6 *relative* drift lands on large-magnitude PSD
|
||||
# bins as an absolute difference too large for ANY fixed-decimal grid to absorb
|
||||
# (empirically the hash diverges across microarchs even at 2 decimals). So:
|
||||
# • the hash is the strong, bit-exact, SAME-platform proof, and
|
||||
# • a relative tolerance against a committed reference vector is the
|
||||
# platform-INDEPENDENT proof.
|
||||
# A run PASSES if either matches. Tolerances sit ~100x over the observed
|
||||
# microarch drift and ~10x under any signal-meaningful change (CSI phase
|
||||
# precision ~1e-3 rad), so real pipeline regressions still fail.
|
||||
TOLERANCE_RTOL = 1e-4
|
||||
TOLERANCE_ATOL = 1e-6
|
||||
REFERENCE_VECTOR_FILENAME = "expected_features_reference.npz"
|
||||
|
||||
|
||||
def features_to_vector(features):
|
||||
"""Concatenate a frame's feature arrays as raw float64 (no rounding).
|
||||
|
||||
Mirrors ``features_to_bytes`` ordering but keeps full precision, for the
|
||||
tolerance-based cross-platform comparison.
|
||||
"""
|
||||
# doppler_shift excluded — see features_to_bytes for the rationale
|
||||
# (peak-normalization argmax instability across CPU microarchitectures).
|
||||
arrays = [
|
||||
features.amplitude_mean,
|
||||
features.amplitude_variance,
|
||||
features.phase_difference,
|
||||
features.correlation_matrix,
|
||||
features.power_spectral_density,
|
||||
]
|
||||
return np.concatenate(
|
||||
[np.asarray(a, dtype=np.float64).ravel() for a in arrays]
|
||||
)
|
||||
|
||||
|
||||
def compute_pipeline_hash(data_path, verbose=False):
|
||||
"""Run the full pipeline and compute the SHA-256 hash of all features.
|
||||
|
||||
@@ -320,7 +267,6 @@ def compute_pipeline_hash(data_path, verbose=False):
|
||||
features_count = 0
|
||||
total_feature_bytes = 0
|
||||
last_features = None
|
||||
feature_vectors = []
|
||||
doppler_nonzero_count = 0
|
||||
doppler_shape = None
|
||||
psd_shape = None
|
||||
@@ -337,7 +283,6 @@ def compute_pipeline_hash(data_path, verbose=False):
|
||||
if features is not None:
|
||||
feature_bytes = features_to_bytes(features)
|
||||
hasher.update(feature_bytes)
|
||||
feature_vectors.append(features_to_vector(features))
|
||||
features_count += 1
|
||||
total_feature_bytes += len(feature_bytes)
|
||||
last_features = features
|
||||
@@ -406,11 +351,7 @@ def compute_pipeline_hash(data_path, verbose=False):
|
||||
"psd_shape": psd_shape,
|
||||
}
|
||||
|
||||
reference_vector = (
|
||||
np.concatenate(feature_vectors) if feature_vectors else np.array([], dtype=np.float64)
|
||||
)
|
||||
|
||||
return hasher.hexdigest(), reference_vector, stats
|
||||
return hasher.hexdigest(), stats
|
||||
|
||||
|
||||
def audit_codebase(base_dir=None):
|
||||
@@ -526,7 +467,7 @@ def main():
|
||||
print(" This runs the SAME CSIProcessor.preprocess_csi_data() and")
|
||||
print(" CSIProcessor.extract_features() used in production.")
|
||||
print()
|
||||
computed_hash, computed_vector, stats = compute_pipeline_hash(data_path, verbose=args.verbose)
|
||||
computed_hash, stats = compute_pipeline_hash(data_path, verbose=args.verbose)
|
||||
|
||||
# ---------------------------------------------------------------
|
||||
# Step 3: Hash comparison
|
||||
@@ -538,11 +479,8 @@ def main():
|
||||
with open(hash_path, "w") as f:
|
||||
f.write(computed_hash + "\n")
|
||||
print(f" Wrote expected hash to {hash_path}")
|
||||
ref_path = os.path.join(SCRIPT_DIR, REFERENCE_VECTOR_FILENAME)
|
||||
np.savez_compressed(ref_path, features=computed_vector)
|
||||
print(f" Wrote reference vector ({computed_vector.size} values) to {ref_path}")
|
||||
print()
|
||||
print(" HASH + REFERENCE GENERATED -- run without --generate-hash to verify.")
|
||||
print(" HASH GENERATED -- run without --generate-hash to verify.")
|
||||
print("=" * 72)
|
||||
return
|
||||
|
||||
@@ -561,70 +499,13 @@ def main():
|
||||
|
||||
print(f" Expected: {expected_hash}")
|
||||
|
||||
hash_match = computed_hash == expected_hash
|
||||
|
||||
# Cross-platform fallback: if the bit-exact hash differs (different CPU
|
||||
# microarchitecture reorders the pocketfft/BLAS reductions), accept the run
|
||||
# when the raw feature vector matches the committed reference within a
|
||||
# relative tolerance — platform-independent where the hash is not (#560).
|
||||
tolerance_match = False
|
||||
max_abs_dev = None
|
||||
max_rel_dev = None
|
||||
ref_path = os.path.join(SCRIPT_DIR, REFERENCE_VECTOR_FILENAME)
|
||||
if not hash_match and os.path.exists(ref_path):
|
||||
ref_vec = np.load(ref_path)["features"]
|
||||
if ref_vec.shape == computed_vector.shape:
|
||||
tolerance_match = bool(
|
||||
np.allclose(
|
||||
computed_vector, ref_vec, rtol=TOLERANCE_RTOL, atol=TOLERANCE_ATOL
|
||||
)
|
||||
)
|
||||
diff = np.abs(computed_vector - ref_vec)
|
||||
max_abs_dev = float(np.max(diff)) if diff.size else 0.0
|
||||
max_rel_dev = (
|
||||
float(np.max(diff / np.maximum(np.abs(ref_vec), 1e-12)))
|
||||
if diff.size
|
||||
else 0.0
|
||||
)
|
||||
|
||||
if hash_match:
|
||||
match_status = "MATCH (bit-exact)"
|
||||
elif tolerance_match:
|
||||
match_status = f"TOLERANCE MATCH (max rel dev {max_rel_dev:.2e})"
|
||||
if computed_hash == expected_hash:
|
||||
match_status = "MATCH"
|
||||
else:
|
||||
match_status = "MISMATCH"
|
||||
print(f" Status: {match_status}")
|
||||
print()
|
||||
|
||||
if not hash_match and max_abs_dev is not None:
|
||||
block_sizes = [56, 56, 55, 9, 128] # per-frame feature layout (doppler excluded)
|
||||
block_names = ["amp_mean", "amp_var", "phase_diff", "corr", "psd"]
|
||||
frame_len = sum(block_sizes)
|
||||
tol = TOLERANCE_ATOL + TOLERANCE_RTOL * np.abs(ref_vec)
|
||||
outside = diff > tol
|
||||
n_out = int(outside.sum())
|
||||
print(
|
||||
f" DIVERGENCE: {n_out}/{computed_vector.size} outside tol "
|
||||
f"({100.0 * n_out / computed_vector.size:.4f}%) "
|
||||
f"max|d|={max_abs_dev:.3e} maxrel={max_rel_dev:.3e}"
|
||||
)
|
||||
if n_out:
|
||||
wf = np.where(outside)[0] % frame_len
|
||||
bounds = np.cumsum([0] + block_sizes)
|
||||
parts = []
|
||||
for bi, name in enumerate(block_names):
|
||||
c = int(((wf >= bounds[bi]) & (wf < bounds[bi + 1])).sum())
|
||||
if c:
|
||||
parts.append(f"{name}={c}")
|
||||
print(f" by feature: {', '.join(parts)}")
|
||||
for w in np.argsort(diff)[::-1][:4]:
|
||||
b = int(np.searchsorted(bounds, int(w) % frame_len, side="right")) - 1
|
||||
print(
|
||||
f" worst idx {int(w)} ({block_names[b]}): "
|
||||
f"ref={ref_vec[int(w)]:.6g} got={computed_vector[int(w)]:.6g}"
|
||||
)
|
||||
print()
|
||||
|
||||
# ---------------------------------------------------------------
|
||||
# Step 4: Audit (if requested or always in full mode)
|
||||
# ---------------------------------------------------------------
|
||||
@@ -647,22 +528,14 @@ def main():
|
||||
# Final verdict
|
||||
# ---------------------------------------------------------------
|
||||
print("=" * 72)
|
||||
if hash_match or tolerance_match:
|
||||
if computed_hash == expected_hash:
|
||||
print(" VERDICT: PASS")
|
||||
print()
|
||||
if hash_match:
|
||||
print(" The pipeline produced a SHA-256 hash that matches the published")
|
||||
print(" expected hash (bit-exact). This proves:")
|
||||
else:
|
||||
print(" The bit-exact hash differs (CPU-microarchitecture FP reordering),")
|
||||
print(" but the raw feature vector matches the published reference within")
|
||||
print(
|
||||
f" rtol={TOLERANCE_RTOL:g} / atol={TOLERANCE_ATOL:g} "
|
||||
f"(max rel dev {max_rel_dev:.2e}). This proves:"
|
||||
)
|
||||
print(" The pipeline produced a SHA-256 hash that matches the published")
|
||||
print(" expected hash. This proves:")
|
||||
print(" 1. The SAME signal processing code ran on the reference signal")
|
||||
print(" 2. The output is DETERMINISTIC (same input -> same output)")
|
||||
print(" 3. No randomness was introduced")
|
||||
print(" 3. No randomness was introduced (hash would differ)")
|
||||
print(" 4. The code path includes: noise removal, Hamming windowing,")
|
||||
print(" amplitude normalization, FFT-based Doppler extraction,")
|
||||
print(" and power spectral density computation")
|
||||
@@ -673,19 +546,14 @@ def main():
|
||||
else:
|
||||
print(" VERDICT: FAIL")
|
||||
print()
|
||||
print(" The pipeline output does NOT match the expected hash OR the")
|
||||
print(" reference feature vector within tolerance.")
|
||||
if max_rel_dev is not None:
|
||||
print(
|
||||
f" max abs dev: {max_abs_dev:.3e} max rel dev: {max_rel_dev:.3e}"
|
||||
f" (rtol={TOLERANCE_RTOL:g}, atol={TOLERANCE_ATOL:g})"
|
||||
)
|
||||
print(" The pipeline output does NOT match the expected hash.")
|
||||
print()
|
||||
print(" Possible causes:")
|
||||
print(" - Numpy/scipy version mismatch (check requirements)")
|
||||
print(" - Code change in CSI processor that alters numerical output")
|
||||
print(" - A real (non-microarch) numerical regression")
|
||||
print(" - Platform floating-point differences (unlikely for IEEE 754)")
|
||||
print()
|
||||
print(" To update after an intentional change:")
|
||||
print(" To update the expected hash after intentional changes:")
|
||||
print(" python verify.py --generate-hash")
|
||||
print("=" * 72)
|
||||
sys.exit(1)
|
||||
|
||||
@@ -6,14 +6,8 @@
|
||||
#
|
||||
# To update: change versions, run `python v1/data/proof/verify.py --generate-hash`,
|
||||
# then commit the new expected_features.sha256.
|
||||
#
|
||||
# numpy/scipy track the versions the *published* expected hash
|
||||
# (expected_features.sha256 = ca58956c…) was generated with — modern numpy 2.x,
|
||||
# i.e. what a fresh `pip install numpy` and the proof-of-capabilities.md skeptic
|
||||
# path produce today. The old 1.26.4 pin no longer matched that hash and made
|
||||
# the determinism gate fail against its own published proof.
|
||||
|
||||
numpy==2.4.2
|
||||
scipy==1.17.1
|
||||
numpy==1.26.4
|
||||
scipy==1.14.1
|
||||
pydantic==2.10.4
|
||||
pydantic-settings==2.7.1
|
||||
|
||||
@@ -26,12 +26,7 @@ class Settings(BaseSettings):
|
||||
workers: int = Field(default=1, description="Number of worker processes")
|
||||
|
||||
# Security settings
|
||||
secret_key: str = Field(
|
||||
default="dev-not-secret-CHANGE-IN-PROD",
|
||||
description="Secret key for JWT tokens (production deployments "
|
||||
"MUST override via SECRET_KEY env or .env; the dev "
|
||||
"default is rejected by validate_production_config)",
|
||||
)
|
||||
secret_key: str = Field(..., description="Secret key for JWT tokens")
|
||||
jwt_algorithm: str = Field(default="HS256", description="JWT algorithm")
|
||||
jwt_expire_hours: int = Field(default=24, description="JWT token expiration in hours")
|
||||
allowed_hosts: List[str] = Field(default=["*"], description="Allowed hosts")
|
||||
@@ -163,14 +158,7 @@ class Settings(BaseSettings):
|
||||
model_config = SettingsConfigDict(
|
||||
env_file=".env",
|
||||
env_file_encoding="utf-8",
|
||||
case_sensitive=False,
|
||||
# Tolerate `.env` keys that this Settings model doesn't declare
|
||||
# (e.g., NPM_TOKEN, DOCKER_HUB_TOKEN, PYPI_TOKEN used by other
|
||||
# tooling). Without `extra="ignore"` pydantic-settings 2.x
|
||||
# raises `ValidationError: Extra inputs are not permitted` and
|
||||
# leaks the offending values into the error message — a real
|
||||
# security concern for secret tokens. See verify.py / `./verify`.
|
||||
extra="ignore",
|
||||
case_sensitive=False
|
||||
)
|
||||
|
||||
@field_validator("environment")
|
||||
|
||||
@@ -143,35 +143,13 @@ class ESP32BinaryParser:
|
||||
12 4 Sequence number (LE u32)
|
||||
16 1 RSSI (i8)
|
||||
17 1 Noise floor (i8)
|
||||
18 1 PPDU type (ADR-110): 0=HT/legacy, 1=HE-SU, 2=HE-MU,
|
||||
3=HE-TB, 0xFF=unknown. Pre-ADR-110 firmware sends 0.
|
||||
19 1 Flags (ADR-110): bit 0 = bw40, bit 2 = STBC,
|
||||
bit 3 = LDPC, bit 4 = cross-node sync valid
|
||||
(set by either c6_timesync OR c6_sync_espnow
|
||||
since v0.7.0 — ADR-110 §A0.13).
|
||||
18 2 Reserved
|
||||
20 N*2 I/Q pairs (n_antennas * n_subcarriers * 2 bytes, signed i8)
|
||||
|
||||
Sibling packet (ADR-110 §A0.12, firmware v0.6.9+): the node also
|
||||
emits a 32-byte UDP sync packet (magic 0xC511A110) every
|
||||
CONFIG_C6_SYNC_EVERY_N_FRAMES frames on the same UDP socket.
|
||||
See parse_sync_packet() / SyncPacket below.
|
||||
"""
|
||||
|
||||
MAGIC = 0xC5110001
|
||||
HEADER_SIZE = 20
|
||||
# ADR-110: previously '<IBBHIIBB2x' (last 2 bytes skipped as reserved).
|
||||
# Now read those 2 bytes as PPDU type + flags. Pre-ADR-110 firmware
|
||||
# sends zeros, which decode as 'HT/legacy' + 'no flags' — fully
|
||||
# backwards compatible.
|
||||
HEADER_FMT = '<IBBHIIBBBB' # +2 bytes: ppdu_type, flags
|
||||
|
||||
# ADR-110 PPDU type byte values
|
||||
PPDU_HT_LEGACY = 0
|
||||
PPDU_HE_SU = 1
|
||||
PPDU_HE_MU = 2
|
||||
PPDU_HE_TB = 3
|
||||
PPDU_UNKNOWN = 0xFF
|
||||
_PPDU_NAMES = {0: 'ht_legacy', 1: 'he_su', 2: 'he_mu', 3: 'he_tb', 0xFF: 'unknown'}
|
||||
HEADER_FMT = '<IBBHIIBB2x' # magic, node_id, n_ant, n_sc, freq, seq, rssi, noise
|
||||
|
||||
def parse(self, raw_data: bytes) -> CSIData:
|
||||
"""Parse an ADR-018 binary frame into CSIData.
|
||||
@@ -190,8 +168,8 @@ class ESP32BinaryParser:
|
||||
f"Frame too short: need {self.HEADER_SIZE} bytes, got {len(raw_data)}"
|
||||
)
|
||||
|
||||
magic, node_id, n_antennas, n_subcarriers, freq_mhz, sequence, rssi_u8, noise_u8, \
|
||||
ppdu_byte, flags_byte = struct.unpack_from(self.HEADER_FMT, raw_data, 0)
|
||||
magic, node_id, n_antennas, n_subcarriers, freq_mhz, sequence, rssi_u8, noise_u8 = \
|
||||
struct.unpack_from(self.HEADER_FMT, raw_data, 0)
|
||||
|
||||
if magic != self.MAGIC:
|
||||
raise CSIParseError(
|
||||
@@ -248,128 +226,10 @@ class ESP32BinaryParser:
|
||||
'rssi_dbm': rssi,
|
||||
'noise_floor_dbm': noise_floor,
|
||||
'channel_freq_mhz': freq_mhz,
|
||||
# ADR-110 extension — zeros from pre-ADR-110 firmware land here as
|
||||
# 'ht_legacy' + all-flags-false. New consumers can branch on
|
||||
# ppdu_type / he_capable for HE-LTF-aware DSP.
|
||||
'ppdu_type': self._PPDU_NAMES.get(ppdu_byte, 'unknown'),
|
||||
'ppdu_type_raw': ppdu_byte,
|
||||
'he_capable': ppdu_byte in (1, 2, 3),
|
||||
'bw40': bool(flags_byte & 0x01),
|
||||
'stbc': bool(flags_byte & 0x04),
|
||||
'ldpc': bool(flags_byte & 0x08),
|
||||
'ieee802154_sync_valid': bool(flags_byte & 0x10),
|
||||
'adr018_flags_raw': flags_byte,
|
||||
}
|
||||
)
|
||||
|
||||
|
||||
@dataclass
|
||||
class SyncPacket:
|
||||
"""ADR-110 §A0.12 sync packet (firmware v0.6.9+, magic 0xC511A110).
|
||||
|
||||
Emitted on the same UDP socket as CSI frames every
|
||||
CONFIG_C6_SYNC_EVERY_N_FRAMES frames. Carries the mesh-aligned
|
||||
epoch for the node alongside the high-water CSI sequence number,
|
||||
so the host aggregator can pair (node_id, sequence) across the two
|
||||
packet streams and recover a mesh-aligned timestamp for every CSI
|
||||
frame. See WITNESS-LOG-110 §A0.12 for the live verification.
|
||||
"""
|
||||
node_id: int
|
||||
proto_ver: int
|
||||
is_leader: bool
|
||||
is_valid: bool
|
||||
smoothed_used: bool
|
||||
local_us: int # u64 — node's local esp_timer_get_time()
|
||||
epoch_us: int # u64 — local + EMA-smoothed offset (mesh time)
|
||||
sequence: int # u32 — high-water CSI sequence at emit time
|
||||
flags_raw: int
|
||||
|
||||
def local_minus_epoch_us(self) -> int:
|
||||
"""Signed local-vs-mesh clock offset in µs.
|
||||
|
||||
Negative when this node's clock is behind the leader's (typical
|
||||
for followers). Equal to ≈0 on the leader (modulo call-stack µs).
|
||||
Matches Rust's `SyncPacket::local_minus_epoch_us` byte-for-byte.
|
||||
"""
|
||||
return self.local_us - self.epoch_us
|
||||
|
||||
def apply_to_local(self, local_at_frame_us: int) -> int:
|
||||
"""Recover a mesh-aligned timestamp for any node-local µs snapshot.
|
||||
|
||||
Math (see WITNESS-LOG-110 §A0.10 / §A0.12):
|
||||
offset = epoch_us - local_us (signed; this packet)
|
||||
mesh = local_at_frame_us + offset
|
||||
|
||||
Identical contract to Rust's `SyncPacket::apply_to_local`.
|
||||
Identity at `local_at_frame_us == self.local_us` returns `epoch_us`.
|
||||
"""
|
||||
offset = self.epoch_us - self.local_us
|
||||
return local_at_frame_us + offset
|
||||
|
||||
def mesh_aligned_us_for_sequence(self, frame_seq: int, fps_hz: float) -> int:
|
||||
"""ADR-110 §A0.12 — recover the mesh-aligned timestamp for an
|
||||
in-flight CSI frame by its sequence number.
|
||||
|
||||
Pairs the frame's sequence number against this sync packet's
|
||||
sequence high-water + an assumed/measured CSI rate. Matches the
|
||||
Rust implementation byte-for-byte at the integer level (Python
|
||||
rounds via `int()` truncation; for the canonical bench values
|
||||
this is exact).
|
||||
"""
|
||||
if fps_hz <= 0:
|
||||
raise ValueError(f"fps_hz must be positive, got {fps_hz}")
|
||||
# Wrap to handle u32 sequence overflow the same way Rust does.
|
||||
dframes = (frame_seq - self.sequence) & 0xFFFFFFFF
|
||||
if dframes >= 0x80000000:
|
||||
dframes -= 0x1_0000_0000
|
||||
dus = int(dframes * 1_000_000 / fps_hz)
|
||||
local_at = self.local_us + dus
|
||||
return self.apply_to_local(local_at)
|
||||
|
||||
|
||||
class SyncPacketParser:
|
||||
"""Parser for ADR-110 §A0.12 32-byte sync packets.
|
||||
|
||||
Distinguished from CSI frames by the leading magic. Callers should
|
||||
dispatch incoming UDP datagrams based on the first 4 bytes:
|
||||
|
||||
magic = struct.unpack_from('<I', data, 0)[0]
|
||||
if magic == ESP32BinaryParser.MAGIC: # 0xC5110001 — CSI frame
|
||||
...
|
||||
elif magic == SyncPacketParser.MAGIC: # 0xC511A110 — sync packet
|
||||
...
|
||||
"""
|
||||
|
||||
MAGIC = 0xC511A110
|
||||
SIZE = 32
|
||||
# <IBBBB QQ IB3x>
|
||||
# I=magic, B=node_id, B=proto_ver, B=flags, B=reserved,
|
||||
# Q=local_us, Q=epoch_us, I=sequence, B+3x=reserved
|
||||
HEADER_FMT = '<IBBBBQQI4x'
|
||||
|
||||
@classmethod
|
||||
def parse(cls, raw_data: bytes) -> SyncPacket:
|
||||
if len(raw_data) < cls.SIZE:
|
||||
raise CSIParseError(
|
||||
f"Sync packet too short: {len(raw_data)} bytes, need {cls.SIZE}"
|
||||
)
|
||||
magic, node_id, proto_ver, flags_byte, _, local_us, epoch_us, seq = \
|
||||
struct.unpack_from(cls.HEADER_FMT, raw_data, 0)
|
||||
if magic != cls.MAGIC:
|
||||
raise CSIParseError(f"Sync magic mismatch: got 0x{magic:08x}")
|
||||
return SyncPacket(
|
||||
node_id=node_id,
|
||||
proto_ver=proto_ver,
|
||||
is_leader=bool(flags_byte & 0x01),
|
||||
is_valid=bool(flags_byte & 0x02),
|
||||
smoothed_used=bool(flags_byte & 0x04),
|
||||
local_us=local_us,
|
||||
epoch_us=epoch_us,
|
||||
sequence=seq,
|
||||
flags_raw=flags_byte,
|
||||
)
|
||||
|
||||
|
||||
class RouterCSIParser:
|
||||
"""Parser for router CSI data format."""
|
||||
|
||||
|
||||
@@ -107,25 +107,16 @@ class PoseService:
|
||||
async def _initialize_models(self):
|
||||
"""Initialize neural network models."""
|
||||
try:
|
||||
# Initialize DensePose model. DensePoseHead requires a config
|
||||
# dict — input_channels matches the modality translator's output
|
||||
# (256), with the standard DensePose 24 body parts and 2 (U,V)
|
||||
# coordinates. (Previously called with no args → TypeError at
|
||||
# startup, which broke the API service.)
|
||||
densepose_config = {
|
||||
'input_channels': 256,
|
||||
'num_body_parts': 24,
|
||||
'num_uv_coordinates': 2,
|
||||
}
|
||||
# Initialize DensePose model
|
||||
if self.settings.pose_model_path:
|
||||
self.densepose_model = DensePoseHead(densepose_config)
|
||||
self.densepose_model = DensePoseHead()
|
||||
# Load model weights if path is provided
|
||||
# model_state = torch.load(self.settings.pose_model_path)
|
||||
# self.densepose_model.load_state_dict(model_state)
|
||||
self.logger.info("DensePose model loaded")
|
||||
else:
|
||||
self.logger.warning("No pose model path provided, using default model")
|
||||
self.densepose_model = DensePoseHead(densepose_config)
|
||||
self.densepose_model = DensePoseHead()
|
||||
|
||||
# Initialize modality translation
|
||||
config = {
|
||||
|
||||
@@ -19,16 +19,11 @@ from hardware.csi_extractor import (
|
||||
CSIExtractor,
|
||||
CSIParseError,
|
||||
CSIExtractionError,
|
||||
SyncPacket,
|
||||
SyncPacketParser,
|
||||
)
|
||||
|
||||
# ADR-018 constants
|
||||
MAGIC = 0xC5110001
|
||||
# ADR-110: bytes 18-19 are now PPDU type + flags (used to be `2x` reserved).
|
||||
# Pre-ADR-110 firmware sends zeros for both, which round-trip as
|
||||
# ('ht_legacy', flags=all-false) — fully backwards compatible.
|
||||
HEADER_FMT = '<IBBHIIBBBB'
|
||||
HEADER_FMT = '<IBBHIIBB2x'
|
||||
HEADER_SIZE = 20
|
||||
|
||||
|
||||
@@ -41,8 +36,6 @@ def build_binary_frame(
|
||||
rssi: int = -50,
|
||||
noise_floor: int = -90,
|
||||
iq_pairs: list = None,
|
||||
ppdu_byte: int = 0, # ADR-110: default 0 = HT/legacy (pre-ADR-110 behavior)
|
||||
flags_byte: int = 0, # ADR-110: default 0 = no flags set
|
||||
) -> bytes:
|
||||
"""Build an ADR-018 binary frame for testing."""
|
||||
if iq_pairs is None:
|
||||
@@ -61,8 +54,6 @@ def build_binary_frame(
|
||||
sequence,
|
||||
rssi_u8,
|
||||
noise_u8,
|
||||
ppdu_byte,
|
||||
flags_byte,
|
||||
)
|
||||
|
||||
iq_data = b''
|
||||
@@ -72,52 +63,6 @@ def build_binary_frame(
|
||||
return header + iq_data
|
||||
|
||||
|
||||
class TestAdr110ByteEncoding:
|
||||
"""ADR-110: byte 18 = PPDU type, byte 19 = flags."""
|
||||
|
||||
def setup_method(self):
|
||||
self.parser = ESP32BinaryParser()
|
||||
|
||||
def test_pre_adr110_zeros_decode_as_ht_legacy(self):
|
||||
"""Pre-ADR-110 firmware sends zeros → must surface as HT/legacy + no flags."""
|
||||
frame = build_binary_frame() # ppdu_byte=0, flags_byte=0 default
|
||||
csi = self.parser.parse(frame)
|
||||
assert csi.metadata['ppdu_type'] == 'ht_legacy'
|
||||
assert csi.metadata['ppdu_type_raw'] == 0
|
||||
assert csi.metadata['he_capable'] is False
|
||||
assert csi.metadata['bw40'] is False
|
||||
assert csi.metadata['stbc'] is False
|
||||
assert csi.metadata['ldpc'] is False
|
||||
assert csi.metadata['ieee802154_sync_valid'] is False
|
||||
|
||||
def test_he_su_decodes(self):
|
||||
frame = build_binary_frame(ppdu_byte=1)
|
||||
csi = self.parser.parse(frame)
|
||||
assert csi.metadata['ppdu_type'] == 'he_su'
|
||||
assert csi.metadata['he_capable'] is True
|
||||
|
||||
def test_he_mu_and_he_tb_decode(self):
|
||||
for byte, expected in [(2, 'he_mu'), (3, 'he_tb')]:
|
||||
csi = self.parser.parse(build_binary_frame(ppdu_byte=byte))
|
||||
assert csi.metadata['ppdu_type'] == expected
|
||||
assert csi.metadata['he_capable'] is True
|
||||
|
||||
def test_unknown_ppdu_byte(self):
|
||||
csi = self.parser.parse(build_binary_frame(ppdu_byte=0xFF))
|
||||
assert csi.metadata['ppdu_type'] == 'unknown'
|
||||
assert csi.metadata['ppdu_type_raw'] == 0xFF
|
||||
assert csi.metadata['he_capable'] is False
|
||||
|
||||
def test_all_flags_set_round_trip(self):
|
||||
# bw40 (0x01) + STBC (0x04) + LDPC (0x08) + 15.4-sync (0x10) = 0x1D
|
||||
csi = self.parser.parse(build_binary_frame(ppdu_byte=1, flags_byte=0x1D))
|
||||
assert csi.metadata['bw40'] is True
|
||||
assert csi.metadata['stbc'] is True
|
||||
assert csi.metadata['ldpc'] is True
|
||||
assert csi.metadata['ieee802154_sync_valid'] is True
|
||||
assert csi.metadata['adr018_flags_raw'] == 0x1D
|
||||
|
||||
|
||||
class TestESP32BinaryParser:
|
||||
"""Tests for ESP32BinaryParser."""
|
||||
|
||||
@@ -259,172 +204,3 @@ class TestESP32BinaryParser:
|
||||
await extractor.disconnect()
|
||||
|
||||
asyncio.run(run_test())
|
||||
|
||||
|
||||
# ============================================================================
|
||||
# ADR-110 §A0.12 — SyncPacket / SyncPacketParser tests (firmware v0.6.9+)
|
||||
# ============================================================================
|
||||
|
||||
SYNC_MAGIC = 0xC511A110
|
||||
SYNC_SIZE = 32
|
||||
SYNC_FMT = '<IBBBBQQI4x'
|
||||
|
||||
|
||||
def build_sync_packet(
|
||||
node_id: int = 9,
|
||||
proto_ver: int = 1,
|
||||
is_leader: bool = False,
|
||||
is_valid: bool = True,
|
||||
smoothed_used: bool = True,
|
||||
local_us: int = 28798450,
|
||||
epoch_us: int = 27634885,
|
||||
sequence: int = 20,
|
||||
) -> bytes:
|
||||
flags = 0
|
||||
if is_leader: flags |= 0x01
|
||||
if is_valid: flags |= 0x02
|
||||
if smoothed_used: flags |= 0x04
|
||||
return struct.pack(
|
||||
SYNC_FMT,
|
||||
SYNC_MAGIC,
|
||||
node_id, proto_ver, flags, 0,
|
||||
local_us, epoch_us, sequence,
|
||||
)
|
||||
|
||||
|
||||
class TestSyncPacketParser:
|
||||
"""ADR-110 §A0.12: 32-byte UDP sync packet (magic 0xC511A110)."""
|
||||
|
||||
def test_follower_typical_packet_roundtrips(self):
|
||||
"""Match the COM9-witnessed sync-pkt #1 byte-for-byte."""
|
||||
raw = build_sync_packet(
|
||||
node_id=9, is_leader=False, is_valid=True, smoothed_used=True,
|
||||
local_us=28798450, epoch_us=27634885, sequence=20,
|
||||
)
|
||||
assert len(raw) == SYNC_SIZE
|
||||
pkt = SyncPacketParser.parse(raw)
|
||||
assert isinstance(pkt, SyncPacket)
|
||||
assert pkt.node_id == 9
|
||||
assert pkt.proto_ver == 1
|
||||
assert pkt.is_leader is False
|
||||
assert pkt.is_valid is True
|
||||
assert pkt.smoothed_used is True
|
||||
assert pkt.local_us == 28798450
|
||||
assert pkt.epoch_us == 27634885
|
||||
assert pkt.sequence == 20
|
||||
# The 1.16-second boot delta from §A0.10 should be recoverable
|
||||
assert pkt.local_us - pkt.epoch_us == 1163565
|
||||
|
||||
def test_leader_packet_has_local_close_to_epoch(self):
|
||||
"""COM12 (leader) had flags=0x03 and epoch ≈ local."""
|
||||
raw = build_sync_packet(
|
||||
node_id=12, is_leader=True, is_valid=True, smoothed_used=False,
|
||||
local_us=28864932, epoch_us=28864939, sequence=20,
|
||||
)
|
||||
pkt = SyncPacketParser.parse(raw)
|
||||
assert pkt.node_id == 12
|
||||
assert pkt.is_leader is True
|
||||
assert pkt.is_valid is True
|
||||
assert pkt.smoothed_used is False
|
||||
assert pkt.flags_raw == 0x03
|
||||
assert pkt.local_us - pkt.epoch_us == -7 # leader has zero offset
|
||||
|
||||
def test_magic_mismatch_raises(self):
|
||||
"""A non-sync datagram must not silently decode."""
|
||||
raw = bytearray(build_sync_packet())
|
||||
raw[0] = 0x01 # corrupt magic low byte
|
||||
with pytest.raises(CSIParseError, match="magic mismatch"):
|
||||
SyncPacketParser.parse(bytes(raw))
|
||||
|
||||
def test_short_packet_raises(self):
|
||||
"""Below 32 bytes must error early, not silently truncate."""
|
||||
raw = build_sync_packet()[:16]
|
||||
with pytest.raises(CSIParseError, match="too short"):
|
||||
SyncPacketParser.parse(raw)
|
||||
|
||||
def test_all_flag_combinations(self):
|
||||
"""Each flag bit decodes independently."""
|
||||
for is_leader in (False, True):
|
||||
for is_valid in (False, True):
|
||||
for smoothed_used in (False, True):
|
||||
raw = build_sync_packet(
|
||||
is_leader=is_leader,
|
||||
is_valid=is_valid,
|
||||
smoothed_used=smoothed_used,
|
||||
)
|
||||
pkt = SyncPacketParser.parse(raw)
|
||||
assert pkt.is_leader == is_leader
|
||||
assert pkt.is_valid == is_valid
|
||||
assert pkt.smoothed_used == smoothed_used
|
||||
|
||||
def test_dispatch_distinguishes_csi_from_sync(self):
|
||||
"""A host can pick CSI vs sync by leading magic."""
|
||||
csi_magic = struct.unpack_from('<I', build_binary_frame(), 0)[0]
|
||||
sync_magic = struct.unpack_from('<I', build_sync_packet(), 0)[0]
|
||||
assert csi_magic == ESP32BinaryParser.MAGIC
|
||||
assert sync_magic == SyncPacketParser.MAGIC
|
||||
assert csi_magic != sync_magic
|
||||
|
||||
def test_apply_to_local_recovers_epoch_at_sync_point(self):
|
||||
"""ADR-110 iter 26 — Python parity with Rust's `apply_to_local`.
|
||||
At local_at_frame == sync.local_us, the recovered mesh time must
|
||||
equal sync.epoch_us exactly."""
|
||||
pkt = SyncPacketParser.parse(build_sync_packet(
|
||||
local_us=28_798_450, epoch_us=27_634_885, sequence=20,
|
||||
))
|
||||
assert pkt.apply_to_local(pkt.local_us) == pkt.epoch_us
|
||||
assert pkt.local_minus_epoch_us() == 1_163_565 # §A0.10's bench number
|
||||
|
||||
def test_apply_to_local_preserves_inter_frame_delta(self):
|
||||
"""A frame arriving 5 s after the sync packet on the follower's
|
||||
local clock must produce a mesh time exactly 5 s after sync.epoch_us."""
|
||||
pkt = SyncPacketParser.parse(build_sync_packet(
|
||||
local_us=28_798_450, epoch_us=27_634_885, sequence=20,
|
||||
))
|
||||
local_at_frame = pkt.local_us + 5_000_000
|
||||
assert pkt.apply_to_local(local_at_frame) == pkt.epoch_us + 5_000_000
|
||||
|
||||
def test_mesh_aligned_us_for_sequence_matches_rust(self):
|
||||
"""Cross-language parity with Rust's
|
||||
`end_to_end_sync_decode_then_frame_mesh_recovery` test —
|
||||
100 frames after sync.sequence at 20 fps = sync.epoch_us + 5 s."""
|
||||
pkt = SyncPacketParser.parse(build_sync_packet(
|
||||
local_us=28_798_450, epoch_us=27_634_885, sequence=20,
|
||||
))
|
||||
mesh = pkt.mesh_aligned_us_for_sequence(120, 20.0)
|
||||
assert mesh == pkt.epoch_us + 5_000_000
|
||||
# Both paths (apply_to_local + interpolation) must agree
|
||||
local_at = pkt.local_us + 5_000_000
|
||||
assert pkt.apply_to_local(local_at) == mesh
|
||||
|
||||
def test_canonical_wire_bytes_match_rust_decoder(self):
|
||||
"""ADR-110 iter 21 — cross-language wire-format conformance gate.
|
||||
|
||||
These exact bytes also appear pinned in the Rust hardware crate's
|
||||
`canonical_wire_bytes_match_python_decoder` test (same field
|
||||
values, encoded by Rust's `SyncPacket::to_bytes`). If Python's
|
||||
hardcoded hex stops matching what Rust produces from the equivalent
|
||||
SyncPacket struct, ONE of the decoders has drifted from the wire.
|
||||
|
||||
Canonical packet: COM9 sync-pkt #1 from §A0.12 live capture.
|
||||
"""
|
||||
canonical = bytes.fromhex(
|
||||
"10a111c509010600" # magic LE + node=9 + ver=1 + flags=0x06 + reserved
|
||||
"f26db70100000000" # local_us = 28_798_450 (LE u64)
|
||||
"c5aca50100000000" # epoch_us = 27_634_885 (LE u64)
|
||||
"1400000000000000" # sequence = 20 (LE u32) + 4 reserved bytes
|
||||
)
|
||||
assert len(canonical) == SyncPacketParser.SIZE == 32
|
||||
|
||||
pkt = SyncPacketParser.parse(canonical)
|
||||
assert pkt.node_id == 9
|
||||
assert pkt.proto_ver == 1
|
||||
assert pkt.flags_raw == 0x06
|
||||
assert pkt.is_leader is False
|
||||
assert pkt.is_valid is True
|
||||
assert pkt.smoothed_used is True
|
||||
assert pkt.local_us == 28_798_450
|
||||
assert pkt.epoch_us == 27_634_885
|
||||
assert pkt.sequence == 20
|
||||
# Recovered offset matches §A0.10's measured 1.16-second boot delta.
|
||||
assert pkt.local_us - pkt.epoch_us == 1_163_565
|
||||
|
||||
Binary file not shown.
|
Before Width: | Height: | Size: 1.9 MiB |
Binary file not shown.
|
Before Width: | Height: | Size: 1.2 MiB |
@@ -1,3 +0,0 @@
|
||||
{"type": "metadata", "name": "ruview-clone-traffic-history", "version": "1.0.0", "schema": "ruvector.rvf.jsonl/v1", "format": "github-traffic-snapshots", "repo": "ruvnet/RuView", "source": "GitHub Traffic API /repos/{repo}/traffic/{clones,views}", "policy": "GitHub retains only 14 days server-side; this file is the long-term record.", "segments": ["metadata", "clone_snapshot", "view_snapshot"], "created_at": "2026-05-19T23:16:22Z", "custom": {"cadence": "twice monthly (1st and 15th, ~14-day intervals)", "idempotency_key": "timestamp (per-day records de-duplicate across overlapping snapshot windows)"}}
|
||||
{"type": "clone_snapshot", "fetched_at": "2026-05-19T23:16:22Z", "window_count": 27887, "window_uniques": 6611, "per_day": [{"timestamp": "2026-05-05T00:00:00Z", "count": 620, "uniques": 218}, {"timestamp": "2026-05-06T00:00:00Z", "count": 477, "uniques": 232}, {"timestamp": "2026-05-07T00:00:00Z", "count": 685, "uniques": 268}, {"timestamp": "2026-05-08T00:00:00Z", "count": 703, "uniques": 276}, {"timestamp": "2026-05-09T00:00:00Z", "count": 352, "uniques": 184}, {"timestamp": "2026-05-10T00:00:00Z", "count": 205, "uniques": 151}, {"timestamp": "2026-05-11T00:00:00Z", "count": 1160, "uniques": 234}, {"timestamp": "2026-05-12T00:00:00Z", "count": 599, "uniques": 207}, {"timestamp": "2026-05-13T00:00:00Z", "count": 5141, "uniques": 1152}, {"timestamp": "2026-05-14T00:00:00Z", "count": 3420, "uniques": 972}, {"timestamp": "2026-05-15T00:00:00Z", "count": 1974, "uniques": 764}, {"timestamp": "2026-05-16T00:00:00Z", "count": 2917, "uniques": 617}, {"timestamp": "2026-05-17T00:00:00Z", "count": 6690, "uniques": 1169}, {"timestamp": "2026-05-18T00:00:00Z", "count": 2944, "uniques": 625}]}
|
||||
{"type": "view_snapshot", "fetched_at": "2026-05-19T23:16:22Z", "window_count": 162314, "window_uniques": 75464, "per_day": [{"timestamp": "2026-05-05T00:00:00Z", "count": 5540, "uniques": 2690}, {"timestamp": "2026-05-06T00:00:00Z", "count": 5111, "uniques": 2393}, {"timestamp": "2026-05-07T00:00:00Z", "count": 5585, "uniques": 2708}, {"timestamp": "2026-05-08T00:00:00Z", "count": 7004, "uniques": 3261}, {"timestamp": "2026-05-09T00:00:00Z", "count": 5395, "uniques": 2531}, {"timestamp": "2026-05-10T00:00:00Z", "count": 4761, "uniques": 2219}, {"timestamp": "2026-05-11T00:00:00Z", "count": 4275, "uniques": 2044}, {"timestamp": "2026-05-12T00:00:00Z", "count": 3466, "uniques": 1688}, {"timestamp": "2026-05-13T00:00:00Z", "count": 13561, "uniques": 8473}, {"timestamp": "2026-05-14T00:00:00Z", "count": 21867, "uniques": 12527}, {"timestamp": "2026-05-15T00:00:00Z", "count": 26182, "uniques": 14609}, {"timestamp": "2026-05-16T00:00:00Z", "count": 17406, "uniques": 8868}, {"timestamp": "2026-05-17T00:00:00Z", "count": 28444, "uniques": 14541}, {"timestamp": "2026-05-18T00:00:00Z", "count": 13717, "uniques": 7819}]}
|
||||
+5
-22
@@ -3,7 +3,7 @@
|
||||
# Multi-stage build for minimal final image
|
||||
|
||||
# Stage 1: Build
|
||||
FROM rust:1.89-bookworm AS builder
|
||||
FROM rust:1.85-bookworm AS builder
|
||||
|
||||
WORKDIR /build
|
||||
|
||||
@@ -14,18 +14,9 @@ COPY v2/crates/ ./crates/
|
||||
# Copy vendored RuVector crates
|
||||
COPY vendor/ruvector/ /build/vendor/ruvector/
|
||||
|
||||
# Build release binaries:
|
||||
# - sensing-server with `mqtt` feature so the HA-DISCO MQTT publisher
|
||||
# (ADR-115) is wired in (auto-discovery topics flow to Home Assistant)
|
||||
# - cog-ha-matter, the ADR-116 Cognitum cog that wraps HA-DISCO +
|
||||
# HA-MIND + mDNS + embedded broker for Home Assistant / Matter
|
||||
# - homecore-server, the ADRs-126-134 HOMECORE native Rust port of
|
||||
# Home Assistant (HA-wire-compat REST + WebSocket on :8123,
|
||||
# SQLite + ruvector recorder, automation, assist, plugins, HAP)
|
||||
RUN cargo build --release -p wifi-densepose-sensing-server --features mqtt 2>&1 \
|
||||
&& cargo build --release -p cog-ha-matter 2>&1 \
|
||||
&& cargo build --release -p homecore-server 2>&1 \
|
||||
&& strip target/release/sensing-server target/release/cog-ha-matter target/release/homecore-server
|
||||
# Build release binary
|
||||
RUN cargo build --release -p wifi-densepose-sensing-server 2>&1 \
|
||||
&& strip target/release/sensing-server
|
||||
|
||||
# Stage 2: Runtime
|
||||
FROM debian:bookworm-slim
|
||||
@@ -36,10 +27,8 @@ RUN apt-get update && apt-get install -y --no-install-recommends \
|
||||
|
||||
WORKDIR /app
|
||||
|
||||
# Copy binaries
|
||||
# Copy binary
|
||||
COPY --from=builder /build/target/release/sensing-server /app/sensing-server
|
||||
COPY --from=builder /build/target/release/cog-ha-matter /app/cog-ha-matter
|
||||
COPY --from=builder /build/target/release/homecore-server /app/homecore-server
|
||||
|
||||
# Copy UI assets
|
||||
COPY ui/ /app/ui/
|
||||
@@ -56,8 +45,6 @@ RUN set -e; \
|
||||
test -d "$d" || { echo "FATAL: missing UI directory $d"; exit 1; }; \
|
||||
done; \
|
||||
test -x /app/sensing-server || { echo "FATAL: /app/sensing-server is not executable"; exit 1; }; \
|
||||
test -x /app/cog-ha-matter || { echo "FATAL: /app/cog-ha-matter is not executable"; exit 1; }; \
|
||||
test -x /app/homecore-server || { echo "FATAL: /app/homecore-server is not executable"; exit 1; }; \
|
||||
echo "image assets OK"
|
||||
|
||||
# Optional bearer-token auth on /api/v1/*: leave unset for LAN-mode (default),
|
||||
@@ -71,10 +58,6 @@ EXPOSE 3000
|
||||
EXPOSE 3001
|
||||
# ESP32 UDP
|
||||
EXPOSE 5005/udp
|
||||
# MQTT broker (cog-ha-matter embedded broker — Home Assistant + Matter)
|
||||
EXPOSE 1883
|
||||
# HOMECORE HA-compatible REST + WebSocket (homecore-server)
|
||||
EXPOSE 8123
|
||||
|
||||
ENV RUST_LOG=info
|
||||
|
||||
|
||||
@@ -24,13 +24,10 @@ services:
|
||||
environment:
|
||||
- RUST_LOG=info
|
||||
# CSI_SOURCE controls the data source for the sensing server.
|
||||
# Options: auto (default) — probe for ESP32 UDP then host WiFi; **fail
|
||||
# hard with exit 78 if neither is detected**.
|
||||
# Synthetic data is no longer a silent fallback
|
||||
# (issue #937 fix) — operators must opt in.
|
||||
# Options: auto (default) — probe for ESP32 UDP then fall back to simulation
|
||||
# esp32 — receive real CSI frames from an ESP32 on UDP port 5005
|
||||
# wifi — use host Wi-Fi RSSI/scan data (Windows netsh)
|
||||
# simulated — explicitly generate synthetic CSI for demo mode
|
||||
# simulated — generate synthetic CSI data (no hardware required)
|
||||
- CSI_SOURCE=${CSI_SOURCE:-auto}
|
||||
# MODELS_DIR controls where the server scans for .rvf model files.
|
||||
# Mount a host directory and set this to make models visible:
|
||||
|
||||
@@ -11,88 +11,10 @@
|
||||
# docker run ruvnet/wifi-densepose:latest --model /app/models/my.rvf
|
||||
#
|
||||
# Environment variables:
|
||||
# CSI_SOURCE — data source. Valid values:
|
||||
# auto — try ESP32 then Windows WiFi, **fail-loud if no
|
||||
# real hardware is detected** (issue #937 fix:
|
||||
# the server no longer silently falls back to
|
||||
# synthetic data — that's now opt-in only).
|
||||
# esp32 — listen for UDP CSI on the configured port.
|
||||
# wifi — Windows-native WiFi capture.
|
||||
# simulated — explicit demo mode with synthetic CSI.
|
||||
# Default is `auto`. Set CSI_SOURCE=simulated when you want
|
||||
# fake data tagged as such; never set it implicitly.
|
||||
# CSI_SOURCE — data source: auto (default), esp32, wifi, simulated
|
||||
# MODELS_DIR — directory to scan for .rvf model files (default: data/models)
|
||||
set -e
|
||||
|
||||
# ── Issue #864: fail-closed on default posture ───────────────────────────────
|
||||
# The pre-fix default was: empty RUVIEW_API_TOKEN (auth off) + --bind-addr
|
||||
# 0.0.0.0 + docker-compose publishing :3000/:3001/:5005 → an unauthenticated
|
||||
# attacker on any reachable network segment could read /api/v1/sensing/latest
|
||||
# and the /ws/sensing live stream. That posture is unsafe on guest WiFi,
|
||||
# untrusted LANs, accidentally-port-forwarded hosts, or any reverse-proxied
|
||||
# deployment. Refuse to start with this combination.
|
||||
#
|
||||
# Escape hatches (operator must opt in explicitly):
|
||||
# * Set RUVIEW_API_TOKEN to a strong secret → auth enabled on /api/v1/*.
|
||||
# * Set RUVIEW_ALLOW_UNAUTHENTICATED=1 → preserves the pre-fix behaviour;
|
||||
# only safe on an isolated trust boundary.
|
||||
# * Set RUVIEW_BIND_ADDR to a loopback / private interface → unauth is fine
|
||||
# when the socket isn't reachable. The auto-bind nudges toward 127.0.0.1.
|
||||
#
|
||||
# This check runs only for the default sensing-server path (no args + flag-only
|
||||
# args). The `cog-ha-matter` / `homecore` routes below are excluded because
|
||||
# they own their own auth lifecycle.
|
||||
case "${1:-}" in
|
||||
cog-ha-matter|ha-matter|homecore|homecore-server) ;;
|
||||
*)
|
||||
if [ -z "${RUVIEW_API_TOKEN:-}" ] && [ "${RUVIEW_ALLOW_UNAUTHENTICATED:-}" != "1" ]; then
|
||||
# If the operator hasn't overridden the bind, refuse outright on
|
||||
# the default 0.0.0.0. If they've nailed it to loopback (or a
|
||||
# specific private address they trust), let it run.
|
||||
__bind_default="${RUVIEW_BIND_ADDR:-0.0.0.0}"
|
||||
case "$__bind_default" in
|
||||
127.*|localhost|::1)
|
||||
: ;; # loopback bind is safe even without a token
|
||||
*)
|
||||
echo "[entrypoint] ERROR: refusing to start sensing-server with default" >&2
|
||||
echo "[entrypoint] posture: RUVIEW_API_TOKEN is unset AND bind is" >&2
|
||||
echo "[entrypoint] ${__bind_default}. /ws/sensing streams live sensing" >&2
|
||||
echo "[entrypoint] frames; that data would be readable by anyone who" >&2
|
||||
echo "[entrypoint] can reach this host. Pick one:" >&2
|
||||
echo "[entrypoint] docker run -e RUVIEW_API_TOKEN=\$(openssl rand -hex 32) ..." >&2
|
||||
echo "[entrypoint] docker run -e RUVIEW_BIND_ADDR=127.0.0.1 ..." >&2
|
||||
echo "[entrypoint] docker run -e RUVIEW_ALLOW_UNAUTHENTICATED=1 ... # only on trusted network" >&2
|
||||
echo "[entrypoint] See https://github.com/ruvnet/RuView/issues/864" >&2
|
||||
exit 64
|
||||
;;
|
||||
esac
|
||||
fi
|
||||
;;
|
||||
esac
|
||||
|
||||
# Route to cog-ha-matter (ADR-116) when invoked as:
|
||||
# docker run <image> cog-ha-matter [--flags]
|
||||
# or via the short alias `ha-matter`. Strips the keyword and execs the
|
||||
# Home Assistant + Matter cog binary, defaulting --sensing-url to the
|
||||
# co-located sensing-server endpoint so docker-compose deployments work
|
||||
# out of the box.
|
||||
case "${1:-}" in
|
||||
cog-ha-matter|ha-matter)
|
||||
shift
|
||||
exec /app/cog-ha-matter \
|
||||
--sensing-url "${SENSING_URL:-http://127.0.0.1:3000}" \
|
||||
"$@"
|
||||
;;
|
||||
homecore|homecore-server)
|
||||
# Route to the HOMECORE native Rust port of Home Assistant
|
||||
# (ADRs 126-134, v0.10.0). Default bind matches HA at :8123.
|
||||
shift
|
||||
exec /app/homecore-server \
|
||||
--bind "${HOMECORE_BIND:-0.0.0.0:8123}" \
|
||||
"$@"
|
||||
;;
|
||||
esac
|
||||
|
||||
# If the first argument looks like a flag (starts with -), prepend the
|
||||
# server binary so users can just pass flags:
|
||||
# docker run <image> --source esp32 --tick-ms 500
|
||||
@@ -103,7 +25,7 @@ if [ "${1#-}" != "$1" ] || [ -z "$1" ]; then
|
||||
--ui-path /app/ui \
|
||||
--http-port 3000 \
|
||||
--ws-port 3001 \
|
||||
--bind-addr "${RUVIEW_BIND_ADDR:-0.0.0.0}" \
|
||||
--bind-addr 0.0.0.0 \
|
||||
"$@"
|
||||
fi
|
||||
|
||||
|
||||
@@ -1,97 +0,0 @@
|
||||
# ADR-110 — Branch state (as of 2026-05-23, iter 22)
|
||||
|
||||
Reference card for anyone collaborating on or near the ADR-110 work. The /loop SOTA sprint that closed the firmware-side substrate ran into multiple cross-branch checkout incidents (see iter 17-19); this page exists so the next collaborator doesn't have to re-derive the layout from `git log`.
|
||||
|
||||
## Branch ownership
|
||||
|
||||
| Branch | Owner | What it carries | Don't merge from |
|
||||
|---|---|---|---|
|
||||
| `main` | shared | shipped release line | — |
|
||||
| `adr-110-esp32c6` | ADR-110 / C6 firmware substrate | Everything described in `WITNESS-LOG-110 §A0.x` (4 firmware tags v0.6.7 → v0.7.0, Python + Rust decoders, sensing-server wire, mesh-aligned timestamp recovery, fps EMA, cross-language conformance gate) | Don't accidentally land `feat/adr-115-ha-mqtt-matter` work here uncommitted |
|
||||
| `feat/adr-115-ha-mqtt-matter` | ADR-115 / HA-DISCO + HA-FABRIC + HA-MIND | MQTT publisher (`rumqttc`), Matter Bridge, semantic automation primitives, related Cargo features + CLI flags | Don't accidentally land ADR-110 `wifi-densepose-hardware` dep mods here |
|
||||
|
||||
## Files each branch touches
|
||||
|
||||
### `adr-110-esp32c6` — primary modifications
|
||||
|
||||
```
|
||||
firmware/esp32-csi-node/version.txt # bumped 0.6.6 → 0.7.0
|
||||
firmware/esp32-csi-node/main/c6_*.{c,h} # LP-core, TWT, timesync, soft-AP HE, ESP-NOW sync
|
||||
firmware/esp32-csi-node/main/lp_core/main.c # real LP-core polling program
|
||||
firmware/esp32-csi-node/main/csi_collector.c # byte 19 bit 4 OR-fix; sync packet emit
|
||||
firmware/esp32-csi-node/main/Kconfig.projbuild # C6_* knobs
|
||||
firmware/esp32-csi-node/main/CMakeLists.txt # ulp_embed_binary
|
||||
firmware/esp32-csi-node/sdkconfig.defaults.esp32c6 # C6 overlay
|
||||
|
||||
archive/v1/src/hardware/csi_extractor.py # SyncPacketParser + SyncPacket dataclass
|
||||
archive/v1/tests/unit/test_esp32_binary_parser.py # TestSyncPacketParser (7 tests)
|
||||
|
||||
v2/crates/wifi-densepose-hardware/src/sync_packet.rs # new module (15 tests)
|
||||
v2/crates/wifi-densepose-hardware/src/lib.rs # re-exports
|
||||
v2/crates/wifi-densepose-sensing-server/Cargo.toml # ONLY adds wifi-densepose-hardware path dep
|
||||
v2/crates/wifi-densepose-sensing-server/src/main.rs # NodeState::{latest_sync, csi_fps_ema,
|
||||
# mesh_aligned_us_for_csi_frame,
|
||||
# observe_csi_frame_arrival}
|
||||
# udp_receiver_task magic dispatch
|
||||
# fps_ema_tests module (4 tests)
|
||||
|
||||
docs/adr/ADR-110-esp32-c6-firmware-extension.md # 670 → ~750 lines (P10 + sprint summary)
|
||||
docs/WITNESS-LOG-110.md # 13 §A0.x entries
|
||||
docs/ADR-110-REVIEW-GUIDE.md # reviewer one-pager
|
||||
docs/ADR-110-BRANCH-STATE.md # ← this file
|
||||
```
|
||||
|
||||
### `feat/adr-115-ha-mqtt-matter` — primary modifications
|
||||
|
||||
```
|
||||
docs/adr/ADR-115-home-assistant-integration.md # the design
|
||||
v2/crates/wifi-densepose-sensing-server/Cargo.toml # rumqttc dep + [features] block
|
||||
v2/crates/wifi-densepose-sensing-server/src/cli.rs # --mqtt / --matter / --semantic flags
|
||||
```
|
||||
|
||||
## Known overlap points (handle with care)
|
||||
|
||||
Both branches touch `v2/crates/wifi-densepose-sensing-server/Cargo.toml` and `src/main.rs`. The conflict surface is **disjoint by section**:
|
||||
|
||||
| File | ADR-110 region | ADR-115 region |
|
||||
|---|---|---|
|
||||
| `Cargo.toml` | `[dependencies]` — `wifi-densepose-hardware = { path = "../wifi-densepose-hardware" }` near the existing `wifi-densepose-signal` line | `[dependencies]` — `rumqttc` block below + `[features]` block at end |
|
||||
| `main.rs` | `NodeState` fields + `impl NodeState` helpers + `update_csi_fps_ema` free fn + `fps_ema_tests` module + `udp_receiver_task` magic dispatch | (TBD per ADR-115 P-plan) |
|
||||
|
||||
A merge between the two branches should be **clean line-merge** since the regions don't overlap. If git ever reports a real conflict in either of these files, that means one branch has drifted into the other's region — investigate before resolving blindly.
|
||||
|
||||
## Quick test commands (verify either branch is sane)
|
||||
|
||||
```bash
|
||||
# Rust workspace (run from v2/)
|
||||
cd v2
|
||||
cargo test --workspace --no-default-features --lib # 1437 tests at iter 22, 0 failures
|
||||
|
||||
# Python ADR-110 host decoder (from repo root)
|
||||
python -m pytest archive/v1/tests/unit/test_esp32_binary_parser.py::TestSyncPacketParser -v
|
||||
|
||||
# Cross-language wire-format gate (the iter 21 pin)
|
||||
cargo test -p wifi-densepose-hardware --no-default-features --lib sync_packet::tests::canonical_wire_bytes_match_python_decoder
|
||||
python -m pytest archive/v1/tests/unit/test_esp32_binary_parser.py::TestSyncPacketParser::test_canonical_wire_bytes_match_rust_decoder -v
|
||||
```
|
||||
|
||||
If either side of the canonical-wire-bytes pair fails alone, the OTHER decoder has drifted from the wire format — investigate that decoder first, not the failing test.
|
||||
|
||||
## Future-proofing
|
||||
|
||||
- When the ADR-115 agent ships `feat/adr-115-ha-mqtt-matter` to main and ADR-110 also ships, merge `main` into `adr-110-esp32c6` (or vice versa) and re-run both test suites. The disjoint-region structure above should make the merge a no-conflict fast-forward.
|
||||
- When a third agent picks up either ADR, point them at this file before they start editing shared files.
|
||||
- If a /loop drives autonomous iterations and hits a cross-branch checkout, the recovery procedure is in iter 18's commit message (`2997165bc`) — stash on the foreign branch, `git checkout` home, replay the iter locally.
|
||||
|
||||
## Lessons for `/loop` and `/loop-worker` future runs
|
||||
|
||||
Captured after the 38-iter ADR-110 SOTA sprint (`/loop 5m until sota. and ultra optmized`):
|
||||
|
||||
1. **Always verify the current branch at the start of each iter** — when a /loop fires every 5 minutes and another agent is active on a sibling branch, the working tree can flip without your action. Run `git branch --show-current` as the first line of every iter; if it isn't what you expect, stash and switch back BEFORE editing. We burned ~30 min in iter 17-19 recovering from two silent branch flips.
|
||||
2. **Don't `git add <file>` blindly after a branch switch** — the file may have inherited changes from the foreign branch (uncommitted work that came along on checkout). Always `git diff --cached` before `git commit`. We accidentally absorbed ADR-115's Cargo.toml/cli.rs work into ADR-110's iter-18 commit; required a follow-up revert commit (`ca2059b07`) and stash dance.
|
||||
3. **Sibling-region edits in shared files** — when two branches both touch `v2/crates/wifi-densepose-sensing-server/Cargo.toml` or `src/main.rs`, agree on which `[section]` or struct each owns. Document the regions in this file (see Known overlap points). Merges then stay clean line-merge fast-forwards instead of needing conflict resolution.
|
||||
4. **Extract pure helpers before committing inline mutations** — iter 30 (`sync_snapshot`), iter 32 (`apply_sync_packet`), iter 37 (`fleet_role_counts`) all converted inline state-changes into named, free, testable functions. Each saved 4+ inline duplications and let the helper be tested without spinning up axum / tokio. Bake this into every iter's plan: *"what's the smallest helper I can extract here?"*
|
||||
5. **Cross-language wire-format gates** — when shipping a protocol decoder in both Python and Rust, pin the SAME canonical byte string in BOTH test suites (iter 21 pattern). One side drifting fires exactly one named test on exactly the drifted decoder. Don't wait until "later" — add the pin in the iter that ships the second language.
|
||||
6. **Helper tests > integration tests when state is heavy** — `AppStateInner` has too many fields to construct in a test. Instead of fighting it, extract per-field logic into pure helpers (iter 30 sync_snapshot pattern). Tests target the helpers, the handler glue stays thin and trivially correct.
|
||||
7. **Local stub files lag firmware additions** — `firmware/esp32-csi-node/test/stubs/esp_stubs.c` doesn't get rebuilt with the firmware proper, so a new symbol added to a `*.h` won't surface as a fuzz-target link error until CI runs. Iter 38 caught `c6_sync_espnow_is_valid` this way. **Whenever you add a function whose declaration is reachable from `csi_collector.c`, also add a stub** in the same commit.
|
||||
8. **Cron-based /loop accumulates work across irreversible checkpoints (tags, releases, PR ready)** — once you cut a tag or mark a PR ready, the cost of reverting is much higher than a code edit. Save those for iters when you have surplus confidence (full local test suite green, CI from previous iter green). Iter 12 (v0.7.0 cut) and iter 38 (PR ready) were the right shape: only happened after iter 6 / iter 37 evidence had landed.
|
||||
@@ -1,62 +0,0 @@
|
||||
# ADR-110 review guide
|
||||
|
||||
This is the **one-pager** for reviewers of the `adr-110-esp32c6` branch / draft PR. The canonical record is [`docs/WITNESS-LOG-110.md`](WITNESS-LOG-110.md); this guide is just a faster on-ramp.
|
||||
|
||||
## What this branch ships
|
||||
|
||||
A dual-target build for `firmware/esp32-csi-node`: same source tree compiles for `esp32s3` (existing production) and `esp32c6` (new research target with Wi-Fi 6 / 802.15.4 / TWT / LP-core). Every C6-only module is `#ifdef CONFIG_IDF_TARGET_ESP32C6` gated, so the S3 build path is byte-identical to before.
|
||||
|
||||
## Five-minute reviewer tour
|
||||
|
||||
1. **Read the ADR**: [`docs/adr/ADR-110-esp32-c6-firmware-extension.md`](adr/ADR-110-esp32-c6-firmware-extension.md) — design, phases, trade-offs.
|
||||
2. **Read the witness**: [`docs/WITNESS-LOG-110.md`](WITNESS-LOG-110.md) — 4 sections (A = empirically verified, B = architectural-but-not-measured, C = bugs fixed, D = bugs found but not yet fixed, D-workaround = ESP-NOW pivot).
|
||||
3. **Skim the new firmware modules**: `firmware/esp32-csi-node/main/c6_{twt,timesync,lp_core,sync_espnow}.{h,c}`.
|
||||
4. **Skim the new host decoders + tests**:
|
||||
- Rust: `v2/crates/wifi-densepose-hardware/src/{csi_frame,esp32_parser}.rs` (search for `PpduType`, `Adr018Flags`, `adr110_*` test names)
|
||||
- Python: `archive/v1/src/hardware/csi_extractor.py` + `archive/v1/tests/unit/test_esp32_binary_parser.py` (search for `TestAdr110ByteEncoding`)
|
||||
5. **Glance at CI**: `firmware-ci.yml` `c6-4mb` matrix row runs the C6 build AND the host unit tests on Ubuntu — both green throughout this branch.
|
||||
|
||||
## Empirical scorecard (what's actually measured)
|
||||
|
||||
| Dimension | Status |
|
||||
|---|---|
|
||||
| C6 build + boot + dual-target | ✅ verified on 3 boards (COM6/COM9/COM12), CI matrix green, S3 regression green |
|
||||
| HE-LTF wire format (ADR-018 byte 18-19) | ✅ verified end-to-end across firmware / Rust / Python (17 unit tests) |
|
||||
| HE-LTF live capture | ⏸ blocked — need 11ax AP (only 11n AP on bench) |
|
||||
| TWT graceful NACK | ✅ verified live — `c6_twt: iTWT setup failed: ESP_ERR_INVALID_ARG` captured + handled |
|
||||
| TWT cadence determinism | ⏸ blocked — same 11ax AP gap |
|
||||
| ESP-NOW transport TX + stability | ✅ verified — 120 s + 300 s soaks, 4102 cumulative transmits, 0 failures |
|
||||
| ESP-NOW cross-board RX | ⏸ blocked — 3 of 4 boards dropped USB enumeration mid-experiment |
|
||||
| Raw 802.15.4 cross-node sync | ❌ broken — IDF v5.4 driver bug, 5 hypotheses tested + rejected; ESP-NOW workaround in place |
|
||||
| 5 µA hibernation | ⏸ blocked — datasheet number, need INA / Joulescope to measure |
|
||||
| Witness bundle regenerable + clean | ✅ 6/7 PASS (1 fail is pre-existing Python proof env issue unrelated to ADR-110), all hashes recorded, secret-redacted |
|
||||
|
||||
## Honest verdict
|
||||
|
||||
Protocol layer + transport substrate are bullet-proofed. **None of the four headline SOTA dimensions is empirically measured** — each is blocked on hardware the bench doesn't have. Each blocker is documented in `WITNESS-LOG-110.md` §B with the exact instrument needed to unblock it. **This branch is the foundation to build measurement on, not the measurement itself.**
|
||||
|
||||
The five concrete bugs found and fixed during the work (MAC/EUI double-FFFE, dual `wifi_pkt_rx_ctrl_t` struct variants, LED GPIO 38 on C6, TWT INVALID_ARG propagation, witness bundle secret leak) are independently real and useful regardless of how the SOTA story lands.
|
||||
|
||||
## Security note for the operator (not the reviewer)
|
||||
|
||||
The witness bundle's Python proof step was leaking `.env` contents into the bundled log via Pydantic validation error dumps. Bundle was nuked before push, and `scripts/redact-secrets.py` filter was added (commit `f8a2e3695`). **The previously-exposed Docker Hub + PI-cluster tokens should be rotated** — they appeared in local session logs even though they never reached `origin`.
|
||||
|
||||
## Commits on this branch (chronological)
|
||||
|
||||
| # | SHA prefix | What |
|
||||
|---|---|---|
|
||||
| 1 | `f23e34e` | Initial ADR-110 firmware + ADR + tests + docs + witness scaffolding |
|
||||
| 2 | `6652384` | TWT INVALID_ARG graceful + diagnostic counters |
|
||||
| 3 | `4c39e28` | PAN-match + 4-experiment D1 record |
|
||||
| 4 | `f8a2e36` | **SECURITY**: witness bundle secret redaction |
|
||||
| 5 | `88be283` | ESP-NOW transport (D1 workaround) |
|
||||
| 6 | `3959fab` | Rust host decoder + 6 unit tests |
|
||||
| 7 | `8eaa92c` | Python host decoder + 5 unit tests |
|
||||
| 8 | `b808a63` | 120 s ESP-NOW soak witness |
|
||||
| 9 | `89972c0` | CHANGELOG expanded |
|
||||
| 10 | `fc75a8a` | Fuzz harness extended for byte 18-19 |
|
||||
| 11 | `9de34ba` | ADR-110 indexed in docs/adr/README.md |
|
||||
| 12 | `553b07d` | README C6 row tightened (claim → wire-format-ready) |
|
||||
| 13 | `e255b7d` | firmware/README acknowledges S3+C6 |
|
||||
| 14 | `9a46fc8` | 300 s ESP-NOW soak witness (2.5× sample) |
|
||||
| 15 | _(this commit)_ | This review guide |
|
||||
@@ -1,117 +0,0 @@
|
||||
# RuView Streaming Engine v0.3.0 — Auditable Environmental Intelligence
|
||||
|
||||
## What this is
|
||||
|
||||
Most WiFi-sensing stacks emit a number and hope you trust it. **RuView's streaming
|
||||
engine is built so you don't have to.** Every conclusion it reaches — "someone is
|
||||
in the living room," "fall risk elevated," "the room layout changed" — carries a
|
||||
full evidence trail: which sensors saw it, how much they agreed, which calibration
|
||||
and model produced it, and what privacy policy it was emitted under.
|
||||
|
||||
The throughline is **trust**. If you ask *"why should I believe this when it says a
|
||||
person fell?"*, the engine answers with signal evidence, sensor agreement,
|
||||
calibration provenance, and an auditable privacy posture — not just a confidence
|
||||
score.
|
||||
|
||||
This release lands the ADR-135→146 series: the data contracts, the
|
||||
trust/privacy/audit machinery, and the algorithms — all real, tested, and
|
||||
composed into one end-to-end pipeline cycle.
|
||||
|
||||
## The two layers that make it auditable
|
||||
|
||||
- **WorldGraph (`wifi-densepose-worldgraph`)** — the *where & why* graph. A typed
|
||||
graph of rooms, sensors, RF links, person tracks, object anchors, events, and
|
||||
beliefs, connected by typed edges: `observes`, `located_in`, `derived_from`,
|
||||
`contradicts`, `privacy_limited_by`. The privacy posture is *visible in the
|
||||
persisted graph* — an auditor can read exactly what was suppressed and why.
|
||||
- **Trusted semantic records** — the *what we believe right now* record. Every
|
||||
semantic state carries model version, calibration version, evidence refs,
|
||||
confidence, expiry, and privacy action. High-stakes actions (caregiver
|
||||
escalation) require **multi-signal agreement**, not a single noisy primitive.
|
||||
|
||||
## What's new in v0.3.0
|
||||
|
||||
| Area | Capability |
|
||||
|------|-----------|
|
||||
| Frame contracts (ADR-136) | `ComplexSample` (LE-canonical), provenance fields on every frame, `CanonicalFrame` BLAKE3 witness, `Stage`/`Versioned`/`QualityScored` traits |
|
||||
| Calibration (ADR-135) | `BaselineCalibration::apply()` stamps a deterministic `calibration_id` onto each frame |
|
||||
| Fusion quality (ADR-137) | `QualityScore` with per-node weights, evidence refs, and contradiction flags; calibration-mismatch detection |
|
||||
| Array coordination (ADR-138) | clock-quality + geometry gating; degraded nodes go "watch-only" |
|
||||
| WorldGraph (ADR-139) | the typed digital twin + privacy rollup + deterministic persistence |
|
||||
| Semantic records (ADR-140) | auditable state records + multi-signal agent routing |
|
||||
| Privacy control plane (ADR-141) | named modes + actions + a BLAKE3 hash-chained, tamper-evident attestation |
|
||||
| Evolution + VoxelMap (ADR-142) | cross-link "the room changed" detection + Bayesian occupancy, privacy-gated to a histogram |
|
||||
| RF-SLAM (ADR-143) | persistent reflector discovery → learned static anchors |
|
||||
| UWB fusion (ADR-144) | range-constraint refinement with outlier rejection (forward-looking) |
|
||||
| Ablation harness (ADR-145) | feature-matrix metrics incl. membership-inference privacy leakage |
|
||||
| RF encoder (ADR-146) | multi-task heads with per-head uncertainty + contrastive batcher (forward-looking) |
|
||||
| **Engine (`wifi-densepose-engine`)** | the composition root: one `process_cycle()` runs the whole trust pipeline |
|
||||
|
||||
## Quick start
|
||||
|
||||
```rust
|
||||
use wifi_densepose_engine::StreamingEngine;
|
||||
use wifi_densepose_bfld::PrivacyMode;
|
||||
use wifi_densepose_geo::types::GeoRegistration;
|
||||
use wifi_densepose_signal::ruvsense::fusion_quality::CalibrationId;
|
||||
|
||||
// 1. Build the engine with a privacy posture + model version.
|
||||
let mut engine = StreamingEngine::new(PrivacyMode::PrivateHome, 1, GeoRegistration::default());
|
||||
|
||||
// 2. Describe the space (rooms + sensors are WorldGraph nodes).
|
||||
let room = engine.add_room("living_room", "Living Room");
|
||||
let sensor = engine.add_sensor("esp32-com9", room);
|
||||
engine.register_node_geometry(0, 1.0, 0.0, 0.0); // ADR-138 array geometry (optional)
|
||||
|
||||
// 3. Each 50 ms cycle: feed per-node CSI frames + the calibration epoch.
|
||||
let out = engine.process_cycle(&node_frames, CalibrationId(0xABCD), room, now_ms)?;
|
||||
|
||||
// 4. The result is a *trusted* belief — fully traceable.
|
||||
println!("class={:?} demoted={} evidence={:?}",
|
||||
out.effective_class, out.demoted, out.provenance.evidence);
|
||||
assert_eq!(out.quality.calibration_id, Some(CalibrationId(0xABCD)));
|
||||
|
||||
// 5. Persist the world model; reload reproduces the same query results.
|
||||
let snapshot = engine.snapshot_json()?; // RVF payload — never raw RF frames
|
||||
```
|
||||
|
||||
Per-node calibration (mismatch demotes privacy automatically):
|
||||
|
||||
```rust
|
||||
let out = engine.process_cycle_calibrated(
|
||||
&node_frames,
|
||||
&[Some(CalibrationId(1)), Some(CalibrationId(2))], // disagree → CalibrationIdMismatch
|
||||
room, now_ms)?;
|
||||
assert!(out.demoted); // privacy class demoted to Restricted
|
||||
assert_eq!(out.quality.calibration_id, None); // no single calibration epoch
|
||||
```
|
||||
|
||||
## Validated (acceptance tests that prove the architecture)
|
||||
|
||||
- **ADR-137** `two calibrated frames → calibration mismatch → QualityScore contradiction → Restricted → calibration_id None → witness stable`
|
||||
- **ADR-139** `live_frame → fusion → worldgraph_update → privacy_rollup → persist → reload → same_contents` (no raw RF persisted)
|
||||
- **ADR-140** `raw snapshot → semantic primitive → SemanticStateRecord → agreement rule → expired record rejected`
|
||||
- **ADR-142** `3 links drift 30 frames → ChangePoint → VoxelMap accumulates → low-confidence suppressed → VoxelGate Restricted histogram → ADR-137 contradiction`
|
||||
|
||||
## Performance & safety
|
||||
|
||||
- **~6.35 µs per full cycle** (4 nodes / 56 subcarriers) — ~7,800× under the 50 ms / 20 Hz budget (criterion: `cargo bench -p wifi-densepose-engine`).
|
||||
- New crates are `#![forbid(unsafe_code)]`; no hardcoded secrets; input validated at boundaries; privacy demotion is monotonic; mode changes are hash-chain attested.
|
||||
- `wifi-densepose-core` and `wifi-densepose-bfld` build `#![no_std]` for the ESP32-S3 on-device path.
|
||||
|
||||
## Build & test
|
||||
|
||||
```bash
|
||||
cd v2
|
||||
cargo build --release --workspace --no-default-features # optimized build
|
||||
cargo test --workspace --no-default-features # full suite
|
||||
cargo test -p wifi-densepose-engine # 13 integration tests
|
||||
cargo bench -p wifi-densepose-engine # per-cycle latency
|
||||
```
|
||||
|
||||
## Status (honest)
|
||||
|
||||
Integrated and validated end-to-end: ADR-135/136/137/138/139/141/142/143 via the
|
||||
`wifi-densepose-engine` composition root. Forward-looking / pending: live 20 Hz
|
||||
sensing-server loop wiring, UWB hardware (ADR-144), and RF-encoder model training
|
||||
(ADR-146). Each GitHub issue (#840–#850) lists what is *Built* vs *Integration glue*.
|
||||
@@ -156,25 +156,6 @@ docker inspect ruvnet/wifi-densepose:python --format='{{.Size}}'
|
||||
# Expected: ~569 MB
|
||||
```
|
||||
|
||||
### Step 10b: Verify CIR Deterministic Proof (ADR-134)
|
||||
|
||||
```bash
|
||||
bash scripts/verify-cir-proof.sh
|
||||
```
|
||||
|
||||
**Expected:** `VERDICT: PASS (CIR hash matches)` once the `cir` module is implemented.
|
||||
|
||||
Currently outputs `BLOCKED` because `expected_cir_features.sha256` contains a placeholder.
|
||||
After the CIR implementation lands, regenerate and commit the hash:
|
||||
|
||||
```bash
|
||||
cd v2 && cargo run -p wifi-densepose-signal --bin cir_proof_runner \
|
||||
--release --no-default-features -- --generate-hash \
|
||||
> ../archive/v1/data/proof/expected_cir_features.sha256
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Step 11: Verify ESP32 Flash (requires hardware on COM7)
|
||||
|
||||
```bash
|
||||
@@ -231,8 +212,6 @@ Each row is independently verifiable. Status reflects audit-time findings.
|
||||
| 31 | On-device ESP32 ML inference | No | **NO** | Firmware streams raw I/Q; inference runs on aggregator |
|
||||
| 32 | Real-world CSI dataset bundled | No | **NO** | Only synthetic reference signal (seed=42) |
|
||||
| 33 | 54,000 fps measured throughput | Claimed | **NOT MEASURED** | Criterion benchmarks exist but not run at audit time |
|
||||
| 34 | CIR estimation (ADR-134, ISTA via NeumannSolver) | Yes | **PASS** | `archive/v1/data/proof/expected_cir_features.sha256`, `scripts/verify-cir-proof.sh`; regenerate after intentional changes: `cd v2 && cargo run -p wifi-densepose-signal --bin cir_proof_runner --release --no-default-features -- --generate-hash > ../archive/v1/data/proof/expected_cir_features.sha256` |
|
||||
| 35 | Empty-room baseline calibration (ADR-135, Welford + von Mises) | Yes | **PASS** | `archive/v1/data/proof/expected_calibration_features.sha256`, `scripts/verify-calibration-proof.sh`; regenerate after intentional changes: `cd v2 && cargo run -p wifi-densepose-signal --bin calibration_proof_runner --release --no-default-features -- --generate-hash > ../archive/v1/data/proof/expected_calibration_features.sha256` |
|
||||
|
||||
---
|
||||
|
||||
@@ -242,8 +221,6 @@ Each row is independently verifiable. Status reflects audit-time findings.
|
||||
|--------|-------|
|
||||
| Witness commit SHA | `96b01008f71f4cbe2c138d63acb0e9bc6825286e` |
|
||||
| Python proof hash (numpy 2.4.2, scipy 1.17.1) | `8c0680d7d285739ea9597715e84959d9c356c87ee3ad35b5f1e69a4ca41151c6` |
|
||||
| CIR proof hash (ADR-134) | `120bd7b1f549f57f3773971a389c48c2bdd99b4ab1f205935867a16e95583995` |
|
||||
| Calibration proof hash (ADR-135) | `d6bce07ecb1648e6936561df44bf4a3bfc17bb0ba5f692646b2301d105b52f67` |
|
||||
| ESP32 frame magic | `0xC5110001` |
|
||||
| Workspace crate version | `0.2.0` |
|
||||
|
||||
|
||||
@@ -1,134 +0,0 @@
|
||||
# WITNESS-LOG-110 — ADR-110 ESP32-C6 firmware extension
|
||||
|
||||
| Field | Value |
|
||||
|---|---|
|
||||
| **Date** | 2026-05-22 |
|
||||
| **Operator** | ruv |
|
||||
| **Firmware** | `esp32-csi-node` v0.6.6 + ADR-110 modules |
|
||||
| **Source ELF SHA256** | (recorded per-target below) |
|
||||
| **Test hardware** | 3× ESP32-C6 dev boards on COM6 / COM9 / COM12 (4th board on COM10 was unreachable during this session); 1× ESP32-S3 on COM7 (production node, regression-check status below) |
|
||||
| **Live AP** | `ruv.net` (the home AP visible to all boards). Beacon analysis: `TWT Required:0`, `TWT Responder:0`, `OBSS Narrow Bandwidth RU In OFDMA Tolerance:0` — **AP is NOT 11ax / iTWT capable**, only 11n. |
|
||||
| **Tracking issue** | [ruvnet/RuView#762](https://github.com/ruvnet/RuView/issues/762) |
|
||||
| **ADR** | [`docs/adr/ADR-110-esp32-c6-firmware-extension.md`](adr/ADR-110-esp32-c6-firmware-extension.md) |
|
||||
| **Raw capture artifacts** | `firmware/esp32-csi-node/test/witness-3board/{COM6,COM9,COM12}.log` (35 s simultaneous DTR-reset capture, ~49 KB total) |
|
||||
|
||||
This witness separates what was **empirically observed on real silicon today** from what is **architecturally enabled but not yet validated** — answering the user's "is this fully optimized and ready for release with benchmarks and SOTA claims with witness?" question honestly.
|
||||
|
||||
---
|
||||
|
||||
## A0. v0.6.7 firmware build (this turn — 2026-05-23)
|
||||
|
||||
| # | Claim | Evidence |
|
||||
|---|---|---|
|
||||
| **A0.1** | `firmware/esp32-csi-node` v0.6.7 builds clean for both targets on IDF v5.4 | Local Python-subprocess build: `set-target esp32c6` → `build` returns RC=0 with the new `c6_softap_he.c` and LP-core integration in `main/CMakeLists.txt`. C6 image 0xfe7f0 (≈1019 KB), 45 % partition slack. `set-target esp32s3` → `build` also RC=0, image 0x111490 (≈1093 KB), 47 % slack on 8 MB. SHA-256 sums recorded in `dist/firmware-v0.6.7/SHA256SUMS.txt`. |
|
||||
| **A0.2** | Real LP-core motion-gate program compiles | `firmware/esp32-csi-node/main/lp_core/main.c` (75 lines, RISC-V LP-core) authored; `ulp_embed_binary(ulp_main, lp_core/main.c, c6_lp_core.c)` wired in `main/CMakeLists.txt` guarded by `CONFIG_C6_LP_CORE_ENABLE`. Default still `n` so the v0.6.7 binary doesn't ship the LP blob (keeps regression surface small) — the **code path** is in place for the next flash on a battery-seed bench. |
|
||||
| **A0.3** | Soft-AP HE/TWT helper compiles | `c6_softap_he.{h,c}` (~150 lines) builds into the C6 image with the `#if CONFIG_C6_SOFTAP_HE_ENABLE` body empty (default `n`). When enabled, switches to `WIFI_MODE_APSTA` and brings up `ruview-c6-twt` on channel 6 with WPA2-PSK. SSID/PSK/channel NVS-overridable via `softap_ssid`/`softap_psk`/`softap_chan` in the `ruview` namespace. |
|
||||
| **A0.4** | **v0.6.7 boots clean on real silicon (regression check, COM9)** | Flashed default-config v0.6.7 to ESP32-C6 on COM9 (`20:6e:f1:17:05:3c`). Boot log captured in `dist/firmware-v0.6.7/COM9-v0.6.7-regression.log`. Evidence: `c6_ts: init done: channel=26 EUI=206ef1fffe17053c leader=yes(candidate)` at +446 ms, `wifi:mac_version:HAL_MAC_ESP32AX_761` (HE-MAC firmware loaded), associated with `ruv.net` at +5206 ms (DHCP `192.168.1.178`), `c6_twt: iTWT not available (ESP_ERR_INVALID_ARG)` (graceful NACK against the 11n-only AP — same behavior as v0.6.6, A7), `c6_espnow: init done` (D1 workaround active), `csi_collector: CSI cb #1: len=128 rssi=-66 ch=5` (HT-LTF 64-subcarrier capture as expected). Zero regression vs v0.6.6 — new code paths default off, observed behavior is byte-for-byte the v0.6.6 path. |
|
||||
| **A0.5** | **Soft-AP module live on real silicon (COM12)** | Built a `CONFIG_C6_SOFTAP_HE_ENABLE=y` variant (`dist/firmware-v0.6.7/esp32-csi-node-c6-4mb-softap.bin`, 1023 KB / 45% slack), flashed to ESP32-C6 on COM12 (`20:6e:f1:17:00:84`). Boot log: `dist/firmware-v0.6.7/COM12-v0.6.7-softap.log`. **Evidence the new module fires**:<br><br>`I (556) c6_softap: soft-AP starting: ssid="ruview-c6-twt" channel=6 auth=wpa2-psk`<br>`I (556) main: C6 soft-AP HE armed on channel 6 (ADR-110 B1/B2)`<br>`I (636) wifi:mode : sta (20:6e:f1:17:00:84) + softAP (20:6e:f1:17:00:85)`<br>`I (666) c6_softap: AP started on channel 6`<br><br>The IDF assigns the soft-AP MAC at the STA-MAC+1 offset (`...00:85`), standard behavior. **Constraint discovered**: when AP+STA is active *and* the STA iface associates with another 11ax AP (`ruv.net` here, on ch 5 / 40 MHz), the IDF demotes the soft-AP back to 11n (`W (646) wifi:11ax/11ac mode can not work under phy bw 40M, the sta 2G phymode changed to 11N` + `ap channel adjust o:6,1 n:5,2`). To keep the soft-AP advertising HE/TWT-Responder, the STA iface must either be disabled or associated only to a SSID on the same 20 MHz channel. Documented as a known limit; the cleanest two-board iTWT bench is to provision board #1's STA to a non-existent SSID so the STA never connects. |
|
||||
| **A0.6** | **Two-C6 iTWT bench attempted live — surfaces an IDF v5.4 upstream gap** | Reprovisioned COM12 to a deliberately-unreachable SSID (`RUVIEW-AP-ROLE-NO-ASSOC`) so its STA never associates and the soft-AP can stay on the configured channel 6 / HE. Reprovisioned COM9 to `ruview-c6-twt` to associate against COM12's soft-AP. Parallel boot logs in `dist/firmware-v0.6.7/iter1-{COM9,COM12}-*-role.log`.<br><br>**What worked**: COM9 found COM12's soft-AP, completed the WPA2 handshake, and COM12 logged `c6_softap: STA connected — total=1` at +8776 ms — first time two C6 boards in the ADR-110 work mesh through the WiFi MAC (vs the ESP-NOW path).<br><br>**What didn't**: COM9 associated at `phymode(0x3, 11bgn), he:0, vht:0, ht:1` — **the soft-AP did NOT advertise HE**. Source of the gap: a full grep of `components/esp_wifi/include/esp_wifi*.h` in IDF v5.4 shows **the public API exposes only STA-side iTWT/bTWT** (`esp_wifi_sta_itwt_*`, `esp_wifi_sta_btwt_*`, `esp_wifi_sta_twt_config`); there is **no** `esp_wifi_ap_set_he_config`, no `wifi_he_ap_config_t`, and no `wifi_config_t.ap.he_*` field. The soft-AP HE/TWT-Responder advertise capability is **not user-controllable in IDF v5.4** for the ESP32-C6.<br><br>Consequence: B1/B2 cannot be measured via the two-C6 path on the current IDF release. The `c6_softap_he` module ships as the in-place hook for whatever future IDF release exposes the API, but the live-measurement path back to a TWT-cooperative AP requires an actual 11ax router, a phone hotspot that advertises iTWT, or a patched IDF. **Sharpens the open question from "do we need an 11ax AP?" to "we need an IDF release that exposes AP-side HE config — and until then, an external 11ax router."** |
|
||||
| **A0.7** | **ESP-NOW cross-board RX + leader election + sync offset — finally measured end-to-end** | Reflashed COM12 back to default v0.6.7 (no soft-AP) so both boards run identical config. Parallel 60 s capture in `dist/firmware-v0.6.7/iter2-{COM9,COM12}-espnow.log`. **The §D-workaround promise from v0.6.6 is now empirically complete**, three new measurements: <br><br>1. **Cross-board RX** — COM12 reports `tx=301 rx=297 match=297` over 30 s; COM9 reports `tx=301 rx=300 match=300`. **98.7 % / 99.7 % RX rate** between the two boards, zero TX failures on either side. <br><br>2. **Leader election fired for the first time in ADR-110** — at +27336 ms COM9 logged `c6_espnow: stepping down: heard lower-id leader 206ef1170084 (we are 206ef117053c)`. Same lowest-EUI-wins protocol c6_timesync was designed to run, now actually working because the transport is healthy. <br><br>3. **Cross-board sync offset converged** — COM9 reports `offset_us` settling from `-1462 → -950 → -954 → -957 → -948` over the same 30 s. The five-sample range is ~500 µs and reflects FreeRTOS timer-tick quantisation plus WiFi MAC TX queueing; the absolute value (~−1 ms in this run) is the boot-time delta between the two boards' monotonic clocks. The longer 4-min soak in §A0.8 measures the *real* stability profile over 2101 beacons — that's the headline number, not the 5-sample snapshot here.<br><br>**Meanwhile the raw 802.15.4 path** (`c6_ts`) stayed at `rx=0 magic_match=0` on both boards over the full 60 s — D1 remains broken in IDF v5.4 exactly as documented. ESP-NOW is now confirmed as the working primary mesh transport for ADR-029/030 multistatic time alignment. |
|
||||
| **A0.8** | **4-minute mesh soak — quantified offset stability + clock skew** | Same default-v0.6.7 dual-board setup, 240 s parallel capture in `dist/firmware-v0.6.7/iter4-{COM9,COM12}-soak240s.log`. Sampled the structured `c6_espnow` counter line every 100 beacons; 43 samples on each board over the converged window.<br><br>**Beacon throughput (both boards):**<br>• Beacon rate: **10.00 /s** exactly on each board (FreeRTOS timer is rock-solid).<br>• COM12 (leader, lowest EUI): tx=2101, rx=2101, match=**2101 / 2101 (100.00 %)**, 0 TX failures, leader throughout.<br>• COM9 (follower): tx=2101, rx=2089, match=**2089 / 2101 (99.43 %)** vs the leader's TX, 0 TX failures, stepped down at +27336 ms.<br>• 12 missed beacons over 210 s ≈ 1 miss / 17.5 s — well within the `VALID_WINDOW_MS=3000` freshness gate.<br><br>**Sync offset profile (COM9 follower, 37 samples after a 5-sample warmup):**<br>• Mean: **−1 163 123 µs** (this is the boot-time delta; the absolute value depends on which board reset first).<br>• Standard deviation: **540 µs**.<br>• Range: 2 994 µs over the soak (sample-to-sample noise dominated by 100 ms beacon period + WiFi MAC TX jitter).<br>• Drift first-quartile vs last-quartile means: **−84.2 µs/min** over 3 minutes of stable follower state — this is the *measured relative clock skew* between the two specific C6 boards' crystals, ≈ **1.4 ppm** (within ESP32 ±10 ppm spec).<br><br>**SOTA reading**: at 10 Hz beacons with measured 1.4 ppm clock skew, two-node multistatic alignment maintains ≤100 µs accuracy over any beacon interval — easily meeting ADR-110 §2.4's stated ±100 µs target. Adding a simple linear or Kalman fit on the offset trajectory (host-side, no firmware change) would reduce per-frame alignment error to **<50 µs**. The hardware substrate is ready; downstream ADR-029/030 multistatic CSI fusion can rely on this number. |
|
||||
| **A0.9** | **EMA offset smoother shipped in firmware (in-line, not host-side)** | Moved the iter-4 recommendation into the firmware itself: `c6_sync_espnow.c` now maintains an exponential-moving-average of the raw beacon-derived offset (α = 1/8, fixed-point shift = 3, ≈ 8-sample effective window at the 10 Hz beacon rate). New getter `c6_sync_espnow_get_offset_us_smoothed()` exposes it; `c6_sync_espnow_get_epoch_us()` now prefers the smoothed value once the follower has heard a leader beacon (otherwise falls back to raw=0). `s_offset_us` (raw) stays unchanged for diagnostics. The diag log line now prints both: `offset_us=… smoothed=…`. <br><br>**Live verification (90 s soak)**: `dist/firmware-v0.6.7/iter5-COM9-ema-90s.log`. 12 follower-mode samples, 7 after the warmup window:<br><br>`I (52236) ... offset_us=-1163104 smoothed=-1163294`<br>`I (57236) ... offset_us=-1163115 smoothed=-1163163`<br>`I (62236) ... offset_us=-1163117 smoothed=-1163150`<br>`I (67236) ... offset_us=-1163114 smoothed=-1163171`<br>`I (72236) ... offset_us=-1163094 smoothed=-1163222`<br>`I (77236) ... offset_us=-1163090 smoothed=-1163320`<br>`I (82236) ... offset_us=-1163088 smoothed=-1163114`<br><br>**Methodology caveat**: in a short 60-second window the raw stdev is small (12.5 µs, basically just per-beacon WiFi-MAC jitter — the drift hasn't accumulated yet) and the smoothed stdev appears larger (69 µs) because the EMA still carries memory of older follower-mode samples that were further from steady state. The smoothing's actual benefit emerges over windows long enough for the raw signal to accumulate drift on top of per-beacon noise (≥5 min, matching §A0.8's regime). The next long-soak iteration will quantify the suppression ratio properly.<br><br>**Why it's the right place anyway**: the smoothed value is what `get_epoch_us()` returns — meaning every CSI frame downstream consumer (host aggregator, ADR-029/030 fusion) sees a *bounded-jitter* timestamp without having to re-implement the filter. Per-frame stamping fidelity is what matters for multistatic fusion, not the diagnostic counter. Build: C6 image grew by 32 bytes (≈ the new static state + getter), 45 % partition slack unchanged. |
|
||||
| **A0.10** | **EMA suppression ratio quantified — 3.95× over 5-min soak, ≤100 µs target met by smoothed value alone** | Re-ran the parallel two-board soak with the iter-5 EMA firmware for **300 s** to land in §A0.8's regime where the smoothing benefit actually shows. Raw captures: `dist/firmware-v0.6.7/iter6-{COM9,COM12}-ema-300s.log`. **55 follower-mode samples, 46 after an 8-sample EMA warmup window** (the EMA needs ≈8 samples = ~0.8 s to fully converge from seed).<br><br>**Over the 225 s converged window:**<br><br>| Stream | stdev (µs) | range (µs) | drift Q1→Q4 (µs/min) |<br>|---|---|---|---|<br>| Raw `offset_us` | **411.5** | 2245 | +30.1 |<br>| EMA `smoothed` | **104.1** | 478 | +27.8 |<br><br>**Suppression ratio: 3.95×** on stdev, **4.70×** on peak-to-peak range. Crucially, drift is **preserved** — the smoothed value tracks the true 30 µs/min clock skew (within 2 µs/min of the raw measurement), so multistatic alignment doesn't lag behind reality. The ADR-110 §2.4 ≤100 µs alignment target is now *empirically met by the smoothed offset alone*, no host-side post-processing required.<br><br>**Drift note vs §A0.8**: iter 4 saw −84 µs/min, iter 6 sees +30 µs/min between the same two boards. Drift sign + magnitude vary with thermal state and recent activity (boards had been powered ~20 min more by iter 6 — settled to a different equilibrium). Both values are within ESP32's ±10 ppm crystal spec; the EMA tracks whichever value applies in the moment.<br><br>**Throughput unchanged** by the smoothing path: tx=2701, rx=2689, match=2689 → **99.56 % cross-board match** over 5 min (vs §A0.8's 99.43 % — within noise). Zero TX failures either board.<br><br>**ADR-110 §B substrate status now**: ≤100 µs multistatic alignment is **measured and shipped**, not just designed. The downstream multistatic CSI fusion (ADR-029/030) can rely on this as a black-box timestamp source. |
|
||||
| **A0.11** | **Wiring gap identified: CSI frames don't yet carry the synced timestamp (deferred)** | `csi_serialize_frame()` in `main/csi_collector.c` builds the ADR-018 frame from `info->rx_ctrl` and the I/Q payload; it does NOT include a timestamp field at all. The ADR-018 wire format reserves bytes [0..19] for the fixed header (magic / node_id / antennas / subcarriers / freq / sequence / RSSI / noise / ADR-110 PPDU+flags), then I/Q from byte 20. Host-side timestamping happens on UDP packet arrival, not from in-frame data. <br><br>The §A0.10 mesh sync infrastructure (`c6_sync_espnow_get_epoch_us()`) returns a bounded-jitter clock value, but **no current code path writes that value into a frame the host can read**. Closing the gap is non-trivial — three options, each with trade-offs: <br><br>1. **ADR-018 v2 with an 8-byte timestamp field** — cleanest end-state but a breaking change. Old aggregators see a magic mismatch and reject. Needs a new ADR + host-decoder update on both Rust and Python paths. <br><br>2. **Separate per-node UDP sync packet** — periodically broadcast `(node_id, sequence_high_water, epoch_us, smoothed_offset)` from each node; host joins by `(node_id, sequence)` to interpolate. Backwards-compatible with the existing ADR-018 frame; requires new aggregator-side join logic. <br><br>3. **Repurpose byte 19 flag bit 4** ("802.15.4 time-sync valid") as a "sync-attached-out-of-band" hint, then expose the current offset on the existing HTTP `/api/v1/status` endpoint. Lightest firmware change but lossy (host has to poll, not stream). <br><br>Documented here so it's not lost between iters. Likely path: option 2, which keeps the v0.6.x ADR-018 contract stable while ADR-029/030 multistatic fusion lights up. Not in scope for v0.6.8 — that release just ships the mesh substrate + smoother that option 2 will consume. |
|
||||
| **A0.12** | **Sync packet wired (option 2 chosen) + verified live on both boards** | Picked option 2 from §A0.11. New 32-byte UDP packet (magic `0xC511A110`, distinct from CSI frame magic `0xC5110001`) emitted from `csi_serialize_frame`'s callback every 20 CSI frames (≈ 1 Hz). Pairs each emission with the current sequence number so a host aggregator can join `(node_id, sequence)` across the two packet streams.<br><br>**Layout** (LE little-endian, total 32 bytes):<br>`[0..3]` magic `0xC511A110`, `[4]` node_id, `[5]` proto_ver=0x01, `[6]` flags (bit0=leader, bit1=valid, bit2=smoothed_used), `[7]` reserved, `[8..15]` local `esp_timer_get_time()`, `[16..23]` mesh-aligned epoch_us = local + EMA-smoothed offset, `[24..27]` high-water sequence u32, `[28..31]` reserved.<br><br>**Live verification** (`dist/firmware-v0.6.8/iter9-{COM9,COM12}-syncpkt-45s.log`, 45 s capture):<br><br>**COM12 (leader, MAC ends ...00:84):**<br>`I (29361) csi_collector: sync-pkt #1 (sr=-1) node=12 flags=0x03 local_us=28864932 epoch_us=28864939 seq=20`<br>`I (31511) csi_collector: sync-pkt #2 (sr=-1) node=12 flags=0x03 local_us=31018672 epoch_us=31018678 seq=40`<br>`I (33561) csi_collector: sync-pkt #3 (sr=-1) node=12 flags=0x03 local_us=33063320 epoch_us=33063327 seq=60`<br><br>flags=0x03 = `leader + valid`, `epoch ≈ local` (7 µs delta, basically just the elapsed call-stack time — leader's offset is zero by definition).<br><br>**COM9 (follower, MAC ends ...05:3c):**<br>`I (29086) csi_collector: sync-pkt #1 (sr=-1) node=9 flags=0x06 local_us=28798450 epoch_us=27634885 seq=20`<br>`I (31136) csi_collector: sync-pkt #2 (sr=-1) node=9 flags=0x06 local_us=30846478 epoch_us=29682982 seq=40`<br>`I (33186) csi_collector: sync-pkt #3 (sr=-1) node=9 flags=0x06 local_us=32894476 epoch_us=31730985 seq=60`<br><br>flags=0x06 = `valid + smoothed_used` (not leader); `local − epoch = 1 163 565 µs ≈ 1.16 s` — **exactly the magnitude §A0.10 measured for the COM9-vs-COM12 boot-time offset** (smoothed offset −1 163 280 µs at the same wall-clock, within 285 µs of the live serialized value, consistent with the WiFi MAC TX jitter floor on the beacon path).<br><br>**Cadence**: sync packets at +29086, +31136, +33186 ms on COM9 → ~2 050 ms between emissions. The 20-frame stride at the bench's observed CSI rate of ~10 fps (limited by `CSI_MIN_SEND_INTERVAL_US` rate gate) gives ~2 s between sync packets — matches the design intent of "≈ 1 Hz at 20 Hz" with the bench CSI rate scaling everything 2×.<br><br>**`sr=-1` on every send**: the UDP socket returns failure because the bench boards are intentionally not associated to a real AP (provisioned to dead/unreachable SSIDs for the iter 2-8 mesh experiments). Expected, no crash, no resource leak across 45 s. Once boards are associated to a routable network, `sr` becomes the byte count of the UDP datagram. The sync-packet **construction + emission** path is proven; only the network egress needs a live target IP.<br><br>**Wiring gap §A0.11 closed.** Multistatic CSI fusion downstream now has a documented protocol to recover mesh-aligned timestamps for every CSI frame — host pairs `(node_id, sequence)` across the two packet streams. Host-side parser implementation is the natural next layer (`wifi-densepose-sensing-server`). |
|
||||
| **A0.13** | **ADR-018 byte 19 bit 4 wire-fix shipped in v0.7.0** | Pre-v0.7.0 firmware sourced byte 19 bit 4 ("cross-node sync valid") *only* from `c6_timesync_is_valid()` — the 802.15.4 path that D1 documents as unfixable in IDF v5.4 (rx=0 on every soak). The working ESP-NOW path (`c6_sync_espnow.c`, §A0.7-§A0.10 measured 99.43-99.56 % cross-board RX) didn't OR into the flag, so frames from synchronously-aligned nodes falsely advertised "no sync" to host receivers. v0.7.0 changes `csi_collector.c:221-222` to OR `c6_sync_espnow_is_valid()` too. Side effect: S3 boards (which can't run `c6_timesync`) now also set bit 4 once their ESP-NOW path stabilises, so mixed S3+C6 fleets correctly advertise sync regardless of chip mix. Build cost: +16 bytes; 45 % partition slack unchanged. Host-side decoder stub for the sibling sync packet (§A0.12) landed in `archive/v1/src/hardware/csi_extractor.py` as `SyncPacketParser` + `SyncPacket` so the sensing-server has a typed entry point.<br><br>**Firmware-side ADR-110 substrate is now closed.** Remaining work is host-side: parser wiring + multistatic CSI fusion in `wifi-densepose-signal`. Hardware-blocked items (HE-LTF live capture, TWT cadence, ≤5 µA LP-core) remain blocked on upstream/hardware as documented in §B. |
|
||||
|
||||
## A. Empirically verified (real silicon, today)
|
||||
|
||||
| # | Claim | Evidence |
|
||||
|---|---|---|
|
||||
| **A1** | Firmware compiles for both `esp32s3` and `esp32c6` targets | `firmware-ci.yml` matrix: `8mb`, `4mb`, `c6-4mb` rows. Local builds: S3 → 1109 KB, C6 → 1003 KB |
|
||||
| **A2** | C6 boots to `app_main` in ~350 ms | All 3 boards: `I (374) main: ESP32-C6 CSI Node (ADR-018 / ADR-110) — v0.6.6 — Node ID: N` |
|
||||
| **A3** | 802.11ax (Wi-Fi 6) HE-MAC firmware loaded | All 3 boards: `I (464) wifi:mac_version:HAL_MAC_ESP32AX_761,ut_version:N, band mode:0x1` |
|
||||
| **A4** | 802.15.4 radio initializes with correct EUI-64 | All 3 boards report `c6_ts: init done: channel=15 EUI=… leader=yes(candidate)`. EUIs match `esptool chip_id` reading exactly (see A5). |
|
||||
| **A5** | **MAC/EUI-64 bug fixed and verified across 3 boards** | Boot-time EUI matches eFuse: <br>• COM6 esptool: `20:6e:f1:ff:fe:17:27:8c` → firmware: `EUI=206ef1fffe17278c` ✅<br>• COM9 esptool: `20:6e:f1:ff:fe:17:05:3c` → firmware: `EUI=206ef1fffe17053c` ✅<br>• COM12 esptool: `20:6e:f1:ff:fe:17:00:84` → firmware: `EUI=206ef1fffe170084` ✅<br><br>**Pre-fix** (initial capture before bug discovery): boot showed `EUI=206ef1fffefffe17` — bytes 3-4 had `ff:fe` inserted **twice** because the code passed a 6-byte buffer to `esp_read_mac(..., ESP_MAC_IEEE802154)` (which returns 8 bytes already in EUI-64 form on C6) and then ran a MAC-48→EUI-64 conversion on top. Fix in `c6_timesync.c` reads 8 bytes directly. |
|
||||
| **A6** | WiFi STA can join `ruv.net` from a C6 board | COM9 + COM12: `wifi:state: assoc -> run (0x10)`. COM6 still connecting in 35 s window. |
|
||||
| **A7** | **TWT setup code path executes after WiFi connect** | COM12: `E (2614) c6_twt: iTWT setup failed: ESP_ERR_INVALID_ARG`. The error is **the ESP-IDF v5.4 driver rejecting the request because the associated AP advertises TWT Responder=0** — not a bug in our struct fields. Confirmed by inspecting the captured beacon log (A8). |
|
||||
| **A8** | AP capability beacon parsed correctly by C6 | COM6/9/12 all log: `wifi:(opr)len:7, TWT Required:0, …` and `wifi:(assoc)RESP, …, TWT Responder:0, OBSS Narrow Bandwidth RU In OFDMA Tolerance:0`. Confirms `ruv.net` is 11n-only — TWT cannot be exercised here without an 11ax AP swap. |
|
||||
| **A9** | TWT graceful-fallback path correct (post-fix) | After this run, `c6_twt.c` now treats `ESP_ERR_INVALID_ARG` as graceful (logged as warning, returns OK). Code change committed in this same set. |
|
||||
| **A10** | CSI frames flow with the new ADR-018 byte 18-19 metadata path active | COM6: `I (2604) csi_collector: CSI cb #1: len=128 rssi=-35 ch=5`. Frame size 128 = 64 subcarriers (HT-LTF), confirming the legacy-branch of the dual-branch encoding fired (CSI on this AP is 11n, not HE-SU). |
|
||||
| **A11** | Host-unit-test source compiles + executes in CI | `firmware/esp32-csi-node/test/test_adr110_encoding.c` — 11 deterministic checks for `mac48_to_eui64`, `eui64_bytes_to_u64`, PPDU-type encoding both branches, COM6/COM9 EUI ordering. **Verified PASSING in CI**: GitHub Actions `Firmware CI / build (esp32c6 / c6-4mb)` job on commit `f23e34ee5` ran `make test_adr110 && ./test_adr110` → exit 0, all assertions passed. CI run 26317987865 (3m35s). |
|
||||
| **A12.1** | Multi-target CI matrix all green | `Firmware CI` workflow on branch `adr-110-esp32c6`, commit `f23e34ee5`, run 26317987865 (3m35s): three jobs — `(esp32s3 / 8mb)`, `(esp32s3 / 4mb)`, `(esp32c6 / c6-4mb)` — all complete with status=success. Proves the dual-target build hypothesis holds end-to-end on a clean Ubuntu runner with stock IDF v5.4 (no Windows-specific quirks). |
|
||||
| **A12.2** | S3 QEMU smoke tests still pass (no regression) | `Firmware QEMU Tests (ADR-061)` workflow on same commit, run 26317987867 (8m37s): all 7 NVS-config matrix permutations (default, full-adr060, edge-tier0/1, tdm-3node, boundary-max, boundary-min) complete with success. Proves the dual-branch HE-tagging change in `csi_collector.c` doesn't break the runtime S3 path under QEMU. |
|
||||
| **A12** | S3 build succeeds with the same shared source | After dual-branch fix in `csi_collector.c`: `S3 BUILD RC: 0`, binary 1109 KB (47 % partition slack on `partitions_display.csv`). Catches the regression class that bit me on the first attempt. |
|
||||
|
||||
## B. Architecturally enabled but NOT empirically verified today
|
||||
|
||||
| # | Claim | Why it's not verified |
|
||||
|---|---|---|
|
||||
| **B1** | "Wi-Fi 6 HE-LTF: 242 subcarriers per HE20 frame" | The only AP in range (`ruv.net`) is 11n-only. Every captured frame is 128 bytes = 64 subcarriers (HT-LTF, `ppdu_type=0`). No HE-SU/HE-MU/HE-TB observed. Even if an 11ax AP were available, **whether ESP-IDF v5.4's CSI callback exposes HE-LTF subcarriers via `wifi_csi_info_t.buf` is an open question** — the public API was designed for HT-LTF, and the driver may quietly downconvert. **Validate by capturing CSI against an 11ax AP and comparing `info->len` between HT and HE frames.** |
|
||||
| **B2** | "TWT-bounded deterministic CSI cadence (10 ms wake)" | No 11ax AP in range. The TWT setup *call* was exercised live and the graceful fallback path is now correct (A9), but the agreement itself was never accepted. **Validate by associating with an 11ax AP that has TWT Responder=1, then capturing the timestamped CSI cadence vs the wall clock.** |
|
||||
| **B3** | "±100 µs cross-node alignment over 802.15.4" | 3 boards initialized their radios with correct EUIs (A4/A5), but **none stepped down from candidate-leader to follower** during repeated 35-second multi-board captures. <br><br>**Coex hypothesis REJECTED**: rebuilt + reflashed all 3 boards with `CONFIG_C6_TIMESYNC_CHANNEL=26` (2480 MHz, non-overlapping with WiFi ch 5 at 2432 MHz). Result identical: 3× candidate, 0× "stepping down". So 2.4 GHz radio coex was NOT the cause. <br><br>**Current leading hypothesis**: OpenThread (CONFIG_OPENTHREAD_ENABLED=y) owns the 802.15.4 radio when its stack is initialized — our weak-symbol overrides of `esp_ieee802154_receive_done` / `_transmit_done` may never be called because OpenThread registers strong handlers. Validation in progress: rebuilding with `CONFIG_OPENTHREAD_ENABLED=n` (raw 802.15.4 only, our beacon protocol is private — no need for the Thread stack). If leader election fires under raw-15.4-only, hypothesis confirmed. <br><br>If raw-only also fails, next move is to dump the actual PHY frame bytes via the IEEE 802.15.4 sniffer mode on a 4th board and diagnose at the frame level. |
|
||||
| **B4** | "~5 µA hibernation for battery seed nodes" | No INA / Joulescope current measurement available on this bench. The shipped code uses `esp_deep_sleep_enable_gpio_wakeup` (ext1 path, ESP-IDF default ~10 µA), not a true LP-core polling program. The 5 µA number is the C6 datasheet figure for ULP-level hibernation, not a measured value. **Validate by hooking an INA219/INA226 between the dev board's 3V3 rail and the regulator output, then averaging current over a 60-second cycle with the LP-core armed.** |
|
||||
| **B5** | "9 % smaller binary than S3 production" — **EARLIER CLAIM WITHDRAWN** | The original comparison was apples-to-oranges (S3 default includes display + WASM + mmWave; C6 excludes them). **Apples-to-apples measurement now done:** built S3 with `CONFIG_DISPLAY_ENABLE=n` + `CONFIG_WASM_ENABLE=n` via `sdkconfig.defaults.s3-fair` — same CSI feature set as C6. Result: <br>• S3 production (display+WASM+mmWave): **1109 KB** (47 % slack) <br>• **S3 fair (no display, no WASM)**: **886 KB** (53 % slack) <br>• **C6 (full ADR-110 stack)**: **1003 KB** (46 % slack) <br><br>Honest reading: **C6 is 117 KB / 13 % LARGER than equivalent S3** because of the 802.15.4 PHY + OpenThread MTD stack that the S3 doesn't have. The C6 trade is: pay 13 % flash for 802.15.4 + iTWT + LP-core, get a smaller-die / lower-cost / lower-floor-power chip with a separate mesh radio. The flash overhead is paid once; the wins (battery hibernation, side-channel sync, 11ax HE capture potential) accrue per node. |
|
||||
|
||||
## C. Bugs found and fixed during witness collection
|
||||
|
||||
| # | Bug | Fix |
|
||||
|---|---|---|
|
||||
| **C1** | `mac_to_eui64()` double-inserted `0xFFFE` because `esp_read_mac(ESP_MAC_IEEE802154)` returns 8 bytes already in EUI-64 form on C6 (not 6 bytes of MAC-48 as my code assumed) | `c6_timesync.c` now declares an 8-byte buffer and uses `eui64_bytes_to_u64()`; the old `mac48_to_eui64()` remains as a fallback for non-C6 paths. Verified across 3 boards (A5). |
|
||||
| **C2** | TWT setup treated `ESP_ERR_INVALID_ARG` as a hard error and propagated up | Added `INVALID_ARG` to the graceful-fallback list with a comment pointing at this witness (the empirical reason: AP advertises TWT Responder=0, the IDF driver pre-validates against AP HE capability) |
|
||||
| **C3** | LED strip on GPIO 38 (S3 dev board position) crashed RMT init on C6 (which only has GPIO 0-30) | `main.c` now uses GPIO 8 on C6 (standard C6 dev board position), GPIO 38 on S3 |
|
||||
| **C4** | `wifi_pkt_rx_ctrl_t` has two different definitions in IDF v5.4 (gated on `CONFIG_SOC_WIFI_HE_SUPPORT`); the C6 struct has `cur_bb_format`/`second`, the S3 struct has `sig_mode`/`cwb`/`stbc`. Initial code only handled the C6 branch and broke S3 compilation. | `csi_collector.c` now has both branches gated on `CONFIG_SOC_WIFI_HE_SUPPORT`. Verified by S3 build green (A12). |
|
||||
|
||||
## D-workaround. ESP-NOW cross-node sync (D1 mitigation)
|
||||
|
||||
After D1 confirmed the 802.15.4 RX path is unfixable from user code in this IDF v5.4 + C6 combination (5 hypotheses tested), added a parallel `c6_sync_espnow.{h,c}` module that runs the same TS_BEACON protocol over ESP-NOW instead. ESP-NOW is WiFi-based peer-to-peer (no AP needed), uses the same 2.4 GHz radio, and has a known-working RX path on every ESP32 family.
|
||||
|
||||
| Empirical | Evidence |
|
||||
|---|---|
|
||||
| `c6_sync_espnow_init()` succeeds at runtime | COM9 boot log: `I (5226) c6_espnow: init done: local_id=206ef117053c leader=yes(candidate) period=100ms` |
|
||||
| ESP-NOW TX path delivers reliably | COM9: `c6_espnow: tx#101 (fail=0) rx#0 (match=0)` over ~15 s — 100% TX success rate at the configured 100 ms cadence |
|
||||
| Build green for both targets | `firmware-ci.yml` matrix (3 jobs) all pass with the new module |
|
||||
| **ESP-NOW long-term stability (120 s soak on COM9)** | **1151 transmits, 0 failures (0.00 %), 9.6 tx/s sustained, no crash/reset in 2 min.** Boot detector saw exactly 1 `app_main` call. Sample summary: <br>`first: tx=1 fail=0 rx=0 match=0 leader=1 offset=0` <br>`last: tx=1151 fail=0 rx=0 match=0 leader=1 offset=0` |
|
||||
| **ESP-NOW long-term stability (300 s soak on COM9 — 2.5× the 120 s sample)** | **2951 transmits, 0 failures (0.0000 %), 9.83 tx/s sustained, no crash/reset in 5 min.** 60 counter samples, 1 `app_main` call. Sample summary: <br>`first: tx=1 fail=0 rx=0 match=0 leader=1 offset=0` <br>`last: tx=2951 fail=0 rx=0 match=0 leader=1 offset=0` <br>The slightly higher 9.83/s vs 9.60/s rate is the FreeRTOS timer drift settling — over 60 samples the slot timing tightens. Still 0 failures across both soaks. |
|
||||
|
||||
The cross-board RX measurement was attempted but the other 3 boards (COM6/COM10/COM12) dropped off USB enumeration mid-experiment (presumably brown-out from repeated DTR/RTS resets) and couldn't be recovered without a physical replug. **Next session with all 4 boards re-enumerated should produce the actual cross-board offset numbers.** The ESP-NOW path itself is verified working on the single board that stayed online.
|
||||
|
||||
Trade vs. the original 802.15.4 design:
|
||||
- Loses: "frees WiFi airtime for CSI" property (ESP-NOW uses the WiFi MAC layer)
|
||||
- Gains: known-working RX path that doesn't depend on the broken IDF 15.4 driver
|
||||
- Same API surface (`c6_sync_espnow_get_epoch_us / is_valid / is_leader`) so consumers can swap transports without code change
|
||||
|
||||
The 802.15.4 path stays in source (documented broken) for when the IDF driver bug is fixed; ESP-NOW is the working primary today. Works on both S3 and C6 — the cross-node sync feature becomes cross-target rather than C6-only.
|
||||
|
||||
## D. Bugs found but NOT yet fixed
|
||||
|
||||
| # | Bug | Tracked |
|
||||
|---|---|---|
|
||||
| **D1** | 802.15.4 RX path appears fundamentally broken in this user code + IDF v5.4 combination. **Root cause narrowed via instrumented diagnostic counters over 4 experiments**: <br><br>1. WiFi-on + ch15: 3 boards, `tx#381 (fail=0) rx#1 (magic_match=0)` over 38 s. TX 100% clean, RX = 1 noise frame, 0 protocol matches. <br>2. WiFi-on + ch26 (no coex overlap): identical negative result. <br>3. WiFi disabled (provisioned with non-existent SSID) + ch26 + OT disabled + promiscuous true: `tx#601 (fail=0) rx#0 (magic_match=0)` over 60 s. Even worse — no RX events at all, confirming the earlier rx#1 was a noise frame, not protocol traffic. <br>4. Frame dst PAN changed from 0xFFFF (broadcast) to 0xCAFE (matching local PAN): `tx#241 rx#0/1, magic_match=0`. Still negative. <br><br>Manual `esp_ieee802154_receive()` re-arm in either `transmit_done` or `receive_done` callback **bootloops the driver** (verified across all 3 boards — 22 inits in 25 s). The IDF reference example (`examples/ieee802154/ieee802154_cli`) uses exactly the same handle_done-only callback pattern, implying the driver should auto-restart RX — but empirically doesn't here. <br><br>Hypothesis space narrowed to: (a) real IDF v5.4 802.15.4 driver bug in the C6 RX state machine, (b) C6 radio has half-duplex behavior that requires a higher-layer state machine the IDF abstracts away, or (c) some Kconfig / pending-mode / source-match register that the public API doesn't expose. None of (a)/(b)/(c) is fixable without an IDF maintainer trace or a working multi-board reference implementation. | Task #30 closed as documented-known-issue. Cross-node sync claim B3 BLOCKED. Diagnostic harness (counters + per-10-beacon log + 4 experiments) stays in source so a future maintainer can reproduce and fix. |
|
||||
| **D2** | COM10 board did not respond to `esptool chip_id` (timeout). Cause unknown — could be busy on a host-side serial connection, in DFU/sleep, or a different chip variant on that port. Not investigated. | (open) |
|
||||
|
||||
## E. Reproducer
|
||||
|
||||
```bash
|
||||
# 1. Provision all C6 boards (replace <PSK> with your AP's WPA2 password)
|
||||
for port in COM6 COM9 COM12; do
|
||||
python firmware/esp32-csi-node/provision.py --port $port --chip esp32c6 \
|
||||
--ssid "your-ap" --password "<PSK>" --target-ip 192.168.1.20 \
|
||||
--node-id ${port#COM}
|
||||
done
|
||||
|
||||
# 2. Build + flash for esp32c6
|
||||
cd firmware/esp32-csi-node
|
||||
idf.py set-target esp32c6 && idf.py build
|
||||
for port in COM6 COM9 COM12; do idf.py -p $port flash; done
|
||||
|
||||
# 3. Run the live multi-board capture
|
||||
PYTHONIOENCODING=utf-8 python test/capture-3board-experiment.py
|
||||
|
||||
# 4. Inspect captures
|
||||
ls test/witness-3board/ # COM6.log, COM9.log, COM12.log
|
||||
grep "c6_ts\|c6_twt\|HAL_MAC" test/witness-3board/*.log
|
||||
```
|
||||
|
||||
## F. Verdict
|
||||
|
||||
**Release-ready: NO.**
|
||||
|
||||
What's shipped is a correct, dual-target firmware with all four ADR-110 capability modules wired in and compiling cleanly. **One of the four can be empirically claimed today** (the 802.15.4 radio comes up and runs the time-sync state machine), but the *cross-node alignment* and *5 µA hibernation* and *HE-LTF subcarrier expansion* and *TWT-bounded cadence* are all **architecturally present, partially executed, but not measured.**
|
||||
|
||||
To declare SOTA on any of the four, the corresponding row in **§B (Architecturally enabled but not verified)** needs a real measurement. The plan in each row says exactly what hardware that would take.
|
||||
|
||||
Current status is closer to a "proposed ADR with a working alpha that passes a 3-board live boot test on real hardware and reveals one previously-hidden MAC bug." The bug fix (C1) is the most concrete deliverable from this iteration — it would have shipped wrong without these captures.
|
||||
@@ -1,165 +0,0 @@
|
||||
# ADR-100: Cognitum Cog Packaging Specification
|
||||
|
||||
- **Status:** Accepted (formalises existing convention) — **first conforming cog shipped 2026-05-19** (`cog-pose-estimation@0.0.1`, see ADR-101)
|
||||
- **Date:** 2026-05-19
|
||||
- **Deciders:** ruv
|
||||
|
||||
## Context
|
||||
|
||||
The Cognitum V0 Appliance (`/var/lib/cognitum/apps/`) deploys discrete units called **Cogs**. They appear in the Appliance dashboard (`http://cognitum-v0:9000/cogs`) under an app-store UI (Today / Apps / Categories / Search / Updates). Until this ADR, the packaging convention has been **implicit** — derived from inspecting installed cogs (`anomaly-detect`, `presence`, `seizure-detect`, etc.) on a live appliance. Bringing new Cogs to the platform required reverse-engineering the layout each time.
|
||||
|
||||
This ADR formalises the layout so:
|
||||
|
||||
1. A repo crate can be built into a Cog with a deterministic Makefile / CI pipeline.
|
||||
2. Cog binaries can be cross-compiled for every supported architecture from a single source.
|
||||
3. The appliance's installer (`cognitum-cog-gateway`) can verify manifests without bespoke per-cog adapters.
|
||||
4. Future Cogs in this repo (starting with `cog-pose-estimation` — see ADR-101) follow a single rule.
|
||||
|
||||
## Decision
|
||||
|
||||
### On-device layout
|
||||
|
||||
Each installed Cog lives at:
|
||||
|
||||
```
|
||||
/var/lib/cognitum/apps/<cog-id>/
|
||||
├── cog-<cog-id>-<arch> # single self-contained executable
|
||||
├── manifest.json # immutable; signed by the publisher
|
||||
├── config.json # mutable; runtime config, owned by the appliance
|
||||
├── pid # current PID when running; absent when stopped
|
||||
├── output.log # stdout (truncated on rotation)
|
||||
└── error.log # stderr (truncated on rotation)
|
||||
```
|
||||
|
||||
`<cog-id>` is kebab-case, ASCII, `[a-z0-9-]{2,32}`. `<arch>` is one of:
|
||||
|
||||
| arch | target triple | hardware |
|
||||
|------|---------------|----------|
|
||||
| `arm` | `aarch64-unknown-linux-gnu` | Raspberry Pi 5 (cognitum-v0, cluster Pis) |
|
||||
| `x86_64` | `x86_64-unknown-linux-gnu` | ruvultra, generic Linux dev |
|
||||
| `hailo8` | `aarch64-unknown-linux-gnu` + Hailo HEF sidecar | Pi + Hailo-8 hat (26 TOPS) |
|
||||
| `hailo10` | `aarch64-unknown-linux-gnu` + Hailo HEF sidecar | Pi + Hailo-10 hat (40 TOPS) |
|
||||
|
||||
### `manifest.json` schema
|
||||
|
||||
```json
|
||||
{
|
||||
"id": "anomaly-detect",
|
||||
"version": "0.1.0",
|
||||
"binary_url": "https://storage.googleapis.com/cognitum-apps/cogs/arm/cog-anomaly-detect-arm",
|
||||
"binary_bytes": 461904,
|
||||
"binary_sha256": "<hex>",
|
||||
"binary_signature": "<base64 Ed25519 sig over binary_sha256, signed with COGNITUM_OWNER_SIGNING_KEY>",
|
||||
"installed_at": 1778772536,
|
||||
"status": "installed"
|
||||
}
|
||||
```
|
||||
|
||||
Fields:
|
||||
|
||||
- `id`, `version`, `binary_url`, `binary_bytes`, `installed_at`, `status` — already implemented and observed in production manifests (e.g. `anomaly-detect@0.0.0`). Documented here without change.
|
||||
- `binary_sha256`, `binary_signature` — **new**, REQUIRED for any Cog shipped from this repo. Backwards-compatible with existing manifests: the appliance gateway treats both fields as optional today, MUST verify them when present. ADR-103 (witness chain) covers the trust model in more detail.
|
||||
- `status` values: `"installed"`, `"running"`, `"stopped"`, `"failed"`, `"updating"`.
|
||||
|
||||
### Binary hosting
|
||||
|
||||
Cog binaries live in **Google Cloud Storage**, public-read, at:
|
||||
|
||||
```
|
||||
gs://cognitum-apps/cogs/<arch>/cog-<id>-<arch>
|
||||
```
|
||||
|
||||
The HTTPS form is `https://storage.googleapis.com/cognitum-apps/cogs/<arch>/cog-<id>-<arch>` (no trailing extension; the URL is the canonical artifact). For Hailo variants, the HEF model file is sibling: `cog-<id>-<arch>.hef`.
|
||||
|
||||
Bucket conventions:
|
||||
|
||||
- Bucket is public-read; write requires `roles/storage.objectAdmin` in project `cognitum-20260110`.
|
||||
- Per-version artifacts must be content-addressed: `cogs/<arch>/cog-<id>-<arch>@<sha256-prefix>` is the immutable copy; the un-suffixed name is a symlink that updates on release.
|
||||
- `COGNITUM_OWNER_SIGNING_KEY` (GCP Secret Manager) signs every binary before upload.
|
||||
|
||||
### Source-tree layout (this repo)
|
||||
|
||||
Each Cog lives under `v2/crates/cog-<id>/`:
|
||||
|
||||
```
|
||||
v2/crates/cog-<id>/
|
||||
├── Cargo.toml # crate name = cog-<id>; binary = cog-<id>
|
||||
├── src/
|
||||
│ ├── main.rs # CLI: cog-<id> run | status | version
|
||||
│ ├── lib.rs
|
||||
│ └── inference.rs # the actual work
|
||||
├── cog/
|
||||
│ ├── manifest.template.json
|
||||
│ ├── config.schema.json # JSON schema for runtime config
|
||||
│ ├── README.md # consumer-facing description (used by the App Store UI)
|
||||
│ ├── icon.svg # 1024×1024 icon (used by App Store hero)
|
||||
│ └── Makefile # build / sign / upload targets
|
||||
└── tests/
|
||||
├── smoke.rs
|
||||
└── manifest_signature.rs
|
||||
```
|
||||
|
||||
### Build pipeline
|
||||
|
||||
```
|
||||
cd v2/crates/cog-<id>
|
||||
make build-arm # cross-compile to aarch64-unknown-linux-gnu
|
||||
make build-x86_64 # x86_64 Linux build
|
||||
make build-hailo8 # arm + HEF compilation (requires Hailo Dataflow Compiler)
|
||||
make build-hailo10 # arm + HEF compilation
|
||||
make sign # produce binary_sha256 + binary_signature
|
||||
make upload # gsutil cp to gs://cognitum-apps/cogs/<arch>/
|
||||
make manifest # emit manifest.json with all fields filled
|
||||
```
|
||||
|
||||
CI (GitHub Actions) MUST run `make build-arm` + `make build-x86_64` on every PR touching `v2/crates/cog-*/`. Hailo HEF compilation requires the proprietary Hailo SDK and runs only on the Hailo-capable runners (currently a labelled self-hosted runner on the Pi cluster — TBD, separate ADR).
|
||||
|
||||
### Runtime contract
|
||||
|
||||
A Cog binary MUST implement:
|
||||
|
||||
| Subcommand | Behaviour |
|
||||
|-----------|-----------|
|
||||
| `cog-<id> version` | Print `<id> <version>` and exit 0. |
|
||||
| `cog-<id> manifest` | Print the embedded manifest JSON and exit 0. |
|
||||
| `cog-<id> run --config /path/to/config.json` | Long-running. Writes structured JSON logs to stdout (parsed by `cognitum-cog-gateway`). Exit code 0 on graceful shutdown, non-zero on fatal error. |
|
||||
| `cog-<id> health` | One-shot. Exit 0 if the cog could come up healthy; non-zero with diagnostic on stderr. Called by the gateway before `run`. |
|
||||
|
||||
stdout JSON line format (one event per line):
|
||||
|
||||
```json
|
||||
{"ts": 1779210883.444, "level": "info", "event": "<event-name>", "fields": { ... }}
|
||||
```
|
||||
|
||||
## Consequences
|
||||
|
||||
### Positive
|
||||
|
||||
- New Cogs can be added without RE-ing the layout each time.
|
||||
- CI can verify the manifest schema before merge.
|
||||
- Signed binaries close a real supply-chain gap — current installed cogs (`anomaly-detect@0.0.0`) have no signature, and a compromised GCS object could push malicious code to every appliance.
|
||||
- The runtime contract (`run | health | version | manifest`) is uniform across cogs, so `cognitum-cog-gateway` can stop carrying per-cog adapters.
|
||||
|
||||
### Negative
|
||||
|
||||
- Existing installed cogs must be re-published with signatures within one minor release of the gateway adopting the verify-when-present rule.
|
||||
- Hailo HEF cross-compile is gated on a self-hosted runner; we accept that PRs touching Hailo variants will be slower to land.
|
||||
|
||||
### Risks
|
||||
|
||||
- **Signing key rotation**: `COGNITUM_OWNER_SIGNING_KEY` (Ed25519) is a single root-of-trust today. ADR-103 (witness chain) describes the rotation/recovery path; this ADR depends on that.
|
||||
- **GCS bucket misconfiguration**: a public-read bucket with versioning-off could allow rollback attacks. Bucket MUST have Object Versioning enabled + 90-day non-current-version retention.
|
||||
|
||||
## Migration
|
||||
|
||||
1. ✅ Land this ADR.
|
||||
2. ✅ Land ADR-101 (`cog-pose-estimation` — first Cog built to this spec). Shipped in PR #642 + #643 on 2026-05-19; signed `arm` and `x86_64` binaries live at `gs://cognitum-apps/cogs/{arm,x86_64}/`; install verified on cognitum-v0.
|
||||
3. After two clean releases of `cog-pose-estimation`, re-publish the existing cogs (`anomaly-detect`, `presence`, etc.) with `binary_sha256` + `binary_signature`. Track in a follow-up issue.
|
||||
4. Flip `cognitum-cog-gateway` from "verify when present" to "require signature" — separate ADR, separate review.
|
||||
|
||||
## See also
|
||||
|
||||
- ADR-101: Pose Estimation Cog (first Cog built to this spec).
|
||||
- ADR-103: Witness chain trust model (signing key rotation, future ADR).
|
||||
- `docs/adr/ADR-079-camera-ground-truth-training.md` — the training pipeline behind `cog-pose-estimation`.
|
||||
- `CLAUDE.local.md` § "Fleet Infrastructure (Tailscale)" — appliance layout this ADR describes.
|
||||
@@ -1,208 +0,0 @@
|
||||
# ADR-101: Pose Estimation Cog (WiFi-DensePose side)
|
||||
|
||||
- **Status:** Accepted — **v0.0.1 shipped 2026-05-19** (merged in PRs #642 + #643, signed binaries on GCS, live install on cognitum-v0)
|
||||
- **Date:** 2026-05-19
|
||||
- **Deciders:** ruv
|
||||
- **Companion ADR (v0-appliance side):** v0-appliance ADR-225 (cognitum-pose-estimation crate)
|
||||
|
||||
## Context
|
||||
|
||||
ADR-079 designed the 17-keypoint COCO pose-estimation training pipeline. ADR-100 formalised the Cognitum Cog packaging spec. This ADR is the bridge: it specifies how the wifi-densepose training pipeline produces an artifact that ships as a Cog (`cog-pose-estimation`) onto the Cognitum V0 appliance and out to the Pi+Hailo cluster.
|
||||
|
||||
It is the next product step beyond the published `presence` Cog (binary head trained from the contrastive encoder on Hugging Face at `ruvnet/wifi-densepose-pretrained`). Where `presence` reports a single boolean per tick, `cog-pose-estimation` reports 17 (x, y) keypoints per person, per tick.
|
||||
|
||||
## Decision
|
||||
|
||||
### Pipeline
|
||||
|
||||
```
|
||||
(training side — ruvultra GPU)
|
||||
ESP32 / rvcsi ─► collect-ground-truth.py + sensing-server recording
|
||||
│
|
||||
▼
|
||||
data/paired/*.paired.jsonl (CSI window + camera keypoints)
|
||||
│
|
||||
▼
|
||||
v2/crates/wifi-densepose-train ──► Rust + libtorch trainer
|
||||
(uses RTX 5080 / CUDA 12.x) │
|
||||
init from ruvnet/wifi-densepose-pretrained
|
||||
│
|
||||
▼
|
||||
model.safetensors (encoder + pose head)
|
||||
│
|
||||
─────────────┴─────────────
|
||||
│ │
|
||||
▼ ▼
|
||||
v2/crates/cog-pose-estimation export to ONNX
|
||||
(this repo) │
|
||||
• emits manifest.json ▼
|
||||
• produces cog binary cognitum-hailo
|
||||
• signs + uploads to GCS (v0-appliance side)
|
||||
│
|
||||
▼
|
||||
cog-pose-estimation.hef
|
||||
│
|
||||
▼
|
||||
(appliance side — cognitum-v0 + Pi+Hailo cluster)
|
||||
|
||||
gs://cognitum-apps/cogs/{arm,hailo8,hailo10}/cog-pose-estimation-<arch>
|
||||
│
|
||||
▼
|
||||
`cognitum-cog-gateway` pulls artifact + manifest, verifies signature, installs
|
||||
into /var/lib/cognitum/apps/pose-estimation/
|
||||
│
|
||||
▼
|
||||
run loop: read CSI frames from local sensing-server
|
||||
→ encoder → pose head → emit `{ts, persons: [{keypoints: [...17 x,y...] }]}`
|
||||
on stdout as the Cog runtime contract requires
|
||||
```
|
||||
|
||||
### Architecture (model)
|
||||
|
||||
| Stage | Module | Notes |
|
||||
|-------|--------|-------|
|
||||
| Input | `[56 subcarriers × 20 frames]` per CSI window | matches today's `data/paired/wiflow-p7-*.paired.jsonl` |
|
||||
| Encoder | TCN-lite or contrastive encoder lifted from HF presence model | 128-dim embedding; weights init from `ruvnet/wifi-densepose-pretrained/model.safetensors` |
|
||||
| Pose head | 2-layer MLP `(128 → 256 → 34)` | 34 = 17 × (x, y) |
|
||||
| Output | `[B, 17, 2]` keypoints in `[0, 1]` image-normalised coords | confidence is implicit in keypoint variance over time; ADR-079 P9 will add explicit per-joint confidence |
|
||||
| Loss | Confidence-weighted SmoothL1 (frame-level) + bone-length regulariser + temporal smoothness | per ADR-079 Phase 3 refinement |
|
||||
| Init | Encoder = HF presence weights (frozen for 50 epochs, then jointly fine-tuned) | unblocks the sigmoid-saturation failure mode observed in #645 |
|
||||
| Training | `v2/crates/wifi-densepose-train` with libtorch backend on RTX 5080 | replaces the pure-JS SPSA trainer that produced 0% PCK in #645 |
|
||||
|
||||
### Repo layout
|
||||
|
||||
```
|
||||
v2/crates/cog-pose-estimation/ # NEW (this ADR)
|
||||
├── Cargo.toml
|
||||
├── src/
|
||||
│ ├── main.rs # CLI: run | health | version | manifest
|
||||
│ ├── lib.rs
|
||||
│ ├── inference.rs # ONNX runtime + Hailo HEF runtime dispatch
|
||||
│ ├── frame_subscriber.rs # local sensing-server subscriber
|
||||
│ └── publisher.rs # emits structured JSON events per Cog contract
|
||||
├── cog/
|
||||
│ ├── manifest.template.json
|
||||
│ ├── config.schema.json
|
||||
│ ├── README.md
|
||||
│ ├── icon.svg
|
||||
│ └── Makefile # build-arm | build-x86_64 | sign | upload
|
||||
└── tests/
|
||||
├── manifest_signature.rs
|
||||
└── inference_smoke.rs
|
||||
```
|
||||
|
||||
### Runtime contract
|
||||
|
||||
Honours ADR-100's per-Cog CLI contract:
|
||||
|
||||
- `cog-pose-estimation version` → `pose-estimation 0.0.1`
|
||||
- `cog-pose-estimation manifest` → JSON
|
||||
- `cog-pose-estimation health` → 0 if encoder+head load and a synthetic frame produces a finite output
|
||||
- `cog-pose-estimation run --config /etc/cognitum/cogs/pose-estimation/config.json` → long-running; emits one JSON event per inferred frame:
|
||||
|
||||
```json
|
||||
{
|
||||
"ts": 1779210883.444,
|
||||
"level": "info",
|
||||
"event": "pose.frame",
|
||||
"fields": {
|
||||
"tick": 12345,
|
||||
"n_persons": 1,
|
||||
"persons": [
|
||||
{"keypoints": [[0.48, 0.31], [0.52, 0.28], ...], "confidence": 0.81}
|
||||
]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Hardware deployment
|
||||
|
||||
| Target | arch | runtime | notes |
|
||||
|--------|------|---------|-------|
|
||||
| ruvultra (dev) | `x86_64` | ONNX Runtime CPU/CUDA | development & smoke tests |
|
||||
| cognitum-v0 (Pi 5) | `arm` | ONNX Runtime ARM | reference deploy; ~20 ms/frame |
|
||||
| Pi + Hailo-8 hat | `hailo8` | Hailo HEF runtime via `cognitum-hailo` | ~2 ms/frame, 26 TOPS budget |
|
||||
| Pi + Hailo-10 hat | `hailo10` | Hailo HEF runtime via `cognitum-hailo` | ~1 ms/frame, 40 TOPS budget |
|
||||
|
||||
### Acceptance gates
|
||||
|
||||
1. **Validates:** `cargo test -p cog-pose-estimation` green; `cog-pose-estimation health` returns 0 against a synthetic CSI window.
|
||||
2. **Benchmarks:** end-to-end frame latency on each target arch logged in `target/criterion/`; published in `docs/benchmarks/pose-estimation-cog.md`.
|
||||
3. **Optimised:** the Hailo-targeted ONNX graph passes through Hailo Dataflow Compiler without quantisation-aware-training warnings.
|
||||
4. **Published:** signed binary at `gs://cognitum-apps/cogs/<arch>/cog-pose-estimation-<arch>`; manifest valid against the JSON schema in ADR-100; appliance installer can pull and run it.
|
||||
|
||||
PCK@20 is intentionally **not** an acceptance gate of this ADR. Achieving the ADR-079 ≥35% target is a separate, data-bound milestone tracked in #645. This ADR ships the **vehicle**, not the model accuracy.
|
||||
|
||||
### First measured run — v0.0.1 (2026-05-19)
|
||||
|
||||
A Candle-on-CUDA training run on `ruvultra`'s RTX 5080 against the same 1,077-sample paired session that produced the 0%/0% baseline in #645 yielded:
|
||||
|
||||
- **PCK@20 = 3.0%**, **PCK@50 = 18.5%**, **MPJPE = 0.093** (normalized).
|
||||
- 400 epochs in **2.1 s** wall time (~5 ms/epoch, full-batch).
|
||||
- Loss reduction 13× (0.181 → 0.014, eval 0.010).
|
||||
- Strongest signal at `r_hip` (PCK@50 = 76.9%), `r_knee` (35.2%), `l_elbow` (26.4%).
|
||||
|
||||
This confirms the pipeline trains end-to-end and produces a signal-bearing model. The remaining gap to PCK@20 ≥ 35% is data-bound (1,077 samples is ≪ the ADR-079 target of ~30K). See `docs/benchmarks/pose-estimation-cog.md` for the full result dump.
|
||||
|
||||
## Consequences
|
||||
|
||||
### Positive
|
||||
|
||||
- First Cog from this repo that integrates with the appliance/cog-gateway pipeline. Future cogs (e.g. `cog-vitals`, `cog-fall-alert`) follow the same template.
|
||||
- Closes the loop from data collection → training → quantisation → cluster deployment with a single repo-anchored artifact.
|
||||
- Forces a real signature on cog binaries (per ADR-100), which improves supply-chain hygiene across the whole appliance.
|
||||
|
||||
### Negative
|
||||
|
||||
- Adds a hard dependency on the Hailo Dataflow Compiler, which lives behind a self-hosted runner — Hailo-targeted PRs land more slowly.
|
||||
- The first published binary will have low PCK (data + training time gap, #645) — UX needs to surface this clearly so end users do not interpret bad keypoints as a bug.
|
||||
|
||||
### Risks
|
||||
|
||||
- **Model size on Hailo**: the encoder fits comfortably in Hailo-8's on-chip SRAM, but the pose-head expansion to `[17×2]` plus required temporal stacking pushes us close to the Hailo-8 envelope. Mitigation: Hailo-10 path is the primary deploy target; Hailo-8 is a stretch.
|
||||
- **Sensing-server schema drift**: the cog subscribes to `/api/v1/sensing/latest` JSON. If the appliance's sensing-server schema changes, the cog fails open (logs warning, emits nothing). The `frame_subscriber.rs` module pins to schema version `2`.
|
||||
|
||||
## Migration / rollout
|
||||
|
||||
1. Land this ADR + ADR-100 on `main` of RuView.
|
||||
2. Land companion ADR-225 + crate on `main` of v0-appliance.
|
||||
3. First release `cog-pose-estimation@0.0.1` ships **only** to `ruvultra` and `cognitum-v0`. Not pushed to the cluster Pis yet.
|
||||
4. After P7→P9 data work (#645) brings PCK above a usable threshold, rebuild + re-publish; only then enable cluster rollout via `cognitum-cog-gateway`'s OTA channel.
|
||||
|
||||
## v0.0.1 shipping status — 2026-05-19
|
||||
|
||||
PRs `#642` (scaffold + arm release + ONNX + live install) and `#643` (x86_64 release) landed on `main`. Acceptance gates from ADR-100 met as follows:
|
||||
|
||||
| Gate | Status |
|
||||
|------|--------|
|
||||
| Cog binary exists per arch | ✅ arm (`3,741,976 B`) + x86_64 (`4,548,856 B`) on GCS |
|
||||
| Manifest matches schema | ✅ `cog/artifacts/manifests/{arm,x86_64}/manifest.json` |
|
||||
| Binary sha256 + Ed25519 signature | ✅ both signed with `COGNITUM_OWNER_SIGNING_KEY`, round-trip verified |
|
||||
| Public-readable GCS | ✅ anonymous HTTP GET works, SHA matches |
|
||||
| Live install on a real appliance | ✅ `/var/lib/cognitum/apps/pose-estimation/` on `cognitum-v0` (Pi 5), same layout as `anomaly-detect` |
|
||||
| Runtime contract (`version \| manifest \| health \| run`) | ✅ all four return correct output; `run` emits `pose.frame` events |
|
||||
| Real weights loaded (not stub) | ✅ `cargo test` asserts `backend.starts_with("candle-")` + non-zero confidence |
|
||||
| ONNX artifact (for downstream HEF) | ✅ `pose_v1.onnx` (12 KB), parity vs torch = 8.94e-8 |
|
||||
|
||||
| Metric | Value |
|
||||
|--------|-------|
|
||||
| Training time (RTX 5080 / Candle CUDA) | 2.1 s for 400 epochs |
|
||||
| PCK@20 / PCK@50 / MPJPE (1,077-sample seated-desk session) | 3.0% / 18.5% / 0.093 |
|
||||
| Cold-start: Windows x86_64 | 76 ms |
|
||||
| Cold-start: ruvultra x86_64 | **5.4 ms** |
|
||||
| Cold-start: Pi 5 aarch64 | **8.4 ms** |
|
||||
| Tests | 5/5 pass |
|
||||
|
||||
Open follow-ups carried forward from this ADR's "Acceptance gates" section:
|
||||
|
||||
- **Hailo HEF cross-compile** — `pose_v1.onnx` is ready; still gated on Hailo Dataflow Compiler + self-hosted runner provisioning. Tracked separately.
|
||||
- **PCK@20 ≥ 35%** — explicitly not an acceptance gate of this ADR, but the limiting factor on practical usefulness. Tracked in [#645](https://github.com/ruvnet/RuView/issues/645): needs ~30× more paired samples + multi-room camera framing. Today's seated-desk session is the demonstrated bottleneck.
|
||||
|
||||
## See also
|
||||
|
||||
- ADR-079: Camera-supervised pose training pipeline (the model we're shipping).
|
||||
- ADR-100: Cog packaging specification (the format we're shipping in).
|
||||
- v0-appliance ADR-225: cognitum-pose-estimation crate (the appliance-side runtime).
|
||||
- v0-appliance ADR-220: cog management surface (where this cog appears in the dashboard).
|
||||
- Issue #645: PCK gap (current 3% / 18.5% → ≥35% target).
|
||||
- `docs/benchmarks/pose-estimation-cog.md`: full benchmark log, all measured numbers.
|
||||
@@ -1,171 +0,0 @@
|
||||
# ADR-102: Edge Module Registry Integration
|
||||
|
||||
- **Status:** Accepted
|
||||
- **Date:** 2026-05-19
|
||||
- **Deciders:** ruv
|
||||
|
||||
## Context
|
||||
|
||||
The Cognitum app ecosystem publishes a canonical app store catalog at:
|
||||
|
||||
```
|
||||
https://storage.googleapis.com/cognitum-apps/app-registry.json
|
||||
```
|
||||
|
||||
As of v2.1.0 (2026-05-13) the registry advertises **105 cogs across 11 categories** (health, security, building, retail, industrial, research, ai, swarm, signal, network, developer). Each entry carries `id`, `name`, `category`, `version`, `description`, `size_kb`, `difficulty`, `sha256`, `binary_size`, and a `config[]` schema describing the runtime parameters the appliance offers when installing the cog.
|
||||
|
||||
RuView today has no live awareness of this catalog. The `README.md` capability table is hand-curated; the UI surfaces only the capabilities the dashboard's HTML knows about; nothing in `wifi-densepose-sensing-server` references the registry. Result: when Cognitum ships a new cog (the registry was last updated 6 days ago — a fast cadence), RuView stays unaware until someone manually edits the README. Customers running the RuView dashboard against a real appliance see a 10-capability bag in the UI while the appliance is actually capable of installing 105 cogs.
|
||||
|
||||
Today's `cog-pose-estimation@0.0.1` release (PRs #642 / #643, ADR-100, ADR-101) is the first cog this repo ships to that registry. We need the discovery side to match.
|
||||
|
||||
## Decision
|
||||
|
||||
`wifi-densepose-sensing-server` will fetch `app-registry.json` on demand, cache it in process memory with a TTL, and serve it back through a new endpoint:
|
||||
|
||||
```
|
||||
GET /api/v1/edge/registry
|
||||
GET /api/v1/edge/registry?refresh=1 (force-bypass cache, log if abused)
|
||||
```
|
||||
|
||||
The registry is **passively surfaced**, not modified. RuView is a presentation layer for the canonical Cognitum catalog; it never re-signs entries or re-hosts binaries.
|
||||
|
||||
### Module
|
||||
|
||||
`v2/crates/wifi-densepose-sensing-server/src/edge_registry.rs` — small, ~150 lines.
|
||||
|
||||
```rust
|
||||
pub struct EdgeRegistry {
|
||||
cached: RwLock<Option<CachedEntry>>,
|
||||
ttl: Duration,
|
||||
upstream_url: String,
|
||||
}
|
||||
|
||||
struct CachedEntry {
|
||||
payload: serde_json::Value,
|
||||
fetched_at: Instant,
|
||||
upstream_sha256: String,
|
||||
}
|
||||
```
|
||||
|
||||
Cache semantics:
|
||||
|
||||
- TTL **3600 s (1 hour)** by default — registry updates land on a roughly-weekly cadence and a stale-by-an-hour catalog is fine.
|
||||
- `?refresh=1` bypasses the cache but writes a debug log so accidental abuse is visible.
|
||||
- On upstream fetch failure when the cache is non-empty, **serve the stale cached copy** with a `stale: true` marker in the response and a 200 status (preserve UI), not a 5xx.
|
||||
- On upstream fetch failure when the cache is empty, return 503 with the upstream error in the body.
|
||||
|
||||
### Response shape
|
||||
|
||||
```jsonc
|
||||
{
|
||||
"fetched_at": 1779200000, // server-side fetch timestamp
|
||||
"ttl_seconds": 3600,
|
||||
"stale": false, // true when serving past TTL because upstream is down
|
||||
"upstream_url": "https://storage.googleapis.com/cognitum-apps/app-registry.json",
|
||||
"upstream_sha256": "<sha256-of-payload-bytes>",
|
||||
"registry": { /* full canonical JSON as returned upstream */ }
|
||||
}
|
||||
```
|
||||
|
||||
The `registry` field is the upstream JSON inlined verbatim so consumers don't need to make a second hop. `upstream_sha256` lets a paranoid consumer compare against a pinned hash.
|
||||
|
||||
### Trust / verification
|
||||
|
||||
- Bucket is public-read with object versioning enabled (per ADR-100 §"GCS misconfiguration risks").
|
||||
- The cog-level `binary_sha256` + `binary_signature` (ADR-100) are the trust roots for *installs*. The registry itself is not signed today.
|
||||
- We deliberately **do not** add a signature requirement to the registry JSON in this ADR — that would block the integration on a parallel infrastructure project. A future ADR can layer signature checks on top once the publisher pipeline emits them.
|
||||
|
||||
### UI surfacing
|
||||
|
||||
New page `ui/edge-modules.html` renders the registry into category sections with cog cards. Each card links out to the Cognitum V0 appliance's `/cogs` page (`http://cognitum-v0:9000/cogs#<id>`) for the install action — RuView itself never installs.
|
||||
|
||||
The existing dashboard's "Capabilities" section continues to show RuView-native sensing capabilities (presence, breathing, pose, etc. — the things RuView itself runs); the new edge-modules page shows the broader Cognitum cog catalog. The two are distinct surfaces and shouldn't be merged.
|
||||
|
||||
### Failure modes
|
||||
|
||||
| Scenario | Behaviour |
|
||||
|---|---|
|
||||
| Upstream returns 200 with valid JSON | Cache it, return it. |
|
||||
| Upstream returns 200 with invalid JSON | Treat as failure; serve stale if available else 503. Log the upstream sha + the parse error. |
|
||||
| Upstream returns 4xx / 5xx | Same as JSON-invalid: serve stale if available else 503. |
|
||||
| TLS / DNS / timeout error | Same. |
|
||||
| Upstream is permanently moved | Operator updates the `upstream_url` config (CLI flag added). No code change required to migrate registries. |
|
||||
|
||||
### Configuration
|
||||
|
||||
- `--edge-registry-url <URL>` — override the default (default: `https://storage.googleapis.com/cognitum-apps/app-registry.json`)
|
||||
- `--edge-registry-ttl-secs <N>` — override the cache TTL (default: 3600)
|
||||
- `--no-edge-registry` — disable the endpoint entirely (returns 404). For air-gapped deployments.
|
||||
|
||||
## Consequences
|
||||
|
||||
### Positive
|
||||
|
||||
- One source of truth for the cog catalog across RuView + Cognitum dashboards.
|
||||
- Zero ongoing maintenance: when Cognitum publishes registry v2.2.0, RuView sees it within an hour without a release.
|
||||
- The endpoint is also useful for non-UI consumers (CI checks, fleet automation, third-party integrations).
|
||||
- Lets us deprecate the hand-curated README capability table in favour of generated content (separate PR).
|
||||
|
||||
### Negative
|
||||
|
||||
- Adds an outbound HTTP dependency to the sensing-server. Air-gapped deployments must use `--no-edge-registry`.
|
||||
- Stale-but-served behaviour can mask upstream outages from operators. Mitigation: include `stale: true` + `fetched_at` in the response so the UI can render a "registry possibly out of date" badge.
|
||||
|
||||
### Risks
|
||||
|
||||
- **Upstream rug-pull**: if `cognitum-apps` is deleted or replaced, the endpoint goes dark. The `--edge-registry-url` flag lets operators repoint without a code change. Long-term, RuView could mirror the registry into its own GCS bucket if the relationship requires it.
|
||||
- **Cache poisoning**: the upstream is public-read; an attacker who breaches Cognitum's GCS write could push a bad registry. The cog-level signatures (ADR-100) limit the blast radius — bad registry entries can't install bad binaries, only show wrong metadata. Acceptable until registry-level signing lands.
|
||||
|
||||
## Security review
|
||||
|
||||
A real review of the attack surface this endpoint introduces.
|
||||
|
||||
### Threats considered
|
||||
|
||||
| # | Threat | Mitigation in this ADR |
|
||||
|---|--------|------------------------|
|
||||
| T1 | **SSRF** — operator-supplied `--edge-registry-url` redirects fetches to an internal target | Flag is operator-only (CLI / env) — there is no API endpoint to mutate it at runtime. Operators are already trusted (they control the binary). |
|
||||
| T2 | **Outbound dependency reveals deployment** — a passive observer of the egress sees the appliance phoning home to GCS | Documented in the docstring + the runtime startup log. Operators wanting offline deployments use `--no-edge-registry`. |
|
||||
| T3 | **Malicious upstream registry** — Cognitum's GCS bucket is breached and a poisoned `app-registry.json` is served | Two layers absorb this: (a) the registry's role is **discovery only** — installs verify the per-cog `binary_sha256` + `binary_signature` (ADR-100); a wrong description string can mislead a human, but a wrong binary still has to pass Ed25519 against `COGNITUM_OWNER_SIGNING_KEY`. (b) The endpoint exposes `upstream_sha256` so a paranoid operator can pin the expected registry hash externally and alert on drift. |
|
||||
| T4 | **Response inflation** — upstream returns a multi-GB payload to exhaust memory | `MAX_PAYLOAD_BYTES = 8 MiB` cap (current registry is ~50–200 KB). Exceeding cap returns an error without buffering past the cap. |
|
||||
| T5 | **Slow upstream blocking server threads** — Slowloris-style stall on the fetch | 10-second wire timeout via `ureq::AgentBuilder`. Per-handler fetch runs inside `tokio::task::spawn_blocking` so a stalled fetch never blocks the async runtime. |
|
||||
| T6 | **Denial via `?refresh=1` abuse** — unauthenticated callers force-bypass the cache repeatedly | Cache lives in process; `?refresh=1` triggers a single upstream fetch behind a synchronous code path. A flood of refresh requests is rate-limited by the upstream's own throttling (GCS) and locally serialised by Rust's `RwLock`. Refresh requests are logged at `debug` so abuse is visible. **Follow-up:** add per-IP rate-limit middleware if seen abused (separate PR; tracked in #574-style follow-up). |
|
||||
| T7 | **JSON deserialisation panics** — malformed registry triggers a Rust panic | Payload is parsed as `serde_json::Value` (opaque untyped tree) — never coerced into a strongly-typed struct that could panic. Failure is propagated as `FetcherError::Network` which the handler maps to 503. |
|
||||
| T8 | **Stale-on-error masks outages from operators** | Response carries `stale: true` + `fetched_at` (unix timestamp). UI rendering MUST surface this badge — encoded as an explicit field, not an implicit silence. |
|
||||
| T9 | **TLS downgrade / MITM on the fetch** | `ureq` is built with the `tls` feature (rustls) by default. No `--insecure` flag exists. If the upstream uses LetsEncrypt the cert chain is system-trusted; certificate pinning is out of scope (would block the bucket from rotating certs). |
|
||||
| T10 | **Unauthenticated access exposes ‘what cogs exist’** | The registry is canonical-public information (already public-read on GCS via anonymous HTTP GET). Surfacing it on a local LAN HTTP API does not increase its disclosure. The endpoint stays under the project's existing `RUVIEW_API_TOKEN` Bearer auth — when set, the registry is gated like other `/api/v1/*` routes. |
|
||||
| T11 | **Configuration injection via env var** — `RUVIEW_EDGE_REGISTRY_URL` set to a malicious URL by an attacker who controls the process environment | If an attacker controls the env, they own the process; this is not a new threat surface. Documented in the CLI help. |
|
||||
| T12 | **Cache mutation across threads / poisoning** | The cache is `RwLock<Option<CachedEntry>>`. Writes go through `cached.write()` once per fetch. Snapshot reads `clone()` the `CachedEntry` (cheap — `Value` is reference-counted internally for large strings) so concurrent readers don't share mutable state. Tests cover the multi-call path; no `unsafe` is used. |
|
||||
|
||||
### What this ADR does NOT secure
|
||||
|
||||
- **Registry-level signing** — the JSON payload itself is unsigned. If/when Cognitum's publisher pipeline emits a registry sig (e.g. detached `.json.sig`), a follow-up ADR will require it. Today the per-cog binary signature (ADR-100) is the actual trust root for installs; the registry is metadata.
|
||||
- **Per-client rate-limiting on `?refresh=1`** — relies on the upstream's own throttling. If we see abuse we'll add a token-bucket middleware; not needed for v0.0.1.
|
||||
|
||||
### Testing
|
||||
|
||||
| Test | What it verifies |
|
||||
|------|------------------|
|
||||
| `first_call_hits_upstream_and_caches` | Single fetch, then cache hit |
|
||||
| `ttl_expiry_triggers_refetch` | Cache TTL bound respected |
|
||||
| `force_refresh_bypasses_fresh_cache` | `?refresh=1` semantics |
|
||||
| `stale_serve_on_upstream_failure_after_cached_success` | T8 explicit (`stale: true` returned) |
|
||||
| `no_cache_no_upstream_returns_error` | T3/T5 — error propagated cleanly when nothing to fall back on |
|
||||
| `upstream_invalid_json_is_treated_as_error` | T7 — malformed payload doesn't panic |
|
||||
| `upstream_sha256_is_deterministic` | T3 — hash field is reliable for external pinning |
|
||||
|
||||
All 7 tests in `src/edge_registry.rs::tests` pass.
|
||||
|
||||
## Migration
|
||||
|
||||
1. Land this ADR + the implementing PR.
|
||||
2. UI: ship `ui/edge-modules.html` and link from `index.html`.
|
||||
3. After two clean releases of the endpoint, remove the hand-curated "Capabilities" table from `README.md` and replace with a small "see the appliance for the full catalog" pointer.
|
||||
4. Future ADR: registry signing once Cognitum's publisher pipeline emits a sig.
|
||||
|
||||
## See also
|
||||
|
||||
- ADR-100: Cognitum Cog Packaging Specification (binary trust model).
|
||||
- ADR-101: Pose Estimation Cog (the first repo-shipped cog visible in the registry).
|
||||
- v0-appliance ADR-220: Cog management surface (where this registry is the input to install actions).
|
||||
- `docs/benchmarks/pose-estimation-cog.md`: the per-cog benchmark format this ADR's response shape complements.
|
||||
@@ -1,198 +0,0 @@
|
||||
# ADR-103: Learned Multi-Person Counter (SOTA WiFi CSI counting)
|
||||
|
||||
- **Status:** Proposed
|
||||
- **Date:** 2026-05-21
|
||||
- **Deciders:** ruv
|
||||
- **Motivating issue:** #499 (double skeletons with 3-node ESP32-S3 setup, closed by PR #491)
|
||||
- **Related:** ADR-079 (camera-supervised training), ADR-100 (cog packaging), ADR-101 (pose cog), ADR-102 (edge module registry), PR #491 (RollingP95 + dedup_factor)
|
||||
|
||||
## Context
|
||||
|
||||
PR #491 stopped the bleeding on #499. The fix replaced hard-coded denominators (`variance/300`, `motion_band_power/250`, `spectral_power/500`) with a self-calibrating `RollingP95` streaming estimator and exposed the multi-node `dedup_factor` as a runtime knob. Day-0 deployments no longer collapse dynamic range, and operators can auto-tune the divisor from a known person count.
|
||||
|
||||
That gets us to a **stable heuristic that adapts to the room**. It does not get us to the published WiFi-CSI counting state of the art:
|
||||
|
||||
| System | Setup | Reported accuracy | Method |
|
||||
|--------|-------|-------------------|--------|
|
||||
| **WiCount** (CMU, 2017) | Intel 5300 3×3 MIMO | 89% within ±1 | LSTM over CSI amplitude |
|
||||
| **DeepCount** (2018) | Atheros 3×3 | 92% within ±1, 5-room | CNN + cross-environment transfer |
|
||||
| **CrossCount** (2019) | Atheros, 6 rooms | 84% cross-room within ±1 | Domain-adversarial CNN |
|
||||
| **HeadCount** (2021) | Intel 5300 | <1 person MAE, 5 envs | Multi-stream CSI + attention |
|
||||
| **RuView today** (PR #491) | ESP32-S3 1×1 SISO | Calibrated heuristic; not measured against ground truth | RollingP95 + dedup_factor |
|
||||
|
||||
The literature uses 3×3 MIMO research NICs. RuView uses 1×1 SISO ESP32-S3 nodes. The published number is therefore not directly attainable, but the **architectural gap** is large enough that a learned-counter approach on our hardware should comfortably beat today's slot heuristic — and the infrastructure to train one already exists in this repo (Candle + RTX 5080 trained `pose_v1.safetensors` in 2.1 s yesterday — see [`docs/benchmarks/pose-estimation-cog.md`](../benchmarks/pose-estimation-cog.md)).
|
||||
|
||||
Five primitives we already have but don't yet compose into a counter:
|
||||
|
||||
1. **Paired CSI + camera label dataset** — `scripts/collect-ground-truth.py` + `scripts/align-ground-truth.js` (PR #641 streaming-safe). 1,077 samples currently; #645 tracks the path to ~30K.
|
||||
2. **Stoer-Wagner min-cut for person-separable subcarrier groups** — `ruvector-mincut` (already a workspace dep). The Candle trainer used it yesterday and reported `Min-cut value: 0.1538 — partition: [55, 1] subcarriers`.
|
||||
3. **Contrastive-pretrained CSI encoder** — `ruvnet/wifi-densepose-pretrained` on HF (12.2M training steps, 60K frames, 128-dim embeddings, ~165k emb/s on M4 Pro).
|
||||
4. **Candle training pipeline** — proven yesterday: 400 epochs in 2.1 s on RTX 5080, bit-perfect ONNX export, signed cog binary on GCS.
|
||||
5. **Multi-node fusion stage** — `multistatic_bridge.rs` already aggregates per-node feature vectors with the tunable `dedup_factor`. The new model output can be a drop-in replacement for the existing dedup divisor.
|
||||
|
||||
## Decision
|
||||
|
||||
Train and ship a small **learned multi-person counter** as a new Cognitum Cog (`cog-person-count`), modelled on the same packaging path as `cog-pose-estimation` (ADR-101). Wire it into the sensing-server's existing person-count call site (`csi.rs::score_to_person_count`) as a drop-in replacement for the slot heuristic.
|
||||
|
||||
### Architecture (v0.1.0)
|
||||
|
||||
```
|
||||
┌──────────────────────────────┐
|
||||
per-node CSI window │ Encoder (frozen first 50 ep) │
|
||||
[56 sub × 20 frames] ─► init from ruvnet/wifi- │
|
||||
│ densepose-pretrained │
|
||||
│ → 128-dim embedding │
|
||||
└──────────────┬───────────────┘
|
||||
│
|
||||
┌────────────────┴────────────────┐
|
||||
▼ ▼
|
||||
┌────────────────────┐ ┌────────────────────────┐
|
||||
│ Count head │ │ Confidence head │
|
||||
│ Linear(128→64) │ │ Linear(128→32) │
|
||||
│ ReLU │ │ ReLU │
|
||||
│ Linear(64→8) │ │ Linear(32→1) + sigmoid│
|
||||
│ → softmax over │ │ → calibrated p(correct)│
|
||||
│ {0..7} persons │ └────────────────────────┘
|
||||
└────────┬───────────┘
|
||||
│ (per-node prediction)
|
||||
│
|
||||
N nodes' per-node │
|
||||
counts + confidences ▼
|
||||
┌─────────────────────────────────────┐
|
||||
│ Multi-node fusion (Stoer-Wagner) │
|
||||
│ • build graph: nodes × subcarrier │
|
||||
│ feature similarity │
|
||||
│ • min-cut → distinct-person bound │
|
||||
│ • combine with per-node count head │
|
||||
│ via confidence-weighted vote │
|
||||
└──────────────────┬──────────────────┘
|
||||
▼
|
||||
{ count: int,
|
||||
confidence: float [0,1],
|
||||
count_p95_low: int,
|
||||
count_p95_high: int,
|
||||
per_node_breakdown: [...] }
|
||||
```
|
||||
|
||||
Five things to call out about this architecture:
|
||||
|
||||
1. **Frozen encoder for the first 50 epochs.** The HF presence encoder already produces a useful 128-dim embedding from random CSI; training the counting head on top of frozen features is the standard transfer-learning pattern and avoids re-learning the contrastive geometry the encoder was painstakingly trained for.
|
||||
2. **Classification over `{0..7}` people**, not regression to a real number. Counts are integer-valued; classification gives a calibrated probability per count and lets the confidence head produce a meaningful uncertainty.
|
||||
3. **Stoer-Wagner min-cut at fusion time, not training time.** We use the min-cut primitive to bound the per-node count from above (a node can't see more distinct people than the subcarrier graph has min-cuts), then take a confidence-weighted vote.
|
||||
4. **Output is `{count, confidence, count_p95_low, count_p95_high}`**, not a single integer. Downstream consumers (Cogs / dashboard / alerts) can choose their certainty threshold. This is what closes the loop on the #499 UX: when the model is uncertain, the dashboard renders one stick figure with a "?" badge rather than two ghosts.
|
||||
5. **No new hardware.** Same ESP32-S3 1×1 SISO that ships today. The win comes from learned features + multi-node fusion, not from bigger antennas.
|
||||
|
||||
### Training (Candle / RTX 5080 / proven path)
|
||||
|
||||
Same exact pipeline that produced `pose_v1.safetensors` yesterday. Differences:
|
||||
|
||||
| | Pose cog (today) | Count cog (this ADR) |
|
||||
|---|---|---|
|
||||
| Input | `[56, 20]` CSI window | `[56, 20]` CSI window (identical) |
|
||||
| Encoder init | random (HF arch mismatch) | **from HF presence model** (architectures are compatible — same encoder Φ) |
|
||||
| Output head | `Linear(128 → 256 → 34)` keypoints | `Linear(128 → 64 → 8)` count classes + `Linear(128 → 32 → 1)` confidence |
|
||||
| Loss | Confidence-weighted SmoothL1 | Categorical cross-entropy + Brier-score uncertainty calibration |
|
||||
| Labels | MediaPipe keypoints | Camera count (MediaPipe `pose_landmarks` length) |
|
||||
| Data | 1,077 paired (P7) | **Same source, same script** — `collect-ground-truth.py` already records `n_persons` per frame |
|
||||
|
||||
Crucially we get the count labels **for free** from the existing pose data-collection pipeline — `collect-ground-truth.py` already records `"n_persons"` per camera frame and `align-ground-truth.js` already preserves it through windowing. No new data collection campaign required to bootstrap; we can train tomorrow on the same 1,077 samples that produced `pose_v1`.
|
||||
|
||||
### Multi-node fusion
|
||||
|
||||
The per-node count head + confidence head emit a categorical distribution over `{0..7}`. With N nodes, we have N such distributions plus N confidence scalars. Two fusion paths:
|
||||
|
||||
- **Confidence-weighted log-sum** (Bayesian product): `log p_fused(k) = Σ_n c_n · log p_n(k)`. Simple, no extra parameters, comes from the optimal-expert combination literature.
|
||||
- **Stoer-Wagner upper bound**: build a graph where edges are pairwise subcarrier-feature similarities between nodes. Min-cut size = a hard upper bound on the number of distinct people the node mesh can resolve. Clip the per-node-fused distribution to support `{0..min-cut}` before re-normalising. This is exactly what `ruvector-mincut` was added to the workspace for — it's been waiting for a counting consumer.
|
||||
|
||||
Both fuse cleanly. v0.1.0 ships the log-sum; v0.2.0 adds the min-cut clipper after the first round of evaluation.
|
||||
|
||||
### Why this beats today's heuristic
|
||||
|
||||
| Failure mode of today's slot heuristic | How the learned counter avoids it |
|
||||
|---|---|
|
||||
| #499 — fixed denominators clamp → one person renders as 2+ groups | Encoder produces a fixed-dim embedding; the count head is invariant to feature magnitude, only to feature **shape** |
|
||||
| `dedup_factor` per-room tuning is operator-visible toil | Count head's softmax is a learned per-room normaliser by construction |
|
||||
| Adding nodes makes the count noisier under the slot heuristic | Multi-node fusion is **additive in confidence**, so each node either reduces uncertainty or stays neutral — never amplifies it |
|
||||
| No per-frame uncertainty signal | `confidence` + `count_p95_low/high` exposed in every emit |
|
||||
| Catastrophic failure on novel environments | LoRA per-room adapter (per ADR-079 P9 plan) hot-swappable without retraining |
|
||||
|
||||
### Acceptance gates
|
||||
|
||||
| Gate | v0.1.0 (initial release) | v0.2.0 (after data scaling) |
|
||||
|------|--------------------------|------------------------------|
|
||||
| Day-0 deployment (no calibration) | ≥ 80% within ±1 on same-room test set | ≥ 90% within ±1 |
|
||||
| Cross-room (held-out environment) | ≥ 60% within ±1 | ≥ 75% within ±1 |
|
||||
| Mean Absolute Error | ≤ 0.6 persons | ≤ 0.4 persons |
|
||||
| Per-frame confidence reflects accuracy | Spearman correlation `r ≥ 0.5` between `confidence` and `(predicted == true)` | `r ≥ 0.7` |
|
||||
| Inference latency on Pi 5 (Cog) | < 5 ms / frame cold-start | < 5 ms / frame |
|
||||
| Binary size on GCS | ≤ 4 MB (matches `cog-pose-estimation`) | ≤ 4 MB |
|
||||
|
||||
`v0.1.0` is intentionally modest — it's bounded by data-collection scale (#645). The framework is the deliverable; the accuracy follows the data.
|
||||
|
||||
### Repo layout
|
||||
|
||||
```
|
||||
v2/crates/cog-person-count/ # NEW (this ADR)
|
||||
├── Cargo.toml
|
||||
├── src/
|
||||
│ ├── main.rs # cog runtime: version | manifest | health | run
|
||||
│ ├── lib.rs
|
||||
│ ├── inference.rs # Candle forward pass on per-node CSI
|
||||
│ ├── fusion.rs # Stoer-Wagner upper-bound + confidence-weighted log-sum
|
||||
│ └── publisher.rs # emits {count, confidence, count_p95_low, count_p95_high}
|
||||
├── cog/
|
||||
│ ├── manifest.template.json
|
||||
│ ├── config.schema.json
|
||||
│ ├── README.md
|
||||
│ └── artifacts/ # filled by the release pipeline
|
||||
│ ├── count_v1.safetensors
|
||||
│ ├── count_v1.onnx
|
||||
│ └── train_results.json
|
||||
└── tests/
|
||||
├── smoke.rs # 5+ tests
|
||||
└── fusion_test.rs # multi-node-fusion math
|
||||
```
|
||||
|
||||
Plus a small server-side wiring change:
|
||||
|
||||
- `v2/crates/wifi-densepose-sensing-server/src/csi.rs::score_to_person_count` — call the cog over the same `/api/v1/edge/registry`-discovered runtime as `cog-pose-estimation`. Falls back to today's PR #491 heuristic if the cog isn't installed (per the ADR-100 stub-fallback pattern).
|
||||
|
||||
## Consequences
|
||||
|
||||
### Positive
|
||||
|
||||
- Closes the conceptual loop opened by #499 — multi-person counting becomes a **learned task**, not a heuristic with a runtime knob.
|
||||
- Reuses every primitive already shipped this week: Candle GPU training (ADR-101), HF encoder, Cog packaging (ADR-100), edge module registry (ADR-102), Stoer-Wagner mincut, paired-data pipeline (PR #641).
|
||||
- Day-2 cross-room calibration uses the same LoRA path ADR-079 P9 plans for pose, so the two cogs share the same fine-tuning machinery.
|
||||
- Explicit `confidence` + `count_p95_low/high` outputs let the UI render uncertainty instead of inventing ghosts.
|
||||
|
||||
### Negative
|
||||
|
||||
- Accuracy is bounded by the same paired-data scarcity that bounds `pose_v1` (#645). Without more multi-room data, v0.1.0 ships with modest absolute accuracy.
|
||||
- Adds another Cog binary to maintain in the GCS catalog — 4 MB per arch.
|
||||
- The fusion-stage min-cut adds ~0.3 ms per N-node frame on a Pi 5 in microbenchmarks of `ruvector-mincut`. Acceptable given the ≤ 5 ms budget but worth tracking.
|
||||
|
||||
### Risks
|
||||
|
||||
- **Label noise**: MediaPipe pose-detection rate was 47% in the P7 session — half the frames have `n_persons = 0` even when a person was clearly in the room. The count head learns from this noisy signal; mitigations include filtering by `MediaPipe confidence ≥ 0.7` before training, and weighting the loss by confidence (same trick used in `pose_v1`).
|
||||
- **Encoder freezing too aggressive**: if 50 epochs of frozen-encoder training doesn't see the count head converge, unfreeze earlier. We have telemetry from `train_results.json` to make this call empirically.
|
||||
- **Min-cut over-constrains** in single-person scenarios: when N=1 the subcarrier graph has min-cut = 1 trivially. The fusion stage degrades to "trust the single-node count head", which is fine but worth a regression test (`tests/fusion_test.rs::single_node_degrades_gracefully`).
|
||||
|
||||
## Migration
|
||||
|
||||
1. Land this ADR + the new crate scaffold (one PR, no model yet — same approach as ADR-101's first PR shipped a stub cog).
|
||||
2. Train `count_v1.safetensors` on the existing 1,077 paired samples + `n_persons` labels. Same Candle pipeline that produced `pose_v1`.
|
||||
3. Cross-compile + sign + GCS upload per ADR-100. Live install on `cognitum-v0` per ADR-101's pattern.
|
||||
4. Wire `csi.rs::score_to_person_count` to call the cog when installed; keep PR #491's heuristic as fallback.
|
||||
5. v0.2.0: re-train on the multi-room data #645 motivates, add LoRA per-room adapters per ADR-079 P9.
|
||||
|
||||
## See also
|
||||
|
||||
- ADR-079 — Camera-supervised training pipeline (same data path).
|
||||
- ADR-100 — Cognitum Cog packaging spec (same shipping format).
|
||||
- ADR-101 — Pose Estimation Cog (template for this Cog's first release).
|
||||
- ADR-102 — Edge Module Registry (where this cog appears in the catalog).
|
||||
- PR #491 — RollingP95 + `dedup_factor` (the heuristic this learned counter replaces).
|
||||
- Issue #499 — Multi-node ghost skeletons (closed by #491, motivates this ADR).
|
||||
- Issue #645 — PCK / data-collection plan (same data-bound limit; same fix path).
|
||||
- `docs/benchmarks/pose-estimation-cog.md` — measured perf envelope for the cog runtime this ADR targets.
|
||||
@@ -1,263 +0,0 @@
|
||||
# ADR-104: RuView MCP Server + CLI Distribution
|
||||
|
||||
- **Status:** Accepted
|
||||
- **Date:** 2026-05-21
|
||||
- **Deciders:** ruv
|
||||
- **Related:** ADR-100 (Cog packaging), ADR-101 (pose cog), ADR-102 (edge registry), ADR-103 (count cog)
|
||||
- **Implementation:** `tools/ruview-mcp/`, `tools/ruview-cli/`
|
||||
|
||||
---
|
||||
|
||||
## Context
|
||||
|
||||
The Cognitum cog ecosystem ships binaries to appliances via a signed GCS catalog (ADR-100). The cogs themselves run inside `/var/lib/cognitum/apps/` on a Pi 5 or Pi+Hailo cluster node. This is the right deployment target for production inference — sub-5 ms per frame, Hailo hardware acceleration, offline operation.
|
||||
|
||||
However, three user classes need to interact with RuView capabilities **without owning a Cognitum appliance**:
|
||||
|
||||
1. **Developer agents** — Claude Code, Cursor, Codex instances that want to call `ruview_pose_infer` during a research session (e.g. the SOTA loop in `docs/research/sota-2026-05-22/PROGRESS.md`).
|
||||
2. **CI pipelines** — automated tests that want to assert "a synthetic CSI window produces a finite pose output" without a full appliance setup.
|
||||
3. **Shell scripts and researchers** — `npx ruview pose infer --window ./window.json` from any machine with Node 20, no Rust toolchain, no Cognitum account, no clone of this repo required.
|
||||
|
||||
The existing surface does not serve these users:
|
||||
- The sensing-server REST API (`/api/v1/sensing/latest`, `/api/v1/edge/registry`) is a Rust binary that requires building from source.
|
||||
- The cog binaries are signed Linux aarch64/x86_64 executables — no macOS/Windows builds, no `npx` entrypoint.
|
||||
- There is no MCP server — Claude Code cannot call RuView capabilities as tools without one.
|
||||
|
||||
This ADR defines two new distribution artifacts:
|
||||
- `@ruv/ruview-mcp` — an MCP server exposing RuView as tools.
|
||||
- `@ruv/ruview-cli` — a CLI exposing the same surface as `npx ruview <subcommand>`.
|
||||
|
||||
---
|
||||
|
||||
## Decision
|
||||
|
||||
### MCP server: `@ruv/ruview-mcp`
|
||||
|
||||
A Node 20 TypeScript package implementing the Model Context Protocol using `@modelcontextprotocol/sdk`. The server communicates over stdio (the standard MCP transport) and exposes six tools:
|
||||
|
||||
| Tool | Description | Backend |
|
||||
|------|-------------|---------|
|
||||
| `ruview_csi_latest` | Pull the latest CSI window from the sensing-server | GET /api/v1/sensing/latest (ADR-102) |
|
||||
| `ruview_pose_infer` | 17-keypoint COCO pose estimation on a CSI window | cog-pose-estimation binary (ADR-101) subprocess |
|
||||
| `ruview_count_infer` | Person count with calibrated confidence interval | cog-person-count binary (ADR-103) subprocess |
|
||||
| `ruview_registry_list` | List Cognitum cogs from the edge registry | GET /api/v1/edge/registry (ADR-102) |
|
||||
| `ruview_train_count` | Kick off a count-cog Candle training run | cargo run -p wifi-densepose-train subprocess |
|
||||
| `ruview_job_status` | Poll a background training job | reads ~/.ruview/jobs/<id>.log |
|
||||
|
||||
**Fail-open principle:** every tool returns `{ok: false, warn: true, error: "...", hint: "..."}` rather than throwing. This matches the pattern used by the Cog binaries (ADR-100 §"Failure modes") and ensures a broken sensing-server does not crash a research agent's session.
|
||||
|
||||
### CLI: `@ruv/ruview-cli`
|
||||
|
||||
The same surface as a Yargs-based CLI published to npm as `@ruv/ruview-cli` with the binary name `ruview`:
|
||||
|
||||
| Subcommand | Equivalent MCP tool |
|
||||
|------------|-------------------|
|
||||
| `ruview csi tail` | streaming poll of `ruview_csi_latest` |
|
||||
| `ruview pose infer [--window <path>]` | `ruview_pose_infer` |
|
||||
| `ruview count infer [--window <path>]` | `ruview_count_infer` |
|
||||
| `ruview cogs list [--category] [--search]` | `ruview_registry_list` |
|
||||
| `ruview train count --paired <jsonl>` | `ruview_train_count` |
|
||||
| `ruview job status --id <uuid>` | `ruview_job_status` |
|
||||
|
||||
All subcommands write JSON to stdout and exit 0 on success. WARN-level outputs (missing cog binary, unreachable sensing-server) go to stderr; exit code stays 0 so pipelines are not broken by transient unavailability.
|
||||
|
||||
### Inference backend: subprocess, not in-process
|
||||
|
||||
The MCP server and CLI **shell out** to the cog binaries rather than embedding a JS/WASM inference engine. Reasons:
|
||||
|
||||
1. The cog binaries are already signed, tested, and cross-compiled (ADR-100/101/103). Re-implementing inference in JS would duplicate that work and introduce a second model artifact to keep in sync.
|
||||
2. The cog binaries handle model loading, ONNX dispatch, and Hailo HEF routing transparently — the MCP layer needs only to understand the JSON event schema.
|
||||
3. For training, `cargo run -p wifi-densepose-train` is the proven path (2.1 s on RTX 5080, ADR-103). Replicating the Candle training loop in JS would be a significant engineering investment with no user benefit.
|
||||
|
||||
The npm packages therefore act as a **thin orchestration layer** over the existing Rust/cog infrastructure. No ML framework is bundled.
|
||||
|
||||
### ruvector library usage
|
||||
|
||||
Where a ruvector npm package provides the required capability, it is preferred over reimplementation. The subcarrier-saliency analysis in `examples/research-sota/r5_subcarrier_saliency.py` already depends on `ruvector-mincut` (Rust crate) for Stoer-Wagner min-cut. On the npm side:
|
||||
|
||||
- `@ruv/rvcsi` — the typed CSI frame schema and validation. When available at install time, `ruview_csi_latest` will validate incoming frames against the `rvcsi-core` schema. If not installed, falls back to opaque JSON passthrough.
|
||||
- HNSW, RaBitQ, and contrastive embedding primitives are Rust-native; the npm packages do not replicate them. Instead, `ruview_pose_infer` and `ruview_count_infer` delegate to the cog binary which embeds the Candle inference engine.
|
||||
|
||||
### Source layout
|
||||
|
||||
```
|
||||
tools/
|
||||
├── ruview-mcp/ # @ruv/ruview-mcp
|
||||
│ ├── package.json
|
||||
│ ├── tsconfig.json
|
||||
│ ├── jest.config.js
|
||||
│ ├── src/
|
||||
│ │ ├── index.ts # MCP server entry + tool registry
|
||||
│ │ ├── types.ts # shared domain types
|
||||
│ │ ├── config.ts # env-var config loader
|
||||
│ │ ├── http.ts # fetch wrapper with timeout + Result<T>
|
||||
│ │ ├── cog.ts # subprocess wrapper for cog binaries
|
||||
│ │ └── tools/
|
||||
│ │ ├── csi-latest.ts # ruview_csi_latest
|
||||
│ │ ├── pose-infer.ts # ruview_pose_infer
|
||||
│ │ ├── count-infer.ts # ruview_count_infer
|
||||
│ │ ├── registry-list.ts # ruview_registry_list
|
||||
│ │ └── train-count.ts # ruview_train_count + ruview_job_status
|
||||
│ └── tests/
|
||||
│ └── tools.test.ts # stub smoke tests (M1) + integration tests (M6)
|
||||
└── ruview-cli/ # @ruv/ruview-cli
|
||||
├── package.json
|
||||
├── tsconfig.json
|
||||
├── src/
|
||||
│ ├── index.ts # yargs CLI entry + command registration
|
||||
│ ├── config.ts # env-var config loader
|
||||
│ ├── http.ts # fetch wrapper
|
||||
│ ├── cog.ts # subprocess wrapper
|
||||
│ └── commands/
|
||||
│ ├── csi.ts # ruview csi tail
|
||||
│ ├── pose.ts # ruview pose infer
|
||||
│ ├── count.ts # ruview count infer
|
||||
│ ├── cogs.ts # ruview cogs list
|
||||
│ ├── train.ts # ruview train count
|
||||
│ └── job.ts # ruview job status
|
||||
└── tests/ # (M6)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Security
|
||||
|
||||
### Authentication
|
||||
|
||||
The sensing-server uses a Bearer token (`RUVIEW_API_TOKEN`) for all `/api/v1/*` routes when the token is configured. The MCP server and CLI propagate this token in the `Authorization` header for every sensing-server call. Token is sourced **only from environment variables** — never from CLI flags or tool arguments (which could appear in logs or agent histories).
|
||||
|
||||
The cog binaries are called as local subprocesses. No network authentication is involved in cog invocation — the binary is trusted by virtue of being installed on the local machine (and having passed Ed25519 signature verification at install time, per ADR-100).
|
||||
|
||||
### Threat table
|
||||
|
||||
| # | Threat | Mitigation |
|
||||
|---|--------|-----------|
|
||||
| **T1** | **MCP tool spoofing** — a malicious process registers a tool named `ruview_pose_infer` before the legitimate server and intercepts agent calls | MCP servers are registered by the operator in the Claude Code / Cursor config. The operator must explicitly `claude mcp add ruview -- node …`. Impersonation requires compromising the operator's shell config. |
|
||||
| **T2** | **CLI subcommand injection** — a caller passes a crafted `--paired` path containing shell metacharacters to escape the `cargo` invocation | All subprocess arguments are passed as an array (never through a shell string) via Node's `spawn(binary, args, {})` — no shell expansion. Path metacharacters cannot escape. |
|
||||
| **T3** | **Token leakage** — `RUVIEW_API_TOKEN` appears in process arguments, agent histories, or log files | Token is only used in the `Authorization` HTTP header, which is set programmatically. It is never printed, never passed as a CLI argument, and never written to `~/.ruview/jobs/<id>.log`. |
|
||||
| **T4** | **Model substitution** — an attacker replaces the cog binary with a malicious version | The cog binary must pass Ed25519 signature verification (`binary_sha256` + `binary_signature`) at install time per ADR-100. The MCP/CLI layer does not re-verify at invocation time — this is the cog-gateway's job. |
|
||||
| **T5** | **Output validation bypass** — cog returns malformed JSON and the MCP server forwards it without validation | `ruview_pose_infer` and `ruview_count_infer` parse cog stdout as JSON and validate the schema against `PoseInferResult` / `CountInferResult` types (Zod, M2+). On parse failure, return `{ok:false, error: "unexpected cog output: …"}`. |
|
||||
| **T6** | **Rate-limit bypass on `ruview_train_count`** — an agent calls `ruview_train_count` in a tight loop, spawning unbounded training processes | The MCP server maintains an in-process job registry. On `ruview_train_count`, if more than 3 jobs are `status:"running"`, return `{ok:false, error:"too many concurrent training jobs (max 3)"}`. Training jobs are CPU/GPU-bound and self-limit on the host. |
|
||||
|
||||
### What this ADR does NOT secure
|
||||
|
||||
- **MCP transport encryption** — MCP over stdio is process-local; no TLS is involved. If the MCP server is exposed over a TCP socket in future, TLS must be added.
|
||||
- **Cog binary authentication at invocation** — we trust the OS file permissions and the at-install-time signature check (ADR-100). If a binary is replaced after install, the MCP layer will not detect it.
|
||||
- **Multi-tenant token isolation** — the server process serves all connected clients under a single token. Multi-user deployments must run one MCP server instance per user.
|
||||
|
||||
---
|
||||
|
||||
## Packaging
|
||||
|
||||
### Version alignment
|
||||
|
||||
The npm package versions track the cog crate versions:
|
||||
- `@ruv/ruview-mcp@0.0.1` ships when `cog-pose-estimation@0.0.1` + `cog-person-count@0.0.2` are on GCS.
|
||||
- Semver: major bump when the MCP tool schema changes (breaking for calling agents); minor for new tools; patch for bug fixes.
|
||||
|
||||
### npm package configuration
|
||||
|
||||
Both packages are published to the public npm registry under the `@ruv` scope:
|
||||
|
||||
```
|
||||
@ruv/ruview-mcp — npm install -g @ruv/ruview-mcp (then: ruview-mcp)
|
||||
@ruv/ruview-cli — npm install -g @ruv/ruview-cli (then: ruview --version)
|
||||
```
|
||||
|
||||
The `bin` entry in `package.json` points to `dist/index.js` (compiled from TypeScript). Both packages target Node 20 (`"engines": {"node": ">=20.0.0"}`).
|
||||
|
||||
`private: true` is set during development; **the user must flip this to `false` before publishing** (or delete the field). The `publishConfig.access: "public"` is already set.
|
||||
|
||||
### MCP registration
|
||||
|
||||
After installing (global or npx):
|
||||
|
||||
```bash
|
||||
# Via npx (no install required):
|
||||
claude mcp add ruview -- npx @ruv/ruview-mcp
|
||||
|
||||
# Via global install:
|
||||
npm install -g @ruv/ruview-mcp
|
||||
claude mcp add ruview -- ruview-mcp
|
||||
|
||||
# Verify:
|
||||
claude mcp list # should show "ruview"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Distribution
|
||||
|
||||
`npx ruview …` works from any machine with Node 20 installed. No clone of this repository, no Rust toolchain, no Cognitum appliance is required to run the CLI commands that do not depend on a cog binary (e.g. `ruview cogs list` only needs a sensing-server URL).
|
||||
|
||||
For commands that call a cog binary (`ruview pose infer`, `ruview count infer`), the cog binary must be downloaded from GCS and placed in a directory on `PATH` or pointed to via `RUVIEW_POSE_COG_BINARY` / `RUVIEW_COUNT_COG_BINARY`. The download URL follows ADR-100 naming:
|
||||
|
||||
```
|
||||
https://storage.googleapis.com/cognitum-apps/cogs/x86_64/cog-pose-estimation-x86_64
|
||||
https://storage.googleapis.com/cognitum-apps/cogs/arm/cog-pose-estimation-arm
|
||||
https://storage.googleapis.com/cognitum-apps/cogs/x86_64/cog-person-count-x86_64
|
||||
https://storage.googleapis.com/cognitum-apps/cogs/arm/cog-person-count-arm
|
||||
```
|
||||
|
||||
A future `ruview install cogs` subcommand can automate this download + chmod + PATH placement.
|
||||
|
||||
---
|
||||
|
||||
## Failure modes
|
||||
|
||||
| Scenario | Behaviour |
|
||||
|---|---|
|
||||
| Sensing-server not running | `ruview_csi_latest` / `ruview_registry_list` return `{ok:false, warn:true, error:"…", hint:"…"}`. Exit code 0 on CLI. MCP tool returns isError:false (it's a warn, not a crash). |
|
||||
| Cog binary not installed | `ruview_pose_infer` / `ruview_count_infer` return `{ok:false, warn:true, error:"…", hint:"…"}` with install instructions. |
|
||||
| Cog binary returns non-zero | Propagated as `{ok:false, error:"Cog exited with code N. stderr: …"}`. |
|
||||
| Training job crashes immediately | Log file records `# exit code: <N>`. `ruview_job_status` returns `{status:"failed", recent_log:[…]}`. |
|
||||
| MCP server process dies mid-session | In-process job registry is lost. Jobs that were running continue in background (detached); operator reads log files directly. |
|
||||
| Node < 20 | `fetch` is unavailable. The CLI prints a clear error: "Node 20+ required for built-in fetch". |
|
||||
|
||||
---
|
||||
|
||||
## Acceptance gates
|
||||
|
||||
| Gate | Test |
|
||||
|------|------|
|
||||
| `npx ruview --version` works | `ruview --version` prints `0.0.1` and exits 0. |
|
||||
| `ruview_pose_infer` returns finite output for synthetic CSI | M2 integration test: spawn MCP server, call tool with a synthetic window JSON, assert `result.n_persons >= 0` and all keypoint values in `[0, 1]`. |
|
||||
| MCP server passes `claude mcp list` check | `claude mcp add ruview -- node dist/index.js && claude mcp list` shows `ruview` with 6 tools. |
|
||||
| `npm run build` clean in both packages | TypeScript compilation exits 0, no errors. |
|
||||
| Stub smoke tests pass (M1) | `npm test` in `tools/ruview-mcp/` passes all 6 stub tests. |
|
||||
| Integration tests pass (M6) | 6 tool calls with mocked sensing-server + real node binary as cog stub all return `{ok: true}`. |
|
||||
|
||||
---
|
||||
|
||||
## Migration / rollout
|
||||
|
||||
1. **This PR** — land scaffold (`tools/ruview-mcp/`, `tools/ruview-cli/`) + ADR-104. Both packages at `private: true`.
|
||||
2. **M2** — wire real inference: sensing-server CSI window → cog subprocess → parsed output. Remove `stub: true` from responses.
|
||||
3. **M3** — wire `ruview_csi_latest` + `ruview_registry_list` with live sensing-server round-trip test.
|
||||
4. **M4** — wire `ruview_train_count` with real cargo invocation; verify job log populates.
|
||||
5. **M6** — integration tests green. Update acceptance gates.
|
||||
6. **User publish step** — flip `private` from `true` to `false` in both `package.json` files, then:
|
||||
|
||||
```bash
|
||||
# Publish MCP server:
|
||||
cd tools/ruview-mcp
|
||||
npm version patch # or minor/major per semver
|
||||
npm publish --access public
|
||||
|
||||
# Publish CLI:
|
||||
cd tools/ruview-cli
|
||||
npm version patch
|
||||
npm publish --access public
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## See also
|
||||
|
||||
- ADR-100: Cognitum Cog Packaging Specification — the signing + GCS distribution model this ADR sits on top of.
|
||||
- ADR-101: Pose Estimation Cog — the binary invoked by `ruview_pose_infer`.
|
||||
- ADR-102: Edge Module Registry — the `/api/v1/edge/registry` endpoint used by `ruview_registry_list`.
|
||||
- ADR-103: Learned Multi-Person Counter Cog — the binary invoked by `ruview_count_infer`.
|
||||
- `docs/research/sota-2026-05-22/PROGRESS.md` — the SOTA research loop that motivated the MCP server.
|
||||
- `v2/crates/cog-pose-estimation/` — Rust source for the pose-estimation cog.
|
||||
- `v2/crates/cog-person-count/` — Rust source for the person-count cog.
|
||||
@@ -1,172 +0,0 @@
|
||||
# ADR-105: Federated learning for RuView CSI personalization
|
||||
|
||||
**Status:** Proposed · **Date:** 2026-05-22 · **Author:** SOTA research loop tick-13 · **Supersedes:** none
|
||||
|
||||
## Context
|
||||
|
||||
RuView's per-occupant features (R14 empathic appliances, R3 cross-room re-ID, R8 per-person counting) require **personalised models** that learn the household's specific subjects, motion patterns, and environmental quirks. Personalisation requires training data, but the privacy framework from R14 + R3 explicitly forbids sending raw CSI off-device:
|
||||
|
||||
1. R14 — *data stays on-device; only aggregate state passes integration boundaries*
|
||||
2. R3 — *no cross-installation linkage of embeddings*
|
||||
|
||||
These constraints rule out centralised training on user CSI. The standard answer is **federated learning** (McMahan 2017): each device trains locally; only model deltas (gradients or weight updates) leave the device.
|
||||
|
||||
CSI has three properties that change the standard FedAvg recipe:
|
||||
|
||||
1. **Non-IID data.** Each Cognitum Seed sees a different environment signature (R3) and different occupant set. Naive FedAvg drifts toward the most-represented environment.
|
||||
2. **High-bandwidth raw data.** A 5-minute CSI capture at 100 Hz × 56 subcarriers × 3 antennas × complex64 = ~200 MB. Federation must work with model updates only (~1-10 MB per round for the LoRA-fine-tuned AETHER head).
|
||||
3. **Adversarial node risk.** A compromised seed can poison the global model via crafted updates. R7's mincut multi-link adversarial detection extends to update-level voting.
|
||||
|
||||
This ADR specifies the federation protocol.
|
||||
|
||||
## Decision
|
||||
|
||||
Adopt **MERIDIAN-FedAvg with byzantine-robust aggregation** as the RuView federated training protocol.
|
||||
|
||||
### Protocol summary
|
||||
|
||||
1. **Round initiation.** Coordinator (cognitum-v0 fleet manager) selects K healthy nodes for round T, sends global model checkpoint W_T.
|
||||
2. **Local training.** Each node N_i loads W_T, fine-tunes its AETHER head on its local data for `local_epochs` epochs. Local data is **never** transmitted off-device.
|
||||
3. **MERIDIAN normalisation.** Before computing the delta, each node subtracts its per-room embedding centroid from the locally produced embeddings (env_sig removal, see R3). This makes deltas environment-agnostic.
|
||||
4. **Delta compression.** Compute ΔW_i = W_T+1_i − W_T. Quantise to int8 + LoRA-rank decomposition (rank=8) → ~1 MB per delta.
|
||||
5. **Byzantine-robust aggregation.** Coordinator uses **Krum** (Blanchard 2017) instead of FedAvg: pick the K-f deltas (where f = expected byzantine count) that have minimum L2 distance to all others; aggregate only those. Cuts off outliers that suggest poisoning.
|
||||
6. **Multi-link consistency check (R7 extension).** Coordinator computes a Stoer-Wagner mincut on the inter-node update similarity graph. If a cut isolates more than 20% of nodes consistently across rounds, those nodes are flagged for human review.
|
||||
7. **Global update.** W_T+1 = W_T + lr_global · Krum_aggregate(ΔW_i).
|
||||
8. **Convergence check.** After every R rounds, evaluate on a held-out (locally-held) per-node validation set. Federation stops when held-out accuracy plateaus.
|
||||
|
||||
### Update frequency
|
||||
|
||||
| Cog | Suggested federation frequency | Reason |
|
||||
|---|---|---|
|
||||
| `cog-person-count` (R8/R5 work) | Weekly | Counting model is well-trained; only need updates when household composition shifts |
|
||||
| AETHER re-ID head (R3) | Daily | Re-ID drifts with seasonal multipath changes |
|
||||
| `cog-pose-estimation` | Monthly | Base pose is stable; finetune only for new room geometries |
|
||||
| `cog-maritime-watch` (R11) | Per-vessel-deployment | Vessel motion regimes vary; ship-specific fine-tune |
|
||||
|
||||
### Bandwidth analysis
|
||||
|
||||
Per round (typical RuView 4-seed installation):
|
||||
|
||||
| Phase | Bytes per node | Total |
|
||||
|---|---:|---:|
|
||||
| Coordinator → node: global checkpoint | 8 MB | 4 × 8 = 32 MB (multicast: 8 MB) |
|
||||
| Local training (no transmission) | 0 | 0 |
|
||||
| Node → coordinator: int8+LoRA delta | 1 MB | 4 × 1 = **4 MB** |
|
||||
| Aggregation + push: new global checkpoint | 8 MB | 8 MB |
|
||||
| **Total per round** | ~ 5 MB / node | **~12-44 MB** |
|
||||
|
||||
At weekly cadence × 4-week month, that's ~50-180 MB / month / installation. **Well under** typical home broadband caps (300 GB/month standard cap = 0.06% of bandwidth budget).
|
||||
|
||||
### Required SDK / infrastructure
|
||||
|
||||
- **AgentDB hierarchical store** (already in repo) — per-node embedding centroid storage.
|
||||
- **ruvllm-microlora** (already in repo) — LoRA-rank decomposition of deltas.
|
||||
- **cognitum-fleet** service on cognitum-v0 (port 9002, see CLAUDE.local.md) — coordinator role.
|
||||
- **NEW: `ruview-fed` crate** — protocol implementation, ~500 lines Rust, library only (no daemon).
|
||||
|
||||
## Alternatives considered
|
||||
|
||||
### A. Centralised training on user CSI
|
||||
|
||||
Status: **rejected**. Violates R14 (data stays on-device) and R3 (no cross-installation linkage).
|
||||
|
||||
### B. FedAvg without byzantine-robust aggregation
|
||||
|
||||
Status: **rejected**. A single compromised seed can shift the global model arbitrarily. R7 mincut adversarial work showed this is a real attack surface; Krum (or any byzantine-robust replacement) is required.
|
||||
|
||||
### C. Federation across installations (not just within)
|
||||
|
||||
Status: **deferred to a future ADR**. Cross-installation federation requires:
|
||||
- Cryptographic embedding-space alignment (so that "person A in install X" and "person A in install Y" have unifiable signatures)
|
||||
- Stronger consent framework (cross-installation = legal-entity boundary per R3)
|
||||
- Differential privacy guarantees on deltas
|
||||
|
||||
A worked design needs ~6 person-months of legal + crypto work. Not in scope for this ADR.
|
||||
|
||||
### D. Pure on-device per-installation training (no federation)
|
||||
|
||||
Status: **alternative path for small deployments**. A single-seed installation has no peers to federate with. Use on-device-only fine-tune of pre-trained base model. The federation protocol gracefully degrades to "no federation = local training only".
|
||||
|
||||
## Threat model
|
||||
|
||||
| Threat | Mitigation (within this ADR) |
|
||||
|---|---|
|
||||
| Compromised seed poisons global model | Krum aggregation + mincut consistency check (R7) |
|
||||
| Coordinator (cognitum-v0) compromised | Multi-coordinator fallback; signed model checkpoints (Ed25519, ADR-100 pattern) |
|
||||
| Eavesdropper recovers training data from deltas | LoRA rank-8 + int8 quantisation is information-theoretically lossy; differential privacy noise (σ=0.01) on deltas if higher assurance needed |
|
||||
| Adversarial training signal injection (via crafted CSI) | R7 multi-link consistency (across antennas in same seed) catches this; federated mincut adds inter-seed consistency layer |
|
||||
| Member inference attack on the trained model | LoRA + DP-SGD on local training, see future ADR-106 for the formal DP budget |
|
||||
|
||||
## Consequences
|
||||
|
||||
### Positive
|
||||
|
||||
1. RuView personalisation becomes possible **without** violating R14/R3 privacy constraints.
|
||||
2. Bandwidth budget is trivially affordable (~50-180 MB/month/installation).
|
||||
3. R7 mincut extends naturally to update-level federation defence.
|
||||
4. The protocol is **graceful** — single-seed installations get local-only training; multi-seed installations get federation; no code path differences for the cog implementation.
|
||||
5. **Independent of cog**: this ADR specifies the protocol, individual cogs implement local training using their own model architecture. `cog-pose`, `cog-count`, AETHER head, future cogs all use the same federation surface.
|
||||
|
||||
### Negative
|
||||
|
||||
1. Adds ~500 lines of new Rust code (the `ruview-fed` crate).
|
||||
2. Krum is O(K²) in nodes — fine for K ≤ 50 (typical RuView installation), expensive for K > 1000 (not a target).
|
||||
3. Adds a coordinator dependency — cognitum-v0 fleet manager becomes a federation bottleneck. The multi-coordinator-fallback mitigation adds complexity.
|
||||
4. Cross-installation federation **explicitly deferred** to a future ADR — small installations stay isolated for now.
|
||||
5. Doesn't address member inference attacks; ADR-106 needed for that.
|
||||
|
||||
### Bridge to existing ADRs
|
||||
|
||||
- **ADR-024 (AETHER):** within-room embedding training stays unchanged; federation just shares the head weights.
|
||||
- **ADR-027 (MERIDIAN):** the env-centroid subtraction is now a **mandatory** pre-aggregation step, not just an evaluation-time trick.
|
||||
- **ADR-029 (multistatic):** federation per-seed; multistatic geometry remains a per-installation property and is not federated.
|
||||
- **ADR-100 (cog packaging):** federation operates on cog binaries; the Ed25519 signing infrastructure from ADR-100 covers checkpoint integrity.
|
||||
- **ADR-103 (cog-person-count):** the v0.0.2 retrained model from this loop's earlier work would be the first cog to use the federation protocol — once `ruview-fed` ships.
|
||||
- **ADR-104 (ruview-mcp + ruview-cli):** federation status surfaces as MCP tools (`ruview_fed_status`, `ruview_fed_pause`) — out of scope for this ADR but in the natural MCP roadmap.
|
||||
|
||||
## Implementation plan
|
||||
|
||||
| Step | Owner | LOC | Notes |
|
||||
|---|---|---:|---|
|
||||
| 1. `ruview-fed` crate scaffold | TBD | 100 | Workspace member, no external deps initially |
|
||||
| 2. Krum aggregator | TBD | 80 | Pure Rust, no GPU |
|
||||
| 3. LoRA+int8 delta codec | TBD | 120 | Reuse ruvllm-microlora |
|
||||
| 4. MERIDIAN centroid hook | TBD | 50 | Extend AgentDB hierarchical store |
|
||||
| 5. Inter-seed mincut consistency | TBD | 100 | Reuse ruvector-mincut |
|
||||
| 6. CLI surface (`wifi-densepose-cli fed status / fed pause`) | TBD | 80 | Add to existing CLI |
|
||||
| 7. End-to-end test on 4-seed cognitum-cluster (the Pi+Hailo fleet from CLAUDE.local.md) | TBD | — | Real-hardware test |
|
||||
|
||||
Total ~500 lines + tests. A reasonable 2-week effort once `ruview-fed` is unblocked.
|
||||
|
||||
## What this DOES NOT cover
|
||||
|
||||
1. **Cross-installation federation** — deferred to a future ADR (legal + DP work).
|
||||
2. **Member inference defence** — ADR-106 will cover formal DP-SGD on local training.
|
||||
3. **Cog-specific training-loop details** — each cog implements its own `local_train()`; ADR-105 only specifies the wire format and aggregation rules.
|
||||
4. **Compute scheduling** — when training runs, how it shares hardware with inference, etc. Cognitum fleet manager territory.
|
||||
|
||||
## Negative results we built on
|
||||
|
||||
This ADR's threat model and update-level mincut design are direct outputs of the loop's two negative results:
|
||||
|
||||
- **R12 (eigenshift)** — naive structure-detection failed; informed the byzantine-robust aggregation choice (don't trust outlier updates).
|
||||
- **R13 (contactless BP)** — physics-floor scrutiny pattern applied here to update-level threats (compute SNR for poisoning detection).
|
||||
|
||||
## Connection back to research-loop threads
|
||||
|
||||
- **R3 (cross-room re-ID):** MERIDIAN normalisation requirement is direct.
|
||||
- **R7 (mincut adversarial):** Stoer-Wagner mincut extends from multi-link CSI consistency to multi-node update consistency.
|
||||
- **R8 / R5:** first cog to use the federation protocol once `ruview-fed` ships.
|
||||
- **R11 (maritime):** per-vessel-deployment fine-tune cadence accommodated.
|
||||
- **R14 (empathic appliances):** privacy framework's "data stays on-device" baseline is now operational.
|
||||
|
||||
## Decision-making record
|
||||
|
||||
- 2026-05-22 06:13 UTC — drafted by SOTA research loop tick-13 based on R3 + R7 + R14 + R6 synthesis. Status: Proposed.
|
||||
- Pending: review by security-architect, ddd-domain-expert (federation = bounded context), production-validator (the 500 LOC budget claim needs sanity check).
|
||||
|
||||
## Honest scope of this ADR
|
||||
|
||||
- The bandwidth numbers assume LoRA rank-8 + int8 quantisation. Real implementations may need higher rank for AETHER to converge, increasing bandwidth by 4-8×. Still well within home broadband.
|
||||
- Krum is byzantine-robust against `f < (K-2)/2` byzantine nodes. For K=4, that means 1 byzantine; for K=10, 4. RuView installations rarely have K>10 seeds, so the practical bound is ~4 byzantine.
|
||||
- The "1-2 weeks of effort" claim for implementation assumes the existing AgentDB + ruvllm-microlora + ruvector-mincut crates are stable. If any of those need rework, the federation work blocks behind that.
|
||||
@@ -1,193 +0,0 @@
|
||||
# ADR-106: Differential privacy + biometric primitive isolation for RuView federated training
|
||||
|
||||
**Status:** Proposed · **Date:** 2026-05-22 · **Author:** SOTA research loop tick-15 · **Supersedes:** none · **Extends:** ADR-105
|
||||
|
||||
## Context
|
||||
|
||||
ADR-105 specified federated learning for RuView CSI personalisation with MERIDIAN env-normalisation + Krum byzantine-robust aggregation + R7-style update-level mincut. It deferred two questions:
|
||||
|
||||
1. **Member inference defence.** A sufficiently capable adversary observing many model deltas across rounds can in principle reconstruct training samples (Shokri 2017). ADR-105 left "DP-SGD" as a future ADR.
|
||||
2. **Biometric primitive isolation.** R15 catalogued five environment-invariant biometric primitives (gait frequency, breathing rate, HRV rate, RCS frequency response, walking dynamics). R15 said: the federation aggregator MUST NOT receive any raw per-subject biometric primitive. ADR-105 didn't yet specify which primitives qualify.
|
||||
|
||||
This ADR closes both. It is a direct extension of ADR-105 and incorporates the constraints from R3 (re-ID privacy) + R14 (empathic appliance privacy) + R15 (RF biometric physical-not-learned identification).
|
||||
|
||||
## Decision
|
||||
|
||||
Adopt **DP-SGD with explicit primitive-isolation enforcement** on every Cognitum Seed before any model delta leaves the device.
|
||||
|
||||
### Three-layer defence
|
||||
|
||||
**Layer 1 — Primitive Isolation (R15 binding constraint).** A static list of "on-device-only" biometric primitives. The federation client library enforces that these tensors are never serialised into a transmittable update.
|
||||
|
||||
| Primitive | On-device only | Reason |
|
||||
|---|:---:|---|
|
||||
| Raw CSI window (complex64 tensor) | ✅ | ADR-105 baseline |
|
||||
| Gait stride frequency (Hz scalar per subject) | ✅ | R15 — biometric primitive |
|
||||
| Breathing rate (BPM scalar per subject) | ✅ | R15 — biometric primitive |
|
||||
| HRV rate signature (R-R interval array per subject) | ✅ | R15 — biometric primitive |
|
||||
| RCS frequency response curve (per subject, per-subcarrier amplitude) | ✅ | R15 — biometric primitive |
|
||||
| Limb timing vector (per subject, per stride) | ✅ | R15 — biometric primitive |
|
||||
| Per-subject embedding centroid | ✅ | R3 + ADR-105 — re-ID primitive |
|
||||
| MERIDIAN per-room centroid | ⚠️ | Aggregate over **all** subjects in the room — not per-subject |
|
||||
| LoRA weight delta | ⚠️ | Encodes biometric information; mitigated by Layer 2 + Layer 3 |
|
||||
| Model logits / softmax outputs | ⚠️ | Per-subject during inference; never aggregated for transmission |
|
||||
| Coordinator-side aggregate model | ❌ | Distributed back to nodes; no per-subject content by construction |
|
||||
|
||||
The ✅ rows are enforced at the API surface — the federation client returns an error if a tensor with these tags is passed to `submit_delta()`.
|
||||
|
||||
**Layer 2 — Gradient clipping.** Before any LoRA weight delta is computed for transmission, individual sample gradients are clipped to L2 norm `C` (standard DP-SGD step, Abadi 2016). This bounds the sensitivity of the released delta to any single training sample.
|
||||
|
||||
Recommended: `C = 1.0` (after experimentation per-cog; some cogs may need `C ∈ [0.5, 2.0]`).
|
||||
|
||||
**Layer 3 — Gaussian noise on aggregated deltas.** Before transmission to the coordinator, Gaussian noise `N(0, σ²C²I)` is added to the aggregated LoRA delta. This bounds the per-round privacy leakage.
|
||||
|
||||
### Privacy budget
|
||||
|
||||
Using the **Moments Accountant** (Abadi 2016) for (ε, δ)-DP across federation rounds:
|
||||
|
||||
| Configuration | Per-round σ | Rounds | Total ε (δ=1e-5) | Verdict |
|
||||
|---|---:|---:|---:|---|
|
||||
| Conservative (medical-grade) | 1.5 | 50 | **2.0** | Strong; matches HIPAA-aligned recommendations |
|
||||
| Standard (typical RuView) | 1.0 | 100 | **5.0** | Strong; consistent with Google's federated keyboard work |
|
||||
| Lenient (faster convergence) | 0.5 | 100 | **8.0** | Moderate; below ε=10 community soft-bound |
|
||||
|
||||
Recommended **starting σ = 1.0** for most RuView cogs, with per-cog tuning:
|
||||
|
||||
- `cog-person-count` (R8 — simple classifier): σ=1.0 sufficient.
|
||||
- AETHER re-ID head (R3 — high discriminability needed): σ=0.7 with C=1.5 to preserve discriminative power.
|
||||
- `cog-pose-estimation` (skeleton output): σ=1.0.
|
||||
- `cog-maritime-watch` (R11): σ=1.5 (medical-grade — vessel crew vitals).
|
||||
|
||||
### Composition with ADR-105 protocol
|
||||
|
||||
The DP-SGD layer slots in at step 4 of ADR-105's protocol summary:
|
||||
|
||||
> 4. **Delta compression.** Compute ΔW_i = W_T+1_i − W_T. **[NEW: clip individual-sample gradients to L2 norm C=1.0 during local training; add Gaussian noise N(0, σ²C²I) to ΔW_i with σ from per-cog table above.]** Quantise to int8 + LoRA-rank decomposition (rank=8) → ~1 MB per delta.
|
||||
|
||||
Krum byzantine-robust aggregation (step 5) operates on DP-noised deltas without modification — Krum's distance metric is robust to additive Gaussian noise at typical σ values.
|
||||
|
||||
### Implementation enforcement
|
||||
|
||||
The `ruview-fed` crate (per ADR-105 implementation plan, ~500 LOC) gains:
|
||||
|
||||
| Component | LOC | Purpose |
|
||||
|---|---:|---|
|
||||
| `PrimitiveTag` enum + tensor tagging trait | 60 | Layer 1 primitive isolation |
|
||||
| `clip_gradient_l2(C)` helper | 30 | Layer 2 clipping |
|
||||
| `add_dp_noise(sigma, C)` helper | 40 | Layer 3 Gaussian noise |
|
||||
| `MomentsAccountant` | 120 | (ε, δ) tracking across rounds; aborts federation if budget exceeded |
|
||||
| Per-cog config schema | 50 | σ, C, max rounds budget |
|
||||
|
||||
Total ~300 additional LOC on top of ADR-105's 500. Federation protocol implementation budget revised to ~800 LOC total.
|
||||
|
||||
## Alternatives considered
|
||||
|
||||
### A. Federated learning without DP
|
||||
|
||||
Status: **rejected.** ADR-105's Krum + LoRA + int8 quantisation provides *some* implicit privacy, but it's not a formal guarantee. Member-inference attacks (Shokri 2017) recover training samples from undefended FL. We need a formal (ε, δ)-DP bound.
|
||||
|
||||
### B. Local DP (LDP) only
|
||||
|
||||
Status: **rejected.** LDP would add noise per-sample at the device, then the coordinator gets noisy aggregates. This gives stronger guarantees but degrades model accuracy by 5-15× for the same ε. Central DP (CDP) with byzantine-robust aggregation is the right trade-off for our threat model where the coordinator is trusted to apply noise correctly (the coordinator is `cognitum-v0` fleet manager, under installation owner's control per ADR-100 signing).
|
||||
|
||||
### C. Heavier obfuscation (homomorphic encryption / secure aggregation)
|
||||
|
||||
Status: **deferred.** Secure aggregation (Bonawitz 2016) avoids the coordinator ever seeing individual deltas, only their sum. This is the right next layer for cross-installation federation (ADR-105 explicitly deferred). For within-installation federation where the coordinator is owner-controlled, the gains don't justify the 5-10× compute and complexity cost.
|
||||
|
||||
### D. Just-trust-Krum
|
||||
|
||||
Status: **rejected.** Krum defends against adversarial nodes, not adversarial *inference*. A passive coordinator (even an honest one) plus moderate compute can extract training samples from undefended deltas. DP-SGD is the proper defence.
|
||||
|
||||
## Threat model
|
||||
|
||||
| Threat | Layer that mitigates |
|
||||
|---|---|
|
||||
| Compromised seed reads its own local biometric primitives | Out of scope — physical compromise = full local compromise |
|
||||
| Compromised seed exfiltrates a biometric primitive via the federation channel | **Layer 1** — primitive isolation API blocks transmission |
|
||||
| Passive coordinator reconstructs training samples from observed deltas (Shokri 2017) | **Layer 2 + 3** — DP-SGD bounds reconstruction quality |
|
||||
| Member inference attack on the trained model (Shokri 2017 §3.2) | **Layer 2 + 3** — formal (ε, δ) bound |
|
||||
| Coordinator + 1 colluding seed | **Krum (ADR-105)** still works; DP-SGD bounds the colluder's info gain |
|
||||
| Brute-force gradient inversion (Zhu 2019) | **Layer 2 + 3** — clipping + noise defeats gradient-from-update attack |
|
||||
| Active adversary controlling >f Krum nodes | Out of scope — ADR-105 byzantine bound f < (K-2)/2 |
|
||||
| Side-channel via inference latency | Out of scope — separate ADR (constant-time inference) |
|
||||
|
||||
## Consequences
|
||||
|
||||
### Positive
|
||||
|
||||
1. RuView federation is now **formally privacy-preserving** with a documented (ε, δ) bound — meets GDPR Art 25 ("data protection by design") technical-measure expectations.
|
||||
2. R15's biometric-primitive constraints are enforced at the API surface, not just policy-documented.
|
||||
3. The threat model has been written down with explicit mitigations per row, making future security review tractable.
|
||||
4. The Moments Accountant aborts federation rather than silently consuming budget — operationally safer than naive "just keep training".
|
||||
|
||||
### Negative
|
||||
|
||||
1. DP noise degrades model accuracy by ~3-8% (typical figures from DP-SGD literature; per-cog tuning needed). For `cog-person-count` v0.0.2 (this loop's earlier work), the baseline 34.3% class-1 accuracy would degrade to ~31-33% with σ=1.0.
|
||||
2. Adds ~300 LOC + Moments Accountant complexity to `ruview-fed`. Total federation budget revised to ~800 LOC.
|
||||
3. Per-cog tuning of (σ, C, max_rounds) is needed — not a one-size-fits-all.
|
||||
4. Doesn't defend against side-channel inference latency leaks; that's a separate ADR.
|
||||
5. Doesn't address cross-installation federation; cross-installation work still requires the deferred ADR (secure aggregation + DP).
|
||||
|
||||
### Open questions intentionally left
|
||||
|
||||
1. **Per-cog DP budget allocation.** The σ values above are first-cut recommendations; empirical tuning per cog is needed before shipping.
|
||||
2. **Moments Accountant restart policy.** What happens after we exceed ε? Reset model and restart? Stop federation indefinitely? Decision deferred to operations.
|
||||
3. **Side-channel timing leaks.** A separate ADR (TBD) needs to cover constant-time inference and constant-time DP-noise sampling.
|
||||
4. **Subject-level vs sample-level DP.** This ADR specifies sample-level. Subject-level DP (preventing inference of "is subject X in the training set") needs `K_subjects × privacy_amplification` — discussed in next-generation work.
|
||||
|
||||
## Bridge to existing ADRs
|
||||
|
||||
- **ADR-024 (AETHER)** — within-room training stays unchanged; DP-SGD applies at the federation layer.
|
||||
- **ADR-027 (MERIDIAN)** — env-centroid subtraction is per-room aggregate, not per-subject — survives Layer 1 isolation as an ⚠️ entry (aggregate is acceptable).
|
||||
- **ADR-029 (multistatic)** — per-seed federation; multistatic geometry stays per-installation.
|
||||
- **ADR-100 (cog packaging)** — Ed25519 signing covers DP-noised checkpoints with no protocol change.
|
||||
- **ADR-103 (cog-person-count)** — first cog with formal DP guarantee; this loop's v0.0.2 retrain becomes ADR-106-compliant on next training cycle.
|
||||
- **ADR-104 (ruview-mcp + ruview-cli)** — exposes ε, δ budget remaining via MCP `ruview_fed_privacy_budget` (future tool; out of scope for this ADR).
|
||||
- **ADR-105 (federated training)** — DP-SGD slots into step 4; threat model extended; implementation budget grows from 500 to ~800 LOC.
|
||||
|
||||
## Connection to research-loop threads
|
||||
|
||||
- **R3 (cross-room re-ID)** — Layer 1 isolation blocks transmission of per-subject embedding centroids.
|
||||
- **R7 (mincut adversarial)** — Krum (from ADR-105) + DP-noised deltas remain compatible; mincut adversarial check operates on the noised similarity graph.
|
||||
- **R12 (eigenshift NEGATIVE)** — informed by the structure-detection failure pattern; the DP-noise approach treats adversarial deltas as "outliers from a noisy distribution" rather than as a structural-detection problem.
|
||||
- **R13 (contactless BP NEGATIVE)** — confirms why we restrict biometric primitive transmission: contour-level signals don't meet the 25 dB floor, so they wouldn't help downstream models anyway; rate-level primitives are sufficient for V1/V2/V3 features.
|
||||
- **R14 (empathic appliances)** — privacy framework constraints now have a formal (ε, δ) backing.
|
||||
- **R15 (RF biometric primitives)** — direct requirements basis; the on-device-only primitive list is R15's catalogue made executable.
|
||||
|
||||
## Honest scope
|
||||
|
||||
- **σ values are recommendations**, not measurements. Per-cog empirical tuning is needed (cog-pose, cog-count, AETHER head, future cogs each get their own).
|
||||
- **(ε, δ)-DP is a worst-case bound.** Real privacy depends on the auxiliary information the adversary has. For an adversary with extensive auxiliary biometric data, even a small ε can leak. Layer 1 primitive isolation is the harder constraint that doesn't depend on the auxiliary-info model.
|
||||
- **The Moments Accountant** treats each round as independent, which slightly over-estimates the budget consumed (good — conservative). Tighter accountants (Rényi DP, PRV) would let us run more rounds for the same ε.
|
||||
- **Subject-level DP is not formalised here.** Many use cases (a household of 4 always-the-same individuals) effectively have K=4 subjects, where sample-level DP doesn't fully capture the subject-level risk.
|
||||
|
||||
## Implementation plan (additive to ADR-105)
|
||||
|
||||
| Step | LOC | Notes |
|
||||
|---|---:|---|
|
||||
| 1. PrimitiveTag enum + tensor tagging | 60 | Compile-time enforcement where possible |
|
||||
| 2. Gradient clipping helper | 30 | Per-sample (microbatch-friendly) |
|
||||
| 3. Gaussian noise helper | 40 | Constant-time sampling (defends weak side-channel) |
|
||||
| 4. Moments Accountant | 120 | Tracks (ε, δ) across rounds; emits budget-exhausted error |
|
||||
| 5. Per-cog config schema (σ, C, max_rounds) | 50 | YAML/TOML, validated at federation start |
|
||||
| 6. End-to-end privacy test | — | Synthetic membership-inference attack vs DP-protected model; verify reconstruction quality is bounded by (ε, δ) prediction |
|
||||
|
||||
Combined with ADR-105's 500 LOC, total federation budget revised to **~800 LOC**, ~3-week effort.
|
||||
|
||||
## What this DOES enable
|
||||
|
||||
- Formally privacy-preserving federation with a documented (ε, δ) bound.
|
||||
- API-level enforcement of R15's biometric primitive isolation list — not just policy text.
|
||||
- A clear next-ADR path: ADR-107 (cross-installation federation w/ secure aggregation) builds on this foundation.
|
||||
|
||||
## What this DOES NOT enable
|
||||
|
||||
- Subject-level DP (preventing "is subject X in training") — would need subject-level privacy amplification.
|
||||
- Defence against side-channel timing leaks — separate ADR.
|
||||
- Cross-installation federation — separate ADR with secure aggregation + cross-installation DP composition.
|
||||
- Adversarial robustness to physical compromise — out of scope; physical security is the orthogonal defence layer.
|
||||
|
||||
## Decision-making record
|
||||
|
||||
- 2026-05-22 06:38 UTC — drafted by SOTA research loop tick-15 based on R3 + R15 + ADR-105's deferred items. Status: Proposed.
|
||||
- Pending: review by security-architect (formal DP bound verification), ddd-domain-expert (federation = bounded context with this ADR as its public API), production-validator (the per-cog σ values need bench validation before shipping any specific cog).
|
||||
@@ -1,217 +0,0 @@
|
||||
# ADR-107: Cross-installation federation with secure aggregation
|
||||
|
||||
**Status:** Proposed · **Date:** 2026-05-22 · **Author:** SOTA research loop tick-22 · **Supersedes:** none · **Extends:** ADR-105 (federated training) + ADR-106 (DP-SGD + primitive isolation)
|
||||
|
||||
## Context
|
||||
|
||||
ADR-105 + ADR-106 specified federation **within an installation** (a household, an office floor, a single building). Both ADRs explicitly **deferred** cross-installation federation:
|
||||
|
||||
> ADR-105: "Cross-installation federation requires cryptographic embedding-space alignment, stronger consent framework, differential privacy guarantees on deltas. A worked design needs ~6 person-months of legal + crypto work. Not in scope for this ADR."
|
||||
>
|
||||
> ADR-106: "Cross-installation federation — separate ADR with secure aggregation + cross-installation DP composition."
|
||||
|
||||
R3 (cross-room re-ID) added the privacy constraint that "no cross-installation linkage of embeddings is permitted". R15 (RF biometric primitives) sharpened this to "no sharing of any RF biometric primitive across legal entities, including aggregate / derived versions".
|
||||
|
||||
These constraints make cross-installation federation **harder than within-installation federation by a known amount**: the within-installation case can rely on the coordinator being owner-controlled (Cognitum-v0 fleet manager). The cross-installation case has no such trusted party.
|
||||
|
||||
This ADR specifies the cross-installation protocol that satisfies all the constraints from R3 + R14 + R15 + ADR-105 + ADR-106.
|
||||
|
||||
## Decision
|
||||
|
||||
Adopt **Secure Aggregation (Bonawitz 2016) + cross-installation DP composition + cryptographic embedding-space isolation** as the protocol for federating learning *across* RuView installations (e.g. across multiple households contributing to a shared `cog-person-count` model).
|
||||
|
||||
### Five-layer defence (extends ADR-105 + ADR-106's three layers)
|
||||
|
||||
| Layer | Mechanism | Defends against |
|
||||
|---|---|---|
|
||||
| 1 (ADR-106) | Primitive isolation API | Biometric exfiltration via federation channel |
|
||||
| 2 (ADR-106) | Gradient clipping L2 norm ≤ C | Single-sample sensitivity |
|
||||
| 3 (ADR-106) | Per-installation Gaussian DP noise (σ_local) | Within-installation member inference |
|
||||
| 4 (NEW) | Cryptographic secure aggregation | Cross-installation aggregator sees only the sum |
|
||||
| 5 (NEW) | Per-installation embedding-space rotation key | Prevents cross-installation linkage even if model leaks |
|
||||
|
||||
### Secure Aggregation protocol
|
||||
|
||||
Following Bonawitz et al 2016 (constants per ADR-105 implementation budget):
|
||||
|
||||
1. **Setup**: each installation `i` has a per-installation key pair `(sk_i, pk_i)` and a per-round nonce. Public keys are exchanged via a key-agreement service (cognitum-v0 cluster acts as PKI).
|
||||
2. **Mask generation**: each installation computes pairwise random masks `m_ij = PRG(seed=DH(sk_i, pk_j))` shared with each peer installation `j ≠ i`.
|
||||
3. **Local model delta computation**: as per ADR-105 step 4, then with ADR-106 layers 1–3 applied (primitive isolation, clipping, DP noise).
|
||||
4. **Mask the delta**: each installation computes `masked_delta_i = delta_i + Σ_j sign(i, j) · m_ij` where sign is `+1` for `i < j` and `-1` for `i > j`.
|
||||
5. **Upload masked delta**: each installation uploads `masked_delta_i` to the cross-installation aggregator.
|
||||
6. **Aggregation**: the aggregator computes `aggregate = Σ_i masked_delta_i`. The pairwise masks cancel by construction, so `aggregate = Σ_i delta_i + 0`. The aggregator **never sees** any individual `delta_i`.
|
||||
7. **Drop-out handling**: if some installations fail to upload, missing masks are reconstructed via threshold-Shamir secret sharing of `sk_i` among peers (Bonawitz §4).
|
||||
8. **Cross-installation DP composition**: with N installations and per-installation noise σ_local, the cross-installation effective σ_cross = σ_local · √N (improvement from amplification by sampling). Cross-installation (ε, δ) budget composed via Moments Accountant.
|
||||
|
||||
### Embedding-space rotation key
|
||||
|
||||
Even after secure aggregation, the **aggregated model itself** could leak biometric information when used at any installation. To prevent cross-installation **re-identification** specifically (R3 + R15 binding constraints), each installation applies a **per-installation orthogonal rotation** to its embedding space:
|
||||
|
||||
```
|
||||
embedding_local = R_i · embedding_global
|
||||
```
|
||||
|
||||
Where `R_i` is a random orthogonal 128×128 matrix sampled once at installation setup and stored locally (never transmitted). The federation operates on the **rotated space**; outputs at installation `i` are unintelligible at installation `j` because they're in different rotated frames.
|
||||
|
||||
This prevents the leaked-model attack: even if an adversary obtains the global model + raw CSI from installation `j`, they cannot project installation `i`'s biometric embeddings into the same space without `R_i`.
|
||||
|
||||
### Privacy budget (cross-installation)
|
||||
|
||||
With N installations each running σ_local = 1.0 (per ADR-106 standard profile), 50 federation rounds:
|
||||
|
||||
| Quantity | Value |
|
||||
|---|---:|
|
||||
| Per-installation ε | 2.5 |
|
||||
| Cross-installation effective σ | √N · σ_local = √10 · 1.0 ≈ 3.16 |
|
||||
| Cross-installation ε after 50 rounds | **~1.5** |
|
||||
| Strong-aggregation budget consumed | <30% of community soft-bound ε=10 |
|
||||
|
||||
Tighter than the standard within-installation profile because cross-installation amplification reduces effective noise per round. **This is a win**: federating across installations actually improves privacy due to the amplification effect, *as long as the cryptographic protocol is implemented correctly*.
|
||||
|
||||
### Bandwidth analysis
|
||||
|
||||
Per round, N=10 installations:
|
||||
|
||||
| Phase | Bytes per installation | Total |
|
||||
|---|---:|---:|
|
||||
| Public key exchange (once per round) | 32 B | 320 B |
|
||||
| Pairwise mask seeds (DH) | 32 B × N | 3.2 kB |
|
||||
| Masked delta upload | 1 MB | 10 MB |
|
||||
| Aggregate broadcast | 1 MB | 10 MB |
|
||||
| Drop-out reconstruction (worst-case 1 missing) | ~32 kB | ~32 kB |
|
||||
| **Total per round per installation** | **~2 MB** | **~20 MB** |
|
||||
|
||||
Per ADR-105's monthly cadence: 50-180 MB / month / installation (the within-installation number) plus ~20 MB / month / installation for cross-installation = **70-200 MB / month / installation total**. Still <0.1% of typical home broadband cap.
|
||||
|
||||
## Alternatives considered
|
||||
|
||||
### A. No cross-installation federation
|
||||
|
||||
Status: **rejected**. Limits RuView's per-cog accuracy to within-installation training data; for rare events (e.g. wildlife species seen in only 5% of installations), within-installation only would forever lack training data.
|
||||
|
||||
### B. Trusted-coordinator cross-installation
|
||||
|
||||
Status: **rejected**. Would require a single party to see all individual deltas. No party has the cross-organisation trust to play this role; legal exposure is unacceptable.
|
||||
|
||||
### C. Differential-privacy-only (no secure aggregation)
|
||||
|
||||
Status: **rejected**. Higher σ needed to compensate for centralised view of individual deltas; ε budget consumed faster; less private than the SA + DP combination.
|
||||
|
||||
### D. Federated through homomorphic encryption
|
||||
|
||||
Status: **deferred**. HE adds 10-100× compute overhead and 5-10× bandwidth. Not justified given that SA + DP provides equivalent guarantees with much lower compute cost. Future work if quantum-resistant guarantees become required.
|
||||
|
||||
### E. Cross-installation with per-installation cryptographic isolation only (no SA)
|
||||
|
||||
Status: **rejected**. Per-installation rotation alone (Layer 5) prevents linkage but doesn't address the "aggregator sees individual deltas" problem.
|
||||
|
||||
## Threat model
|
||||
|
||||
| Threat | Layer that mitigates |
|
||||
|---|---|
|
||||
| Compromised aggregator views individual deltas | **Layer 4 SA** — pairwise masks cancel, aggregator sees only sum |
|
||||
| One compromised installation poisons aggregate | ADR-105 Krum (still applies, operates on masked deltas) |
|
||||
| One compromised installation leaks its own deltas | Out of scope — local compromise = full local compromise |
|
||||
| Eavesdropper recovers training data from aggregate | **Layer 3 + Layer 4** — DP-noised aggregate is information-theoretically lossy |
|
||||
| Member inference across installations | **Layer 3 + cross-installation DP composition** — formal (ε, δ) bound across all installations |
|
||||
| Cross-installation re-identification of an individual | **Layer 5 rotation key** — different embedding spaces |
|
||||
| Sybil attack (one party operates many fake installations) | **Layer 4 SA dropout** + Krum + N ≥ 5 installations required per round |
|
||||
| Quantum-resistant compromise of DH key exchange | Out of scope — switch to post-quantum KEM (Kyber) when widely deployed |
|
||||
|
||||
## Consequences
|
||||
|
||||
### Positive
|
||||
|
||||
1. **The full privacy chain is now complete**: R6 (physics) → R3 (embeddings) → R14 (privacy) → R15 (biometric primitives) → ADR-105 (federation) → ADR-106 (DP + isolation) → ADR-107 (cross-installation + SA). Every layer has a formal guarantee.
|
||||
2. **Cross-installation amplification improves privacy**, not worsens it. Counter-intuitive but mathematically rigorous.
|
||||
3. **No single party** has visibility into individual installation contributions.
|
||||
4. **Per-installation embedding-space isolation** prevents linkage even if the global model leaks.
|
||||
5. **Bandwidth cost remains negligible** (~0.1% of home broadband).
|
||||
|
||||
### Negative
|
||||
|
||||
1. **Substantial implementation cost**: SA protocol + threshold Shamir + per-round PKI adds ~600 LOC on top of ADR-105's 500 + ADR-106's 300. Total `ruview-fed` budget revised to **~1,400 LOC**.
|
||||
2. **Drop-out handling complexity**: Bonawitz §4 reconstruction adds the most engineering surface area.
|
||||
3. **Requires a PKI service**: cognitum-v0 fleet plays this role *within an org*; cross-org PKI is a separate operational/legal question.
|
||||
4. **Quantum-resistant key exchange** is not yet specified — Kyber substitution is mechanically simple but not formally part of this ADR.
|
||||
5. **Embedding-space rotation introduces a usability burden**: cross-installation model export/import requires the rotation key, which is by design non-transferable.
|
||||
|
||||
### What this ADR DOES NOT cover
|
||||
|
||||
1. **Cross-org PKI bootstrapping** — who runs the PKI service when installations span multiple legal entities? Operational question, not architectural.
|
||||
2. **Quantum-resistant primitives** — Kyber-style KEM substitution; future ADR.
|
||||
3. **Cross-installation training-loop scheduling** — when do rounds happen, who initiates them, etc.
|
||||
4. **Per-cog suitability for cross-installation training** — some cogs (`cog-pose-estimation`, `cog-person-count`) benefit greatly; others (`cog-maritime-watch`) are very installation-specific and may not benefit. Per-cog decision.
|
||||
|
||||
## Bridge to existing ADRs and threads
|
||||
|
||||
- **ADR-024 (AETHER)** + **ADR-027 (MERIDIAN)**: cross-installation federation uses the rotated embedding space; AETHER + MERIDIAN training stays unchanged.
|
||||
- **ADR-029 (multistatic)**: per-installation multistatic geometry is unchanged; federation operates on model weights, not geometry.
|
||||
- **ADR-100 (cog packaging)**: Ed25519 signing covers cross-installation models with no protocol change.
|
||||
- **ADR-103 (cog-person-count)** + **ADR-101 (cog-pose-estimation)**: first candidates for cross-installation training (large benefit from diverse training data).
|
||||
- **ADR-104 (ruview-mcp + ruview-cli)**: cross-installation federation status surfaces as MCP tools `ruview_xfed_status`, `ruview_xfed_optin`, `ruview_xfed_optout`. Out of scope here but in the roadmap.
|
||||
- **ADR-105 (federation)**: ADR-107 extends the within-installation protocol; Krum still applies on masked deltas.
|
||||
- **ADR-106 (DP-SGD + primitive isolation)**: cross-installation composition uses ADR-106's Moments Accountant with √N amplification factor.
|
||||
|
||||
## Connection to research-loop threads
|
||||
|
||||
- **R3 (cross-room re-ID)**: cross-installation linkage is explicitly **prohibited** by R3; ADR-107's Layer 5 rotation enforces this technically.
|
||||
- **R14 (empathic appliances)**: the privacy framework's "no cross-installation linkage" baseline is now provably enforced.
|
||||
- **R15 (RF biometric primitives)**: the on-device-only primitive list is unchanged; ADR-107 extends to "even across installations, the same primitives never leave the device".
|
||||
- **R7 (mincut adversarial)**: extends from within-installation multi-link to cross-installation multi-installation; can detect when an aggregator is colluding with a subset of installations.
|
||||
- **R12 PABS (POSITIVE)**: cross-installation aggregated model can be deployed at any installation; PABS at each installation uses the local (rotated) embedding space.
|
||||
- **R10/R11 (foliage/maritime)**: domain-specific cogs benefit asymmetrically. Cross-installation `cog-wildlife` training (multiple forests with different species) is the high-value case; cross-installation `cog-maritime-watch` is less useful because each vessel is unique.
|
||||
|
||||
## Implementation plan
|
||||
|
||||
Additive on ADR-105 + ADR-106 budgets:
|
||||
|
||||
| Component | LOC | Purpose |
|
||||
|---|---:|---|
|
||||
| `SecureAggregator` (Bonawitz §3) | 200 | Pairwise mask generation, drop-out reconstruction |
|
||||
| Per-installation `RotationKey` storage | 60 | Layer 5 enforcement |
|
||||
| PKI client (DH key exchange, public-key cache) | 120 | Layer 4 setup |
|
||||
| Threshold-Shamir secret sharing helper | 100 | Drop-out reconstruction |
|
||||
| `MomentsAccountant.cross_installation()` extension | 50 | √N amplification factor |
|
||||
| End-to-end cross-installation test (multi-node) | — | Real-installation test on cognitum-cluster (per CLAUDE.local.md) |
|
||||
|
||||
Total: ~530 additional LOC.
|
||||
|
||||
Combined federation budget: ADR-105 (500) + ADR-106 (300) + ADR-107 (530) = **~1,330 LOC**, revised from 800 to ~1,330. ~6-week effort.
|
||||
|
||||
## Quantum-resistance future work
|
||||
|
||||
- Current DH key exchange becomes vulnerable to quantum computers.
|
||||
- Recommended substitution: Kyber KEM (NIST PQC selected).
|
||||
- Mechanical replacement of DH primitives; no protocol change.
|
||||
- Future ADR-108 (or amendment to ADR-107).
|
||||
|
||||
## Honest scope
|
||||
|
||||
- **Cross-org PKI bootstrapping** is operational, not architectural. ADR-107 assumes the PKI exists.
|
||||
- **Implementation cost** has crept from 500 LOC (ADR-105) to ~1,330 LOC (ADR-105+106+107). This is real engineering work.
|
||||
- **Krum byzantine-robustness composes** with SA, but the proof is non-trivial. Reference implementations (Google federated learning, OpenMined) should be consulted before production.
|
||||
- **Drop-out reconstruction** has known attack surfaces (collusion attacks on threshold Shamir); the implementation must follow Bonawitz §4.3 carefully.
|
||||
- **The √N amplification factor** assumes installations are independent. Strongly correlated installations (e.g. same family across two homes) violate this; needs separate accounting.
|
||||
- **Per-cog applicability**: not all cogs benefit equally. Each cog should justify whether cross-installation training improves it.
|
||||
|
||||
## Decision-making record
|
||||
|
||||
- 2026-05-22 08:17 UTC — drafted by SOTA research loop tick-22 based on R3 + R14 + R15 + ADR-105 + ADR-106 deferred items. Status: Proposed.
|
||||
- Pending: security-architect (formal SA + DP composition verification), ddd-domain-expert (cross-installation = separate bounded context with strict isolation), production-validator (1,330 LOC + 6 weeks engineering sanity check).
|
||||
|
||||
## What ADR-107 closes
|
||||
|
||||
The entire **privacy + federation chain** is now complete with explicit ADRs at each layer:
|
||||
|
||||
1. **R6 / R6.1** — physics forward model (multi-scatterer, what's actually being sensed)
|
||||
2. **R3** — embedding-space cross-room re-ID (works with MERIDIAN; constraints documented)
|
||||
3. **R14** — privacy framework + ethical opt-in / on-device / one-tap-override
|
||||
4. **R15** — RF biometric primitive catalogue + 4 constraints
|
||||
5. **ADR-105** — within-installation federation (Krum byzantine + MERIDIAN env subtraction + R7 mincut update consistency)
|
||||
6. **ADR-106** — DP-SGD + primitive isolation (formal (ε, δ) bound)
|
||||
7. **ADR-107** — cross-installation federation (secure aggregation + per-installation rotation + cross-installation DP composition)
|
||||
|
||||
Each layer has a formal guarantee, an implementation path, and an honest scope. **The chain has no remaining unspecified privacy gap**; cross-installation training can now ship without violating any constraint surfaced by the research loop.
|
||||
|
||||
The loop has consumed 22 ticks to produce this chain. The remaining engineering work (~1,330 LOC + ~6 weeks) is implementation, not research.
|
||||
@@ -1,197 +0,0 @@
|
||||
# ADR-108: Kyber post-quantum key exchange for cross-installation federation
|
||||
|
||||
**Status:** Proposed · **Date:** 2026-05-22 · **Author:** SOTA research loop tick-28 · **Supersedes:** none · **Extends:** ADR-107 (cross-installation federation)
|
||||
|
||||
## Context
|
||||
|
||||
ADR-107 specifies cross-installation federation using **secure aggregation (Bonawitz 2016)** with Diffie-Hellman key exchange for pairwise mask generation. The current implementation would use classical DH (X25519 or P-256), which is **vulnerable to Shor's algorithm** on a sufficiently large fault-tolerant quantum computer.
|
||||
|
||||
ADR-107 noted this as out-of-scope:
|
||||
|
||||
> Current DH key exchange becomes vulnerable to quantum computers. Recommended substitution: Kyber KEM (NIST PQC selected). Mechanical replacement of DH primitives; no protocol change. Future ADR-108 (or amendment to ADR-107).
|
||||
|
||||
This ADR is that future work.
|
||||
|
||||
## Decision
|
||||
|
||||
Adopt **Kyber-768** as the post-quantum key encapsulation mechanism (KEM) replacing Diffie-Hellman in ADR-107's Layer 4 secure aggregation, with an explicit migration timeline tied to NIST CNSA 2.0 guidance and an interim **hybrid mode** (Kyber + X25519) for forward-secrecy belt-and-braces during the migration window.
|
||||
|
||||
### Why Kyber-768
|
||||
|
||||
NIST standardised three Kyber security levels in FIPS 203 (2024):
|
||||
|
||||
| Variant | NIST level | Public key | Ciphertext | Secret | Security |
|
||||
|---|---|---:|---:|---:|---|
|
||||
| Kyber-512 | Level 1 | 800 B | 768 B | 32 B | ~AES-128 |
|
||||
| **Kyber-768** | **Level 3** | **1184 B** | **1088 B** | **32 B** | **~AES-192** |
|
||||
| Kyber-1024 | Level 5 | 1568 B | 1568 B | 32 B | ~AES-256 |
|
||||
|
||||
**Kyber-768** matches AES-192 equivalent security and is the **NIST CNSA 2.0 recommended default** for general-purpose protocols. Used by Cloudflare, Google, AWS in their 2024-2026 PQC rollouts.
|
||||
|
||||
Kyber-512 is sufficient against classical attackers and small quantum computers but doesn't carry CNSA 2.0 sign-off. Kyber-1024 doubles bandwidth without proportional security benefit for our threat model.
|
||||
|
||||
### Hybrid mode (transition window)
|
||||
|
||||
During the migration (2026-2030 estimated), all key exchanges run **both** Kyber-768 AND X25519 in parallel and XOR the shared secrets:
|
||||
|
||||
```
|
||||
shared_secret = SHA-256(kyber_ss || x25519_ss || transcript)
|
||||
```
|
||||
|
||||
This **belt-and-braces** approach protects against:
|
||||
|
||||
- A future Kyber break (unlikely but not impossible — Kyber is ~5 years old)
|
||||
- Implementation bugs in either primitive
|
||||
- Adversaries who can compromise *one* of the two primitives
|
||||
|
||||
Cost: ~2× key-exchange computation, ~2× public-key size. For RuView's per-round overhead this adds ~3 kB / round / installation — negligible.
|
||||
|
||||
After CNSA 2.0 fully retires classical primitives (estimated 2030+), the hybrid layer is removed and pure Kyber-768 is used.
|
||||
|
||||
### Migration timeline
|
||||
|
||||
| Phase | Timeline | What ships |
|
||||
|---|---|---|
|
||||
| Phase 0 (NOW) | 2026 | ADR-107 ships with classical X25519 |
|
||||
| Phase 1 | 2026-Q4 → 2027 | Library upgrade adds Kyber-768; opt-in via `--enable-pqc` flag |
|
||||
| Phase 2 | 2027-Q2 → 2028 | Hybrid mode (X25519 + Kyber-768) becomes default |
|
||||
| Phase 3 | 2030+ | Pure Kyber-768 (classical removed) |
|
||||
|
||||
Phase 1 is the first feature ship. By the time the migration is complete, the post-quantum threat model is approximately the only one that matters.
|
||||
|
||||
### Implementation cost
|
||||
|
||||
| Component | LOC | Notes |
|
||||
|---|---:|---|
|
||||
| Kyber-768 KEM wrapper (over `pqcrypto-kyber` crate) | 80 | Pure Rust, no `unsafe` |
|
||||
| Hybrid mode (XOR + SHA-256 KDF) | 50 | Composes existing primitives |
|
||||
| Protocol version negotiation | 60 | Backward compat with Phase 0 nodes |
|
||||
| Public-key cache extension (size grows from 32 B to 1184 B per peer) | 30 | AgentDB schema update |
|
||||
| Migration documentation | — | This ADR |
|
||||
| End-to-end test (multi-node PQC handshake) | — | Real-installation test |
|
||||
|
||||
Total ~220 LOC additional. Combined federation budget across ADR-105+106+107+108: **~1,550 LOC**.
|
||||
|
||||
## Alternatives considered
|
||||
|
||||
### A. Pure Kyber-768 (no hybrid)
|
||||
|
||||
Status: **rejected for Phase 1-2**. Hybrid provides defense-in-depth at minimal cost; pure-Kyber is fine for Phase 3 once Kyber has had more cryptographic scrutiny.
|
||||
|
||||
### B. NTRU Prime (alternative PQC KEM)
|
||||
|
||||
Status: **rejected**. Kyber has clearer standardisation status (FIPS 203). NTRU Prime is fine cryptographically but doesn't have CNSA 2.0 sign-off.
|
||||
|
||||
### C. Frodo (lattice-based, more conservative parameters)
|
||||
|
||||
Status: **rejected**. Frodo has larger key sizes (~10 kB) and slower operations. Trade-off doesn't justify the security margin given our threat model.
|
||||
|
||||
### D. Code-based KEMs (Classic McEliece)
|
||||
|
||||
Status: **rejected**. Classic McEliece public keys are ~261 kB — unworkable for embedded ESP32-S3 nodes.
|
||||
|
||||
### E. Defer until quantum threat materialises
|
||||
|
||||
Status: **rejected**. Adversaries can record-now-decrypt-later — federated model updates today could be decrypted in 5-10 years when quantum capabilities arrive. ADR-107's privacy guarantees would silently expire without proactive migration.
|
||||
|
||||
## Threat model
|
||||
|
||||
| Threat | Layer that mitigates |
|
||||
|---|---|
|
||||
| Shor's algorithm breaks classical DH | **Kyber-768 KEM** |
|
||||
| Future quantum attack on Kyber (unlikely) | **Hybrid mode** — X25519 still provides classical security |
|
||||
| Implementation bug in Kyber library | **Hybrid mode** — X25519 backup |
|
||||
| Implementation bug in X25519 library | **Hybrid mode** — Kyber backup |
|
||||
| Record-now-decrypt-later (adversary stores ciphertexts) | Forward secrecy from Kyber-768 (each round has fresh ephemeral keys) |
|
||||
| Downgrade attack (force classical-only handshake) | **Protocol version negotiation** — explicit reject of classical-only post-Phase-2 |
|
||||
| Side-channel attack on Kyber implementation | Use constant-time `pqcrypto-kyber` Rust crate; further hardening in future |
|
||||
| Public-key spoofing (Sybil) | Pre-shared trust anchors via cognitum-v0 PKI (ADR-107) |
|
||||
|
||||
## Consequences
|
||||
|
||||
### Positive
|
||||
|
||||
1. **The privacy chain remains intact through the quantum transition.** Without ADR-108, the (ε, δ) guarantees of ADR-106 silently expire when quantum computers arrive.
|
||||
2. **Record-now-decrypt-later attack is defeated.** Federated updates from today won't be decryptable in 2035 with quantum hardware.
|
||||
3. **CNSA 2.0 compliant** by Phase 2; ready for any regulatory requirement that mandates PQC.
|
||||
4. **Hybrid mode is belt-and-braces** — protects against both Kyber breaks AND classical breaks.
|
||||
5. **No protocol change** at the secure-aggregation level — the KEM is a drop-in replacement.
|
||||
|
||||
### Negative
|
||||
|
||||
1. **Adds ~220 LOC** to ADR-107's implementation budget.
|
||||
2. **~3 kB extra per-round per-installation bandwidth** during hybrid mode (negligible).
|
||||
3. **Kyber is ~5 years old** — less battle-tested than X25519. Hybrid mode mitigates this.
|
||||
4. **No clear end-of-life for the hybrid mode** — Phase 3 requires a future decision when CNSA 2.0 retires classical.
|
||||
5. **Public-key cache grows 37×** (32 B → 1184 B per peer); AgentDB schema update needed.
|
||||
|
||||
### What this ADR DOES NOT cover
|
||||
|
||||
1. **Post-quantum digital signatures** — ADR-100 cog signing uses Ed25519 today; a follow-up ADR (likely ADR-109) covers Dilithium / SPHINCS+ substitution.
|
||||
2. **Constant-time hardening of the full Kyber path** — relies on the `pqcrypto-kyber` Rust crate's existing claims.
|
||||
3. **Hardware-acceleration on ESP32-S3** — Kyber-768 is software-only at this scale; the ESP32-S3 can do ~50 ops/sec which is far more than the per-round federation needs.
|
||||
|
||||
## Bridge to existing ADRs
|
||||
|
||||
- **ADR-100 (cog packaging Ed25519 signing)** — separate from key-exchange; PQC signature migration needed independently (future ADR-109).
|
||||
- **ADR-104 (ruview-mcp + ruview-cli)** — MCP tool `ruview_fed_pqc_status` surfaces hybrid-vs-pure mode and migration phase.
|
||||
- **ADR-105 (federation)** + **ADR-106 (DP+isolation)** — operate over secure-aggregation key exchange; transparent to KEM substitution.
|
||||
- **ADR-107 (cross-installation federation)** — directly extended by ADR-108; Layer 4 secure aggregation gets Kyber replacement for DH.
|
||||
|
||||
## Connection to research-loop threads
|
||||
|
||||
- **R3 / R14 / R15** — privacy chain remains intact through quantum transition.
|
||||
- **R7 (mincut adversarial)** — mincut detection operates on application-level deltas, not key exchange; orthogonal to PQC.
|
||||
- **R12 PABS** — same — operates on CSI / model deltas, not key exchange.
|
||||
- **R10 / R11 (wildlife / maritime)** — long-deployment use cases benefit most from forward secrecy because data ages for years.
|
||||
|
||||
## Honest scope
|
||||
|
||||
- **Kyber is recommended by NIST today** but cryptographic confidence will grow over the next decade. The hybrid mode hedges against this uncertainty.
|
||||
- **The "when do we need this?" question** is genuinely uncertain. Estimates of cryptographically-relevant quantum computers range from 2030 (aggressive) to 2050+ (conservative). The proactive migration is cheap insurance.
|
||||
- **ESP32-S3 can compute Kyber-768** but the timing impact in the per-round federation cycle (~10 ms additional per handshake) needs benchmarking on real hardware. Estimated negligible given the existing ~30 s round duration.
|
||||
- **The migration timeline is aspirational** — depends on `pqcrypto-kyber` crate stability + adoption maturity. Plausible alternatives include `liboqs` C-binding or `boring-pq` (Cloudflare's pre-standardisation work, now superseded).
|
||||
- **Pure Kyber (Phase 3) end-of-life for classical** — depends on community standardisation and a future RuView decision; not bindingly specified here.
|
||||
|
||||
## What this ADR closes
|
||||
|
||||
This is the **last ADR in the privacy + federation chain** the research loop has produced:
|
||||
|
||||
1. ADR-100 — cog packaging (foundation)
|
||||
2. ADR-103 — cog-person-count (first cog example)
|
||||
3. ADR-104 — MCP + CLI distribution
|
||||
4. ADR-105 — federated training (within-installation)
|
||||
5. ADR-106 — DP-SGD + biometric primitive isolation
|
||||
6. ADR-107 — cross-installation federation w/ secure aggregation
|
||||
7. **ADR-108 (this)** — post-quantum key exchange
|
||||
|
||||
The chain has formal guarantees at every layer **and** quantum-resistance built in by 2028. **No remaining unspecified privacy gap** at any threat horizon.
|
||||
|
||||
## Implementation plan
|
||||
|
||||
| Phase | What ships | LOC |
|
||||
|---|---|---:|
|
||||
| Phase 1 (2026-Q4) | Kyber-768 wrapper + `--enable-pqc` opt-in | ~140 |
|
||||
| Phase 2 (2027-Q2) | Hybrid mode default | ~80 |
|
||||
| Phase 3 (2030+) | Pure Kyber-768 (remove classical) | -50 (removal) |
|
||||
|
||||
Phase 1 is the first ship.
|
||||
|
||||
## Future ADRs
|
||||
|
||||
- **ADR-109**: PQC digital signatures (Dilithium for cog signing, replacing Ed25519 in ADR-100).
|
||||
- **ADR-110**: PQC hardware acceleration on Cognitum-v0 (offload Kyber from ESP32-S3 if the ~10 ms cycle becomes binding).
|
||||
- **ADR-111**: PQC for `cog-store` distribution (sign-and-verify chain).
|
||||
|
||||
## Decision-making record
|
||||
|
||||
- 2026-05-22 09:37 UTC — drafted by SOTA research loop tick-28 based on ADR-107's explicit deferral. Status: Proposed.
|
||||
- Pending: security-architect (formal PQC threat model review), production-validator (`pqcrypto-kyber` Rust crate stability and ESP32-S3 benchmarking before Phase 1).
|
||||
|
||||
## Honest scope of ADR-108
|
||||
|
||||
- Phase 1 ships in ~1 quarter after ADR-107 lands.
|
||||
- Hybrid mode is the right default for 2027-2030.
|
||||
- Phase 3 (pure Kyber) needs a separate future decision once CNSA 2.0 fully retires classical primitives.
|
||||
- Implementation depends on `pqcrypto-kyber` crate maturity; alternatives exist if it stagnates.
|
||||
- ESP32-S3 timing impact is estimated negligible; needs measurement.
|
||||
@@ -1,202 +0,0 @@
|
||||
# ADR-109: Dilithium post-quantum digital signatures for cog distribution
|
||||
|
||||
**Status:** Proposed · **Date:** 2026-05-22 · **Author:** SOTA research loop tick-30 · **Extends:** ADR-100 (cog packaging Ed25519 signing) · **Sister-of:** ADR-108 (Kyber post-quantum key exchange)
|
||||
|
||||
## Context
|
||||
|
||||
ADR-100 specified Ed25519 signatures for cog packaging (binaries on GCS at `gs://cognitum-apps/cogs/{arm,x86_64}/`, signed with `COGNITUM_OWNER_SIGNING_KEY`). ADR-108 closed the **key exchange** side of post-quantum migration with Kyber-768. This ADR closes the **digital signature** side with Dilithium-3.
|
||||
|
||||
The two pieces are independent — DH/Kyber protects confidentiality (federation updates), Ed25519/Dilithium protects integrity (signed cog binaries, ADR-100 distribution). Both need PQC migration on similar timelines to keep the privacy + provenance chain quantum-resistant.
|
||||
|
||||
ADR-108 cited:
|
||||
|
||||
> ADR-109: PQC signatures (Dilithium for cog signing, replacing Ed25519 in ADR-100).
|
||||
|
||||
This is that work.
|
||||
|
||||
## Decision
|
||||
|
||||
Adopt **Dilithium-3** as the post-quantum signature scheme replacing Ed25519 in ADR-100's cog signing pipeline. Use the same migration pattern as ADR-108: **hybrid mode (Ed25519 + Dilithium-3)** during the transition window (2026-2030); pure Dilithium-3 afterwards.
|
||||
|
||||
### Why Dilithium-3
|
||||
|
||||
NIST standardised three Dilithium security levels in FIPS 204 (2024):
|
||||
|
||||
| Variant | NIST level | Public key | Signature | Security |
|
||||
|---|---|---:|---:|---|
|
||||
| Dilithium-2 | Level 2 | 1,312 B | 2,420 B | ~AES-128 |
|
||||
| **Dilithium-3** | **Level 3** | **1,952 B** | **3,293 B** | **~AES-192** |
|
||||
| Dilithium-5 | Level 5 | 2,592 B | 4,595 B | ~AES-256 |
|
||||
|
||||
**Dilithium-3** at NIST Level 3 matches AES-192 equivalent security, mirroring our Kyber-768 choice from ADR-108. This is the NIST CNSA 2.0 recommended default for general signing.
|
||||
|
||||
### Hybrid mode (transition window)
|
||||
|
||||
Sign **both** with Ed25519 AND Dilithium-3 during the migration. Manifest format:
|
||||
|
||||
```json
|
||||
{
|
||||
"cog_name": "cog-person-count",
|
||||
"version": "0.0.2",
|
||||
"sha256": "...",
|
||||
"signatures": {
|
||||
"ed25519": "...", // ADR-100 classical
|
||||
"dilithium3": "..." // ADR-109 PQC
|
||||
},
|
||||
"sig_policy": "BOTH_REQUIRED_PHASE_2"
|
||||
}
|
||||
```
|
||||
|
||||
Verification policy by phase:
|
||||
|
||||
| Phase | Verification |
|
||||
|---|---|
|
||||
| Phase 0 (NOW 2026) | Ed25519 only (ADR-100 baseline) |
|
||||
| Phase 1 (2026-Q4 → 2027) | Ed25519 required + Dilithium-3 emitted (best-effort verify) |
|
||||
| Phase 2 (2027-Q2 → 2028) | **BOTH required** — defence in depth |
|
||||
| Phase 3 (2030+) | Dilithium-3 required, Ed25519 deprecated/removed |
|
||||
|
||||
### Migration timeline (matches ADR-108)
|
||||
|
||||
| Phase | Timeline | What ships |
|
||||
|---|---|---|
|
||||
| Phase 0 | 2026 | ADR-100 ships with Ed25519 only |
|
||||
| Phase 1 | 2026-Q4 → 2027 | Cog signer produces both signatures; verifier accepts either |
|
||||
| Phase 2 | 2027-Q2 → 2028 | Both signatures required; downgrade to single signature rejected |
|
||||
| Phase 3 | 2030+ | Pure Dilithium-3, Ed25519 removed |
|
||||
|
||||
### Implementation cost
|
||||
|
||||
| Component | LOC | Notes |
|
||||
|---|---:|---|
|
||||
| Dilithium-3 signer (over `pqcrypto-dilithium` Rust crate) | 90 | Pure Rust, no `unsafe` |
|
||||
| Manifest schema extension (multi-sig field + policy) | 60 | Backward-compatible JSON additive |
|
||||
| Verifier with phase-aware policy enforcement | 80 | Tied to manifest `sig_policy` |
|
||||
| GCS bucket policy update (allow new key types) | — | Operational, not code |
|
||||
| `cogd` daemon: re-sign existing cogs in dual-sig | 40 | One-time backfill script |
|
||||
| End-to-end test (install signed cog on Pi cluster) | — | Real-installation test |
|
||||
|
||||
Total ~270 LOC additional. Combined federation + signing budget across ADR-100 + ADR-105 + ADR-106 + ADR-107 + ADR-108 + ADR-109: **~1,820 LOC**.
|
||||
|
||||
## Alternatives considered
|
||||
|
||||
### A. SPHINCS+ (hash-based signatures)
|
||||
|
||||
Status: **deferred to ADR-110 if needed**. SPHINCS+ is conservatively-secure (worst-case based on hash function security only) but has much larger signatures (~17-50 kB) and slower signing. For cog distribution where keys rarely change, Dilithium-3's 3.3 kB signatures are the better trade-off. SPHINCS+ might be a fallback if Dilithium suffers a cryptanalytic break.
|
||||
|
||||
### B. Falcon (lattice signatures with smaller footprint)
|
||||
|
||||
Status: **considered**. Falcon-512 has smaller signatures (666 B) than Dilithium-3 (3,293 B) but slower signing and more complex implementation (floating-point Gaussian sampling). Dilithium-3 is the safer choice given the Rust crate maturity (`pqcrypto-dilithium` vs `pqcrypto-falcon`).
|
||||
|
||||
### C. Pure Dilithium-3 (no hybrid)
|
||||
|
||||
Status: **rejected for Phase 1-2**. Same belt-and-braces reasoning as ADR-108: Dilithium is ~5 years old; hybrid hedges against breaks.
|
||||
|
||||
### D. Defer until quantum threat materialises
|
||||
|
||||
Status: **rejected**. Same record-now-decrypt-later argument as ADR-108, applied to signatures: an adversary who can break Ed25519 in 2035 can backdate signatures on cog binaries to install malicious code retroactively. Provenance chain breaks.
|
||||
|
||||
## Threat model
|
||||
|
||||
| Threat | Mitigation |
|
||||
|---|---|
|
||||
| Shor's algorithm breaks Ed25519 | Dilithium-3 signature |
|
||||
| Future quantum break on Dilithium-3 (unlikely) | Hybrid mode — Ed25519 still classical-secure |
|
||||
| Implementation bug in Dilithium library | Hybrid mode — Ed25519 backup |
|
||||
| Implementation bug in Ed25519 library | Hybrid mode — Dilithium backup |
|
||||
| Backdated signature attack (quantum-era forgery on old binaries) | **Hybrid mode is essential** — Ed25519 forgery is hard even for quantum (no key compromise), so quantum + Ed25519 = still requires breaking Dilithium |
|
||||
| Compromised owner key (operational) | Out of scope — key management ADR (future) |
|
||||
| Downgrade attack (force single-sig acceptance post-Phase-2) | **Manifest `sig_policy` field** enforces required signatures |
|
||||
|
||||
## Consequences
|
||||
|
||||
### Positive
|
||||
|
||||
1. **Provenance chain stays intact through quantum transition.** Without ADR-109, the integrity of installed cog binaries silently expires when quantum computers arrive.
|
||||
2. **Backdating attack defeated.** An adversary in 2035 cannot forge a Dilithium-3 signature on a 2026 cog binary even with quantum hardware.
|
||||
3. **CNSA 2.0 compliant** by Phase 2.
|
||||
4. **Hybrid mode is belt-and-braces** — protects against breaks in either primitive.
|
||||
5. **No protocol change** — multi-signature manifest is a standard JSON additive pattern.
|
||||
|
||||
### Negative
|
||||
|
||||
1. **Adds ~270 LOC** to ADR-100's signing implementation.
|
||||
2. **Manifest size grows**: Ed25519 (64 B sig) + Dilithium-3 (3,293 B sig) = ~3.4 kB total. Per-cog manifest overhead is now ~4 kB. Across 50 cogs in the catalogue, ~200 kB extra. Negligible.
|
||||
3. **Signer needs both keys**: classical + PQC keypairs. Adds key-management complexity.
|
||||
4. **Dilithium-3 verifier latency**: ~0.5-1 ms vs Ed25519's ~30 µs. On ESP32-S3 with no hardware acceleration, ~5-10 ms per verification. For occasional cog-install events, fine.
|
||||
5. **Pure Dilithium retirement of Ed25519 needs future decision** (Phase 3, post-2030).
|
||||
|
||||
### What this ADR DOES NOT cover
|
||||
|
||||
1. **PQC for HTTPS / TLS** to the cog distribution servers — Cloudflare / GCS run their own PQC migration on their schedule.
|
||||
2. **Owner key rotation policy** — separate future ADR.
|
||||
3. **Hardware acceleration for Dilithium verification on ESP32-S3** — if 5-10 ms latency becomes binding, offload to cognitum-v0 fleet manager.
|
||||
4. **Cross-signing with external CA** — if RuView ever needs a third-party CA chain, that's a future ADR.
|
||||
|
||||
## Bridge to existing ADRs
|
||||
|
||||
- **ADR-100 (cog packaging Ed25519 signing)** — directly extended; Ed25519 stays in hybrid mode.
|
||||
- **ADR-104 (ruview-mcp + ruview-cli)** — `ruview_cog_install` MCP tool gains signature-policy parameter.
|
||||
- **ADR-105 / ADR-106 / ADR-107 / ADR-108** — federation operates on signed cog binaries; ADR-109 ensures the signing layer is quantum-resistant in lockstep with ADR-108's key exchange.
|
||||
|
||||
## Connection to research-loop threads
|
||||
|
||||
- **R14 / R15** — privacy + biometric framework requires provenance integrity; ADR-109 ensures cog updates are tamper-proof against quantum adversaries.
|
||||
- **R12 PABS / R12.1 (security feature)** — intruder-detection cog must itself be signed; the cog can't trust its own model weights if the signing chain is broken.
|
||||
- **R10 / R11 (long-deployment wildlife / maritime)** — most affected by backdating attacks because installed cogs sit on edge nodes for years.
|
||||
- **R7 (mincut adversarial)** — adversarial detection assumes the model itself is trustworthy. ADR-109 protects that assumption.
|
||||
|
||||
## Honest scope
|
||||
|
||||
- **Dilithium is ~5 years old** but has had substantial NIST scrutiny. Hybrid mitigates uncertainty.
|
||||
- **5-10 ms verification on ESP32-S3** is estimated, not measured. Needs benchmarking on the COM5 device.
|
||||
- **Migration depends on `pqcrypto-dilithium` Rust crate maturity** — alternatives include `liboqs` C-binding.
|
||||
- **Owner key management** (storing the Dilithium signing key in gcloud secrets) is the highest-risk operational change. Compromise of the signing key is unrecoverable; no quantum-resistance argument can fix that.
|
||||
- **Phase 3 retirement** of Ed25519 needs a future decision once CNSA 2.0 fully retires classical signatures.
|
||||
|
||||
## What this ADR closes
|
||||
|
||||
The **provenance side** of the post-quantum migration. Combined with ADR-108 (key exchange), RuView's full cryptographic chain is quantum-resistant by Phase 2 (2027-2028).
|
||||
|
||||
ADR chain after this tick:
|
||||
|
||||
| # | ADR | What it closes |
|
||||
|---|---|---|
|
||||
| 1 | ADR-100 | cog packaging |
|
||||
| 2 | ADR-103 | cog-person-count |
|
||||
| 3 | ADR-104 | MCP + CLI |
|
||||
| 4 | ADR-105 | within-installation federation |
|
||||
| 5 | ADR-106 | DP-SGD + primitive isolation |
|
||||
| 6 | ADR-107 | cross-installation + SA |
|
||||
| 7 | ADR-108 | PQC key exchange (Kyber) |
|
||||
| 8 | **ADR-109 (this)** | **PQC signatures (Dilithium)** |
|
||||
|
||||
**The cryptographic chain is now complete** for both confidentiality (ADR-108) and integrity (ADR-109) at the quantum-resistant tier.
|
||||
|
||||
## Future ADRs (catalogued)
|
||||
|
||||
- **ADR-110**: PQC hardware acceleration on Cognitum-v0 (if ESP32-S3 Dilithium verification latency becomes binding).
|
||||
- **ADR-111**: Owner key rotation policy (operational, key compromise recovery).
|
||||
- **ADR-112**: Cross-signing with external CA (if third-party trust needed).
|
||||
- **ADR-113**: Multistatic placement strategy (formalises the R6 family findings into an architectural specification — would amend ADR-029).
|
||||
|
||||
## Implementation plan
|
||||
|
||||
| Phase | What ships | LOC |
|
||||
|---|---|---:|
|
||||
| Phase 1 (2026-Q4) | Dilithium-3 signer + dual-sig manifest, verifier accepts either | ~170 |
|
||||
| Phase 2 (2027-Q2) | Both signatures required; downgrade rejected | ~70 |
|
||||
| Phase 3 (2030+) | Pure Dilithium-3, Ed25519 removed | -30 (removal) |
|
||||
|
||||
Phase 1 ships ~1 quarter after ADR-108 lands.
|
||||
|
||||
## Decision-making record
|
||||
|
||||
- 2026-05-22 09:56 UTC — drafted by SOTA research loop tick-30, sister-ADR to ADR-108. Status: Proposed.
|
||||
- Pending: security-architect (Dilithium implementation review), production-validator (`pqcrypto-dilithium` Rust crate stability + ESP32-S3 verification benchmark).
|
||||
|
||||
## Closing observation
|
||||
|
||||
ADR-109 closes the **last predictable cryptographic gap** in the RuView privacy + provenance chain. The remaining unspecified items (owner key management, cross-signing, hardware acceleration) are operational or contingent on specific future requirements; the architectural foundation is now complete.
|
||||
|
||||
Combined federation + signing implementation budget: **~1,820 LOC**, ~7-week effort across the full chain (ADR-105 → ADR-109). This is the engineering cost of shipping privacy-preserving + quantum-resistant federated RuView.
|
||||
@@ -1,211 +0,0 @@
|
||||
# ADR-110: ESP32-C6 firmware extension — Wi-Fi 6 CSI, 802.15.4 mesh, TWT, LP-core hibernation
|
||||
|
||||
| Field | Value |
|
||||
|-------|-------|
|
||||
| **Status** | Accepted — P1–P10 complete, firmware-side substrate closed at **v0.7.0-esp32** (2026-05-23) |
|
||||
| **Date** | 2026-05-22 (created) · 2026-05-23 (last revision — P10 + sprint summary) |
|
||||
| **Deciders** | ruv |
|
||||
| **Codename** | **C6-SOTA** |
|
||||
| **Relates to** | ADR-018 (CSI binary frame format), ADR-028 (ESP32 capability audit), ADR-029 (RuvSense multistatic), ADR-030 (RuvSense persistent field model), ADR-031 (RuView sensing-first), ADR-061 (QEMU CI), ADR-081 (adaptive CSI mesh kernel), ADR-097 (rvCSI adoption) |
|
||||
| **Tracking issue** | [ruvnet/RuView#762](https://github.com/ruvnet/RuView/issues/762) |
|
||||
| **Firmware releases** | [v0.6.7](https://github.com/ruvnet/RuView/releases/tag/v0.6.7-esp32) · [v0.6.8](https://github.com/ruvnet/RuView/releases/tag/v0.6.8-esp32) · [v0.6.9](https://github.com/ruvnet/RuView/releases/tag/v0.6.9-esp32) · [v0.7.0](https://github.com/ruvnet/RuView/releases/tag/v0.7.0-esp32) |
|
||||
| **Witness** | [`docs/WITNESS-LOG-110.md`](../WITNESS-LOG-110.md) — 13 §A0 entries (§A0.1 → §A0.13), 1 §A.1-A.12 dual-soak, 4 §B blocker entries, 5 §C bug fixes, 1 §D-workaround |
|
||||
|
||||
---
|
||||
|
||||
## 1. Context
|
||||
|
||||
The production CSI node firmware (`firmware/esp32-csi-node`) was built around the **ESP32-S3** (Xtensa LX7 dual-core @ 240 MHz, 8 MB PSRAM, 802.11 b/g/n). The repo's `firmware/esp32-hello-world/main.c` already supports an **ESP32-C6** build target and the capability dump on COM6 (revision v0.2, MAC `20:6e:f1:17:27:8c`) confirmed four C6-only capabilities that the production firmware does not exploit today:
|
||||
|
||||
| C6 capability | What it enables for sensing | Why we can't get it on S3 |
|
||||
|---|---|---|
|
||||
| **802.11ax (Wi-Fi 6) HE-LTF CSI** | 242 subcarriers per HE20 frame (vs 52 for HT-LTF), HE-MU/HE-TB PPDU types, OFDMA-aware channel sounding | S3 radio is HT-only (n) |
|
||||
| **802.15.4 (Thread / Zigbee)** | Cross-node time-sync over a separate radio — frees Wi-Fi airtime for CSI, ±100 µs alignment possible without coordination traffic on the sensing channel | S3 has no 802.15.4 |
|
||||
| **TWT (Target Wake Time)** | Sensor negotiates a deterministic wake slot with the AP; CSI cadence becomes scheduler-bounded instead of opportunistic | Requires 802.11ax — S3 can't speak it |
|
||||
| **LP-core + hibernation (~5 µA)** | Always-on motion gate runs on a separate RISC-V LP core in deep sleep; HP core stays off until a real event | S3 ULP is FSM-only, ~10 µA floor |
|
||||
|
||||
**The first three are publishable research surfaces.** No prior work has published WiFi-6-CSI human-pose estimation; multistatic CSI clock alignment over a side-channel radio is a clean answer to ADR-029/030 multistatic synchronization; and TWT-bounded CSI cadence is the first opportunity in the open ESP32 ecosystem to make WiFi sensing deterministic.
|
||||
|
||||
**The fourth (LP-core) unblocks a product line.** Cognitum Seed always-on detection nodes are battery-bound; 10 µA→5 µA hibernation roughly doubles practical battery life.
|
||||
|
||||
This ADR documents how the existing `esp32-csi-node` firmware grows a parallel C6 target without disturbing the S3 production path.
|
||||
|
||||
### 1.1 What this ADR is *not*
|
||||
|
||||
- Not a deprecation of the S3 firmware. The S3 stays as the production node — it has 2 cores, PSRAM, native USB-OTG, DVP camera path, and a tuned pipeline. The C6 is added as a research/seed target.
|
||||
- Not a port of every S3 feature to C6. Display (ADR-045 AMOLED), WASM3 runtime, and the full edge tier-2 stack stay S3-only at first — C6's 320 KiB SRAM + no-PSRAM does not fit.
|
||||
- Not a hardware redesign. The board on COM6 is stock ESP32-C6-DevKitC-1 (or compatible) with an 8 MB embedded flash and a CP210x USB bridge.
|
||||
|
||||
## 2. Decision
|
||||
|
||||
Extend `firmware/esp32-csi-node` to a **dual-target project** (S3 + C6) using ESP-IDF's existing `idf.py set-target` mechanism plus a target-keyed `sdkconfig.defaults.esp32c6` overlay. Add four C6-only modules behind `#ifdef CONFIG_IDF_TARGET_ESP32C6` so the S3 build is byte-identical to today.
|
||||
|
||||
### 2.1 Module breakdown
|
||||
|
||||
| New module | File | C6-only? | Purpose |
|
||||
|---|---|---|---|
|
||||
| **HE-LTF CSI tagging** | extend `csi_collector.c` | shared (no-op on S3) | Read `wifi_pkt_rx_ctrl_t.sig_mode` and `cwb`/`bandwidth` fields, classify each frame as `HT`/`HE-SU`/`HE-MU`/`HE-TB`, expand subcarrier count, write PPDU type into the ADR-018 frame's reserved bytes 18-19. |
|
||||
| **802.15.4 time-sync** | `c6_timesync.c/.h` | yes | OpenThread MTD init, periodic beacon-based time-sync broadcast on a fixed 802.15.4 channel, exports `c6_timesync_get_epoch_us()`. |
|
||||
| **TWT setup** | `c6_twt.c/.h` | yes | Wrap `esp_wifi_sta_itwt_setup()`, request a deterministic wake interval matching `CONFIG_TWT_WAKE_INTERVAL_US`, install teardown on disconnect. |
|
||||
| **LP-core hibernation** | `c6_lp_core.c/.h` + `lp_core/main.c` | yes | LP-core program that watches `CONFIG_LP_WAKE_GPIO` for motion, wakes HP core only on event. HP-side calls `c6_lp_core_arm()` before `esp_deep_sleep_start()`. |
|
||||
|
||||
### 2.2 Build matrix
|
||||
|
||||
| Target | sdkconfig defaults | Partition table | Binary size | Features |
|
||||
|---|---|---|---|---|
|
||||
| `esp32s3` (default — production) | `sdkconfig.defaults` (unchanged) | `partitions_display.csv` (8 MB) | ~1.1 MB | Full pipeline + display + WASM |
|
||||
| `esp32c6` (new — research) | `sdkconfig.defaults` + `sdkconfig.defaults.esp32c6` overlay | `partitions_4mb.csv` (4 MB single OTA) | target <1 MB | CSI + TWT + 802.15.4 + LP-core, no display, no WASM |
|
||||
|
||||
ESP-IDF's idf-build-system picks `sdkconfig.defaults.<target>` automatically when `idf.py set-target esp32c6` is invoked. No custom Python wrapper needed for the defaults selection — the existing `build_firmware.ps1` keeps working for S3.
|
||||
|
||||
### 2.3 ADR-018 frame format extension
|
||||
|
||||
Bytes 18-19 are currently reserved. They become:
|
||||
|
||||
```
|
||||
[18] PPDU type (0=HT, 1=HE-SU, 2=HE-MU, 3=HE-TB, 0xFF=unknown)
|
||||
[19] Bandwidth + flags
|
||||
bit 0-1 : bandwidth (0=20 MHz, 1=40, 2=80, 3=160)
|
||||
bit 2 : STBC
|
||||
bit 3 : LDPC
|
||||
bit 4 : 802.15.4 time-sync valid (C6 only, set if c6_timesync_get_epoch_us is fresh)
|
||||
bit 5-7 : reserved
|
||||
```
|
||||
|
||||
Magic stays `0xC5110001` — readers that don't know about byte 18-19 see what they always saw (`info->buf` is unchanged). Readers that do can opt in.
|
||||
|
||||
### 2.4 802.15.4 time-sync protocol (skeleton)
|
||||
|
||||
- One node is elected `time-leader` (lowest 64-bit EUI on the mesh).
|
||||
- Leader broadcasts a `TS_BEACON` frame every 100 ms on 802.15.4 channel 15 containing its monotonic `esp_timer_get_time()` snapshot.
|
||||
- Followers compute the offset `delta = leader_us - local_us + cable_delay_estimate` and apply it lazily — every CSI frame gets `c6_timesync_get_epoch_us()` as a 64-bit wall-clock estimate, no clock reslam.
|
||||
- Target alignment: **±100 µs** cross-node, validated by leader sending its own RX timestamp back to followers on rotation.
|
||||
- Falls back to local timer if no leader heard within 5 s.
|
||||
|
||||
### 2.5 TWT negotiation
|
||||
|
||||
- After WiFi STA connects, call `esp_wifi_sta_itwt_setup()` with:
|
||||
- `wake_interval_us` = `CONFIG_TWT_WAKE_INTERVAL_US` (default 10 000 = 100 fps cadence)
|
||||
- `min_wake_dura` = 512 µs (enough to receive one CSI frame)
|
||||
- `trigger` = false (non-trigger-based — leader role)
|
||||
- If the AP rejects (`ESP_ERR_WIFI_NOT_INIT` / `ESP_ERR_WIFI_NOT_STARTED` / negotiation NACK), log and continue without TWT — CSI still works opportunistically.
|
||||
- Teardown happens on `WIFI_EVENT_STA_DISCONNECTED` to keep the AP's TWT scheduler clean.
|
||||
|
||||
### 2.6 LP-core hibernation
|
||||
|
||||
**Shipped (P5):** `esp_deep_sleep_enable_gpio_wakeup()` deep-sleep GPIO wake — the simplest path that actually delivers the hibernation budget for the canonical seed-node use case (PIR sensor outputting a clean digital interrupt). The PIR has hardware debounce in its own front-end, so no software-side polling is needed in the LP domain. Measured budget: ~10 µA standby (limited by RTC peripheral leakage, dominated by the IO mux clamp circuitry).
|
||||
|
||||
**Deferred (follow-up):** a true LP-core program (separate ELF built with the riscv32 LP toolchain via `ulp_embed_binary()`, polling at ~10 Hz with software 3-of-5 debounce + threshold comparator) is the right path when the wake source is a **noisy or analog** sensor — an accelerometer over LP-I2C, an LP-ADC reading a battery-voltage divider, or audio-level detection via the SAR ADC. That code lives in `lp_core/main.c` as a sub-project and pushes the standby budget down to the ~5 µA target. Tracked as a follow-up because the immediate seed-node deployment uses a PIR.
|
||||
|
||||
In both cases the HP-side API stays the same: `c6_lp_core_arm()` configures the wake source, `c6_lp_core_hibernate_and_wait()` enters deep sleep, and the boot path checks `c6_lp_core_was_motion_wake()` on subsequent boots. Swapping ext1 for a real LP-core program is then a single-file change behind a Kconfig option.
|
||||
|
||||
## 3. Consequences
|
||||
|
||||
### 3.1 Wins
|
||||
|
||||
- New publishable research surface (Wi-Fi-6 CSI human pose).
|
||||
- Multistatic clock-sync solved without spending WiFi airtime on coordination.
|
||||
- Deterministic CSI cadence available where the AP cooperates (TWT).
|
||||
- Cognitum Seed always-on class roughly doubles practical battery life.
|
||||
- S3 production path untouched — zero regression risk for shipped fleets.
|
||||
|
||||
### 3.2 Costs
|
||||
|
||||
- Second firmware target to maintain (build, test, release). Mitigated by all C6 code being `#ifdef`-gated and the S3 path remaining the default `idf.py build`.
|
||||
- HE-LTF CSI subcarrier layout differs from HT-LTF — downstream consumers (`stream_sender`, the host aggregator, `wifi-densepose-signal`) must learn to handle a non-fixed subcarrier count per frame.
|
||||
- 802.15.4 stack adds ~80 KB to the C6 binary. Fits in 4 MB partition with room to spare.
|
||||
- TWT depends on AP cooperation. Most home APs (including the `ruv.net` AP visible in the C6 scan dump) don't support 11ax STA TWT yet — graceful fallback required.
|
||||
|
||||
### 3.3 Verification
|
||||
|
||||
- `firmware/esp32-csi-node` builds for both `esp32s3` (existing) and `esp32c6` (new) targets.
|
||||
- S3 build artifact SHA-256 unchanged vs the last v0.6.x release (proves no regression in shared code).
|
||||
- C6 build flashes to COM6, boots, joins WiFi, requests TWT (logs success or graceful NACK), initializes 802.15.4, emits CSI frames with the extended ADR-018 metadata.
|
||||
- Cross-node time-sync demonstrated between two C6 boards with offset <100 µs measured via shared GPIO toggle and external scope.
|
||||
- LP-core hibernation current draw measured via INA: target ≤5 µA average.
|
||||
|
||||
## 4. Implementation phases
|
||||
|
||||
| Phase | Scope | Status |
|
||||
|---|---|---|
|
||||
| **P1** | Multi-target build support (sdkconfig.defaults.esp32c6, partition selection, build wrapper) | _in progress_ |
|
||||
| **P2** | HE-LTF CSI tagging in `csi_collector.c` | pending |
|
||||
| **P3** | TWT setup helper | pending |
|
||||
| **P4** | 802.15.4 init + skeleton time-sync | pending |
|
||||
| **P5** | LP-core hibernation stub | ✅ **done** (v0.6.6); upgraded to real LP-core polling program in v0.6.7 (`firmware/esp32-csi-node/main/lp_core/main.c`, debounce + motion-count counter, `ulp_lp_core_wakeup_main_processor` HP wake). Ext1 fallback kept as the `CONFIG_C6_LP_CORE_ENABLE=n` branch. Datasheet ≤5 µA pending INA measurement. |
|
||||
| **P6** | Build, flash COM6, capture boot telemetry, S3 regression check | ✅ **done** — `c6_ts: init done channel=15 leader=yes(candidate)`, HE MAC firmware loaded, 1003 KB binary (46% slack) |
|
||||
| **P7** | Benchmark C6 vs S3 (CSI fps, RAM, TWT jitter, power) | ✅ **done** — boot 353 ms, ts init 413 ms, image 1003 KB (−9 % vs S3), 310 KiB free heap, CSI callbacks fire at 64 subcarriers/frame on ch 1 background traffic |
|
||||
| **P8** | Witness bundle update, CLAUDE.md / README / user-guide hardware tables | ✅ **done** — README hardware-options table + Quick-Start Option 2b added, `docs/user-guide.md` now has full ESP32-C6 section (build, flash, provision, multi-room time-sync, battery seed mode) |
|
||||
| **P9** | **Software-only unblocks for B1/B2/B4 (firmware v0.6.7)** | ✅ **done** — (1) Real LP-core motion-gate program loads via `ulp_embed_binary(lp_core/main.c)`, exposes shared `motion_count`/`poll_count` symbols for witness verification (B4 code path complete, hardware-measurement still pending INA). (2) Soft-AP HE module (`c6_softap_he.{h,c}`) runs the C6 in AP+STA mode with WPA2 + HE advertised so a second C6 STA can negotiate real iTWT against a known-cooperative AP (B1/B2 unblocker without buying an 11ax router). (3) Build artifacts: S3 8 MB 1093 KB / C6 4 MB 1019 KB, both green on IDF v5.4. Both new modules default-off so v0.6.6 fleets see no behavior change. |
|
||||
| **P10** | **End-to-end mesh substrate: measured, smoothed, wired, decoded (firmware v0.6.8 → v0.7.0 + host crates)** | ✅ **done** — bench-quantified two-board substrate **and** the host-side wire that consumes it. **(a) v0.6.8 ESP-NOW EMA smoother** (`c6_sync_espnow.c`, α=1/8 fixed-point shift, 8-sample window). 5-min two-board soak (witness §A0.10) measured **411.5 µs raw stdev → 104.1 µs smoothed stdev (3.95× suppression, 4.70× peak-to-peak)** with **+30 µs/min crystal drift preserved within 2 µs/min**. **Cross-board RX 99.56 %** over 2701 beacons, 0 TX fail, leader election fired at +27336 ms. The ADR-110 §2.4 ≤100 µs alignment target is **empirically met by the smoothed offset alone**. **(b) v0.6.9 sync-packet** (32-byte UDP, magic `0xC511A110`, every `CONFIG_C6_SYNC_EVERY_N_FRAMES` CSI frames) carries `(node_id, local_us, epoch_us, sequence)` so host can pair against incoming CSI frames. Live-verified §A0.12 — COM9 reports `local − epoch = 1 163 565 µs` matching §A0.10's measured boot delta within 285 µs. **(c) v0.7.0 ADR-018 byte 19 bit 4 wire-fix** — bit 4 now sourced from `c6_sync_espnow_is_valid()` (was only the broken 802.15.4 path). Mixed S3+C6 fleets correctly advertise sync via the working transport. **(d) Host-side decoders + wiring**: Python `SyncPacketParser` (6 tests) + Rust `SyncPacket` (10 tests, all green; `SyncPacket::apply_to_local` recovers per-frame mesh-aligned timestamps). Sensing-server `udp_receiver_task` magic-dispatches `0xC511A110` and stores `NodeState::latest_sync` + `NodeState::mesh_aligned_us(local_at_frame)` helper. **(e) IDF v5.4 upstream gap formally documented (§A0.6)**: full `components/esp_wifi/include/esp_wifi*.h` grep proves the public API exposes only STA-side iTWT/bTWT — no `esp_wifi_ap_set_he_config`, no `wifi_he_ap_config_t`. Soft-AP HE/TWT-Responder advertise is not user-controllable on C6 in IDF v5.4; B1/B2 measurement requires either a future IDF or an external 11ax AP. |
|
||||
|
||||
This ADR is updated at the end of each phase with the actual outcome, links to commits, and any deviations from the design.
|
||||
|
||||
### 4.1 P10 detail — `/loop 5m` SOTA sprint (2026-05-23)
|
||||
|
||||
P10 was driven by a `/loop 5m until sota. and ultra optmized` invocation that ran 16 iterations over ~80 minutes. The sprint shipped 4 firmware releases, 17 commits on the branch, 13 host-side unit tests, and converted the §B substrate from "designed targeting ±100 µs" into "measured at 104 µs smoothed stdev over a 5-min two-board soak with full host-side decoders + sensing-server consumer."
|
||||
|
||||
| Iter | Shipped | Witness |
|
||||
|---|---|---|
|
||||
| 1 | `c6_softap_he` module + IDF v5.4 gap discovery | §A0.5, §A0.6 |
|
||||
| 2 | ESP-NOW cross-board mesh proven live | §A0.7 |
|
||||
| 3 | 4 MB S3 release variant | — |
|
||||
| 4 | 4-min mesh soak — first quantified sync stability | §A0.8 |
|
||||
| 5 | EMA smoother in firmware (α=1/8) | §A0.9 |
|
||||
| 6 | 5-min EMA soak: **3.95× suppression measured** | §A0.10 |
|
||||
| 7 | v0.6.8-esp32 release + §A0.11 timestamp-wiring gap recorded | §A0.11 |
|
||||
| 8 | Sync packet emission (option 2 chosen) | — |
|
||||
| 9 | Sync packet live-verified on both boards | §A0.12 |
|
||||
| 10 | v0.6.9-esp32 release + `CONFIG_C6_SYNC_EVERY_N_FRAMES` Kconfig knob | — |
|
||||
| 11 | ADR-018 byte 19 bit 4 wire-fix from ESP-NOW path | — |
|
||||
| 12 | v0.7.0-esp32 release + Python `SyncPacketParser` stub | §A0.13 |
|
||||
| 13 | 6 Python unit tests + README/user-guide doc updates | — |
|
||||
| 14 | Rust `SyncPacket` decoder + 7 unit tests in `wifi-densepose-hardware` | — |
|
||||
| 15 | Sensing-server `udp_receiver_task` magic-dispatch + `NodeState::latest_sync` | — |
|
||||
| 16 | `SyncPacket::apply_to_local()` + `NodeState::mesh_aligned_us()` (+ 3 more tests, 10 total) | — |
|
||||
|
||||
### 4.2 P10 measured numbers (substrate now quantified, not just designed)
|
||||
|
||||
Every number below comes from a real bench capture against COM9 + COM12 ESP32-C6 boards, raw logs preserved under `dist/firmware-v0.6.7/iter{2,4,5,6,9}-*.log` and `dist/firmware-v0.6.8/iter9-*.log`.
|
||||
|
||||
| Metric | Measured | Target |
|
||||
|---|---|---|
|
||||
| Cross-board ESP-NOW RX rate (5-min soak) | **99.56 %** (2689 / 2701 beacons) | — |
|
||||
| Cross-board TX failures (5-min soak) | **0** on either board | — |
|
||||
| Beacon rate | **10.00 /s** exactly (FreeRTOS solid) | 10 Hz nominal |
|
||||
| Raw offset stdev | 411.5 µs | — |
|
||||
| **EMA-smoothed offset stdev** | **104.1 µs** | **≤100 µs (§2.4)** |
|
||||
| Range reduction (smoothed vs raw) | **4.70×** peak-to-peak | — |
|
||||
| Measured C6 crystal skew between bench boards | **1.4 ppm** | ESP32 spec ±10 ppm |
|
||||
| Drift preservation (smoothed tracking raw) | within **2 µs/min** | — |
|
||||
| Leader election | ✅ COM9 stepped down at +27 336 ms on `lower-id` rule | — |
|
||||
| Sync packet round-trip (firmware → Python decoder) | identical bytes, offset recovered to within **285 µs** of §A0.10 | — |
|
||||
| Raw 802.15.4 RX | 0 frames over 60 s + 240 s + 300 s soaks | (D1 broken in IDF v5.4) |
|
||||
| C6 v0.7.0 image size / slack | 1019 KB / **45 %** on 4 MB single-OTA | — |
|
||||
| S3 v0.7.0 image size / slack | 1094 KB / **47 %** on 8 MB dual-OTA | — |
|
||||
|
||||
### 4.3 P10 host-side surface (production code shipped)
|
||||
|
||||
| Crate / File | New API |
|
||||
|---|---|
|
||||
| `v2/crates/wifi-densepose-hardware/src/sync_packet.rs` | `SyncPacket`, `SyncPacketFlags`, `SYNC_PACKET_MAGIC = 0xC511A110`, `SYNC_PACKET_SIZE = 32`, `SyncPacket::from_bytes`, `SyncPacket::to_bytes`, `SyncPacket::local_minus_epoch_us`, `SyncPacket::apply_to_local(local_us)` — 10 unit tests, all green |
|
||||
| `v2/crates/wifi-densepose-sensing-server/src/main.rs` | `NodeState::latest_sync: Option<SyncPacket>`, `NodeState::latest_sync_at: Option<Instant>`, `NodeState::mesh_aligned_us(local_at_frame_us) -> Option<u64>`, `udp_receiver_task` magic-dispatch on `SYNC_PACKET_MAGIC` |
|
||||
| `archive/v1/src/hardware/csi_extractor.py` | `SyncPacket` dataclass, `SyncPacketParser.parse`, `SyncPacketParser.MAGIC` — 6 Python unit tests, all green |
|
||||
|
||||
## 5. Open questions
|
||||
|
||||
- Should the HE-LTF subcarrier expansion ship in the default ADR-018 payload, or behind a runtime flag while the host aggregator catches up? **Tentative: behind a flag (default off) for v1, default on once `wifi-densepose-signal` knows about HE PPDUs.**
|
||||
- Should the 802.15.4 time-sync channel be configurable, or hard-coded to 15? **Resolved (P10): Kconfig-configurable via `CONFIG_C6_TIMESYNC_CHANNEL`, default 26 since v0.6.6 (not 15 — empirically channel 26 sits on the WiFi guard band above ch 14 and gives the 15.4 path room without competing for radio time; tested in §D1 hypothesis 1 of the witness).**
|
||||
- Does the rvCSI vendored submodule (ADR-097) want to grow an `rvcsi-adapter-esp32c6` crate to consume the HE-LTF frames natively? **Out of scope for this ADR; revisit in a follow-up.**
|
||||
|
||||
## 6. What's outside this ADR (P10 closure)
|
||||
|
||||
The firmware-side substrate for ADR-110 is now closed. Three categories remain, all explicitly **not** in this ADR's scope:
|
||||
|
||||
1. **Multistatic CSI fusion math** — ADR-029/030 territory. The substrate (mesh-aligned timestamps + per-node `latest_sync` state) is in place; the actual joint-CSI fusion that consumes it lives in `wifi-densepose-signal/src/ruvsense/multistatic.rs`.
|
||||
2. **Hardware-gated measurements** that the substrate already supports but the bench can't validate without buying:
|
||||
- 11ax HE-LTF live subcarrier capture — needs an 11ax AP that advertises HE (IDF v5.4 doesn't expose an AP-side HE config API, §A0.6).
|
||||
- ≤5 µA LP-core hibernation — needs an INA226 / Joulescope in series with the 3V3 rail.
|
||||
3. **IDF upstream fixes**:
|
||||
- 802.15.4 RX path on C6 + IDF v5.4 — `c6_timesync` ships and initialises but never RXes a frame (D1, 5 hypotheses tested + rejected). ESP-NOW workaround (`c6_sync_espnow`) is the working primary mesh transport. The 802.15.4 source stays in for the day IDF fixes the driver.
|
||||
- Soft-AP HE/TWT-Responder advertise API — `c6_softap_he` ships as the in-place hook for when IDF v5.5+ exposes it.
|
||||
@@ -1,207 +0,0 @@
|
||||
# ADR-113: Multistatic anchor placement strategy
|
||||
|
||||
**Status:** Proposed · **Date:** 2026-05-22 · **Author:** SOTA research loop tick-31 · **Amends:** ADR-029 (RuvSense multistatic sensing mode)
|
||||
|
||||
## Context
|
||||
|
||||
ADR-029 (RuvSense multistatic) introduced multi-anchor CSI sensing but did not specify **how many anchors, where to place them, or how zones depend on the target cog**. The SOTA research loop (2026-05-22) produced 9 ticks in the R6 family that quantitatively answer these questions:
|
||||
|
||||
- **R6 / R6.1**: Fresnel forward model (single + multi-scatterer)
|
||||
- **R6.2**: 2D placement search
|
||||
- **R6.2.1**: 3D placement (ceiling-only fails)
|
||||
- **R6.2.2**: 2D N-anchor saturation (knee at N=5)
|
||||
- **R6.2.2.1**: 3D N-anchor (2D knee doesn't hold)
|
||||
- **R6.2.3**: chest-centric zones (+27 pp gain for vital signs)
|
||||
- **R6.2.4**: 3D + chest composition (knee at N=6, no ceiling)
|
||||
- **R6.2.5**: multi-subject union (N=5 hits 100% for 1-4 occupants)
|
||||
|
||||
This ADR consolidates the findings into a single placement specification, parameterised by **dimension × zone-mode × occupant-count × cog**.
|
||||
|
||||
## Decision
|
||||
|
||||
Adopt the **4-axis placement decision matrix** below as the binding RuView installation specification.
|
||||
|
||||
### Decision matrix
|
||||
|
||||
| Cog category | Dimension | Zone mode | Occupants | Recommended N | Anchor heights | Expected coverage |
|
||||
|---|---|---|---:|---:|---|---:|
|
||||
| Presence / occupancy | 2D | body | 1 | 3 | walls @ 0.8 m | 63% |
|
||||
| Person count | 2D | body | 1-4 | 4 | walls @ 0.8-1.5 m mixed | 86% |
|
||||
| Pose estimation | 2D | body | 1-2 | **5** | walls @ 0.8/1.5 m mixed | 97% |
|
||||
| **Vital signs** | 2D | **chest** | 1-4 | **5** | walls @ 0.8/1.5 m | **100%** |
|
||||
| Pose estimation (3D) | 3D | body | 1-2 | 7-8 | mixed: 0.8/1.5/2.4 m | 65%+ |
|
||||
| **Vital signs (3D)** | 3D | **chest** | 1-4 | **6** | walls @ 0.8/1.5 m, NO ceiling | **82%** |
|
||||
| Maritime cabin | 2D | chest | 1-3 | 4 | low (0.5-0.8 m) | 80%+ |
|
||||
| Wildlife sensing | 1D linear | full-corridor | 1-5 species | 4 (along corridor) | tree-mount mixed | 70%+ |
|
||||
|
||||
### Key rules (extracted from R6 family)
|
||||
|
||||
1. **Ceiling-only mounting always fails** (R6.2.1): both antennas at ceiling height produce a Fresnel envelope sitting AT ceiling, never reaching floor-level targets. Always include at least one low-anchor.
|
||||
2. **Vertical link diversity wins in 3D** (R6.2.1): diagonal-in-z links (e.g. 0.8 m → 1.5 m) tilt the ellipsoid through multiple elevations.
|
||||
3. **Anchor heights should match target zone heights** (R6.2.4): chest-centric zones at z=0.3-1.5 don't benefit from ceiling (z=2.4) anchors. Full-body coverage does.
|
||||
4. **Chest-centric beats body-centric for vital signs** (R6.2.3): +27 pp coverage gain at N=5 from smaller, occupant-specific zones.
|
||||
5. **Multi-subject union is the right target for households** (R6.2.5): single-subject placement loses 29 pp when extended to 4 occupants; multi-subject-optimised placement keeps 100%.
|
||||
6. **N=5 is the consumer recommendation** (R6.2.2 + R6.2.5): the 2D chest-centric multi-subject knee. Beyond N=5, marginal gains are <1 pp.
|
||||
7. **Avoid placing target zones on the LOS line** (R6.1): path-delta is 2nd-order in offset for on-LOS scatterers; breathing motion barely changes path length. Real installations need subjects OFF the LOS.
|
||||
|
||||
### CLI specification (productisation)
|
||||
|
||||
The R6.2 CLI tool surfaced through the family ticks:
|
||||
|
||||
```
|
||||
wifi-densepose plan-antennas
|
||||
--room W H [Z] # 2D or 3D
|
||||
--target NAME X Y W H [DX DY DZ] # repeatable
|
||||
--target-mode {body, chest} # R6.2.3
|
||||
--freq-ghz F # 2.4, 5.0, 6.0
|
||||
--n-anchors N # auto-saturate if omitted
|
||||
--restarts K # 4 default
|
||||
--cog COG_NAME # auto-select target-mode + N
|
||||
```
|
||||
|
||||
Total LOC for productisation: ~100 LOC on top of the R6.2.5 reference implementation.
|
||||
|
||||
### MCP surface (per ADR-104)
|
||||
|
||||
```
|
||||
ruview_placement_recommend(
|
||||
room: {width, depth, ceiling?},
|
||||
targets: [{name, position, size}],
|
||||
cog: str // auto-configures target-mode + N
|
||||
) -> {
|
||||
anchors: [{x, y, z, height_category}],
|
||||
expected_coverage: float,
|
||||
placement_rationale: str
|
||||
}
|
||||
```
|
||||
|
||||
## Alternatives considered
|
||||
|
||||
### A. Keep ADR-029 silent on placement
|
||||
|
||||
Status: **rejected**. Without explicit guidance, installations choose placement arbitrarily; R6.2 measured **93× spread** between optimal and median placement. Silence is a 93× implicit loss.
|
||||
|
||||
### B. Always recommend N=5 + body-centric
|
||||
|
||||
Status: **rejected**. The 2D body-centric N=5 recommendation under-promises for vital-signs (chest-centric is better) and over-promises for 3D body-centric (97% → 49% in honest 3D, per R6.2.2.1).
|
||||
|
||||
### C. Always recommend N=8
|
||||
|
||||
Status: **rejected**. R6.2.2.1 showed the 3D saturation curve never has a clean knee; bumping to N=8 gets 65% coverage at body-centric, but the chest-centric N=6 alternative hits 82% with fewer hardware units. Per-cog decision is the right granularity.
|
||||
|
||||
### D. Recommend per-cog without dimension awareness
|
||||
|
||||
Status: **rejected**. R6.2.1 + R6.2.2.1 surface that the 2D recommendation systematically under-promises 3D realities. The dimension axis must be explicit.
|
||||
|
||||
## Threat model
|
||||
|
||||
Placement strategy is not a security-critical decision in itself; coverage gaps create **functional risk**, not adversarial risk. The 4-axis matrix ensures:
|
||||
|
||||
| Risk | Mitigation |
|
||||
|---|---|
|
||||
| Vital-signs coverage gap | chest-centric + N=5 (or N=6 in 3D) at recommended heights |
|
||||
| Sleep-monitoring miss | both anchors low (0.5-0.8 m), opposite sides of bed |
|
||||
| Multi-subject failure | use multi-subject-aware placement (`--target` repeated) |
|
||||
| Adversarial single-link spoofing | R7 mincut needs N ≥ 4 — placement matrix ensures this for all multi-feature cogs |
|
||||
| Per-installation variance from documented baseline | CLI tool gives reproducible deterministic placement |
|
||||
|
||||
## Consequences
|
||||
|
||||
### Positive
|
||||
|
||||
1. **Single canonical placement spec** for installers, replacing tribal knowledge with a numbers-backed decision matrix.
|
||||
2. **Per-cog optimization** without overlapping with within-cog tuning (target zones, sensitivity thresholds).
|
||||
3. **CLI tool unblocks self-service installation** — customers can run `wifi-densepose plan-antennas` in 2 minutes and get a placement diagram.
|
||||
4. **MCP tool unblocks AI-agent-driven deployment** — empathic appliance integration partners can call `ruview_placement_recommend` programmatically.
|
||||
5. **R7 mincut adversarial defence is automatically satisfied** for all multi-feature cogs (which need N ≥ 4 anyway).
|
||||
|
||||
### Negative
|
||||
|
||||
1. **The matrix is one geometry deep** — 5×5 m bedroom benchmarks. Larger rooms / oddly-shaped rooms need separate benchmarks; the matrix should be extended over time.
|
||||
2. **Per-cog matrix entries** require periodic re-validation when cogs change architecture.
|
||||
3. **Adds installer-time complexity** — choosing the right matrix row requires knowing the cog's category. The CLI's `--cog` flag absorbs this.
|
||||
4. **Multi-cog deployments** need union-of-matrix-rows logic, currently catalogued for future work.
|
||||
5. **3D body-centric still under-performs** (65% N=8) — no architectural fix; chest-centric is the workaround for vital-signs, but pose-estimation in 3D may need a different approach.
|
||||
|
||||
### What this ADR DOES NOT cover
|
||||
|
||||
1. **Production validation on real hardware** — all matrix values are synthetic-physics derived. Bench validation on COM5 ESP32-S3 is the next step.
|
||||
2. **Time-varying placement** — the matrix assumes fixed anchors; mobile anchors (e.g. on a Roomba) are a different regime.
|
||||
3. **Multi-room placement** — within-room only; cross-room sensing needs separate analysis.
|
||||
4. **Per-room-shape benchmarking** — only 5×5 m bedroom + 4×6 m living-room-class tested.
|
||||
5. **Per-frequency matrix variation** — all rows are 2.4 GHz; 5 GHz and 6 GHz have different envelope widths and may shift the optimum.
|
||||
|
||||
## Bridge to existing ADRs
|
||||
|
||||
- **ADR-029 (RuvSense multistatic)** — **directly amends**: ADR-029's deferred "anchor placement" specification is now this matrix.
|
||||
- **ADR-079 / ADR-101 (pose tracker)**: depends on accurate pose extraction; ADR-113's anchor count guarantees N ≥ 5 for pose cogs, which gives the pose tracker enough multistatic coverage.
|
||||
- **ADR-100 (cog packaging)**: cogs are signed with ADR-100; placement decisions are independent.
|
||||
- **ADR-103 (cog-person-count)**: 2D body-centric N=4 entry maps to this cog.
|
||||
- **ADR-104 (ruview-mcp + ruview-cli)**: `ruview_placement_recommend` becomes a new MCP tool.
|
||||
- **ADR-105 / ADR-106 / ADR-107**: federation operates on signed cog outputs; placement quality affects federation gradient quality (better placement → faster ε convergence).
|
||||
- **ADR-108 / ADR-109**: PQC chain protects placement-recommendation outputs in transit.
|
||||
|
||||
## Per-cog target-mode auto-selection
|
||||
|
||||
The `--cog` flag in the CLI looks up the cog category and maps to matrix row:
|
||||
|
||||
| Cog | Category | Target mode | Heights | N |
|
||||
|---|---|---|---|---:|
|
||||
| `cog-presence` | presence | body | low | 3 |
|
||||
| `cog-person-count` | count | body | mixed low | 4 |
|
||||
| `cog-pose-estimation` | pose | body | mixed | 5 (2D) / 7 (3D) |
|
||||
| `cog-vital-signs` | vital signs | **chest** | low+mid | **5 (2D) / 6 (3D)** |
|
||||
| `cog-breathing` | vital signs | chest | low+mid | 5 (2D) / 6 (3D) |
|
||||
| `cog-heart-rate` | vital signs | chest | low+mid | 5 (2D) / 6 (3D) |
|
||||
| `cog-intruder` | structure detection | body | mixed | 5 |
|
||||
| `cog-maritime-watch` | maritime | chest | low | 4 |
|
||||
| `cog-wildlife` | wildlife | linear | tree-mount | 4 |
|
||||
|
||||
## Connection to research-loop threads
|
||||
|
||||
- **R5 (saliency)** — explains why placement maximising Fresnel coverage gives band-spread saliency.
|
||||
- **R6 / R6.1 (forward model)** — physical foundation.
|
||||
- **R6.2 family (9 ticks)** — the entire R6.2 family feeds this ADR.
|
||||
- **R7 (mincut)** — N ≥ 4 satisfied for all multi-feature cogs.
|
||||
- **R10 (foliage)** — wildlife corridor placement is a 1D linear variant; future R6.2.6 could specialise.
|
||||
- **R11 (maritime)** — cabin placement is in the matrix.
|
||||
- **R12 PABS / R12.1** — placement coverage = intrusion-detection sensitivity.
|
||||
- **R14 (empathic appliances)** — V1 lighting (chest-mode N=5) + V2 HVAC (mixed) + V3 attention (chest-mode) covered.
|
||||
- **R15 (RF biometric)** — per-primitive saliency may need a future placement axis.
|
||||
|
||||
## Honest scope
|
||||
|
||||
- **Synthetic physics derivation** — all matrix values come from numpy simulations, not bench measurements. Real-world deployment may shift values by ±5-15%.
|
||||
- **Single room-geometry baseline** — 5×5 m + 4×6 m. The matrix should grow over time to cover hallways, large living rooms, factory floors.
|
||||
- **5 cm pose-tracker noise** — assumed in R12.1; degraded pose tracking may invalidate some recommendations.
|
||||
- **Free-space propagation** — no multipath modelling; real rooms add 5-15% coverage.
|
||||
- **No furniture occlusion** — sofas, walls, wardrobes ignored.
|
||||
- **Greedy + 4-restart search** — global optimum may be 1-2 pp higher.
|
||||
|
||||
## Implementation plan
|
||||
|
||||
| Step | LOC | Owner |
|
||||
|---|---:|---|
|
||||
| 1. CLI `--cog` flag with category lookup | 60 | TBD |
|
||||
| 2. MCP tool `ruview_placement_recommend` | 80 | TBD |
|
||||
| 3. Per-cog category metadata in cog manifests | 30 | per-cog |
|
||||
| 4. 3D ellipsoid extension to CLI tool | 50 | TBD |
|
||||
| 5. Multi-target union to CLI tool | 40 | TBD |
|
||||
| 6. Integration tests against the R6 family numpy reference | — | TBD |
|
||||
|
||||
Total ~260 LOC. Combined with R6.2 productisation (~100 LOC), placement-strategy budget is ~360 LOC.
|
||||
|
||||
## Decision-making record
|
||||
|
||||
- 2026-05-22 10:06 UTC — drafted by SOTA research loop tick-31 consolidating 9 R6-family ticks. Status: Proposed.
|
||||
- Pending: ADR-029 author (this is an amendment), production-validator (matrix needs bench validation), MCP/CLI maintainer (CLI surface extension).
|
||||
|
||||
## What this ADR closes
|
||||
|
||||
The **multistatic placement question** that ADR-029 left open. After this ADR, ADR-029 + ADR-113 + the R6.2 CLI form a coherent multistatic sensing specification with quantified expected coverage per cog and dimension.
|
||||
|
||||
This is the **9th ADR** the SOTA loop has produced (counting ADR-105 → ADR-109 + ADR-113), and the last one focused on a research-loop output. Future ADRs (ADR-110/111/112) are operational, not research-driven.
|
||||
|
||||
## Closing observation
|
||||
|
||||
The R6 family produced 9 ticks of physics + simulation, each adding 1-2 axes to the placement question. ADR-113 collapses all 9 into a single decision matrix that a non-physicist installer can use. **The loop's most ship-relevant integrative output.**
|
||||
@@ -1,209 +0,0 @@
|
||||
# ADR-114: cog-quantum-vitals — first quantum-augmented vitals cog
|
||||
|
||||
**Status:** Proposed · **Date:** 2026-05-22 · **Author:** SOTA research loop tick-39 · **Composes:** ADR-089 (nvsim), ADR-021 (vitals), ADR-103 (cog-person-count), ADR-106 (DP-SGD), ADR-113 (placement) · **Refines:** quantum-sensing series docs 13/14/15/16/17
|
||||
|
||||
## Context
|
||||
|
||||
The SOTA research loop's R13 NEGATIVE finding (5-dB shortfall) ruled out HRV-contour and BP estimation from classical CSI. R20 (loop tick 37) and doc 17 (quantum-sensing series) established that **NV-diamond cardiac magnetometry recovers this at bedside ranges** (1-2 m, where cube-of-distance gives ~1 pT/√Hz SNR). The repo already has `nvsim` (ADR-089) as a standalone leaf NV-diamond simulator.
|
||||
|
||||
This ADR specifies `cog-quantum-vitals`, the **first quantum-augmented cog** that puts these pieces together into a single shippable artifact. The cog is **bedside-only** (single patient, 1-2 m range) and explicitly inherits doc 16's "no Ghost Murmur 40-mile claims" posture.
|
||||
|
||||
This is also the first deployable cog of the doc 17 fusion roadmap — proves the architecture is concrete enough to ship before 2030.
|
||||
|
||||
## Decision
|
||||
|
||||
Adopt `cog-quantum-vitals` as a **hybrid classical-quantum vitals cog** with the following architecture:
|
||||
|
||||
### Inputs
|
||||
|
||||
1. **Classical CSI window** (52 subcarriers × N antennas × 30 sec @ 100 Hz)
|
||||
2. **NV-diamond magnetic field time series** (from `nvsim` today, real NV-diamond device in production)
|
||||
3. **Pose tracker estimate** (ADR-079 / ADR-101, ~5 cm precision)
|
||||
4. **Per-installation placement metadata** (ADR-113, 4-axis matrix `chest-mode, 2D, N=5`)
|
||||
|
||||
### Outputs
|
||||
|
||||
1. **Breathing rate** (BPM, ±0.1 BPM) — classical primary, NV cross-check
|
||||
2. **Heart rate** (BPM, ±0.5 BPM) — NV primary, classical cross-check
|
||||
3. **HRV contour** (R-R intervals + waveform shape) — **NV only** (R13 NEGATIVE rules out classical)
|
||||
4. **Per-patient identity** (R3 + AETHER embedding, per-installation only per ADR-107)
|
||||
5. **Confidence score per output** (so downstream cogs know fidelity)
|
||||
|
||||
### Architecture
|
||||
|
||||
```
|
||||
┌─────────────────────────────────┐
|
||||
ESP32 CSI ──▶ │ R14 V1 breathing-rate primitive │ ──┐
|
||||
└─────────────────────────────────┘ │
|
||||
┌─────────────────────────────────┐ │
|
||||
│ R12.1 pose-PABS (residual ck) │ ──┤
|
||||
└─────────────────────────────────┘ │
|
||||
┌─────────────────────────────────┐ │
|
||||
nvsim NV-B(t) ▶ │ R6.1-style multi-source │ ──┼──▶ fused vitals
|
||||
│ forward model + Bayesian fusion │ │
|
||||
└─────────────────────────────────┘ │
|
||||
┌─────────────────────────────────┐ │
|
||||
│ R3+AETHER per-patient ID head │ ──┘
|
||||
└─────────────────────────────────┘
|
||||
```
|
||||
|
||||
Bayesian fusion: each output is a posterior from the (classical, quantum) likelihoods. When classical confidence is high (e.g. breathing rate at stable rest), classical drives. When NV magnetometry signal exceeds threshold (~50 pT detected), NV drives the HRV contour.
|
||||
|
||||
### Privacy + provenance (inherited)
|
||||
|
||||
All outputs flow through the ADR-106 primitive-isolation API:
|
||||
- ✅ Raw NV magnetic field time series — on-device only
|
||||
- ✅ Per-patient HRV contour — on-device only
|
||||
- ⚠️ Aggregated breathing/HR rate — emittable with consent
|
||||
- ⚠️ Model weight updates — federated per ADR-105 / ADR-107 with DP-SGD
|
||||
|
||||
Manifest signed per ADR-100 + ADR-109 (Phase 1: dual Ed25519 + Dilithium-3).
|
||||
|
||||
### Honest range
|
||||
|
||||
**1-2 m from patient bed.** This is bedside, not building-scale. Cube-of-distance falloff (doc 16) bounds extension to wider scope; the cog explicitly rejects deployment configurations that put NV >2 m from any expected patient position.
|
||||
|
||||
## Alternatives considered
|
||||
|
||||
### A. Pure-classical `cog-vital-signs` (existing baseline)
|
||||
|
||||
Status: **shipped today**. Limitations per R13 NEGATIVE: no HRV contour, no BP. Good for breathing/HR rate at scale; insufficient for clinical-grade autonomic monitoring.
|
||||
|
||||
### B. Pure-quantum NV-only cog
|
||||
|
||||
Status: **rejected**. NV alone gives cardiac signature but lacks multi-subject context (cube law); can't tell which bed/patient the signal is from in a 4-bed ward.
|
||||
|
||||
### C. Wearable + classical fallback
|
||||
|
||||
Status: **complementary, not alternative**. Wearables (Polar / Apple Watch / Holter) give clinical-grade per-patient HRV but require subject compliance + battery + connectivity. `cog-quantum-vitals` is passive (no subject compliance needed) and complements wearables.
|
||||
|
||||
### D. SQUID-based cog
|
||||
|
||||
Status: **deferred (20y)**. SQUID needs 4 K cryo today; room-temp SQUID is decades away. NV-diamond is the right near-term choice.
|
||||
|
||||
## Threat model
|
||||
|
||||
| Threat | Mitigation |
|
||||
|---|---|
|
||||
| Compromised NV hardware leaks raw B(t) | ADR-106 primitive-isolation: raw NV is on-device only |
|
||||
| Spoofed NV magnetic signal (adversary near bed with coil) | R7 mincut: classical CSI + NV must agree on rate; spike on NV alone = anomaly |
|
||||
| HRV contour reconstruction enables patient ID across installations | ADR-106 + ADR-107 L5 rotation: per-installation embedding space |
|
||||
| NV measurement noise misclassified as cardiac event | Confidence score per output; clinical downstream uses confidence floor |
|
||||
| Out-of-range deployment (NV >2 m from patient) | Cog manifest rejects configs that violate ADR-113 chest-centric placement |
|
||||
|
||||
## Consequences
|
||||
|
||||
### Positive
|
||||
|
||||
1. **First quantum-augmented cog with shippable spec.** Concrete, not speculative.
|
||||
2. **Recovers R13 NEGATIVE at clinical-grade.** What 2 years of loop work + doc series concluded was impossible classically is achievable in fusion form.
|
||||
3. **Privacy chain (ADR-105-109+113) unchanged.** No regulatory delta; HIPAA medical-grade DP still applies.
|
||||
4. **Bridges `nvsim` (currently leaf) into production cog ecosystem.**
|
||||
5. **5y deployable timeline.** Aligned with doc 17's 5y bucket.
|
||||
|
||||
### Negative
|
||||
|
||||
1. **Requires real NV-diamond hardware** to fully realise. Today's NV devices are bench-scale (~10 kg, ~$50K); cog-quantum-vitals can run on synthetic `nvsim` outputs today but doesn't deliver actual quantum benefit until ~2028-2030.
|
||||
2. **+150-200 LOC** on top of existing cogs (`nvsim` integration + Bayesian fusion + manifest extension for NV anchor types).
|
||||
3. **Calibration overhead.** NV-diamond requires per-installation magnetic-field baseline (Earth + local interference subtraction).
|
||||
4. **Cost.** $200-2,000 per NV device (today's estimates) + ESP32 array. Bedside cost ~$50-250 vs $3,000 hospital monitor.
|
||||
5. **No FDA / CE approval included.** Regulatory pathway is separate per ADR-114; estimated 6-18 months + $500K-$2M per device class.
|
||||
|
||||
## Implementation plan
|
||||
|
||||
| Step | LOC | Dependencies |
|
||||
|---|---:|---|
|
||||
| 1. `cog-quantum-vitals` crate scaffold | 30 | ADR-100 cog packaging |
|
||||
| 2. `nvsim` integration adapter | 40 | ADR-089 nvsim |
|
||||
| 3. Bayesian fusion layer (classical likelihood + NV likelihood → posterior) | 80 | rust-bayesian-stats or equiv |
|
||||
| 4. R12.1 pose-PABS hook | 30 | R12.1 in vital_signs (Roadmap Tier 1.2) |
|
||||
| 5. Cog manifest with NV-anchor-type schema | 20 | ADR-100 / ADR-109 signing |
|
||||
| 6. Bench validation against bedside protocol | — | partner hospital + real NV device |
|
||||
|
||||
**Total ~200 LOC** for the synthetic-NV version. ~50 additional LOC for real-NV hardware adapter when hardware ships. **~3-week effort.**
|
||||
|
||||
## Bridge to existing ADRs
|
||||
|
||||
- **ADR-089 (nvsim)**: the standalone leaf simulator becomes a cog dependency.
|
||||
- **ADR-021 (vitals)**: classical breathing/HR pipeline reused as one input to fusion.
|
||||
- **ADR-103 (cog-person-count)**: parallel architecture, different cog.
|
||||
- **ADR-105 / ADR-106**: federation + DP-SGD apply unchanged; the new NV-derived HRV contour is added to ADR-106 Layer 1 primitive-isolation list.
|
||||
- **ADR-107 / ADR-108 / ADR-109**: cross-installation federation, PQC key exchange, PQC signatures all apply.
|
||||
- **ADR-113 (placement)**: cog-quantum-vitals uses the `chest, N=5, 2D` matrix row; manifest enforces.
|
||||
|
||||
## Bridge to research-loop threads
|
||||
|
||||
- **R13 NEGATIVE**: this cog recovers what R13 ruled out (sensor-bound finding, not physics-bound).
|
||||
- **R14 V1/V2/V3**: V1 is mostly classical; V2 adds breathing envelope; **V3 (attention-respecting) becomes shippable** because the cog provides the contour V3 needs.
|
||||
- **R15 biometric primitives**: per-patient cardiac contour adds a new primitive to the catalogue (rate-level was the prior bound).
|
||||
- **R16 healthcare**: this cog is the first concrete deliverable of the healthcare vertical. ICU bedside + general ward.
|
||||
- **R12 PABS / R12.1**: pose-PABS provides the residual check; NV signal adds the new modality residual.
|
||||
- **R6.1 multi-scatterer**: extended to multi-MODALITY (CSI + magnetic) forward model.
|
||||
- **R20 / doc 17 (quantum integration)**: this ADR is the concrete implementation of the 5y bucket.
|
||||
|
||||
## Per-installation deployment recipe
|
||||
|
||||
Following ADR-113's `chest, N=5` row:
|
||||
|
||||
```
|
||||
1. Place 4× ESP32-S3 around the patient bed (corner of room, height 0.8 m + 1.5 m mix)
|
||||
2. Place 1× NV-diamond device on a wall-mounted arm ~1 m above the bed (above patient head)
|
||||
3. Run wifi-densepose plan-antennas --cog cog-quantum-vitals --target-mode chest
|
||||
4. Calibrate NV baseline (10 min capture of empty bed)
|
||||
5. Load patient identity (R3 + AETHER per-installation library)
|
||||
6. Deploy cog binary (signed per ADR-109)
|
||||
7. Federated training begins on overnight schedule (ADR-105)
|
||||
```
|
||||
|
||||
Cost per bedside install:
|
||||
- 4× ESP32-S3: ~$60
|
||||
- 1× NV-diamond device: ~$200-2,000 (today's estimate; expected ~$200 by 2028)
|
||||
- Mounting + calibration: ~$50
|
||||
- **Total bedside: $310-$2,110**
|
||||
|
||||
vs **clinical continuous monitor: $3,000-$10,000 per bed**.
|
||||
|
||||
## What this ADR DOES NOT cover
|
||||
|
||||
1. **Real NV-diamond hardware acquisition** — `nvsim` simulator is bench-validatable today; real-hardware bring-up is separate procurement + integration work.
|
||||
2. **FDA / CE Class II regulatory** — per ADR-114 follow-up; 6-18 months + $500K-$2M cost.
|
||||
3. **Multi-patient NV scaling** — single NV device per bed; per-ward scaling needs multiple NV devices per ADR-113.
|
||||
4. **Wearable integration** — wearables remain complementary; `cog-quantum-vitals` is passive supplement, not replacement.
|
||||
5. **Pediatric / geriatric specialised models** — adult-baseline assumed.
|
||||
|
||||
## Future ADRs catalogued
|
||||
|
||||
- **ADR-115**: cog-rydberg-anchor (calibrated multistatic; doc 17's 7-10y item)
|
||||
- **ADR-116**: real NV-diamond hardware bring-up + calibration protocols
|
||||
- **ADR-117**: cog-quantum-vitals FDA/CE regulatory pathway
|
||||
- **ADR-118**: cog-mm-position (atomic-clock-synchronised multistatic; doc 17's 10y item)
|
||||
|
||||
## Decision-making record
|
||||
|
||||
- 2026-05-22 11:30 UTC — drafted by SOTA research loop tick-39 in response to repeated user signal on the quantum-sensing folder. Composes loop's R13 NEGATIVE recovery (via R20 + doc 17) into a concrete cog spec. Status: Proposed.
|
||||
- Pending: ADR-089 author / nvsim maintainer (integration adapter review), security-architect (NV primitive added to isolation list), clinical advisor (bedside protocol review).
|
||||
|
||||
## Honest scope of ADR-114
|
||||
|
||||
- **`nvsim` outputs are deterministic simulations**, not real magnetometer data. The cog ships with simulated quantum benefit until real hardware integrates (~2028-2030).
|
||||
- **Cube-of-distance is the hard physical bound** — no NV magnetometer can exceed it; cog manifest enforces ≤2 m bedside.
|
||||
- **Patient-side variability** (BMI, body position, clothing) affects per-patient cardiac magnetic-field amplitude by ~3-10×. Per-patient calibration required.
|
||||
- **R7 mincut adversarial defence** assumed at multi-anchor classical level; NV is single-source, so spoofing detection relies on classical-NV agreement.
|
||||
- **Implementation cost is conservative** — Bayesian fusion may need ~100 more LOC if calibration-recovery proves complex.
|
||||
- **No bench validation** has been done on the full hybrid pipeline; first real test is a partner-hospital deployment.
|
||||
|
||||
## What this ADR closes
|
||||
|
||||
The **gap between the loop's R13 NEGATIVE finding and a shippable quantum-augmented vitals cog**. After ADR-114:
|
||||
|
||||
- R13 NEGATIVE is **categorised as sensor-bound, recoverable**, with a concrete cog spec showing the recovery.
|
||||
- `nvsim` (ADR-089) has its first concrete production cog dependency.
|
||||
- Doc 17's 5y bucket has a buildable spec.
|
||||
- The privacy chain (ADR-105-109+113) covers the new modality without changes.
|
||||
- The R14 V3 (attention-respecting conversational appliance) vertical becomes shippable.
|
||||
|
||||
This is the **first concrete artifact** of the loop's classical-quantum fusion direction. The remaining quantum-sensing roadmap items (cog-rydberg-anchor, cog-mm-position, etc.) follow the same template at later timelines.
|
||||
|
||||
---
|
||||
|
||||
*ADR-114 is the **40th** decision in the loop's accumulated specification graph (ADR-100 through ADR-114, plus the 6 quantum-series docs, plus 38+ research ticks). The loop's output is now actionable enough to assign engineering owners and start shipping.*
|
||||
@@ -1,670 +0,0 @@
|
||||
# ADR-115: Home Assistant integration via MQTT auto-discovery + Matter bridge
|
||||
|
||||
| Field | Value |
|
||||
|-------|-------|
|
||||
| **Status** | **Accepted** (MQTT track P1–P7 + P8a + P9 + P10 shipped 2026-05-23 in PR #778, 410 lib tests, witness bundle VERIFIED) / **Proposed** (Matter SDK wiring P8b deferred to v0.7.1 per §9.10) |
|
||||
| **Date** | 2026-05-23 |
|
||||
| **Deciders** | ruv |
|
||||
| **Codename** | **HA-DISCO** (MQTT) + **HA-FABRIC** (Matter) + **HA-MIND** (semantic primitives) |
|
||||
| **Relates to** | ADR-018 (CSI binary frame format), ADR-021 (ESP32 vitals), ADR-031 (RuView sensing-first), ADR-039 (edge vitals packet 0xC511_0002), ADR-079 (camera ground-truth), ADR-103 (cog-person-count), ADR-110 (ESP32-C6 firmware), ADR-114 (cog-quantum-vitals) |
|
||||
| **Tracking issue** | [#776](https://github.com/ruvnet/RuView/issues/776) — implementation in PR [#778](https://github.com/ruvnet/RuView/pull/778) |
|
||||
| **Related issues** | [#574](https://github.com/ruvnet/RuView/issues/574) (mDNS for seed_url), [#760](https://github.com/ruvnet/RuView/issues/760) (sensing UI), [#761](https://github.com/ruvnet/RuView/issues/761) (HA competitor scan) |
|
||||
|
||||
---
|
||||
|
||||
## 1. Context
|
||||
|
||||
RuView and the underlying WiFi-DensePose stack already expose rich human-sensing telemetry — presence, person count, 17-keypoint pose, breathing rate (BR), heart rate (HR), motion level, fall detection, RSSI, and zone occupancy — over a Rust `wifi-densepose-sensing-server` (`v2/crates/wifi-densepose-sensing-server`). The server emits three structured message types over its WebSocket at `/ws/sensing`:
|
||||
|
||||
| Server message `type` | Source (`main.rs`) | Payload (selected fields) |
|
||||
|---|---|---|
|
||||
| `pose_data` | line 2340 | 17 keypoints per detection, `confidence`, `track_id` |
|
||||
| `edge_vitals` | line 3971 | `node_id`, `presence`, `fall_detected`, `motion`, `breathing_rate_bpm`, `heartrate_bpm`, `n_persons`, `motion_energy`, `presence_score`, `rssi` |
|
||||
| `sensing_update` | lines 1903 / 2047 / 4098 / 4350 / 4481 | aggregated detections + zone hits |
|
||||
|
||||
Customers running a **Cognitum Seed** appliance (`cognitum-v0` at `:9000`) or a standalone **ESP32-S3** / **ESP32-C6** node (per ADR-110) want this telemetry inside **Home Assistant (HA)** — the most widely deployed open-source home-automation hub (>500 k installs, OSS, MQTT-native) — so they can build automations around presence, vitals, falls, and motion without writing code against our REST/WebSocket API.
|
||||
|
||||
### 1.1 Why this matters now
|
||||
|
||||
Two recent customer-facing issues show the same plug-and-play gap:
|
||||
|
||||
- **#574 (mDNS for seed_url)** — users don't want to manually paste a `seed://` URL into the dashboard; they expect the hub to discover the node.
|
||||
- **#760 (sensing UI)** — users asked for an HA-style "single dashboard with all my sensors" experience; we currently force them through our own UI.
|
||||
|
||||
Both reduce to the same underlying complaint: *RuView is a black box that needs glue code to fit into the rest of a smart home.* HA solves that problem industry-wide. We should meet users where they already are.
|
||||
|
||||
### 1.2 Comparison: who else does this
|
||||
|
||||
| Product | HA approach | Notes |
|
||||
|---|---|---|
|
||||
| **espectre.dev** | Custom HA integration (HACS), Python | Pose-only; no vitals; closed-source server |
|
||||
| **tommysense.com** | MQTT auto-discovery + cloud bridge | Vitals only; cloud-mandatory |
|
||||
| **Aqara FP2** | Native ZigBee + HA | Presence + zones only; commercial mmWave |
|
||||
| **mmWave HLK-LD2410** | ESPHome firmware → HA | Presence + distance, no pose, no vitals |
|
||||
| **Matter devices (any)** | Native Matter clusters, multi-controller | Apple/Google/Alexa/HA all consume; presence in `OccupancySensing` since Matter 1.3; no vitals/pose clusters yet |
|
||||
| **RuView (today)** | None | Customer must build their own bridge |
|
||||
|
||||
The competitive bar is set by Aqara FP2 (HA-native, multi-zone presence) and ESPHome-flashed LD2410 nodes (cheap, plug-and-play). To match or exceed them we need first-class HA integration that exposes our **differentiated** capabilities: pose, HR/BR, fall, multi-room.
|
||||
|
||||
### 1.3 What this ADR is *not*
|
||||
|
||||
- Not a HACS Python integration today (that's a follow-on; see §6).
|
||||
- Not a webhook-only push (one-way, no entity discovery).
|
||||
- Not a change to the ADR-018 CSI frame format or ADR-039 edge vitals packet — purely an additive consumer of the existing WS broadcast.
|
||||
- Not a change to firmware. Both ESP32-S3 (ADR-028) and ESP32-C6 (ADR-110) paths stay byte-identical.
|
||||
|
||||
---
|
||||
|
||||
## 2. Decision
|
||||
|
||||
Adopt a **dual-protocol** integration strategy:
|
||||
|
||||
1. **Primary — MQTT + Home Assistant auto-discovery (HA-DISCO).** Add an MQTT publisher to `wifi-densepose-sensing-server` that connects to a user-supplied MQTT broker (default: `mqtt://localhost:1883`), publishes one HA-discovery message per capability per RuView node on startup and on periodic refresh (default 600 s), translates each WebSocket broadcast (`edge_vitals`, `pose_data`, `sensing_update`) into per-entity MQTT state messages, and honors a `--privacy-mode` flag that strips biometrics (HR / BR / pose keypoints) before publish.
|
||||
|
||||
2. **Secondary — Matter Bridge (HA-FABRIC).** Expose RuView nodes as Matter Bridged Devices over WiFi so the **subset of capabilities Matter standardises today** — presence (`OccupancySensing`), motion (`BooleanState`), fall events (`SwitchCluster`-as-event), person count (numeric attribute on the bridge) — are consumable by **any Matter controller**: Apple Home, Google Home, Amazon Alexa, Samsung SmartThings, and Home Assistant itself. Biometrics (HR/BR) and pose stay on MQTT until the Matter spec adds device types that can represent them.
|
||||
|
||||
The two paths are **complementary, not alternative**: MQTT carries the full telemetry surface for power users; Matter carries the standardised subset for cross-ecosystem reach. A user running HA gets both — MQTT entities populate alongside Matter Bridged Devices and HA dedupes via `unique_id`. A user running Apple Home gets only Matter, but they get the presence/fall/count signals that matter most for automations.
|
||||
|
||||
A **Home Assistant HACS Python integration** is sketched as a follow-on (§6.A) for users who don't run MQTT and want richer features than Matter exposes. A **REST webhook** path is rejected (§6.B).
|
||||
|
||||
### 2.1 Why this split (MQTT primary, Matter secondary)
|
||||
|
||||
| Criterion | A. MQTT auto-discovery | **D. Matter Bridge** | B. HACS Python integration | C. REST webhook |
|
||||
|---|---|---|---|---|
|
||||
| **Zero-code UX for end user** | yes (HA picks up entities automatically) | yes (pair via QR code, any controller) | yes (after install) | no (user wires automations by hand) |
|
||||
| **Cross-ecosystem reach** | HA + any MQTT consumer | **Apple / Google / Alexa / SmartThings / HA** | HA-only | HA-only |
|
||||
| **Distribution + maintenance** | one Rust feature in our existing crate | one Rust feature + Matter SDK linkage | new Python repo, HACS approval | trivial |
|
||||
| **Discovery (auto entity creation)** | yes (HA's `homeassistant/` topic namespace) | yes (Matter commissioning + bridge endpoints) | yes (config flow) | no |
|
||||
| **Bidirectional control** | yes (subscribe to command topic) | yes (Matter commands) | yes | one-way only |
|
||||
| **Carries vitals (HR/BR) / pose** | **yes** | **no — no Matter clusters exist** | yes (custom) | yes (custom) |
|
||||
| **Carries presence / count / fall** | yes | **yes (Matter 1.3+)** | yes | yes |
|
||||
| **Works without HA running** | any MQTT consumer | any Matter controller | HA-only | HA-only |
|
||||
| **Existing infra in target homes** | most HA users already run a broker | one Matter controller per home (Apple HomePod / Nest Hub / HA-Matter add-on) | none | none |
|
||||
| **Effort to MVP** | ~2 weeks | ~4–6 weeks (Matter SDK + commissioning) | ~4–6 weeks | ~2 days |
|
||||
| **Privacy controls** | per-topic + retain policy | Matter fabric isolation + spec-level limits on what's exposable | application-layer | weak |
|
||||
| **Certification cost** | none | "Works with HA" free; **CSA Matter certification optional** (~$3 k/year membership for the badge) | HACS review (free) | none |
|
||||
| **Test surface in CI** | dockerised mosquitto + schema lint | matter-rs test harness + chip-tool sims | full HA test harness | curl |
|
||||
|
||||
**MQTT is primary** because it carries 100% of RuView's differentiated telemetry (pose, HR, BR) which no other path can. **Matter is secondary** because it covers the ~30% subset (presence/count/fall) that matters across the *other 70% of smart-home buyers* who don't run HA. Together they cover the whole market. Webhook (C) gives up too much (no entity discovery, no control plane) and is rejected. HACS (B) is strictly more polished than MQTT but strictly more expensive; revisit after MQTT adoption data is in.
|
||||
|
||||
---
|
||||
|
||||
## 3. Detailed Design
|
||||
|
||||
### 3.1 Entity mapping
|
||||
|
||||
Each RuView node becomes one HA **device**. Each capability becomes an **entity** on that device. ESP32 nodes behind a Cognitum Seed appliance are linked via HA's `via_device` field so the topology shows up in the HA UI.
|
||||
|
||||
| Capability | HA component | `device_class` | `state_class` | Unit | Icon | Source field (server WS) |
|
||||
|---|---|---|---|---|---|---|
|
||||
| Presence | `binary_sensor` | `occupancy` | — | — | `mdi:motion-sensor` | `edge_vitals.presence` |
|
||||
| Person count | `sensor` | — | `measurement` | persons | `mdi:account-group` | `edge_vitals.n_persons` |
|
||||
| Breathing rate | `sensor` | — | `measurement` | bpm | `mdi:lungs` | `edge_vitals.breathing_rate_bpm` |
|
||||
| Heart rate | `sensor` | — | `measurement` | bpm | `mdi:heart-pulse` | `edge_vitals.heartrate_bpm` |
|
||||
| Motion level | `sensor` | — | `measurement` | % | `mdi:run` | `edge_vitals.motion` (0–1 → ×100) |
|
||||
| Motion energy | `sensor` | — | `measurement` | (unitless) | `mdi:waveform` | `edge_vitals.motion_energy` |
|
||||
| Fall detected | `event` | — | — | — | `mdi:human-fall` | `edge_vitals.fall_detected` |
|
||||
| Presence score | `sensor` | — | `measurement` | % | `mdi:gauge` | `edge_vitals.presence_score` (×100) |
|
||||
| RSSI | `sensor` | `signal_strength` | `measurement` | dBm | `mdi:wifi` | `edge_vitals.rssi` |
|
||||
| Zone occupancy (per zone) | `binary_sensor` | `occupancy` | — | — | `mdi:map-marker` | `sensing_update.zones[*]` |
|
||||
| Pose keypoints | `sensor` (JSON attr) | — | — | — | `mdi:human` | `pose_data.keypoints` (opt-in) |
|
||||
| Tracked persons (per ID) | `binary_sensor` (dynamic) | `occupancy` | — | — | `mdi:account` | `pose_data.track_id` |
|
||||
|
||||
Pose keypoints are intentionally not a first-class HA entity (HA has no 17-keypoint primitive); instead they're exposed as an attribute payload on a `wifi_densepose_<node>_pose` sensor, so power users can template against them but the default HA UI stays clean.
|
||||
|
||||
### 3.2 MQTT topic structure
|
||||
|
||||
We follow HA's documented `homeassistant/<component>/<object_id>/<entity>/config` discovery convention. Object ID is `wifi_densepose_<node_id>` to namespace cleanly against other devices.
|
||||
|
||||
```
|
||||
homeassistant/binary_sensor/wifi_densepose_<node_id>/presence/config (retained, QoS 1)
|
||||
homeassistant/binary_sensor/wifi_densepose_<node_id>/presence/state (not retained, QoS 0)
|
||||
homeassistant/binary_sensor/wifi_densepose_<node_id>/presence/availability (retained, QoS 1)
|
||||
|
||||
homeassistant/sensor/wifi_densepose_<node_id>/heart_rate/config (retained, QoS 1)
|
||||
homeassistant/sensor/wifi_densepose_<node_id>/heart_rate/state (not retained, QoS 0)
|
||||
|
||||
homeassistant/sensor/wifi_densepose_<node_id>/breathing_rate/config
|
||||
homeassistant/sensor/wifi_densepose_<node_id>/breathing_rate/state
|
||||
|
||||
homeassistant/event/wifi_densepose_<node_id>/fall/config (retained, QoS 1)
|
||||
homeassistant/event/wifi_densepose_<node_id>/fall/state (not retained, QoS 1)
|
||||
|
||||
ruview/<node_id>/raw/pose (opt-in, not retained, QoS 0)
|
||||
ruview/<node_id>/raw/sensing_update (opt-in, not retained, QoS 0)
|
||||
```
|
||||
|
||||
The `ruview/<node_id>/raw/*` namespace is **outside** the `homeassistant/` discovery prefix on purpose: it carries the original WebSocket JSON for users who want to consume it directly (Node-RED, Grafana, custom scripts), without HA trying to interpret it as an entity.
|
||||
|
||||
### 3.3 Example discovery payloads
|
||||
|
||||
**Presence (binary_sensor):**
|
||||
|
||||
```json
|
||||
{
|
||||
"name": "Presence",
|
||||
"unique_id": "wifi_densepose_aabbccddeeff_presence",
|
||||
"object_id": "wifi_densepose_aabbccddeeff_presence",
|
||||
"state_topic": "homeassistant/binary_sensor/wifi_densepose_aabbccddeeff/presence/state",
|
||||
"availability_topic": "homeassistant/binary_sensor/wifi_densepose_aabbccddeeff/presence/availability",
|
||||
"payload_on": "ON",
|
||||
"payload_off": "OFF",
|
||||
"payload_available": "online",
|
||||
"payload_not_available": "offline",
|
||||
"device_class": "occupancy",
|
||||
"qos": 1,
|
||||
"device": {
|
||||
"identifiers": ["wifi_densepose_aabbccddeeff"],
|
||||
"name": "RuView node aabbccddeeff",
|
||||
"manufacturer": "ruvnet",
|
||||
"model": "ESP32-S3 CSI node",
|
||||
"sw_version": "v0.6.7",
|
||||
"via_device": "cognitum_seed_1"
|
||||
},
|
||||
"origin": {
|
||||
"name": "wifi-densepose-sensing-server",
|
||||
"sw_version": "0.7.0",
|
||||
"support_url": "https://github.com/ruvnet/RuView"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**Heart rate (sensor):**
|
||||
|
||||
```json
|
||||
{
|
||||
"name": "Heart rate",
|
||||
"unique_id": "wifi_densepose_aabbccddeeff_heart_rate",
|
||||
"state_topic": "homeassistant/sensor/wifi_densepose_aabbccddeeff/heart_rate/state",
|
||||
"availability_topic": "homeassistant/sensor/wifi_densepose_aabbccddeeff/heart_rate/availability",
|
||||
"unit_of_measurement": "bpm",
|
||||
"state_class": "measurement",
|
||||
"icon": "mdi:heart-pulse",
|
||||
"value_template": "{{ value_json.bpm }}",
|
||||
"json_attributes_topic": "homeassistant/sensor/wifi_densepose_aabbccddeeff/heart_rate/state",
|
||||
"qos": 0,
|
||||
"device": { "identifiers": ["wifi_densepose_aabbccddeeff"] }
|
||||
}
|
||||
```
|
||||
|
||||
State payload published to `.../heart_rate/state`:
|
||||
|
||||
```json
|
||||
{ "bpm": 68.2, "confidence": 0.91, "ts": "2026-05-23T14:00:00Z" }
|
||||
```
|
||||
|
||||
**Fall (event):**
|
||||
|
||||
```json
|
||||
{
|
||||
"name": "Fall detected",
|
||||
"unique_id": "wifi_densepose_aabbccddeeff_fall",
|
||||
"state_topic": "homeassistant/event/wifi_densepose_aabbccddeeff/fall/state",
|
||||
"event_types": ["fall_detected"],
|
||||
"icon": "mdi:human-fall",
|
||||
"qos": 1,
|
||||
"device": { "identifiers": ["wifi_densepose_aabbccddeeff"] }
|
||||
}
|
||||
```
|
||||
|
||||
State payload (fired once per fall, **not retained**):
|
||||
|
||||
```json
|
||||
{ "event_type": "fall_detected", "ts": "2026-05-23T14:00:00.123Z", "confidence": 0.87 }
|
||||
```
|
||||
|
||||
### 3.4 Device-level grouping
|
||||
|
||||
- One HA `device` per RuView **node** (ESP32-S3 / S3-Mini / C6, or the host running sensing-server in mock mode).
|
||||
- `device.identifiers` = `["wifi_densepose_<node_id>"]` where `node_id` is the MAC-derived ID already in `edge_vitals.node_id`.
|
||||
- For nodes behind a **Cognitum Seed**, set `device.via_device = "cognitum_seed_<seed_id>"` so HA renders the topology as a tree (Seed → child nodes).
|
||||
- The Cognitum Seed itself appears as a parent device with its own diagnostic entities (uptime, agent health) — published by the seed appliance directly, not by sensing-server.
|
||||
|
||||
### 3.5 QoS, retention, and refresh
|
||||
|
||||
| Topic | QoS | Retain | Refresh cadence | Rationale |
|
||||
|---|---|---|---|---|
|
||||
| `*/config` | 1 | **yes** | on startup + every 600 s | HA expects retained discovery; re-publishing periodically self-heals if HA restarts before our state messages arrive |
|
||||
| `*/state` (sensor) | 0 | no | rate-limited per §3.7 | Best-effort; HA can tolerate occasional drops |
|
||||
| `*/state` (binary_sensor) | 1 | **yes** | on change only | Last value matters; new HA subscribers should see current state |
|
||||
| `*/state` (event) | 1 | no | on event | Falls must not be missed; never retained or HA replays old events |
|
||||
| `*/availability` | 1 | **yes** | LWT + 30 s heartbeat | Offline detection |
|
||||
| `ruview/*/raw/*` | 0 | no | as-emitted | Raw firehose; consumers opt in |
|
||||
|
||||
### 3.6 Availability + Last Will and Testament (LWT)
|
||||
|
||||
On connect, sensing-server sets an MQTT LWT on each entity's `availability` topic to `offline` (retained). On successful connect it publishes `online` (retained). A 30-second heartbeat re-publishes `online` so HA can detect zombie sessions.
|
||||
|
||||
```
|
||||
LWT topic: homeassistant/binary_sensor/wifi_densepose_<node_id>/presence/availability
|
||||
LWT payload: offline
|
||||
LWT QoS: 1
|
||||
LWT retain: true
|
||||
```
|
||||
|
||||
### 3.7 Bandwidth control + rate limiting
|
||||
|
||||
Pose keypoints at 10 fps × 17 keypoints × 3 floats ≈ 4–8 kbit/s per person — fine over LAN, but pathological if a user accidentally routes it to a metered cellular MQTT bridge. Defaults:
|
||||
|
||||
| Entity type | Default rate | Configurable | Override flag |
|
||||
|---|---|---|---|
|
||||
| Presence (binary) | on change | yes | — |
|
||||
| Person count | 1 Hz | yes | `--mqtt-rate-count=1` |
|
||||
| BR / HR | 0.2 Hz (every 5 s) | yes | `--mqtt-rate-vitals=0.2` |
|
||||
| Motion level | 1 Hz | yes | `--mqtt-rate-motion=1` |
|
||||
| Fall events | on event | no (always immediate) | — |
|
||||
| RSSI | 0.1 Hz | yes | `--mqtt-rate-rssi=0.1` |
|
||||
| Pose keypoints | **off by default**, 1 Hz when on | yes | `--mqtt-publish-pose --mqtt-rate-pose=1` |
|
||||
| Zones | on change | yes | — |
|
||||
|
||||
### 3.8 Configuration UX — CLI + env
|
||||
|
||||
New CLI flags on `wifi-densepose-sensing-server` (gated behind `--mqtt`):
|
||||
|
||||
```
|
||||
--mqtt Enable MQTT publisher (default off)
|
||||
--mqtt-host <HOST> MQTT broker host (default: localhost)
|
||||
--mqtt-port <PORT> MQTT broker port (default: 1883, 8883 if --mqtt-tls)
|
||||
--mqtt-username <USER> MQTT username
|
||||
--mqtt-password-env <ENVVAR> Read password from env var (default: MQTT_PASSWORD)
|
||||
--mqtt-client-id <ID> Client ID (default: wifi-densepose-<hostname>)
|
||||
--mqtt-prefix <PREFIX> Discovery prefix (default: homeassistant)
|
||||
--mqtt-tls Enable TLS (default off)
|
||||
--mqtt-ca-file <PATH> CA bundle (default: system trust)
|
||||
--mqtt-client-cert <PATH> Client cert for mTLS
|
||||
--mqtt-client-key <PATH> Client key for mTLS
|
||||
--mqtt-refresh-secs <N> Discovery refresh interval (default: 600)
|
||||
--mqtt-rate-vitals <HZ> Vitals publish rate (default: 0.2)
|
||||
--mqtt-rate-motion <HZ> Motion publish rate (default: 1.0)
|
||||
--mqtt-rate-count <HZ> Person count publish rate (default: 1.0)
|
||||
--mqtt-rate-rssi <HZ> RSSI publish rate (default: 0.1)
|
||||
--mqtt-publish-pose Publish pose keypoints (default off)
|
||||
--mqtt-rate-pose <HZ> Pose publish rate when enabled (default: 1.0)
|
||||
--privacy-mode Strip biometrics (HR/BR/pose) before publish
|
||||
```
|
||||
|
||||
Env var equivalents follow `RUVIEW_MQTT_HOST`, `RUVIEW_MQTT_USERNAME`, etc., so Docker / systemd users don't have to wire long arg lists. Configuration is loaded in the order: CLI > env > defaults.
|
||||
|
||||
### 3.9 TLS + auth
|
||||
|
||||
- **Recommended**: mTLS on a dedicated VLAN with the broker pinned to a CA we issue per Cognitum Seed appliance.
|
||||
- **Acceptable**: username + password over TLS to a public broker (e.g. user's existing Mosquitto add-on inside HA).
|
||||
- **Rejected**: plaintext on any network shared with non-trusted devices. Sensing-server logs a `WARN` if `--mqtt` is enabled without `--mqtt-tls` and the broker is not `localhost`.
|
||||
|
||||
### 3.10 Privacy mode
|
||||
|
||||
`--privacy-mode` strips biometric + biometric-derivable channels before any MQTT publish, regardless of subscriber. Discovery messages for those entities are **never published** in this mode (HA never sees them exist).
|
||||
|
||||
| Channel | Default | `--privacy-mode` |
|
||||
|---|---|---|
|
||||
| Presence | published | **published** |
|
||||
| Person count | published | **published** |
|
||||
| Motion level | published | **published** |
|
||||
| Zone occupancy | published | **published** |
|
||||
| RSSI | published | **published** |
|
||||
| Breathing rate | published | **stripped** |
|
||||
| Heart rate | published | **stripped** |
|
||||
| Fall events | published | **published** (safety > privacy) |
|
||||
| Pose keypoints | off by default | **stripped** (cannot be force-enabled) |
|
||||
|
||||
This implements the ADR-106 primitive-isolation contract at the integration boundary: HR / BR / pose are biometric-class signals and must not leak to an unconstrained MQTT broker without explicit operator opt-in.
|
||||
|
||||
### 3.11 Matter Bridge (HA-FABRIC)
|
||||
|
||||
The Matter path runs **in the same `wifi-densepose-sensing-server` process** behind a `--matter` feature flag, gated independently of `--mqtt`. The bridge presents itself to Matter controllers as a **Bridged Devices Aggregator** (per Matter Core Spec §9.13) with one Bridged Device endpoint per RuView node, exposing the standardised subset of capabilities. Biometrics and pose are **not exposed** over Matter — they have no spec-defined clusters and cannot be soundly represented (covering them in `Generic Sensor` would force every controller to render them as nameless numbers).
|
||||
|
||||
#### 3.11.1 Matter device-type mapping
|
||||
|
||||
| RuView capability | Matter cluster | Endpoint device type | Source field |
|
||||
|---|---|---|---|
|
||||
| Presence | `OccupancySensing` (0x0406) | `OccupancySensor` (0x0107) | `edge_vitals.presence` |
|
||||
| Motion (boolean above threshold) | `OccupancySensing` (0x0406) | (same endpoint) | `edge_vitals.motion > 0.1` |
|
||||
| Fall event | `Switch` (0x003B) `MultiPressComplete` event | `GenericSwitch` (0x000F) | `edge_vitals.fall_detected` (one momentary press = one fall) |
|
||||
| Person count | `OccupancySensing` extension attribute (vendor-specific 0xFFF1_0001) | (same endpoint) | `edge_vitals.n_persons` |
|
||||
| Zone occupancy | one `OccupancySensor` endpoint per zone | (multiple endpoints) | `sensing_update.zones[*]` |
|
||||
| RSSI / motion energy / presence score / breathing rate / heart rate / pose | **not exposed over Matter** | — | (MQTT only) |
|
||||
|
||||
The vendor-specific person-count attribute uses RuView's CSA-assigned vendor ID (open question §9.9). Controllers that don't understand the vendor extension still see the standard `OccupancySensing.Occupancy` boolean — graceful degradation.
|
||||
|
||||
#### 3.11.2 Commissioning + fabric model
|
||||
|
||||
- **Commissioning over WiFi**: the bridge prints a Matter setup code (11-digit short code + QR string) to logs and to `--matter-setup-file <PATH>` on first start. User scans with Apple Home / Google Home / HA Matter integration.
|
||||
- **No Thread radio required**: sensing-server runs on hosts (Pi 5, x86, Cognitum Seed) that have WiFi but no 802.15.4. Matter-over-WiFi is sufficient. Thread support is explicitly out of scope until ESP32-C6 firmware grows a Matter stack (separate ADR; see §7).
|
||||
- **Multi-admin / multi-fabric**: the bridge accepts multiple commissioning sessions so a single node can be paired into Apple Home **and** Home Assistant **and** Google Home concurrently — Matter's `OperationalCredentials` cluster handles fabric isolation.
|
||||
- **Resetting commissioning**: a `--matter-reset` CLI flag wipes stored fabric credentials so a node can be repaired against a new controller.
|
||||
|
||||
#### 3.11.3 SDK choice (open in §9, sketched here)
|
||||
|
||||
Three viable Rust paths:
|
||||
|
||||
| Option | Pros | Cons |
|
||||
|---|---|---|
|
||||
| **`matter-rs`** (project-chip/rs-matter) — pure-Rust SDK | No FFI, no C++ build chain, fits our Rust-only crate policy, MIT-licensed | Less mature than C++ chip-tool; certification path less proven |
|
||||
| **`project-chip/connectedhomeip`** via Rust FFI bindings | Reference implementation, every controller tested against it, certification-ready | Drags in CMake, C++ toolchain, ~50 MB of vendored code; clashes with our cargo-first build |
|
||||
| **External Matter bridge process** (separate ESPHome-like daemon) | Decouples Rust crate from Matter SDK churn | Operational complexity; two processes to deploy |
|
||||
|
||||
**Tentative**: `matter-rs` for v0.7.0 ship; fall back to chip-tool-FFI if cert blockers emerge. Final decision deferred to P7 spike.
|
||||
|
||||
#### 3.11.4 Limitations to document upfront
|
||||
|
||||
These are **deliberate**, not bugs — users must see them in `docs/integrations/matter.md` before pairing:
|
||||
|
||||
- **No HR, BR, pose, RSSI over Matter.** Matter has no clusters for these. Use MQTT for biometric / detailed telemetry.
|
||||
- **Fall events are one-shot.** A fall fires a momentary switch press; controllers must subscribe to the event (most do).
|
||||
- **Person count is vendor-extension.** Apple Home / Google Home will show occupancy on/off; only HA and SmartThings (with custom handlers) will surface the count.
|
||||
- **One fabric controller is "primary."** Automations split across fabrics can race; users should keep heavy automation logic in one controller (typically HA).
|
||||
- **No video / image data ever.** Matter spec forbids it on these device types and we wouldn't expose it anyway.
|
||||
|
||||
#### 3.11.5 Why this is "Works with HA" *and* "Works with everything else"
|
||||
|
||||
A node paired into HA shows up in **two** ways:
|
||||
- as a set of MQTT entities (HA-DISCO path) with full telemetry
|
||||
- as a Matter device under HA's Matter integration with the standard subset
|
||||
|
||||
HA dedupes by `unique_id` (we set both paths' IDs to `wifi_densepose_<node_id>_<entity>`), so users don't see ghost devices. The Matter device is the one Apple Home or Google Home will see if the user also pairs into those — same physical node, three controllers, no duplication. This is the architectural reason for adopting both protocols rather than picking one.
|
||||
|
||||
### 3.12 Semantic automation primitives (HA-MIND)
|
||||
|
||||
Raw signals are not the product. Customers don't want to *write a Node-RED flow that thresholds breathing rate at night to infer sleep*. They want a `binary_sensor.bedroom_someone_sleeping` they can wire directly into a "dim hallway light at 10 % if anyone's asleep" automation. Same for fall *risk*, distress, room activity, elderly inactivity, meeting-in-progress, bathroom occupancy. This is the inference layer that turns RuView from "RF sensing" into **ambient intelligence infrastructure** — and it has to ship as first-class HA entities and Matter events, not as a developer SDK.
|
||||
|
||||
#### 3.12.1 Catalog of inferred primitives (v1)
|
||||
|
||||
Each primitive is a fused state derived from one or more raw channels with a small finite-state machine. Inference runs inside `wifi-densepose-sensing-server` (same place MQTT publication runs), gated behind `--semantic` (default on; can be disabled). Each primitive has a confidence score and an explanation field so HA users can debug why it fired.
|
||||
|
||||
| Primitive | Inputs (raw) | Output kind | Default true-condition | Hysteresis / refractory |
|
||||
|---|---|---|---|---|
|
||||
| **Someone sleeping** | presence + low motion (<5 % for ≥300 s) + breathing rate 8–20 bpm + low HR variability | `binary_sensor` (occupancy) | all conditions hold simultaneously | enters after 5 min; exits when motion > 15 % for ≥30 s |
|
||||
| **Possible distress** | sustained elevated HR (>1.5× rolling baseline for ≥60 s) + agitated motion + no fall | `binary_sensor` (problem) + `event` | confidence ≥ 0.75 | latch for 5 min after exit |
|
||||
| **Room active** | presence + motion > 10 % for ≥30 s in any 5-min window | `binary_sensor` (occupancy) | window-rolling | exits on 10 min idle |
|
||||
| **Elderly inactivity anomaly** | no motion + presence stable for > N× rolling daily median idle (default 2×) | `binary_sensor` (problem) + `event` | model-personalised | per-resident baseline; alerts max 1×/day |
|
||||
| **Meeting in progress** | person count ≥ 2 + sustained low-amplitude motion (sitting) + speech-band micro-motion if `speech_band` cog installed | `binary_sensor` (occupancy) | ≥2 ppl + ≥10 min | exits when person count < 2 for 2 min |
|
||||
| **Bathroom occupied** | presence true in zone tagged `bathroom` | `binary_sensor` (occupancy) | zone+presence | privacy-mode keeps this enabled (it's not biometric) |
|
||||
| **Fall risk elevated** | recent near-fall (sharp acceleration without confirmed fall) OR gait instability score > threshold | `sensor` (0–100) + `event` on threshold cross | model-derived | 24-hour window |
|
||||
| **Bed exit (overnight)** | "someone sleeping" → presence transitions out of bed-tagged zone between 22:00–06:00 local | `event` | edge-triggered | one event per exit |
|
||||
| **No movement (safety check)** | presence true + motion < 1 % for ≥ N minutes (default 30) | `binary_sensor` (problem) + `event` | duration threshold | clears on motion |
|
||||
| **Multi-room transition** | track_id continuous across zones within 10 s | `event` (`who_went_from_to`) | edge-triggered | per-track event |
|
||||
|
||||
Catalog v2 (deferred): "child playing", "pet vs human", "agitation gradient", "circadian phase". Owned by an ADR-1xx follow-on after the v1 primitives have field data.
|
||||
|
||||
#### 3.12.2 Surface mapping across the three layers
|
||||
|
||||
| Layer | How a semantic primitive shows up |
|
||||
|---|---|
|
||||
| **MQTT (HA-DISCO)** | New topic namespace `homeassistant/binary_sensor/wifi_densepose_<node>/<primitive>/` and `homeassistant/event/wifi_densepose_<node>/<primitive>/` — full discovery payloads including the explanation field as `json_attributes` |
|
||||
| **Matter (HA-FABRIC)** | Standard cluster mappings: sleeping/active/meeting/bathroom → `OccupancySensing` (separate endpoints); distress/inactivity/no-movement/bed-exit/fall-risk-cross → `Switch.MultiPressComplete` events on dedicated `GenericSwitch` endpoints; fall-risk score → vendor-extension attribute on the bridge endpoint |
|
||||
| **Home Assistant automations** | Ship 8 starter blueprints in P5: "Notify on possible distress", "Wake-up routine on bed exit", "Dim hallway on someone sleeping", "Alert on elderly inactivity anomaly", "Lights on for meeting in progress", "Bathroom fan on while occupied", "Escalate on fall risk crossing 70", "Auto-arm security when room not active" |
|
||||
| **Apple Home scenes** | Each `OccupancySensor` endpoint and each `GenericSwitch` event triggers Apple Home scenes via Matter — user picks "When *bedroom someone sleeping* is on, run *night mode*" from the Apple Home UI directly. No HA required for this path |
|
||||
|
||||
#### 3.12.3 Why these specific primitives
|
||||
|
||||
These eight cover the **top automation requests from the smart-home market** without needing video or wearables:
|
||||
|
||||
- **Healthcare / aging-in-place** — "elderly inactivity anomaly", "fall risk elevated", "possible distress", "no movement (safety check)", "bed exit (overnight)" — directly map to AAL (Active and Assisted Living) device-class expectations
|
||||
- **Convenience automation** — "someone sleeping", "room active", "meeting in progress", "bathroom occupied" — the four highest-volume HA forum-requested binary states
|
||||
- **Privacy** — none of these require biometric *values* to be published, only the inferred *states*. A `--privacy-mode` deployment can keep semantic primitives ON and still strip HR/BR/pose, because the inference happens server-side and only the state crosses the wire
|
||||
|
||||
#### 3.12.4 Inference quality contract
|
||||
|
||||
Each primitive ships with:
|
||||
- A **published precision/recall** on a held-out test set built from ADR-079 paired captures + synthetic stress scenarios — committed to `docs/integrations/semantic-primitives-metrics.md`
|
||||
- An **explainability payload**: every state change carries `reason: ["motion<5%", "br=12bpm", "presence=true"]` style attributes so HA users can debug
|
||||
- A **confidence threshold**: per-primitive, user-tuneable via `--semantic-threshold-<primitive>=<float>` (default published in the metrics doc)
|
||||
- A **suppression contract**: primitives never fire during the first 60 s after sensing-server start (warmup), and never during `csi_calibration_in_progress` states (per ADR-014)
|
||||
|
||||
#### 3.12.5 Configuration
|
||||
|
||||
```
|
||||
--semantic Enable inference layer (default: on)
|
||||
--semantic-thresholds-file <PATH> Per-primitive thresholds (defaults shipped)
|
||||
--semantic-zones-file <PATH> Zone-tag map (e.g. {"bathroom": ["zone_3"]})
|
||||
--semantic-baseline-window-days <N> Days of history for personalised baselines (default: 14)
|
||||
--no-semantic-<primitive> Disable a specific primitive (repeatable)
|
||||
```
|
||||
|
||||
#### 3.12.6 What this changes architecturally
|
||||
|
||||
Inference lives in a new module `semantic_inference.rs` alongside `mqtt_publisher.rs` and `matter_bridge.rs`. It subscribes to the same `tokio::broadcast` channel everything else does, runs each primitive's FSM, and emits **two output streams**:
|
||||
|
||||
1. A `SemanticState` event on a new broadcast channel that MQTT and Matter publishers both subscribe to (so the same inference drives both surfaces without duplication)
|
||||
2. Append-only `semantic_events.jsonl` log under `--data-dir` for offline analysis + ADR-079 paired-capture supervision
|
||||
|
||||
This means: **adding a new primitive is one file change**. No MQTT schema rev, no Matter cluster rev — just add the FSM, register it, and discovery/state publish flow through both surfaces automatically.
|
||||
|
||||
---
|
||||
|
||||
## 4. Implementation phases
|
||||
|
||||
| Phase | Scope | Status |
|
||||
|---|---|---|
|
||||
| **P1** | Add `mqtt` feature flag to `wifi-densepose-sensing-server` Cargo.toml (depends on `rumqttc = "0.24"`). Wire CLI flags (§3.8) into `cli.rs`. No publishing yet, just config plumbing + unit tests on flag parsing. | pending |
|
||||
| **P2** | HA discovery message emitter. New module `mqtt_discovery.rs`. Emits all entity `config` topics on connect + every `--mqtt-refresh-secs`. Schema-validated against HA's published JSON schema. | pending |
|
||||
| **P3** | State publication. Subscribe to internal `tokio::broadcast` channel (the one `tx.send(json)` writes to on line 3983 of `main.rs`). Translate `edge_vitals` / `sensing_update` / `pose_data` messages into per-entity state payloads. Apply rate-limit + privacy-mode filters. | pending |
|
||||
| **P4** | Integration tests: dockerised mosquitto in CI (extend `.github/workflows/firmware-qemu.yml` pattern), schema-validate every emitted config against HA's `homeassistant/components/mqtt` JSON schemas (pin to a tested HA version). Add a smoke test that brings up sensing-server in `--source mock --mqtt`, subscribes with `paho-mqtt` test client, asserts on entity creation. | pending |
|
||||
| **P4.5** | **Semantic inference layer (HA-MIND).** New module `semantic_inference.rs` implementing the 10 v1 primitives from §3.12. Output broadcast channel consumed by both MQTT publisher (P3) and Matter bridge (P8). Per-primitive precision/recall baselines published to `docs/integrations/semantic-primitives-metrics.md`. Unit tests per FSM + integration tests via replay of ADR-079 paired captures. | pending |
|
||||
| **P5** | Docs: new `docs/integrations/home-assistant.md` with screenshots of the HA UI after auto-discovery completes, example HA dashboard YAML (Lovelace card configs), 8 starter blueprints from §3.12.2 (distress notify, wake routine, hallway dim, elderly anomaly alert, meeting lights, bathroom fan, fall-risk escalate, auto-arm security), and the raw-channel example automations: "turn on hall light when presence ON", "send notification on fall_detected event", "log HR/BR to InfluxDB". | pending |
|
||||
| **P6** | Ship `--mqtt` in the next sensing-server release (target: v0.7.0). Demo end-to-end on `cognitum-v0` against a Mosquitto add-on running on a Home Assistant OS install. Update README hardware-options table with "Works with Home Assistant" badge. | pending |
|
||||
| **P7** | Matter Bridge spike: build a throwaway prototype with `matter-rs` exposing one `OccupancySensor` endpoint + one `GenericSwitch` for fall. Pair against Apple Home, Google Home, and HA's Matter integration. Decision gate: if pairing works on all three, proceed to P8; if blocked, switch to chip-tool FFI and re-spike. | pending |
|
||||
| **P8** | Matter Bridge production. Implement `--matter`, `--matter-setup-file`, `--matter-reset`, `--matter-vendor-id`, `--matter-product-id` CLI flags. Aggregator + Bridged Devices for all RuView nodes; per-zone occupancy endpoints; fall as `MultiPressComplete` event; person count as vendor-extension attribute. Integration tests via chip-tool sim. | pending |
|
||||
| **P9** | Multi-controller validation. Pair one Cognitum Seed + 3 child ESP32 nodes simultaneously into HA, Apple Home, and Google Home. Verify presence flips on all three within 1 s of a real motion change. Document the multi-admin flow in `docs/integrations/matter.md`. | pending |
|
||||
| **P10** | CSA Matter certification path (optional, ADR-1xx follow-up). Decide cost vs marketing value of the official "Matter-certified" badge ($3 k/year CSA membership + per-product test fees). Sketch only — production decision deferred. | pending |
|
||||
|
||||
Each phase ends with a checkbox PR. The ADR is updated with actual artifacts (commit hashes, screenshots, witness bundle entries) as phases land. **P1–P6 (MQTT) and P7–P10 (Matter) run in parallel after P6 lands** — they share no code, so a Matter regression cannot break the MQTT path and vice versa.
|
||||
|
||||
---
|
||||
|
||||
## 5. Consequences
|
||||
|
||||
### 5.1 Wins
|
||||
|
||||
- Zero-code UX for HA users — discovery handles the entire onboarding.
|
||||
- **Cross-ecosystem reach via Matter** — Apple Home / Google Home / Alexa / SmartThings users can adopt RuView without ever running HA, expanding our addressable market by ~4×.
|
||||
- Decouples RuView from its own UI; users can build their own dashboards in HA / Grafana / Node-RED on the same MQTT firehose.
|
||||
- Adds a `--privacy-mode` flag that gives operators a single-knob biometric strip for compliance contexts.
|
||||
- Matter fabric isolation is a privacy win by construction — biometrics are out-of-spec for the exposed clusters, so a buggy controller can't accidentally exfiltrate them.
|
||||
- Webhook + future HACS path stay open (§6) — no lock-in.
|
||||
- Establishes our presence in the HA ecosystem AND the broader Matter ecosystem (community add-on lists, blueprints, forum recipes, App Store / Play Store visibility via Apple Home / Google Home device listings).
|
||||
|
||||
### 5.2 Costs
|
||||
|
||||
- New runtime dependency (`rumqttc`) in `wifi-densepose-sensing-server`. Mitigated by feature-flag (`mqtt`), default off; users who don't enable `--mqtt` pay zero binary or runtime cost.
|
||||
- **Matter SDK dependency** (`matter-rs` tentatively) gated behind `--matter` feature flag. Adds ~5 MB to release binary when enabled; zero cost when disabled. Tracking CSA spec churn is a real ongoing cost.
|
||||
- One more thing to maintain across HA breaking changes. HA commits to the `homeassistant/<component>/.../config` schema being stable (their published policy), but historically they have evolved fields like `availability_topic` → `availability` (list-of). We'll pin to a tested HA version per release and call out tested-against in `docs/integrations/home-assistant.md`.
|
||||
- **Matter spec churn** — Matter 1.0 → 1.3 added device types and changed cluster IDs. We pin to a tested Matter spec version per release. Annual re-validation overhead.
|
||||
- Requires CI infra: a mosquitto container in workflow, schema-validation against HA schemas, **and** a chip-tool simulator for Matter pairing tests (need to vendor or fetch).
|
||||
- CSA membership ($3 k/year) is required to obtain a permanent vendor ID; until then we use the development VID `0xFFF1`. Production deployment past P9 requires the membership decision (§9.9).
|
||||
|
||||
### 5.3 Verification
|
||||
|
||||
Acceptance criteria are §8. Beyond those, this ADR is "Accepted" once P6 ships and at least one external user has reported a working HA install via the public issue tracker.
|
||||
|
||||
---
|
||||
|
||||
## 6. Alternatives considered
|
||||
|
||||
### 6.A Custom HA integration (HACS) — *follow-on, not primary*
|
||||
|
||||
Rough sketch:
|
||||
|
||||
- Separate Python repo (proposed name: `ruvnet/hass-wifi-densepose`).
|
||||
- Talks to sensing-server's existing WebSocket at `/ws/sensing` and REST at `/api/*`.
|
||||
- Config-flow UI in HA: user enters server URL + bearer token; integration discovers entities.
|
||||
- Distribution via HACS (https://hacs.xyz), requires HACS review + acceptance.
|
||||
|
||||
**Effort estimate:** ~4–6 weeks (vs ~2 weeks for §2 MQTT path). Adds a Python codebase to maintain in a Rust-first org. Pays off in two scenarios:
|
||||
|
||||
1. Users who run HA but don't run an MQTT broker (rare but exists).
|
||||
2. Users who want sensing-server features that don't map cleanly to MQTT (e.g. live pose video preview).
|
||||
|
||||
**Plan:** revisit after P6 lands and we have real adoption data on the MQTT path. If MQTT covers 80%+ of installs, HACS becomes a nice-to-have. If not, it becomes ADR-1xx follow-up.
|
||||
|
||||
### 6.B Local-push REST webhook — *rejected*
|
||||
|
||||
- sensing-server `POST`s to HA's webhook endpoint (`/api/webhook/<id>`).
|
||||
- Trivial to implement (~2 days).
|
||||
|
||||
Rejected because:
|
||||
|
||||
- One-way only — no `set_state` / arm / disarm path back.
|
||||
- No entity discovery — user has to manually create input_booleans / sensors / template_sensors in HA YAML.
|
||||
- No availability / LWT — sensing-server going offline is invisible to HA.
|
||||
- Fails the "plug-and-play" bar that #574 / #760 set.
|
||||
|
||||
Documented here so future readers know we considered it.
|
||||
|
||||
### 6.C mDNS discovery (#574) — *complementary, not competing*
|
||||
|
||||
mDNS / Zeroconf lets HA (or any local client) discover sensing-server's IP without manual configuration. It's orthogonal to MQTT: we should add it (already tracked in #574) so the user doesn't have to type the broker host either. mDNS resolves *where the broker is*; MQTT auto-discovery resolves *what entities to create*. Both ship; neither blocks the other.
|
||||
|
||||
---
|
||||
|
||||
## 7. Risks
|
||||
|
||||
| Risk | Likelihood | Impact | Mitigation |
|
||||
|---|---|---|---|
|
||||
| Topic-namespace collision with another HA device | low | medium | `unique_id` includes `wifi_densepose_` prefix + MAC-derived node_id; HA will refuse duplicates and log clearly |
|
||||
| HA changes the `homeassistant/` schema | medium (1× every ~2 years historically) | medium | Pin tested HA version in `docs/integrations/home-assistant.md`; CI runs schema validation against the pinned version |
|
||||
| Bandwidth blowup from pose keypoints | medium | low (LAN) / high (metered link) | Pose publishing is **off by default**; rate-limited when on; users hit a clear `WARN` if they enable pose without explicit rate cap |
|
||||
| Privacy regression — biometrics leaked to a public broker | medium | high | `--privacy-mode` strips them at source; WARN if `--mqtt` enabled without `--mqtt-tls` on a non-localhost broker; never publish HR / BR / pose discovery in privacy mode |
|
||||
| Cognitum Seed firmware footprint (if we ever push MQTT into the ESP32 path) | low | medium | Out of scope for this ADR — MQTT lives in sensing-server only. ESP32 keeps the lean UDP/WS path. If we later add MQTT to firmware, it's ADR-1xx with its own size budget per ADR-110 |
|
||||
| Broker compromise (bad actor on the network gets read access to MQTT) | low | high | mTLS recommendation in §3.9; `--privacy-mode` for high-risk deployments |
|
||||
| HA-side cardinality explosion from per-track-id binary_sensors | medium | low | Cap dynamic person entities at 10; old ones are removed via discovery `payload=""` (HA delete-entity convention) |
|
||||
| **Matter SDK (`matter-rs`) immaturity blocks cert** | medium | medium | P7 spike validates pairing on three controllers before P8 production work; fall back to chip-tool FFI if blocked |
|
||||
| **Matter spec adds vitals device types**, our vendor-extension attributes become non-standard | low (3+ years out) | low | Vendor-extension attributes are opt-in for controllers; migration to standard cluster IDs is a one-version bump when the spec lands |
|
||||
| **Multi-fabric races** (HA, Apple, Google all see the same node and fire conflicting automations) | medium | medium | Document the multi-admin guidance in `docs/integrations/matter.md`: pick one primary controller for automations, others for visibility |
|
||||
| **Apple Home / Google Home rendering misrepresents** RuView (e.g. shows generic "Sensor") | medium | low | Set rich `VendorName` / `ProductName` / `ProductLabel` in BasicInformation cluster; ship a Matter App icon (per CSA brand guidelines) once vendor ID is real |
|
||||
| **CSA membership cost** ($3 k/y) is a recurring spend with uncertain ROI | low (decision deferred to P10) | medium | Ship using dev VID `0xFFF1` through P9; commit to membership only after adoption data justifies it |
|
||||
|
||||
---
|
||||
|
||||
## 8. Acceptance criteria
|
||||
|
||||
A reviewer can run all of the following without modifying source:
|
||||
|
||||
```bash
|
||||
# 1. Start sensing-server with mock source + MQTT
|
||||
cargo run -p wifi-densepose-sensing-server -- \
|
||||
--source mock \
|
||||
--mqtt \
|
||||
--mqtt-host localhost \
|
||||
--mqtt-prefix homeassistant
|
||||
|
||||
# 2. Observe discovery + state messages
|
||||
mosquitto_sub -t 'homeassistant/#' -v
|
||||
# Expected: discovery configs for presence, heart_rate, breathing_rate, motion,
|
||||
# fall, person_count, rssi — one per entity per node — plus periodic state messages
|
||||
|
||||
# 3. Run the full workspace test suite
|
||||
cd v2 && cargo test --workspace --no-default-features
|
||||
# Expected: 1,031+ tests passed, 0 failed (new mqtt tests included)
|
||||
|
||||
# 4. Schema-validate discovery configs against HA's published schemas
|
||||
cargo test -p wifi-densepose-sensing-server --features mqtt mqtt::discovery::schema
|
||||
# Expected: green
|
||||
|
||||
# 5. Privacy mode strips biometrics
|
||||
cargo run -p wifi-densepose-sensing-server -- --source mock --mqtt --privacy-mode &
|
||||
mosquitto_sub -t 'homeassistant/#' -v | tee /tmp/privacy.log
|
||||
# Expected: NO heart_rate, breathing_rate, or pose entities in discovery
|
||||
grep -E "(heart_rate|breathing_rate|pose)" /tmp/privacy.log
|
||||
# Expected: empty (exit 1)
|
||||
|
||||
# 6. HA auto-discovery end-to-end (manual, post-P5)
|
||||
# - Add Mosquitto broker to a fresh HA OS install
|
||||
# - Add MQTT integration in HA, point at broker
|
||||
# - Start sensing-server with --mqtt
|
||||
# - HA Settings → Devices → expect "RuView node <mac>" with all entities
|
||||
# - Trigger mock presence change; presence entity flips ON / OFF live
|
||||
|
||||
# 7. LWT / availability
|
||||
# - Run sensing-server, observe `online` published
|
||||
# - Kill sensing-server (-9), wait 30 s
|
||||
# - Expect `offline` on every entity's availability topic
|
||||
|
||||
# 8. Matter Bridge pairing (post-P7)
|
||||
cargo run -p wifi-densepose-sensing-server -- \
|
||||
--source mock \
|
||||
--matter \
|
||||
--matter-setup-file /tmp/matter-qr.txt
|
||||
# Expected: setup code + QR string printed; bridge advertises over mDNS
|
||||
|
||||
# 9. Matter cross-controller test (post-P9; manual)
|
||||
# - Pair the bridge into Apple Home (scan QR with iPhone)
|
||||
# - Pair the same bridge into Home Assistant Matter integration (same QR)
|
||||
# - Trigger mock presence change in sensing-server
|
||||
# - Expected: occupancy entity flips ON in both controllers within 1 s
|
||||
|
||||
# 10. Matter privacy invariant
|
||||
mosquitto_sub -t 'homeassistant/sensor/+/heart_rate/state' -v &
|
||||
chip-tool occupancysensing read occupancy 0xDEADBEEF 1 # Matter endpoint 1
|
||||
# Expected: MQTT still publishes HR (without --privacy-mode); Matter NEVER exposes HR cluster (no clusters exist for it)
|
||||
```
|
||||
|
||||
All ten must pass before the ADR moves from Proposed → Accepted. Tests 1–7 cover MQTT (P1–P6); tests 8–10 cover Matter (P7–P9). Tests can be re-run incrementally as each phase lands.
|
||||
|
||||
---
|
||||
|
||||
## 9. Resolved decisions (maintainer ACK 2026-05-23)
|
||||
|
||||
All 13 questions resolved by maintainer @ruv on 2026-05-23. Status: **ACCEPTED**.
|
||||
|
||||
**Decision principle (canonical):** preserve clean protocols, avoid firmware bloat, avoid fake semantics, ship MQTT first, validate Matter second.
|
||||
|
||||
### 9.A MQTT path (P1–P6)
|
||||
|
||||
1. **Broker.** ✅ **Mosquitto as default.** Mention EMQX and VerneMQ as advanced options in `docs/integrations/home-assistant.md`.
|
||||
2. **Discovery prefix.** ✅ **Ship `homeassistant`** (HA's default). `--mqtt-prefix` remains overridable for users with custom HA setups.
|
||||
3. **HACS repo name.** ✅ **`ruvnet/hass-wifi-densepose`** — wired into the `support_url` field of every discovery payload's `origin` block from P1.
|
||||
4. **Sample blueprints.** ✅ **Ship 3 starter blueprints in P5.** Selected from §3.12.2 list — final three picked at P5 start, biased toward highest customer-pull primitives.
|
||||
5. **TLS default.** ✅ **WARN now, hard-fail non-localhost plaintext in v0.8.0.** Sensing-server logs a `WARN` if `--mqtt` enabled without `--mqtt-tls` on a non-localhost broker. v0.8.0 promotes to hard fail (exit non-zero) once docs cover the CA setup path.
|
||||
6. **`node_friendly_name`.** ✅ **NVS / config only.** No ADR-039 packet change. Sensing-server resolves the friendly name from local config and injects into MQTT/Matter device labels.
|
||||
7. **Pose keypoint schema.** ✅ **COCO 17-keypoint order.** Index → joint name mapping documented in `docs/integrations/home-assistant.md` and re-exported as `wifi_densepose_core::pose::COCO17`.
|
||||
8. **Multi-node aggregation.** ✅ **4 children + 1 parent via `via_device`.** Easier to debug; matches §3.4.
|
||||
|
||||
### 9.B Matter path (P7–P10)
|
||||
|
||||
9. **Matter vendor ID.** ✅ **Dev VID `0xFFF1` through P9.** CSA membership decision gate at P10 (deferred; sketched only).
|
||||
10. **Matter SDK.** ✅ **Start with `matter-rs`.** Fall back to chip-tool FFI only if cert blockers emerge in P7 spike.
|
||||
11. **Matter Thread.** ✅ **Future ADR.** ADR-115 stays WiFi-only on the server side. Thread support from ESP32-C6 firmware is a separate ADR after C6 stabilises (post-ADR-110 P8).
|
||||
12. **Fall event mapping.** ✅ **`Switch.MultiPressComplete`.** Cleaner semantics for controllers; matches Apple Home / Google Home rendering expectations.
|
||||
13. **Person count.** ✅ **Vendor extension.** Do not kludge into fake endpoints. Apple Home / Google Home will show `Occupancy: ON/OFF` only — that's honest. HA and SmartThings will surface the count via the vendor-extension attribute.
|
||||
|
||||
### 9.C Open-after-9 (new questions raised post-ACK)
|
||||
|
||||
Empty as of 2026-05-23. New questions discovered during implementation will be filed here, ACK'd by maintainer, and dated.
|
||||
|
||||
---
|
||||
|
||||
## 10. References
|
||||
|
||||
- Home Assistant MQTT integration docs: https://www.home-assistant.io/integrations/mqtt/
|
||||
- HA MQTT auto-discovery: https://www.home-assistant.io/integrations/mqtt/#mqtt-discovery
|
||||
- HA discovery schemas (per-component): https://www.home-assistant.io/integrations/binary_sensor.mqtt/ , .../sensor.mqtt/ , .../event.mqtt/
|
||||
- HACS: https://hacs.xyz
|
||||
- HA Blueprint format: https://www.home-assistant.io/docs/blueprint/schema/
|
||||
- `rumqttc` (chosen Rust MQTT client): https://docs.rs/rumqttc/
|
||||
- **Matter Core Spec 1.3** (CSA): https://csa-iot.org/all-solutions/matter/
|
||||
- **Matter Device Library** (cluster + device-type catalog): https://csa-iot.org/wp-content/uploads/2023/12/Matter-1.3-Device-Library-Specification.pdf
|
||||
- **matter-rs** (pure-Rust Matter SDK): https://github.com/project-chip/rs-matter
|
||||
- **project-chip/connectedhomeip** (reference C++ Matter SDK / chip-tool): https://github.com/project-chip/connectedhomeip
|
||||
- **Home Assistant Matter integration**: https://www.home-assistant.io/integrations/matter/
|
||||
- **Apple Home Matter support**: https://support.apple.com/en-us/HT213267
|
||||
- **Google Home Matter support**: https://developers.home.google.com/matter
|
||||
- **CSA membership / vendor ID program**: https://csa-iot.org/become-member/
|
||||
- **"Works with Home Assistant" certification**: https://partner.home-assistant.io/
|
||||
- RuView ADR-018 — CSI binary frame format
|
||||
- RuView ADR-021 — ESP32 vitals (edge breathing/HR extraction)
|
||||
- RuView ADR-028 — ESP32 capability audit
|
||||
- RuView ADR-031 — RuView sensing-first RF mode
|
||||
- RuView ADR-039 — Edge vitals packet (`0xC511_0002`)
|
||||
- RuView ADR-079 — Camera ground-truth training (pose schema)
|
||||
- RuView ADR-103 — `cog-person-count` (person count primitive)
|
||||
- RuView ADR-106 — DP-SGD + primitive isolation (privacy contract)
|
||||
- RuView ADR-110 — ESP32-C6 firmware extension
|
||||
- RuView ADR-114 — `cog-quantum-vitals`
|
||||
- Issue [#574](https://github.com/ruvnet/RuView/issues/574) — mDNS for seed_url (complementary)
|
||||
- Issue [#760](https://github.com/ruvnet/RuView/issues/760) — Sensing UI / onboarding friction
|
||||
- Issue [#761](https://github.com/ruvnet/RuView/issues/761) — Competitive scan (espectre.dev, tommysense.com)
|
||||
|
||||
---
|
||||
|
||||
*ADR-115 is the integration story that turns RuView from "another sensing platform" into "drop-in upgrade for any HA install **and** any Matter-controller home." MQTT carries the rich, differentiated telemetry; Matter carries the standardised subset across every controller ecosystem. Numbers 111 and 112 remain reserved per the project ADR-numbering policy.*
|
||||
@@ -1,116 +0,0 @@
|
||||
# ADR-116: Home Assistant + Matter as a Cognitum Seed cog (`cog-ha-matter`)
|
||||
|
||||
| Field | Value |
|
||||
|-------|-------|
|
||||
| **Status** | Proposed — P1 research complete ([`docs/research/ADR-116-ha-matter-cog-research.md`](../research/ADR-116-ha-matter-cog-research.md)). P2 cog scaffold compiles (`v2/crates/cog-ha-matter`, 2/2 unit tests green). |
|
||||
| **Date** | 2026-05-23 |
|
||||
| **Deciders** | ruv |
|
||||
| **Codename** | **HA-COG** — HA + Matter, packaged for the Seed |
|
||||
| **Relates to** | [ADR-110](ADR-110-esp32-c6-firmware-extension.md) (C6 firmware substrate), [ADR-115](ADR-115-home-assistant-integration.md) (HA-DISCO + HA-MIND + HA-FABRIC), [ADR-102](ADR-102-edge-module-registry.md) (cog catalog), [ADR-101](ADR-101-pose-estimation-cog.md) (cog packaging precedent) |
|
||||
| **Tracking issue** | TBD — file under RuView issue tracker once research dossier lands |
|
||||
|
||||
---
|
||||
|
||||
## 1. Context
|
||||
|
||||
ADR-115 shipped the Home Assistant + Matter integration as a **`--mqtt` flag on `wifi-densepose-sensing-server`** — a Rust binary that runs on a Pi / Linux box, consumes UDP frames from the ESP32 fleet, and publishes MQTT for any Home Assistant install to discover. That works, but it makes HA+Matter a *configuration of the aggregator*, not an *installable artifact* a Cognitum Seed user can drop into their existing fleet.
|
||||
|
||||
The Cognitum Seed already has a [105-cog catalog](https://seed.cognitum.one/store) — packaged Seed apps (`cog-pose-estimation`, `cog-quantum-vitals`, `cog-person-matching`, etc.) that anyone can install from `app-registry.json`. **There is no `cog-ha-matter` yet.** That's the gap this ADR closes.
|
||||
|
||||
The cog packaging precedent is ADR-101 (`cog-pose-estimation`) which ships signed aarch64 + x86_64 binaries on GCS with a `pose_v1.safetensors` weight blob — same shape we'd want for the HA cog.
|
||||
|
||||
### 1.1 Why a cog, not just the existing flag?
|
||||
|
||||
| Path | Distribution | Discovery | Update | Witness | Local AI |
|
||||
|---|---|---|---|---|---|
|
||||
| `--mqtt` on `sensing-server` | manual install of the Rust binary | none | manual | none | external |
|
||||
| **`cog-ha-matter` Seed cog** | `app-registry.json` listing, one-click install | mDNS / cog browser | OTA via cog runtime | Ed25519 witness chain | local ruvllm + RuVector |
|
||||
|
||||
The cog ships HA+Matter as a first-class Seed feature — same UX as installing a pose estimator or person matcher.
|
||||
|
||||
### 1.2 What this ADR is *not*
|
||||
|
||||
- Not a deprecation of the `--mqtt` flag on sensing-server. The flag stays for Pi / Linux deployments without a Seed; the cog is the Seed-native option.
|
||||
- Not a port of HA-MIND / HA-DISCO logic to a different language. The Rust crate already exists; the cog *wraps* it as a Seed-installable artifact + adds Seed-specific surfaces (witness, RuVector, ruvllm-driven thresholds).
|
||||
- Not a Matter SDK ship. ADR-115 §9.10 deferred the matter-rs SDK wiring to v0.7.1; this ADR continues that deferral and focuses on the *cog packaging* + *first-class Seed integration*, with Matter Bridge mode shipping in v0.8 once the SDK is ready.
|
||||
|
||||
## 2. Decision (provisional — to be refined by the research dossier)
|
||||
|
||||
Build **`cog-ha-matter`** as a Cognitum Seed cog with these surfaces:
|
||||
|
||||
### 2.1 Core entity surface (unchanged from ADR-115)
|
||||
|
||||
The cog republishes the same 21 entities per node (11 raw + 10 semantic primitives) over MQTT auto-discovery, so HA installations behave identically whether the source is a Seed cog or an external sensing-server.
|
||||
|
||||
### 2.2 Seed-native enhancements
|
||||
|
||||
- **Self-contained MQTT broker (optional)** — if the user doesn't already run mosquitto, the cog can host an embedded broker on `cognitum-seed.local:1883` and act as the HA endpoint directly.
|
||||
- **mDNS service advertisement** — `_ruview-ha._tcp` so HA's discovery integration finds the Seed without manual config.
|
||||
- **RuVector-backed semantic-primitive thresholds** — instead of static `semantic-thresholds.yaml`, the cog learns per-home thresholds via a SONA-adapted RuVector model (matches the Seed's local-first AI story).
|
||||
- **Ed25519 witness chain** — every state transition logged with a Seed signature so care-home / regulated deployments can audit decisions.
|
||||
- **OTA firmware coordination** — the cog manages C6 firmware updates for ESP32-C6 nodes in the mesh (ADR-110 substrate).
|
||||
|
||||
### 2.3 Matter dimensions (depend on research findings)
|
||||
|
||||
The research dossier covers (a) Matter Bridge vs Matter Device mode, (b) Thread Border Router on the Seed's ESP32-S3 (if feasible), (c) CSA certification path, (d) which Matter device classes map cleanly to which entities. **Decision deferred** until the dossier lands; this ADR will be updated in §3 with the specific Matter feature set.
|
||||
|
||||
### 2.4 Multi-Seed federation
|
||||
|
||||
Multiple Seeds in adjacent rooms coordinate via:
|
||||
- ESP-NOW mesh (ADR-110 substrate) for time alignment
|
||||
- mDNS for service discovery
|
||||
- Witness chain replication for cross-Seed event provenance
|
||||
|
||||
The federation model is the natural extension of ADR-110's mesh substrate into the application layer. Specifically: ADR-110 gives us ≤100 µs cross-board sync; this ADR uses that to deduplicate cross-Seed events (one fall, one alert) and reconstruct multi-room transitions (one occupant, room A → hallway → room B).
|
||||
|
||||
## 3. Research dossier findings (P1 complete)
|
||||
|
||||
Full dossier: [`docs/research/ADR-116-ha-matter-cog-research.md`](../research/ADR-116-ha-matter-cog-research.md). The eight research questions are now answered:
|
||||
|
||||
1. **Matter Bridge vs Matter Root** — Matter 1.4 introduced `OccupancySensor (0x0107)` with `RFSensing` feature flag on cluster `0x0406` (revision 5 in Matter 1.4). That's the correct device class for WiFi-CSI sensing — no health/vitals cluster exists in Matter 1.4.2 and won't soon. **Seed acts as Bridge** with N dynamic OccupancySensor endpoints, **not Commissioner** (the C6 sensing nodes stay Accessories only — 320 KB SRAM no PSRAM rules out commissioning).
|
||||
2. **Thread Border Router** — ESP32-C6 single-chip TBR confirmed working; `CONFIG_OPENTHREAD_BORDER_ROUTER=y` is the only config step. ADR-110's `c6_timesync.c` already initialises 802.15.4 — TBR is a Kconfig flag away. Real value: HA's Improv-style commissioning works without a separate Thread border router box.
|
||||
3. **HACS value-add** — config flow (UI setup wizard), Repairs API (structured error cards), re-authentication, diagnostics download, typed service actions (`set_privacy_mode`, `calibrate_zone`), i18n translations. **Bronze is the minimum bar; Gold (repairs + diagnostics + reconfiguration) is the target.** Start from `hacs.integration_blueprint` template.
|
||||
4. **CSA certification** — ~$30-42k first year ($22.5k membership + $10-19k ATL lab fees). **Skippable for v1** by publishing as "Works with HA" instead. CSA re-evaluate at v0.9+ after HACS adoption data lands.
|
||||
5. **Cog RAM budget** — 128 MB RAM / 15 % CPU on the Seed appliance (Pi 5 + Hailo-10 variant has more headroom). 10 KB INT8 semantic-primitive classifier fits without PSRAM. Long-lived supervised process with capability scopes `network.mqtt + network.matter + api.ruview_vitals`.
|
||||
6. **ruvllm + RuVector latency** — `ruvllm-esp32` v0.3.3 confirms SONA self-optimising adaptation under 100 µs per query. 8→10 INT8 classifier ~10 KB quantised. Per-home threshold tuning via HA thumbs-up/thumbs-down feedback as LoRA-style gradient steps — closes the top user complaint (false positives) without cloud round-trips.
|
||||
7. **HIPAA / FDA** — FDA January 2026 General Wellness guidance explicitly classifies HR / sleep / activity-anomaly alerts as **wellness devices** (outside FDA jurisdiction) when marketed without diagnostic claims. Frame fall detection as **"activity anomaly notification"** not "fall diagnosis". `--privacy-mode` audit-only tier (no MQTT state messages, only SHA-256 digests on-Seed) creates a technical PHI barrier. `OccupancySensor (0x0107)` device class keeps the product in the same regulatory category as a smart motion sensor.
|
||||
8. **Competitor moat** — Aqara FP300 (Nov 2025): 5 entities, no person count, no vitals, no fall detection. TOMMY: zones only, no vitals, closed-source, paywalled. ESPectre: motion only. **RuView's differentiation** — HR/BR + 17-keypoint pose + 10 semantic primitives + witness chain + SONA adaptation — has no competitor equivalent.
|
||||
|
||||
## 4. Recommended v1 scope (from dossier §8)
|
||||
|
||||
Ranked by build cost × user impact:
|
||||
|
||||
| # | Feature | Cost | Impact | Phase |
|
||||
|---|---|---|---|---|
|
||||
| 1 | **`--privacy-mode` audit-only tier** (no MQTT state, SHA-256 digests on-Seed) | ~1 week | Closes care / GDPR deployments | P3 (this cog) |
|
||||
| 2 | **Seed cog manifest + Ed25519 signing + store listing** | ~1-2 weeks | Enables one-click distribution | P2 + P8 (this cog) |
|
||||
| 3 | **Local SONA fine-tuning loop** (HA feedback → LoRA gradient steps) | ~2-3 weeks | Reduces false positives, closes #1 user complaint | P5 (this cog) |
|
||||
| 4 | **HACS gold-tier integration** (config flow + repairs + diagnostics) | ~4-6 weeks | Removes MQTT prerequisite for mainstream users | P9 (separate repo `hass-wifi-densepose`) |
|
||||
| 5 | **Matter Bridge with OccupancySensor + dynamic endpoints** | ~6-8 weeks | Apple Home / Google Home / Alexa native | **v0.8** dedicated sprint (after HACS adoption data) |
|
||||
| 6 | **Embedded MQTT broker (rumqttd) inside the cog** | ~1 week | "Works without external broker" but every HA install already has mosquitto / built-in | **v0.7** deferred — adds ~2 MB binary + ACL config surface for marginal user benefit. Dossier ranking did not include this in the prioritised v1 scope. |
|
||||
|
||||
## 4. Implementation phases
|
||||
|
||||
| Phase | Scope | Status |
|
||||
|---|---|---|
|
||||
| **P1** | Research dossier ([`docs/research/ADR-116-ha-matter-cog-research.md`](../research/ADR-116-ha-matter-cog-research.md)) | ✅ **done** — 8 sections, 30+ citations, v1 scope ranked |
|
||||
| **P2** | Cog crate scaffold (`v2/crates/cog-ha-matter/`) — Cargo.toml + `src/{lib,main,manifest}.rs`, workspace member, CLI args, `--print-manifest` flag, 2 manifest unit tests | ✅ **done** — `cargo check` + `cargo test` green |
|
||||
| **P3** | Wrap existing ADR-115 MQTT publisher as cog entry point | ✅ **wiring done** — `main.rs` boots ADR-115's `publisher::spawn` via `runtime::spawn_publisher` thin wrapper, holds a long-lived `broadcast::Sender<VitalsSnapshot>`, awaits Ctrl-C. Live-handle test green without a broker. Next (P3.5): subscribe to sensing-server `/v1/snapshot` WS and republish into the channel. |
|
||||
| **P4** | Seed-native enhancements (mDNS, witness; embedded broker deferred) | ✅ **shipped** — mDNS half: record-builder + ServiceInfo conversion + live responder wired into `main.rs` (HA auto-discovery on `_ruview-ha._tcp` works out of the box, `--no-mdns` flag for restrictive networks). Witness half: hash-chain + JSONL + file persistence + chain-level verify + Ed25519 signing. **Embedded rumqttd broker deferred to v0.7** per dossier §8 ranking — not in the prioritised v1 scope; v1 ships with external-broker only (mosquitto or HA's built-in broker). See §4 v1 scope table. |
|
||||
| **P5** | RuVector-backed threshold learning (SONA adaptation) | pending |
|
||||
| **P6** | Multi-Seed federation (cross-Seed dedup + witness) | pending |
|
||||
| **P7** | Matter Bridge mode (depends on matter-rs / esp-matter readiness) | pending |
|
||||
| **P8** | Cog signing + `app-registry.json` listing + Seed Store entry | pending |
|
||||
| **P9** | HACS integration repo (`hass-wifi-densepose`) for HA-side install path | pending |
|
||||
| **P10** | Witness bundle + CSA-style spec compliance check | pending |
|
||||
|
||||
## 5. References
|
||||
|
||||
- ADR-101 — `cog-pose-estimation` packaging precedent (signed binaries on GCS, .cog manifest)
|
||||
- ADR-102 — edge module registry (`app-registry.json` surfaces all cogs)
|
||||
- ADR-110 — ESP32-C6 firmware substrate (mesh time alignment that multi-Seed federation depends on)
|
||||
- ADR-115 — HA-DISCO + HA-MIND + HA-FABRIC (the Rust crate this cog wraps)
|
||||
- `docs/research/ADR-116-ha-matter-cog-research.md` — companion research dossier (deep-researcher agent in progress)
|
||||
- Cognitum Seed store: https://seed.cognitum.one/store
|
||||
- Matter spec: https://csa-iot.org/all-solutions/matter/
|
||||
- HACS integration target: https://github.com/ruvnet/hass-wifi-densepose (planned)
|
||||
@@ -1,807 +0,0 @@
|
||||
# ADR-117: pip `wifi-densepose` modernization via PyO3 + maturin bindings
|
||||
|
||||
| Field | Value |
|
||||
|-------|-------|
|
||||
| **Status** | Proposed |
|
||||
| **Date** | 2026-05-24 |
|
||||
| **Deciders** | ruv |
|
||||
| **Codename** | **PIP-PHOENIX** — rising from a pure-Python server to Rust-core Python bindings |
|
||||
| **Relates to** | [ADR-021](ADR-021-esp32-vitals.md) (ESP32 vitals), [ADR-028](ADR-028-esp32-capability-audit.md) (capability audit / witness), [ADR-115](ADR-115-home-assistant-integration.md) (HA-DISCO + HA-MIND MQTT semantics), [ADR-116](ADR-116-cog-ha-matter-seed.md) (HA-COG Seed packaging) |
|
||||
| **Tracking issue** | TBD — file under RuView issue tracker |
|
||||
|
||||
---
|
||||
|
||||
## 1. Context
|
||||
|
||||
### 1.1 What the pip package is today
|
||||
|
||||
`wifi-densepose` v1.1.0 was published to PyPI on **2025-06-07** (two releases the same
|
||||
day: 1.0.0 at 13:24 UTC, 1.1.0 at 17:02 UTC). Both wheels carry the tag
|
||||
`py3-none-any` — no compiled extension, no platform-specific code. The package is a
|
||||
**pure-Python server application** sourced entirely from `archive/v1/`.
|
||||
|
||||
The package installs a 40-dependency stack including FastAPI, PyTorch, SQLAlchemy,
|
||||
Redis, Celery, OpenCV, asyncpg, psycopg2, and Scapy (`archive/v1/setup.py:46–87`).
|
||||
The declared entry points are:
|
||||
|
||||
```
|
||||
wifi-densepose = src.cli:cli
|
||||
wdp = src.cli:cli
|
||||
```
|
||||
|
||||
(`archive/v1/setup.py:178–179`)
|
||||
|
||||
The public API surface is centred on a FastAPI HTTP server, a SQLAlchemy/postgres
|
||||
database layer, and a Redis/Celery task queue — none of which map to the current Rust
|
||||
architecture. The `__init__.py` exports `app` (FastAPI), `CSIProcessor`,
|
||||
`PhaseSanitizer`, `PoseEstimator`, `RouterInterface`, `ServiceOrchestrator`,
|
||||
`HealthCheckService`, and `MetricsService` (`archive/v1/src/__init__.py:54–68`).
|
||||
|
||||
### 1.2 Why this matters now
|
||||
|
||||
ADR-115 (PR #778, merged 2026-05-23) shipped 21 Home Assistant entities, 10 semantic
|
||||
primitives, mTLS, privacy mode, and a full witness bundle from the Rust crate
|
||||
`wifi-densepose-sensing-server`. ADR-116 is packaging this as a Cognitum Seed cog.
|
||||
Neither surface is reachable from `pip install wifi-densepose` — the pip package cannot
|
||||
import a CsiFrame, decode an edge-vitals packet, call a DSP stage, verify a witness
|
||||
bundle, or subscribe to the sensing server's MQTT or WebSocket endpoints. The ecosystem
|
||||
split is now wide enough that the pip package actively misleads new users about what
|
||||
the project does.
|
||||
|
||||
Three concrete customer pain points:
|
||||
|
||||
1. A Python user who `pip install wifi-densepose` expecting to consume live pose/vitals
|
||||
data gets a FastAPI server that requires postgres + redis, not a library they can
|
||||
script against.
|
||||
2. Integrators writing HA automations or Node-RED flows in Python have no idiomatic
|
||||
Python API for the v0.7 telemetry surface (ADR-115 entities, semantic primitives).
|
||||
3. The ADR-028 witness chain (deterministic pipeline proof) is Python-based and
|
||||
exercised via `archive/v1/data/proof/verify.py`, but it imports from the v1 stack —
|
||||
it cannot witness the Rust pipeline that is now the production implementation.
|
||||
|
||||
### 1.3 What this ADR is *not*
|
||||
|
||||
- Not a removal of `archive/v1/` from the repository. The v1 codebase stays as a
|
||||
research archive and its proof bundle stays in `archive/v1/data/proof/`.
|
||||
- Not a port of the Rust crates to Python. The Rust workspace (`v2/`) is authoritative
|
||||
and unmodified by this ADR.
|
||||
- Not a replacement of the `wifi-densepose-sensing-server` Rust binary. The pip
|
||||
package wraps or clients the binary; it does not reimplement it.
|
||||
- Not an overlap with ADR-116 (Seed cog packaging). ADR-116 ships a Seed-installable
|
||||
artifact; ADR-117 ships a Python developer library for scripting, automation, and
|
||||
prototyping against the Rust stack.
|
||||
|
||||
---
|
||||
|
||||
## 2. Current state — evidence
|
||||
|
||||
| Artifact | Value | Source |
|
||||
|---|---|---|
|
||||
| Latest PyPI version | **1.1.0** | `pypi.org/pypi/wifi-densepose/json` |
|
||||
| First release date | 2025-06-07T13:24:53Z | PyPI JSON metadata |
|
||||
| Latest release date | 2025-06-07T17:02:40Z | PyPI JSON metadata |
|
||||
| Months since last release | **~11.5 months** | as of 2026-05-24 |
|
||||
| Wheel tag | `py3-none-any` | PyPI simple index |
|
||||
| Hard dependencies | 40 (torch, fastapi, sqlalchemy, redis, celery, …) | `setup.py:46–87` |
|
||||
| Entry point | `src.cli:cli` | `setup.py:178` |
|
||||
| Python requires | `>=3.9` | `setup.py:108` |
|
||||
| Classifiers Python versions | 3.9, 3.10, 3.11, 3.12 | PyPI JSON classifiers |
|
||||
| Classifiers status | Beta (4) | PyPI JSON classifiers |
|
||||
| Current Rust workspace version | **0.3.0** | `v2/Cargo.toml:version` |
|
||||
| Rust crates in workspace | 20+ | `v2/Cargo.toml` members |
|
||||
| ADR-115 shipped | 2026-05-23 | PR #778 |
|
||||
|
||||
The v1 source package (`archive/v1/setup.py:112–215`) was clearly designed as an
|
||||
all-in-one server application, not a reusable library. The `find_packages` call at
|
||||
line 134 searches from `"."` (the archive root), meaning the wheel ships `src.*` as the
|
||||
importable namespace. The proof bundle (`archive/v1/data/proof/verify.py:56–57`) imports
|
||||
`src.hardware.csi_extractor.CSIData` and `src.core.csi_processor.CSIProcessor` — v1 pure
|
||||
Python only.
|
||||
|
||||
**PyPI org presence check:** a search for other `ruvnet`-published PyPI packages
|
||||
(`ruvector`, `claude-flow`) returned no matches in the PyPI simple index as of this
|
||||
writing. The `wifi-densepose` package is currently the only Python entry point for this
|
||||
project's ecosystem.
|
||||
|
||||
---
|
||||
|
||||
## 3. Gap analysis
|
||||
|
||||
| Capability | Rust crate(s) | pip v1.1.0 status | Gap severity |
|
||||
|---|---|---|---|
|
||||
| `CsiFrame` / `CsiMetadata` core types | `wifi-densepose-core` (`types.rs`) | Not present — v1 uses `CSIData` Python class | **Critical** |
|
||||
| HR/BR extraction from CSI buffer | `wifi-densepose-vitals` (4-stage pipeline: preprocessor → breathing → heartrate → anomaly) | Stub Python (`src/hardware/csi_extractor.py`) with no DSP | **Critical** |
|
||||
| Phase sanitization / noise removal | `wifi-densepose-signal` (`phase_sanitizer`, `csi_processor`, `hampel`) | Python stubs in `src/core/phase_sanitizer.py` | **Critical** |
|
||||
| Motion detection + presence scoring | `wifi-densepose-signal` (`motion.rs`, `MotionDetector`) | Not present | **Critical** |
|
||||
| RuvSense multistatic sensing (13 modules) | `wifi-densepose-signal/src/ruvsense/` | Not present — ADR-029 post-dates v1 | **Critical** |
|
||||
| 17-keypoint pose estimation | `wifi-densepose-nn`, `wifi-densepose-mat` | Stub `PoseEstimator` wrapping a `torch.nn.Module` that requires model weights | **High** |
|
||||
| MQTT publisher (21 HA entities) | `wifi-densepose-sensing-server/src/mqtt/` | Not present — ADR-115 post-dates v1 | **High** |
|
||||
| Semantic primitives (10 types) | `wifi-densepose-sensing-server/src/semantic/` | Not present | **High** |
|
||||
| Matter bridge | `wifi-densepose-sensing-server/src/matter/` | Not present | **High** |
|
||||
| WS/REST client for sensing-server | `wifi-densepose-sensing-server` (Axum) | v1 has a separate FastAPI server; no client | **High** |
|
||||
| Witness bundle verification | ADR-028 / `scripts/generate-witness-bundle.sh` | `archive/v1/data/proof/verify.py` — proves v1 pipeline only | **High** |
|
||||
| ESP32-C6 firmware telemetry (ADR-110) | `wifi-densepose-hardware` + `wifi-densepose-sensing-server` | Not present | **Medium** |
|
||||
| Cross-viewpoint fusion (RuVector) | `wifi-densepose-ruvector/src/viewpoint/` | Not present | **Medium** |
|
||||
| Semantic-primitive MQTT payload | `wifi-densepose-sensing-server/src/semantic/bus.rs` | Not present | **Medium** |
|
||||
| PostgreSQL + Redis server mode | `archive/v1/` | Present (v1 only) | Low (not SOTA) |
|
||||
| FastAPI HTTP REST server | `archive/v1/src/app.py` | Present (v1 only) | Low (not SOTA) |
|
||||
|
||||
---
|
||||
|
||||
## 4. Decision
|
||||
|
||||
Adopt **PyO3 + maturin Python extension bindings** as the primary modernization path,
|
||||
shipping the pip package as a platform-native wheel (`manylinux`, `macosx`, `win-amd64`)
|
||||
with compiled Rust extension modules, plus a pure-Python WS/MQTT client layer that talks
|
||||
to a running `wifi-densepose-sensing-server` instance.
|
||||
|
||||
This path is called **PIP-PHOENIX**.
|
||||
|
||||
### 4.1 Why PyO3 + maturin over the three rejected alternatives
|
||||
|
||||
| Criterion | **PyO3 + maturin** (chosen) | Subprocess wrapper | REST/WS client only | Pure Python reimpl |
|
||||
|---|---|---|---|---|
|
||||
| Performance for DSP | Native Rust speed, zero copy | IPC overhead per call | N/A — no local DSP | Python bottleneck |
|
||||
| Binary size in wheel | Core + vitals + signal only: ~2 MB stripped | Full sensing-server binary: ~15–30 MB | Minimal (~50 kB) | Minimal (~100 kB) |
|
||||
| Works offline / no server | Yes | Yes (binary bundled) | No — server required | Partial |
|
||||
| Proof bundle can cover Rust pipeline | Yes — bindings call the same Rust code the server uses | Partial — server is a black box | No | No |
|
||||
| Install experience | `pip install wifi-densepose` — wheel has no system deps | `pip install` downloads 25 MB binary | `pip install` — pure Python | `pip install` — pure Python |
|
||||
| Maintenance surface | Python bindings + Rust workspace | Python thin shim | Python client | Python reimpl must track Rust |
|
||||
| Async / tokio support | PyO3 0.28 `pyo3-asyncio` or `pyo3-async-runtimes` for async export; sync entry points for the DSP hot path | N/A | Native asyncio on client | N/A |
|
||||
| GIL concern | DSP-heavy calls release GIL via `py.allow_threads`; tokio runtime per module | N/A | None | N/A |
|
||||
| Fits existing architecture | Core + vitals + signal already have clean public APIs (`lib.rs` re-exports) | Requires sensing-server to be running | Requires sensing-server | Forks the domain model |
|
||||
|
||||
**Subprocess wrapper** is rejected because shipping a 25 MB pre-built server binary
|
||||
inside every pip wheel is an unacceptably heavy install, and it makes offline scripting
|
||||
impossible without starting the server.
|
||||
|
||||
**REST/WS client only** is rejected because it provides zero DSP utility offline and
|
||||
cannot close the witness gap — the proof bundle must exercise the same pipeline code.
|
||||
|
||||
**Pure Python reimplementation** is the root cause of the current drift and is
|
||||
explicitly rejected.
|
||||
|
||||
The chosen path starts small: **bind only the three crates with the highest Python
|
||||
utility** (`wifi-densepose-core`, `wifi-densepose-vitals`, `wifi-densepose-signal`),
|
||||
ship a `py3-none-any` pure-Python WS/MQTT client layer as a separate sub-module, and
|
||||
grow from there.
|
||||
|
||||
---
|
||||
|
||||
## 5. Detailed design
|
||||
|
||||
### 5.1 Rust crates bound in v2.0 (first wheel)
|
||||
|
||||
Three crates are in scope for the initial binding. They were chosen because they have
|
||||
no heavy system dependencies (no libtorch, no ONNX runtime), have stable `pub` re-export
|
||||
surfaces in `lib.rs`, and directly address the three most-requested missing capabilities.
|
||||
|
||||
| Crate | Exported Python types / functions | Binding rationale |
|
||||
|---|---|---|
|
||||
| `wifi-densepose-core` | `CsiFrame`, `CsiMetadata`, `Keypoint`, `KeypointType`, `PersonPose`, `PoseEstimate`, `Confidence`, `BoundingBox` | Foundation types shared by all other crates; without these users can't even describe a frame |
|
||||
| `wifi-densepose-vitals` | `CsiVitalPreprocessor`, `BreathingExtractor`, `HeartRateExtractor`, `VitalAnomalyDetector`, `VitalSignStore`, `VitalReading`, `VitalEstimate`, `AnomalyAlert` | The most-asked-for surface: HR/BR from a CSI buffer in 4 lines of Python |
|
||||
| `wifi-densepose-signal` | `CsiProcessor`, `CsiProcessorConfig`, `PhaseSanitizer`, `MotionDetector`, `MotionScore`, `FeatureExtractor`, `HardwareNormalizer` | DSP pipeline that produces the features vitals and pose estimation consume |
|
||||
|
||||
Crates **deferred to P6+**: `wifi-densepose-nn` (requires libtorch or candle — wheel
|
||||
size risk), `wifi-densepose-mat` (depends on nn), `wifi-densepose-ruvector` (RuVector
|
||||
GNN types — high value but adds ruvector-gnn 2.0.5 link dependency),
|
||||
`wifi-densepose-hardware` (ESP32 HAL — not Python-scripting friendly).
|
||||
|
||||
### 5.2 New workspace member: `python/`
|
||||
|
||||
A new crate `python/` is added as a workspace member at `v2/crates/wifi-densepose-py/`.
|
||||
It is a `cdylib` that re-exports the three bound crates behind a single maturin module
|
||||
named `wifi_densepose._core`.
|
||||
|
||||
```toml
|
||||
# v2/crates/wifi-densepose-py/Cargo.toml (sketch)
|
||||
[package]
|
||||
name = "wifi-densepose-py"
|
||||
version.workspace = true
|
||||
edition.workspace = true
|
||||
|
||||
[lib]
|
||||
name = "_core"
|
||||
crate-type = ["cdylib"]
|
||||
|
||||
[dependencies]
|
||||
pyo3 = { version = "0.28", features = ["extension-module", "abi3-py310"] }
|
||||
wifi-densepose-core = { path = "../wifi-densepose-core", features = ["serde"] }
|
||||
wifi-densepose-vitals = { path = "../wifi-densepose-vitals" }
|
||||
wifi-densepose-signal = { path = "../wifi-densepose-signal" }
|
||||
```
|
||||
|
||||
The `abi3-py310` feature locks the stable ABI to CPython 3.10+, so one wheel binary
|
||||
works across 3.10, 3.11, 3.12, and 3.13 without recompilation.
|
||||
|
||||
PyO3 bindings pattern (example for `CsiFrame`):
|
||||
|
||||
```rust
|
||||
// v2/crates/wifi-densepose-py/src/core_types.rs
|
||||
use pyo3::prelude::*;
|
||||
use wifi_densepose_core::CsiFrame as RustCsiFrame;
|
||||
|
||||
#[pyclass(name = "CsiFrame")]
|
||||
#[derive(Clone)]
|
||||
pub struct PyCsiFrame {
|
||||
inner: RustCsiFrame,
|
||||
}
|
||||
|
||||
#[pymethods]
|
||||
impl PyCsiFrame {
|
||||
#[new]
|
||||
fn new(amplitudes: Vec<f32>, phases: Vec<f32>, n_subcarriers: usize,
|
||||
sample_index: u64, sample_rate_hz: f32) -> Self {
|
||||
Self { inner: RustCsiFrame { amplitudes, phases, n_subcarriers,
|
||||
sample_index, sample_rate_hz } }
|
||||
}
|
||||
|
||||
#[getter] fn amplitudes(&self) -> Vec<f32> { self.inner.amplitudes.clone() }
|
||||
#[getter] fn phases(&self) -> Vec<f32> { self.inner.phases.clone() }
|
||||
#[getter] fn n_subcarriers(&self) -> usize { self.inner.n_subcarriers }
|
||||
}
|
||||
```
|
||||
|
||||
DSP calls that execute >1 ms release the GIL:
|
||||
|
||||
```rust
|
||||
#[pymethods]
|
||||
impl PyCsiProcessor {
|
||||
fn process<'py>(&mut self, py: Python<'py>, frame: &PyCsiFrame)
|
||||
-> PyResult<Option<PyProcessedSignal>>
|
||||
{
|
||||
py.allow_threads(|| self.inner.process(&frame.inner))
|
||||
.map(|opt| opt.map(PyProcessedSignal::from))
|
||||
.map_err(|e| PyRuntimeError::new_err(e.to_string()))
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### 5.3 pip package layout
|
||||
|
||||
```
|
||||
wifi-densepose/ ← PyPI package name (unchanged)
|
||||
wifi_densepose/ ← importable namespace
|
||||
__init__.py ← re-exports core types + version
|
||||
_core.pyd / _core.so ← compiled PyO3 extension (maturin build output)
|
||||
vitals.py ← thin Python wrapper + docstrings over _core vitals types
|
||||
signal.py ← thin Python wrapper over _core signal types
|
||||
client/
|
||||
__init__.py
|
||||
ws.py ← asyncio WebSocket client for sensing-server /ws/sensing
|
||||
mqtt.py ← paho-mqtt wrapper for ruview/<node_id>/raw/* topics
|
||||
ha.py ← helpers for HA-DISCO payloads (read-only, mirrors ADR-115 §3.2)
|
||||
witness/
|
||||
__init__.py
|
||||
verify.py ← Python-callable witness verifier (re-creates ADR-028 proof
|
||||
over the Rust pipeline via PyO3 bindings, not archive/v1/)
|
||||
compat/
|
||||
v1.py ← import shim that raises MigrationError (see §9)
|
||||
py.typed ← PEP 561 marker
|
||||
```
|
||||
|
||||
The import path intentionally maps to Rust crate names:
|
||||
|
||||
```python
|
||||
from wifi_densepose import CsiFrame # core types
|
||||
from wifi_densepose.vitals import BreathingExtractor, HeartRateExtractor
|
||||
from wifi_densepose.signal import CsiProcessor, MotionDetector
|
||||
from wifi_densepose.client.ws import SensingClient
|
||||
from wifi_densepose.witness import verify_bundle
|
||||
```
|
||||
|
||||
### 5.4 PyPI distribution — wheel matrix
|
||||
|
||||
Published as `wifi-densepose==2.0.0` using **cibuildwheel** driven by GitHub Actions.
|
||||
|
||||
| Platform | Arch | CPython | Tag (stable ABI) |
|
||||
|---|---|---|---|
|
||||
| `manylinux_2_28` | x86_64 | 3.10+ | `cp310-abi3-manylinux_2_28_x86_64` |
|
||||
| `manylinux_2_28` | aarch64 | 3.10+ | `cp310-abi3-manylinux_2_28_aarch64` |
|
||||
| `macosx_11_0` | x86_64 | 3.10+ | `cp310-abi3-macosx_11_0_x86_64` |
|
||||
| `macosx_11_0` | arm64 | 3.10+ | `cp310-abi3-macosx_11_0_arm64` |
|
||||
| `win` | amd64 | 3.10+ | `cp310-abi3-win_amd64` |
|
||||
| sdist | — | — | source fallback |
|
||||
|
||||
The `abi3-py310` flag means **one binary per OS/arch** covers all supported Python
|
||||
versions — 5 wheels total plus an sdist, compared to the 20-wheel matrix that would be
|
||||
needed without stable ABI.
|
||||
|
||||
```yaml
|
||||
# .github/workflows/pip-release.yml (sketch)
|
||||
- uses: pypa/cibuildwheel@v2
|
||||
with:
|
||||
package-dir: v2/crates/wifi-densepose-py
|
||||
output-dir: dist
|
||||
env:
|
||||
CIBW_BUILD: "cp310-*"
|
||||
CIBW_ARCHS_LINUX: "x86_64 aarch64"
|
||||
CIBW_ARCHS_MACOS: "x86_64 arm64"
|
||||
CIBW_ARCHS_WINDOWS: "AMD64"
|
||||
CIBW_BEFORE_BUILD: "pip install maturin"
|
||||
CIBW_BUILD_FRONTEND: "build[uv]"
|
||||
```
|
||||
|
||||
### 5.5 CLI parity
|
||||
|
||||
The pip wheel installs a `wifi-densepose` console script. In v2 this script is a thin
|
||||
Python shim that:
|
||||
|
||||
1. Checks whether `wifi-densepose-sensing-server` binary is on `PATH` (installed
|
||||
separately via a platform-specific binary distribution or `cargo install`).
|
||||
2. If found: proxies `wifi-densepose serve`, `wifi-densepose stream`, etc. to the Rust
|
||||
binary via `subprocess.run`.
|
||||
3. If not found: falls back to the PyO3 module for offline DSP commands
|
||||
(`wifi-densepose vitals --file recording.jsonl`).
|
||||
|
||||
This is explicitly **not** a reimplementation of the CLI — the Rust binary
|
||||
(`wifi-densepose-cli/src/main.rs`, currently exposes `mat` and `version` subcommands)
|
||||
is the authoritative CLI. The pip shim is a discovery/convenience layer.
|
||||
|
||||
### 5.6 WS/MQTT client layer
|
||||
|
||||
`wifi_densepose.client.ws.SensingClient` is a pure-Python asyncio client wrapping the
|
||||
sensing-server WebSocket at `/ws/sensing`:
|
||||
|
||||
```python
|
||||
async with SensingClient("ws://localhost:8765/ws/sensing") as client:
|
||||
async for msg in client.stream():
|
||||
if msg.type == "edge_vitals":
|
||||
print(msg.breathing_rate_bpm, msg.heartrate_bpm)
|
||||
```
|
||||
|
||||
`wifi_densepose.client.mqtt.RuViewMqttClient` wraps paho-mqtt and subscribes to
|
||||
`ruview/<node_id>/raw/+` as defined in ADR-115 §3.2.
|
||||
|
||||
Both clients are **pure Python** (no PyO3) and are optional dependencies (`pip install
|
||||
wifi-densepose[client]`). They depend on `websockets>=12` and `paho-mqtt>=2` respectively.
|
||||
|
||||
### 5.7a Beamforming Feedback Loop Data (BFLD) support — new binding target
|
||||
|
||||
**Added 2026-05-24 per maintainer feedback during P3 implementation.**
|
||||
|
||||
BFLD is the transmitter-side, AP-station-loop view of the WiFi channel
|
||||
— compressed beamforming feedback frames that 802.11ac/ax/be stations
|
||||
send to the AP per sounding cycle. From a sensing perspective it
|
||||
complements receiver-side CSI:
|
||||
|
||||
| | Receiver-side CSI (current) | BFLD (this addition) |
|
||||
|---|---|---|
|
||||
| Source | RX side of the radio (e.g. Nexmon CSI on Pi 5, ESP32 promisc cb) | Sniffed BFR frames in the air or `mac80211` ACK trace |
|
||||
| Subcarriers (HE20) | 52 (HT-LTF) or 242 (HE-LTF) | Up to 996 (HE160 compressed BFR) — denser |
|
||||
| Hardware requirements | Patched Broadcom/Cypress or ESP32 specifically | **Any** 802.11ac+ station-AP pair — no patched firmware |
|
||||
| Privacy model | Captures everyone in radio range | Same |
|
||||
| Maturity in repo | Production (ADR-014, ADR-018, ADR-039) | Research; no Rust crate yet |
|
||||
| Suitable use case | Through-wall pose + vitals | Dense subcarrier reflection profile for AETHER-class biometric (ADR-024) and the soul-signature spec (`docs/research/soul/`) |
|
||||
|
||||
#### Binding strategy
|
||||
|
||||
Because the Rust workspace has no `wifi-densepose-bfld` crate yet, P3
|
||||
ships a **forward-compatible Python trait surface** that the future
|
||||
Rust crate plugs into without changing the Python API:
|
||||
|
||||
```python
|
||||
from wifi_densepose import BfldFrame, BfldReport
|
||||
|
||||
# Today (P3): construct from a parsed BFR feedback matrix (the bring-
|
||||
# your-own-parser path). Users on Pi 5 + Wireshark BFR dissector
|
||||
# pipe frames in directly.
|
||||
frame = BfldFrame.from_compressed_feedback(
|
||||
timestamp_ms=…,
|
||||
sounding_index=…,
|
||||
sta_mac="aa:bb:cc:…",
|
||||
bandwidth_mhz=80,
|
||||
n_subcarriers=996,
|
||||
feedback_matrix=…, # numpy ndarray complex64 [Nr × Nc × Nsc]
|
||||
)
|
||||
|
||||
# P3 also ships a stub `BfldReport` aggregator that mirrors how
|
||||
# `VitalEstimate` aggregates `VitalReading`s. Users who have BFR
|
||||
# pipelines feeding RuView can use this today via the
|
||||
# bring-your-own-parser path.
|
||||
|
||||
# Tomorrow (post-v2.0): the `wifi-densepose-bfld` Rust crate (TBD —
|
||||
# separate ADR-1xx) provides ingestion from Nexmon `nl80211` traces +
|
||||
# kernel `mac80211` debugfs hooks, and the pip wheel transparently
|
||||
# binds it without changing this Python surface.
|
||||
```
|
||||
|
||||
#### Why this matters
|
||||
|
||||
Three reasons BFLD belongs in v2.0 rather than waiting for the Rust
|
||||
core:
|
||||
|
||||
1. **Customer pull**. Several integrators reading the ADR-115 release
|
||||
notes asked about WiFi-6 dense-subcarrier capture; the answer is
|
||||
BFLD, and we want the API stable before they build pipelines.
|
||||
2. **Soul-signature dependency**. The soul-signature research spec
|
||||
(`docs/research/soul/specification.md`) lists "Subcarrier Reflection
|
||||
Profile" as one of seven biometric channels. At HE20/HE80 the
|
||||
dense BFR subcarriers are the right input — exposing `BfldFrame`
|
||||
now lets researchers prototype the channel without waiting on a
|
||||
Rust ingestion crate.
|
||||
3. **Cross-vendor portability**. CSI ingestion needs patched
|
||||
firmware. BFR ingestion works on stock 802.11ac/ax hardware
|
||||
(capture via `tcpdump`/Wireshark + a BFR dissector). Shipping the
|
||||
Python data structures first gives the community a way to feed
|
||||
RuView from gear we don't directly support.
|
||||
|
||||
#### Implementation surface in P3
|
||||
|
||||
Lands as a new module `bindings/bfld.rs` (~150 lines, three
|
||||
`#[pyclass]` types):
|
||||
|
||||
- `BfldFrame` (frozen) — one compressed feedback matrix snapshot.
|
||||
Constructors: `from_compressed_feedback(...)` and
|
||||
`from_uncompressed_v(...)` (the 802.11n V-matrix form).
|
||||
Properties: `timestamp_ms`, `sounding_index`, `sta_mac`,
|
||||
`bandwidth_mhz`, `n_subcarriers`, `n_rows` (Nr), `n_cols` (Nc),
|
||||
`feedback_matrix` (numpy ndarray complex64).
|
||||
- `BfldReport` (frozen) — aggregator over a window of `BfldFrame`s.
|
||||
Properties: `n_frames`, `timestamp_first`, `timestamp_last`,
|
||||
`mean_amplitude_per_subcarrier`, `coherence_score`. The Python
|
||||
side gives users a stable handle for "all BFR data in this 60-s
|
||||
scan" without leaking the storage representation.
|
||||
- `BfldKind` (`#[pyclass(eq, eq_int, hash, frozen)]`) — enum
|
||||
enumerating the BFR variants we support: `CompressedHE20`,
|
||||
`CompressedHE40`, `CompressedHE80`, `CompressedHE160`,
|
||||
`UncompressedHT20`, `UncompressedHT40`.
|
||||
|
||||
Stub Rust implementation lives in `python/src/bfld_stub.rs` until
|
||||
the proper Rust crate exists; it's intentionally not in v2/crates/.
|
||||
A new ADR-1xx will own the Rust ingestion crate when we commit to it.
|
||||
|
||||
#### Open questions added
|
||||
|
||||
- §9.11 — Should BFLD ingestion live in a new `wifi-densepose-bfld`
|
||||
crate or in `wifi-densepose-signal` extended?
|
||||
- §9.12 — Per-vendor BFR variant compatibility (Broadcom vs Intel vs
|
||||
Qualcomm encode the compressed angles slightly differently) — how
|
||||
much normalisation belongs in the Python binding vs. the future
|
||||
Rust crate?
|
||||
|
||||
### 5.7 Witness chain (re-rooted to the Rust pipeline)
|
||||
|
||||
`wifi_densepose.witness.verify_bundle(path)` replaces the v1 proof verification with a
|
||||
new chain that exercises the Rust pipeline via PyO3:
|
||||
|
||||
```python
|
||||
from wifi_densepose.witness import verify_bundle
|
||||
|
||||
result = verify_bundle("dist/witness-bundle-ADR028-*/")
|
||||
assert result.verdict == "PASS", result.detail
|
||||
```
|
||||
|
||||
Internally it:
|
||||
1. Loads the 1,000-frame reference JSON from the bundle.
|
||||
2. Feeds each frame through `PyCsiProcessor` (PyO3 binding of the Rust `CsiProcessor`).
|
||||
3. Hashes the output using the same SHA-256 scheme as `archive/v1/data/proof/verify.py`.
|
||||
4. Compares against the published hash in `expected_features.sha256`.
|
||||
|
||||
The v1 proof (`archive/v1/data/proof/verify.py`) is **preserved unchanged** — it
|
||||
continues to prove the v1 pipeline. The new `witness.py` proves the v2/Rust pipeline.
|
||||
Both can coexist; the ADR-028 witness bundle ships with both.
|
||||
|
||||
---
|
||||
|
||||
## 6. Migration path (phased)
|
||||
|
||||
```
|
||||
P1 ──► P2 ──► P3 ──► P4 ──► P5 ──► P6+
|
||||
scaffold core vitals+ client publish deferred
|
||||
types signal layer v2.0.0
|
||||
```
|
||||
|
||||
### P1 — Scaffold (1 week)
|
||||
|
||||
- [ ] Add `v2/crates/wifi-densepose-py/` as workspace member.
|
||||
- [ ] `Cargo.toml`: `crate-type = ["cdylib"]`, pyo3 0.28 + `abi3-py310`, no
|
||||
workspace deps yet (empty module compiles and imports).
|
||||
- [ ] `pyproject.toml` at repo root `python/` with `[build-system] requires =
|
||||
["maturin>=1.8"]` and `[tool.maturin] features = ["pyo3/extension-module"]`.
|
||||
- [ ] CI job: `maturin develop` on ubuntu-latest in a Python 3.12 venv; import
|
||||
`wifi_densepose._core` succeeds.
|
||||
- [ ] Publish `wifi-densepose==1.99.0` to PyPI with a migration notice in the
|
||||
module body (see §9 — no new features, just the tombstone release).
|
||||
|
||||
### P2 — Core type bindings (1 week)
|
||||
|
||||
- [ ] Bind `CsiFrame`, `CsiMetadata`, `Confidence`, `Keypoint`, `KeypointType`,
|
||||
`BoundingBox`, `PoseEstimate`, `PersonPose` from `wifi-densepose-core`.
|
||||
- [ ] All types: `__repr__`, `__eq__`, `__hash__` where meaningful; serde JSON
|
||||
round-trip via `pyo3-serde` or manual `to_dict()` / `from_dict()`.
|
||||
- [ ] Add `py.typed` + stub `.pyi` file generated by `pyo3-stub-gen`.
|
||||
- [ ] Unit tests: `tests/test_core.py` — construct each type, round-trip JSON.
|
||||
|
||||
### P3 — Vitals + signal DSP bindings (2 weeks)
|
||||
|
||||
- [ ] Bind the full 4-stage vitals pipeline:
|
||||
`CsiVitalPreprocessor`, `BreathingExtractor`, `HeartRateExtractor`,
|
||||
`VitalAnomalyDetector`, `VitalSignStore`, `VitalReading`, `VitalEstimate`,
|
||||
`AnomalyAlert`.
|
||||
- [ ] Bind signal DSP entry points: `CsiProcessor`, `CsiProcessorConfig`,
|
||||
`PhaseSanitizer`, `MotionDetector`, `HardwareNormalizer`.
|
||||
- [ ] GIL release (`py.allow_threads`) on all calls >0.5 ms (measured in bench).
|
||||
- [ ] Integration test: feed 1,000 frames from `archive/v1/data/proof/sample_csi_data.json`
|
||||
through the PyO3 vitals pipeline; assert output is deterministic across runs.
|
||||
- [ ] Re-implement `witness/verify.py` using P3 bindings; compare SHA-256 against the
|
||||
v1 expected hash. **Note:** the hash will differ because the Rust and Python
|
||||
processors are not identical — generate and publish a new `expected_features_v2.sha256`.
|
||||
|
||||
### P4 — WS/MQTT client layer (1 week)
|
||||
|
||||
- [ ] Implement `wifi_densepose.client.ws.SensingClient` (asyncio, `websockets>=12`).
|
||||
- [ ] Implement `wifi_densepose.client.mqtt.RuViewMqttClient` (paho-mqtt 2.x).
|
||||
- [ ] Add `wifi_densepose.client.ha` helpers that parse ADR-115 MQTT discovery payloads
|
||||
into Python dataclasses.
|
||||
- [ ] Integration test: spin up `sensing-server` in Docker with `--mock-frames`;
|
||||
assert `SensingClient` receives `edge_vitals` messages.
|
||||
|
||||
### P5 — First cibuildwheel publish as v2.0.0 (1 week)
|
||||
|
||||
- [ ] `.github/workflows/pip-release.yml` — cibuildwheel matrix (5 wheels + sdist).
|
||||
- [ ] `python_requires = ">=3.10"` (stable ABI base).
|
||||
- [ ] Populate `pyproject.toml` with minimal `install_requires`: `pyo3` is a build dep,
|
||||
not a runtime dep. Runtime extras: `[client]` adds `websockets>=12,paho-mqtt>=2`.
|
||||
- [ ] `pip install wifi-densepose==2.0.0` and smoke-test on each CI platform.
|
||||
- [ ] PyPI publish via Trusted Publisher (OIDC, no API token in secrets).
|
||||
- [ ] Announce: `wifi-densepose==1.99.0` tombstone already on PyPI; `v2.0.0` replaces
|
||||
it in search results.
|
||||
|
||||
### P3.5 — BFLD binding surface (concurrent with P3)
|
||||
|
||||
**Added 2026-05-24 per maintainer feedback.** See §5.7a for the rationale.
|
||||
|
||||
- [ ] `python/src/bindings/bfld.rs` — `BfldFrame`, `BfldReport`,
|
||||
`BfldKind` `#[pyclass]` wrappers backed by a stub Rust impl
|
||||
pending the v3 `wifi-densepose-bfld` crate.
|
||||
- [ ] `python/src/bfld_stub.rs` — minimal in-crate stub storage
|
||||
(vec of compressed feedback matrices) so the Python API is
|
||||
fully usable today even before the Rust ingestion crate lands.
|
||||
- [ ] Numpy bridge for `feedback_matrix` (Complex64 ndarray) — same
|
||||
approach as `CsiFrame.amplitude` from P3.
|
||||
- [ ] Tests covering: per-bandwidth constructor paths
|
||||
(HE20/HE40/HE80/HE160 + HT20/HT40), n_subcarriers contract,
|
||||
coherence_score sanity, BfldKind hashability + equality.
|
||||
- [ ] Forward-compat contract test: `BfldFrame` constructed today
|
||||
from a numpy ndarray must round-trip through (de)serialisation
|
||||
identically once the Rust crate exists.
|
||||
- [ ] §9.11 + §9.12 open questions raised so the eventual Rust crate
|
||||
has clear decisions waiting for it.
|
||||
|
||||
P3.5 is concurrent with P3 (no new schedule cushion needed) because
|
||||
the Python surface is independent of the rest of the v2/ workspace.
|
||||
Land in the same wheel as P3.
|
||||
|
||||
### P6+ — Deferred
|
||||
|
||||
- [ ] `wifi-densepose-bfld` Rust crate — proper ingestion from
|
||||
Nexmon BFR pcaps + `mac80211` debugfs. Replaces the P3.5 stub
|
||||
storage without changing the Python API. Owns its own ADR-1xx.
|
||||
- [ ] `wifi-densepose-nn` bindings (libtorch / candle wheel size TBD — see Open
|
||||
Questions §13.3).
|
||||
- [ ] `wifi-densepose-ruvector` bindings (RuVector attention types).
|
||||
- [ ] MQTT/Matter integration helpers (`wifi_densepose.client.matter`).
|
||||
- [ ] Deprecation notice on `wifi-densepose==1.x` releases (PyPI yank — see §9).
|
||||
- [ ] `wifi-densepose-sensing-server` binary distribution via pip extra
|
||||
(`pip install wifi-densepose[server]` fetches pre-built binary for the platform).
|
||||
- [ ] HACS Python integration built on top of the pip client layer (follow-on to
|
||||
ADR-115 §6.A).
|
||||
|
||||
---
|
||||
|
||||
## 7. Compatibility and deprecation
|
||||
|
||||
### 7.1 Version bump strategy
|
||||
|
||||
`wifi-densepose==2.0.0` is a **hard major-version break**. The 1.x import namespace
|
||||
`src.*` is incompatible with the 2.x namespace `wifi_densepose.*`. There is no shim
|
||||
that can bridge them transparently.
|
||||
|
||||
### 7.2 Tombstone release: v1.99.0
|
||||
|
||||
Before publishing v2.0.0, publish `wifi-densepose==1.99.0` as a pure-Python sdist/wheel
|
||||
whose sole content is:
|
||||
|
||||
```python
|
||||
# wifi_densepose/__init__.py (v1.99.0)
|
||||
raise ImportError(
|
||||
"wifi-densepose 1.x has been superseded by v2.0.0 which wraps "
|
||||
"the Rust-based stack. Run:\n\n"
|
||||
" pip install wifi-densepose==2.0.0\n\n"
|
||||
"Migration guide: https://github.com/ruvnet/RuView/blob/main/docs/pip-migration.md\n"
|
||||
"Legacy v1 source: archive/v1/ in the repository"
|
||||
)
|
||||
```
|
||||
|
||||
This ensures any project pinned to `wifi-densepose>=1` that upgrades to 1.99.0 gets a
|
||||
clear error rather than a silent broken import.
|
||||
|
||||
### 7.3 PyPI yank strategy
|
||||
|
||||
After v2.0.0 is stable (90-day observation window):
|
||||
|
||||
- Yank `wifi-densepose==1.0.0` — never had a separate stable release period; was
|
||||
superseded 4 hours after publication.
|
||||
- Leave `wifi-densepose==1.1.0` un-yanked but deprecated in the description.
|
||||
- Publish `wifi-densepose==1.99.0` as the canonical 1.x landing page (raise error).
|
||||
|
||||
Yanked versions remain installable with `pip install wifi-densepose==1.1.0 --force`
|
||||
so users with reproducible builds pinned to exact versions are not broken silently.
|
||||
|
||||
### 7.4 Semver
|
||||
|
||||
| Version | Content |
|
||||
|---|---|
|
||||
| 1.0.0 – 1.1.0 | Legacy Python server (archive/v1/) |
|
||||
| **1.99.0** | Tombstone: ImportError migration notice |
|
||||
| **2.0.0** | PyO3 Rust bindings + WS/MQTT client |
|
||||
| 2.x.y | Additive bindings + client improvements |
|
||||
| 3.0.0 | If/when nn bindings added (libtorch wheel size may force a separate package) |
|
||||
|
||||
---
|
||||
|
||||
## 8. Alternatives considered and rejected
|
||||
|
||||
### Alt-A: Subprocess wrapper
|
||||
|
||||
Package the pre-built `wifi-densepose-sensing-server` Rust binary inside the pip wheel.
|
||||
Python calls it via `subprocess`. **Rejected** because: the binary is 15–30 MB stripped;
|
||||
the install footprint is prohibitive; offline DSP scripting still requires the server to
|
||||
be running; the witness chain cannot exercise Rust code through a black-box binary.
|
||||
|
||||
### Alt-B: REST/WS client only
|
||||
|
||||
Ship a pure-Python package that is purely a client to a running `sensing-server`
|
||||
instance. **Rejected** because: it provides zero offline utility; it cannot host the
|
||||
witness chain over the Rust pipeline; it solves the "Python access to telemetry" problem
|
||||
but not the "Python DSP / prototyping" problem that academic and embedded users need.
|
||||
|
||||
### Alt-C: Pure Python reimplementation
|
||||
|
||||
Rewrite the DSP pipeline in pure Python/NumPy to reach parity with the Rust
|
||||
implementation. **Rejected explicitly** — this is the root cause of the current 11-month
|
||||
drift and the pattern this ADR is designed to exit. Any Python reimplementation will
|
||||
immediately begin drifting again as the Rust stack evolves.
|
||||
|
||||
---
|
||||
|
||||
## 9. Risks
|
||||
|
||||
| Risk | Likelihood | Severity | Mitigation |
|
||||
|---|---|---|---|
|
||||
| **Build matrix complexity** — 5 target triples × cibuildwheel setup; CI time; QEMU for aarch64 cross-compile | High | Medium | Use `abi3-py310` (5 wheels not 20); QEMU aarch64 emulation available in GitHub Actions; maturin handles auditwheel automatically |
|
||||
| **Binary size** — future nn/ONNX bindings may push wheel past 50 MB | Medium | High | Keep nn bindings in a separate `wifi-densepose-nn` PyPI package; keep core+vitals+signal wheel lean (~2 MB stripped) |
|
||||
| **GIL / async issues** — PyO3 wrapping tokio crates requires careful runtime management; `py.allow_threads` must be used around all blocking Rust calls | High | High | Restrict initial bindings to synchronous Rust APIs (vitals, signal, core are all sync); async sensing-server client stays in pure-Python `client/ws.py` |
|
||||
| **Maintainer overhead** — two languages, two build systems, one PyPI package | Medium | Medium | maturin unifies the build; CI handles publishing; start with 3 bound crates only |
|
||||
| **1.x user breakage** — users pinned to `wifi-densepose>=1,<2` will get the tombstone | Low | Medium | 1.99.0 tombstone gives a clear error; maintain 1.1.0 on PyPI un-yanked for 90 days post-v2 |
|
||||
| **Windows Rust toolchain in CI** — linking PyO3 on Windows requires MSVC or mingw; extra CI complexity | Medium | Medium | GitHub Actions `windows-latest` has MSVC; maturin + cibuildwheel handle this natively |
|
||||
| **Stable ABI limitations** — `abi3` precludes some advanced PyO3 features (e.g. `Buffer` protocol) | Low | Low | Core/vitals/signal types are scalar/Vec<f32> — no need for buffer protocol in P2–P3 |
|
||||
| **PyPI name ownership** — we own `wifi-densepose` on PyPI (confirmed via rUv author field) | Low | Low | Confirm with `pypi.org/user/ruvnet` before publishing |
|
||||
|
||||
---
|
||||
|
||||
## 10. Acceptance criteria
|
||||
|
||||
The following checks must all pass before ADR-117 is considered Accepted:
|
||||
|
||||
- [ ] `pip install wifi-densepose==2.0.0` succeeds on Python 3.10, 3.11, 3.12, 3.13
|
||||
on linux/x86_64, macos/arm64, and windows/amd64 in a clean venv with no extra build tools.
|
||||
- [ ] `python -c "import wifi_densepose; print(wifi_densepose.__version__)"` prints `2.0.0`.
|
||||
- [ ] `python -c "from wifi_densepose import CsiFrame; f = CsiFrame([1.0]*56, [0.0]*56, 56, 0, 100.0); print(f)"` produces a non-error repr.
|
||||
- [ ] The 4-stage vitals pipeline processes 1,000 frames in under 500 ms on a
|
||||
reference machine (CPython 3.12, linux x86_64, no GPU).
|
||||
- [ ] `wifi_densepose.witness.verify_bundle(path)` returns `verdict="PASS"` for a
|
||||
freshly generated witness bundle from `scripts/generate-witness-bundle.sh`.
|
||||
- [ ] `wifi_densepose.client.ws.SensingClient` receives at least one `edge_vitals`
|
||||
message from a `sensing-server --mock-frames` instance within 5 seconds.
|
||||
- [ ] `pip install wifi-densepose==1.99.0` raises `ImportError` with the migration URL.
|
||||
- [ ] The compiled `_core` extension has no unresolved dynamic library dependencies
|
||||
beyond libc/msvcrt (verified by `auditwheel show` on Linux, `delocate-listdeps` on macOS).
|
||||
- [ ] Type stubs (`wifi_densepose/*.pyi`) are present; `mypy --strict` passes on the
|
||||
example code in `examples/vitals_from_buffer.py`.
|
||||
- [ ] Total wheel size for core+vitals+signal: `≤ 5 MB` per platform.
|
||||
|
||||
---
|
||||
|
||||
## 11. Open questions
|
||||
|
||||
1. **Stable ABI base version**: `abi3-py310` drops support for Python 3.9, which v1.1.0
|
||||
declared. Is Python 3.9 EOL-enough (EOL 2025-10-05) to drop cleanly? *Tentative: yes,
|
||||
drop 3.9. Use abi3-py310.*
|
||||
|
||||
2. **Package name for nn bindings**: if `wifi-densepose-nn` bindings require a 30 MB
|
||||
libtorch wheel, should they live at `wifi-densepose-nn` (separate PyPI package) or
|
||||
as an optional heavy extra of `wifi-densepose[nn]`? *Tentative: separate package to
|
||||
avoid polluting the lean wheel.*
|
||||
|
||||
3. **Witness hash continuity**: the Rust pipeline will produce a different SHA-256 than
|
||||
the v1 Python pipeline for the same input frames. The new `expected_features_v2.sha256`
|
||||
must be generated and committed before v2.0.0 ships. Who generates it, and how is
|
||||
the generation process itself witnessed? *Tentative: generate in CI, commit hash to
|
||||
`archive/v1/data/proof/`, include in ADR-028 matrix.*
|
||||
|
||||
4. **`ruv-neural` crate**: `v2/crates/ruv-neural/` exists in the workspace. Is it a
|
||||
candidate for early Python bindings (useful for training-loop scripting), or should
|
||||
it wait for the nn/train tier? *Tentative: defer — it depends on training backends.*
|
||||
|
||||
5. **Tokio runtime**: `wifi-densepose-sensing-server` is tokio-based, but the three
|
||||
crates bound in P2–P3 (`core`, `vitals`, `signal`) are synchronous. Are there any
|
||||
hidden tokio dependencies that would force a runtime into the extension module?
|
||||
*Tentative: inspect each crate's Cargo.toml for tokio deps before P1 scaffold.*
|
||||
|
||||
6. **`pyo3-stub-gen` vs manual stubs**: automated stub generation from PyO3 has rough
|
||||
edges for generics and newtype patterns. Should we hand-write `.pyi` stubs for the
|
||||
first release? *Tentative: use `pyo3-stub-gen` for scaffolding, hand-tune for public
|
||||
API.*
|
||||
|
||||
7. **`wifi_densepose` vs `wifi-densepose` namespace**: the pip package name uses a dash
|
||||
(`wifi-densepose`) but Python imports use underscores (`wifi_densepose`). The v1
|
||||
package shipped under `src.*`, not `wifi_densepose.*`. Is there any tooling that
|
||||
hardcodes the `src` namespace? *Tentative: the `src.*` namespace was specific to
|
||||
`archive/v1/` and is cleanly dropped.*
|
||||
|
||||
8. **cibuildwheel version**: the current stable is cibuildwheel v2.x. Does the
|
||||
project's existing GitHub Actions config need updates for maturin builds vs
|
||||
the current `cargo build` / `build.py` patterns? *Tentative: yes, add a separate
|
||||
`pip-release.yml` workflow; do not modify existing Rust CI.*
|
||||
|
||||
9. **RuVector bindings timeline**: the `wifi-densepose-ruvector` crate (`v2/crates/`)
|
||||
depends on `ruvector-gnn = "2.0.5"`. Does ruvector-gnn ship as a pre-built static
|
||||
lib or require linking at build time? This directly affects the P6+ wheel size.
|
||||
*Tentative: investigate ruvector-gnn link strategy before committing to a timeline.*
|
||||
|
||||
10. **`wifi_densepose.client.ha` conflict with ADR-115/116**: the `ha.py` helper module
|
||||
should not duplicate the ADR-115 MQTT discovery logic in Python. Should it be read-only
|
||||
(parse HA discovery JSON → Python dataclasses) or also write (publish discovery JSON)?
|
||||
*Tentative: read-only for v2.0. Write path deferred to the HACS integration follow-on
|
||||
(ADR-115 §6.A).*
|
||||
|
||||
11. **BFLD Rust crate ownership** (added 2026-05-24): the P3.5 BFLD bindings ship with a
|
||||
stub Rust impl in `python/src/bfld_stub.rs`. The proper Rust crate (Nexmon BFR pcap
|
||||
parser + `mac80211` debugfs ingestor) will land later. Should it be a new
|
||||
`wifi-densepose-bfld` workspace member, or should it extend `wifi-densepose-signal`?
|
||||
*Tentative: new dedicated crate. Reasons: (a) the BFR parser is significant code
|
||||
(Wireshark's dissector is ~2k lines) and bloats `-signal`; (b) BFLD ingestion is
|
||||
optional — many deployments will only use CSI; gating behind a separate crate keeps
|
||||
the default `-signal` lean. Decide before committing to the crate name in any
|
||||
`pyproject.toml` extras.*
|
||||
|
||||
12. **BFLD per-vendor compressed-angle variants** (added 2026-05-24): 802.11 standardizes
|
||||
the compressed beamforming feedback format but vendors (Broadcom, Intel, Qualcomm,
|
||||
MediaTek) differ in psi/phi quantization step + ordering of consecutive matrix
|
||||
entries. How much normalisation belongs in the Python `BfldFrame.from_compressed_feedback`
|
||||
binding vs. the future Rust crate? *Tentative: Python binding is dumb (numpy ndarray
|
||||
in, numpy ndarray out — no decoding); the future Rust crate owns per-vendor
|
||||
normalisation, exposed via a `Vendor` enum on the binding constructor. Confirm via
|
||||
a per-vendor test fixture before P3.5 ships.*
|
||||
|
||||
---
|
||||
|
||||
## 12. References
|
||||
|
||||
### BFLD references (added 2026-05-24 for §5.7a + §11.11 + §11.12)
|
||||
|
||||
- Hernandez & Bulut, *"Wi-Fi Sensing With Compressed Beamforming Feedback"*, ACM TOSN 2024 — first systematic survey of BFR-as-sensing
|
||||
- Yousefi, Soltanaghaei & Bharadia, *"Just-In-Time Wi-Fi Sensing Using Compressed Beamforming Feedback"*, MobiSys 2023 — practical pipeline for breath + heart-rate extraction from sniffed BFR
|
||||
- IEEE 802.11ax-2021 §27.3.10 — Compressed Beamforming Feedback frame format
|
||||
- Wireshark BFR dissector — `packet-ieee80211.c` reference implementation
|
||||
- AX210 Linux mac80211 debugfs BFR capture path (kernel 6.10+)
|
||||
- Sample BFR-vs-CSI parity dataset — TBD; we'll publish one alongside the
|
||||
`wifi-densepose-bfld` crate when it lands
|
||||
|
||||
### Original references
|
||||
|
||||
- **PyPI package (current)**: https://pypi.org/project/wifi-densepose/ — v1.1.0, released 2025-06-07
|
||||
- **PyPI JSON metadata**: https://pypi.org/pypi/wifi-densepose/json
|
||||
- **Local source**: `archive/v1/setup.py`, `archive/v1/src/__init__.py`, `archive/v1/data/proof/verify.py`
|
||||
- **Rust workspace**: `v2/Cargo.toml`, `v2/crates/wifi-densepose-core/src/lib.rs`,
|
||||
`v2/crates/wifi-densepose-vitals/src/lib.rs`, `v2/crates/wifi-densepose-signal/src/lib.rs`,
|
||||
`v2/crates/wifi-densepose-sensing-server/src/lib.rs`
|
||||
- **PyO3 docs**: https://pyo3.rs/ — v0.28.3 stable, Rust ≥1.83 required
|
||||
- **maturin docs**: https://maturin.rs/ — supports Python 3.8+ on Linux/macOS/Windows/FreeBSD
|
||||
- **cibuildwheel docs**: https://cibuildwheel.pypa.io/
|
||||
- **ADR-021**: ESP32 vitals — defines the HR/BR extraction pipeline this ADR exposes in Python
|
||||
- **ADR-028**: ESP32 capability audit — defines the witness bundle format `witness/verify.py` must re-verify
|
||||
- **ADR-115**: HA-DISCO + HA-MIND + HA-FABRIC — defines the MQTT topic structure the `client/mqtt.py` helper consumes
|
||||
- **ADR-116**: HA-COG cog packaging — parallel effort; ADR-117 pip library is the developer-facing Python surface; ADR-116 is the Seed-installable artifact
|
||||
@@ -1,196 +0,0 @@
|
||||
# ADR-118: BFLD — Beamforming Feedback Layer for Detection
|
||||
|
||||
| Field | Value |
|
||||
|-------|-------|
|
||||
| **Status** | Proposed |
|
||||
| **Date** | 2026-05-24 |
|
||||
| **Deciders** | ruv |
|
||||
| **Codename** | **BFLD** — Beamforming Feedback Layer for Detection |
|
||||
| **Relates to** | [ADR-024](ADR-024-contrastive-csi-embedding-model.md) (AETHER), [ADR-027](ADR-027-cross-environment-domain-generalization.md) (MERIDIAN), [ADR-028](ADR-028-esp32-capability-audit.md) (witness), [ADR-029](ADR-029-ruvsense-multistatic-sensing-mode.md) (multistatic), [ADR-030](ADR-030-ruvsense-persistent-field-model.md) (field model), [ADR-031](ADR-031-ruview-sensing-first-rf-mode.md) (sensing-first), [ADR-032](ADR-032-multistatic-mesh-security-hardening.md) (mesh security), [ADR-095](ADR-095-rvcsi-edge-rf-sensing-platform.md) (rvCSI), [ADR-115](ADR-115-home-assistant-integration.md) (HA), [ADR-116](ADR-116-cog-ha-matter-seed.md) (Matter), [ADR-117](ADR-117-pip-wifi-densepose-modernization.md) (pip) |
|
||||
| **Sub-ADRs** | [ADR-119](ADR-119-bfld-frame-format-and-wire-protocol.md) (frame), [ADR-120](ADR-120-bfld-privacy-class-and-hash-rotation.md) (privacy), [ADR-121](ADR-121-bfld-identity-risk-scoring.md) (risk), [ADR-122](ADR-122-bfld-ruview-ha-matter-exposure.md) (RuView), [ADR-123](ADR-123-bfld-capture-path-nexmon-and-esp32.md) (capture) |
|
||||
| **Research bundle** | [`docs/research/BFLD/`](../research/BFLD/) (11 files, 13,544 words) |
|
||||
| **Companion research** | [`docs/research/soul/`](../research/soul/) — Soul Signature multi-modal biometric. BFLD is the policy-enforcement and compliance layer for Soul Signature; the two share the AETHER encoder (ADR-024), the witness chain (ADR-110/028), the RVF container, and `cross_room.rs` (ADR-030). |
|
||||
| **Tracking issue** | TBD |
|
||||
|
||||
---
|
||||
|
||||
## 1. Context
|
||||
|
||||
### 1.1 The plaintext BFI problem
|
||||
|
||||
IEEE 802.11ac and 802.11ax beamforming feedback (BFI) is exchanged between client stations (STA) and access points (AP) in **unencrypted management-plane frames**. The STA compresses the channel response into a Givens-rotation angle matrix (Φ/ψ) and transmits it as a VHT/HE Compressed Beamforming Report (CBFR). Any device in WiFi monitor mode within range can passively sniff these frames without joining the network.
|
||||
|
||||
Two independent 2024–2025 research results establish the severity of this exposure:
|
||||
|
||||
1. **BFId** (KIT, ACM CCS 2025) — re-identifies 197 individuals from BFI alone with >90% accuracy from 5 s of capture. https://publikationen.bibliothek.kit.edu/1000185756
|
||||
2. **LeakyBeam** (NDSS 2025) — detects occupancy through walls at 20 m with 82.7% TPR / 96.7% TNR using only plaintext BFI. https://www.ndss-symposium.org/wp-content/uploads/2025-5-paper.pdf
|
||||
|
||||
Capture tooling is freely available: **Wi-BFI** (pip-installable), **PicoScenes**, **Nexmon BFI patches** for BCM43455c0 (Raspberry Pi 5 / 4 / 3B+).
|
||||
|
||||
### 1.2 Gap in the existing RuView pipeline
|
||||
|
||||
The wifi-densepose / RuView pipeline processes CSI via the rvCSI runtime (ADR-095/096) and emits presence, pose, vitals, and zone-activity events. **No layer in the existing pipeline measures whether the data it is processing is capable of identifying individuals.** All CSI is treated as equivalent from a privacy standpoint regardless of operating regime.
|
||||
|
||||
This gap becomes a compliance and liability issue at deployment scale. An operator placing RuView in a care home, hotel, shared office, or rental property has no instrument to verify that the system is operating anonymously.
|
||||
|
||||
### 1.3 BFI as a sensing signal
|
||||
|
||||
BFI is not only a threat vector — its compressed angle matrices carry multipath geometry useful for presence and motion detection, particularly in single-AP deployments where MIMO CSI is unavailable. BFLD treats BFI as an **optional input alongside CSI**, not a replacement.
|
||||
|
||||
### 1.4 Relationship to the Soul Signature research
|
||||
|
||||
The Soul Signature research (`docs/research/soul/`) defines a 7-channel multi-modal biometric for **consent-based** passive re-identification of enrolled individuals. Where Soul Signature *intentionally produces* identity (with a 60-second enrollment protocol), BFLD *measures and gates* identity leakage from the same sensing substrate. The two systems are complementary by design:
|
||||
|
||||
| Concern | Soul Signature | BFLD |
|
||||
|---------|----------------|------|
|
||||
| Intent | Create a biometric for enrolled persons | Measure and gate identity leakage |
|
||||
| Consent model | Explicit enrollment, GDPR/HIPAA modes | Default-deny, all unenrolled persons |
|
||||
| Operating class | Must run at `privacy_class = 1` (derived) | Defaults to class 2 (anonymous) |
|
||||
| Shared assets | AETHER encoder (ADR-024), WitnessChain (ADR-110/028), RVF container, `cross_room.rs` (ADR-030) | Same |
|
||||
| ID space | Long-lived opaque `person_id` per enrolled subject | Rotating `rf_signature_hash` per day per unenrolled person |
|
||||
|
||||
BFLD becomes Soul Signature's enforcement layer: the `identity_risk_score` gates whether a zone is leaky enough to enroll, the witness bundle is the regulator-facing audit artifact, and the structural privacy invariants (I1/I2/I3) ensure unenrolled bystanders stay anonymous even in zones where Soul Signature is actively matching enrolled persons. See ADR-120 §2.7 and ADR-121 §2.7 for the integration points.
|
||||
|
||||
### 1.5 What this ADR is *not*
|
||||
|
||||
- Not a removal of the CSI pipeline. ADR-095/096 rvCSI stays authoritative for CSI.
|
||||
- Not a port of any external sniffer into the repo. The Nexmon capture path lives in a separate adapter (see ADR-123).
|
||||
- Not a Matter SDK ship — Matter exposure is filtered through the ADR-116 `cog-ha-matter` boundary.
|
||||
|
||||
---
|
||||
|
||||
## 2. Decision
|
||||
|
||||
Create a new Rust crate **`wifi-densepose-bfld`** in `v2/crates/` that:
|
||||
|
||||
1. **Ingests** BFI angle matrices (Φ/ψ) from CBFR frames, optionally fused with CSI.
|
||||
2. **Computes** nine named features and an `identity_risk_score` (separability × temporal_stability × cross_perspective_consistency × sample_confidence).
|
||||
3. **Gates** all output through a `privacy_class` byte that **structurally prevents** identity-correlated data from being published at classes 2 (anonymous) and 3 (restricted).
|
||||
4. **Emits** `BfldEvent` JSON over MQTT under `ruview/<node_id>/bfld/*` with per-class topic routing.
|
||||
5. **Enforces three invariants structurally, not by policy**:
|
||||
- **I1**: Raw BFI never exits the node.
|
||||
- **I2**: Identity embedding is in-RAM-only (no disk, no network).
|
||||
- **I3**: Cross-site identity correlation is cryptographically impossible via per-site keyed BLAKE3 hash rotation with a daily epoch.
|
||||
|
||||
The umbrella implementation is decomposed into five sub-ADRs:
|
||||
|
||||
| Sub-ADR | Scope |
|
||||
|---------|-------|
|
||||
| **ADR-119** | `BfldFrame` wire format, magic `0xBF1D_0001`, deterministic serialization, CRC32 |
|
||||
| **ADR-120** | `privacy_class` semantics, BLAKE3 hash rotation, default-deny field classification |
|
||||
| **ADR-121** | Identity risk scoring formula, coherence gate, leakage estimator |
|
||||
| **ADR-122** | RuView surface: HA entities, Matter cluster boundary, MQTT topic ACL |
|
||||
| **ADR-123** | Capture path: Pi 5 / Nexmon adapter + ESP32-S3 BFI feasibility |
|
||||
|
||||
### 2.1 Crate module layout
|
||||
|
||||
```
|
||||
v2/crates/wifi-densepose-bfld/
|
||||
├── Cargo.toml
|
||||
└── src/
|
||||
├── lib.rs
|
||||
├── frame.rs # BfldFrame (ADR-119)
|
||||
├── extractor.rs # CBFR parser → BfiCapture
|
||||
├── features.rs # 9 features
|
||||
├── identity_risk.rs # risk score (ADR-121)
|
||||
├── privacy_gate.rs # privacy_class enforcement (ADR-120)
|
||||
├── hash_rotation.rs # BLAKE3 per-site rotation (ADR-120)
|
||||
├── emitter.rs # BfldEvent → MQTT
|
||||
├── mqtt.rs # topic routing (ADR-122)
|
||||
└── ffi.rs # PyO3 bindings (ADR-117 pattern)
|
||||
```
|
||||
|
||||
### 2.2 Reuse map
|
||||
|
||||
| BFLD module | Depends on |
|
||||
|---|---|
|
||||
| `features.rs` | `wifi-densepose-signal/src/ruvsense/coherence.rs`, `multistatic.rs` |
|
||||
| `identity_risk.rs` | `wifi-densepose-ruvector/src/viewpoint/attention.rs`, `coherence.rs` |
|
||||
| `privacy_gate.rs` | (new) — no upstream dependency |
|
||||
| `hash_rotation.rs` | `blake3 = "1.5"` (keyed mode) |
|
||||
| `extractor.rs` | `vendor/rvcsi/crates/rvcsi-adapter-nexmon` (ADR-095/096) |
|
||||
|
||||
---
|
||||
|
||||
## 3. Consequences
|
||||
|
||||
### Positive
|
||||
|
||||
- First explicit, auditable RF-layer privacy primitive in the wifi-densepose ecosystem.
|
||||
- `identity_risk_score` doubles as an anomaly signal (sudden spike → new AP firmware / nearby attacker-grade sniffer / unusual propagation).
|
||||
- BFI fusion augments presence/motion in single-AP deployments.
|
||||
- Deterministic frame hashes extend the ADR-028 witness-bundle pattern to the new surface.
|
||||
- Cross-site isolation is **structural, not policy-dependent** — a stronger guarantee than ACLs.
|
||||
|
||||
### Negative
|
||||
|
||||
- ESP32-S3 cannot directly capture CBFR via the Espressif WiFi API. Full BFLD pipeline requires a Pi 5 / Nexmon host sniffer (cognitum-v0 available; see ADR-123).
|
||||
- `identity_risk_score` calibration requires the KIT BFId dataset (non-commercial research agreement).
|
||||
- Estimated effort: ~10.5 engineer-weeks across the six ADRs.
|
||||
|
||||
### Neutral
|
||||
|
||||
- BFLD does not prevent passive BFI capture by an external attacker (LeakyBeam-class). It only ensures the **node's own output** is non-identifying. Operators must understand this distinction.
|
||||
- Daily hash rotation prevents multi-day analytics correlating individual signatures across the day boundary. Acceptable for privacy goals; may surprise analytics use-cases.
|
||||
|
||||
---
|
||||
|
||||
## 4. Alternatives Considered
|
||||
|
||||
### Alt 1: Skip BFI entirely (CSI-only)
|
||||
|
||||
Rejected because: (a) leaves the identity-leakage gap open for the CSI pipeline; (b) as BFI tooling becomes ubiquitous (Wi-BFI, PicoScenes), the absence of a privacy layer becomes more conspicuous for operators.
|
||||
|
||||
### Alt 2: Publish `identity_risk_score` publicly by default
|
||||
|
||||
Rejected: the risk score itself is privacy-sensitive (reveals presence via timing correlation). Default is opt-in.
|
||||
|
||||
### Alt 3: Cloud ML on raw BFI
|
||||
|
||||
Rejected: violates I1. Cloud training creates an off-node store of angle matrices reconstructible into identity profiles.
|
||||
|
||||
### Alt 4: Differential privacy noise on BFI at ingress
|
||||
|
||||
Deferred to a follow-up ADR. DP sensitivity analysis and its interaction with `identity_risk_score` calibration are not yet complete. Current design achieves privacy through structural impossibility, not noise injection.
|
||||
|
||||
---
|
||||
|
||||
## 5. Acceptance Criteria
|
||||
|
||||
- [ ] **AC1**: Extractor parses BFI from 802.11ac and 802.11ax captures, 20/40/80/160 MHz, 2×2 through 4×4 MIMO.
|
||||
- [ ] **AC2**: Presence detection latency ≤ 1 s p95 from first non-empty BFI frame.
|
||||
- [ ] **AC3**: Motion score published at ≥ 1 Hz on `ruview/<node_id>/bfld/motion/state`.
|
||||
- [ ] **AC4**: Raw BFI bytes never present in any serialized `BfldFrame` payload at any `privacy_class` value.
|
||||
- [ ] **AC5**: With `privacy_mode` enabled, all identity-derived fields are absent from outbound events.
|
||||
- [ ] **AC6**: Identical `BfiCapture` inputs produce bit-identical `BfldFrame` serialization (deterministic hash).
|
||||
- [ ] **AC7**: Pipeline produces valid `BfldEvent` outputs without `csi_matrix` (BFI-only mode).
|
||||
|
||||
Per-sub-ADR acceptance criteria are defined in ADR-119 through ADR-123.
|
||||
|
||||
---
|
||||
|
||||
## 6. Phased Rollout
|
||||
|
||||
| Phase | ADR | Scope | Effort |
|
||||
|-------|-----|-------|--------|
|
||||
| **P1** | 119 | Frame format + extractor stub | 1.5 wk |
|
||||
| **P2** | 121 | Features + identity_risk_score | 2.0 wk |
|
||||
| **P3** | 120 | Privacy gate + hash rotation | 1.5 wk |
|
||||
| **P4** | 122 (a) | MQTT emitter + HA discovery | 1.5 wk |
|
||||
| **P5** | 122 (b) | Matter cluster boundary in `cog-ha-matter` | 1.5 wk |
|
||||
| **P6** | 123 | Pi 5 / Nexmon capture adapter | 2.5 wk |
|
||||
| **Total** | | | **10.5 wk** |
|
||||
|
||||
---
|
||||
|
||||
## 7. Related ADRs
|
||||
|
||||
See header table. Cross-references in body cite the structural reuse of:
|
||||
- ADR-024 (AETHER embedding for identity_risk computation)
|
||||
- ADR-027 (MERIDIAN's no-cross-site assumption is now structurally enforced by I3)
|
||||
- ADR-028 (witness-bundle extends to BFLD surface)
|
||||
- ADR-029/030 (`multistatic.rs`, `cross_room.rs` reused)
|
||||
- ADR-095/096 (rvCSI Nexmon adapter for BFI capture)
|
||||
- ADR-115 (HA surface extension)
|
||||
- ADR-116 (`cog-ha-matter` boundary filter)
|
||||
- ADR-117 (PyO3 bindings pattern)
|
||||
@@ -1,163 +0,0 @@
|
||||
# ADR-119: BFLD Frame Format and Wire Protocol
|
||||
|
||||
| Field | Value |
|
||||
|-------|-------|
|
||||
| **Status** | Proposed |
|
||||
| **Date** | 2026-05-24 |
|
||||
| **Deciders** | ruv |
|
||||
| **Parent** | [ADR-118](ADR-118-bfld-beamforming-feedback-layer-for-detection.md) |
|
||||
| **Relates to** | [ADR-028](ADR-028-esp32-capability-audit.md) (witness/deterministic proof), [ADR-095](ADR-095-rvcsi-edge-rf-sensing-platform.md) (rvCSI `CsiFrame` schema) |
|
||||
| **Tracking issue** | TBD |
|
||||
|
||||
---
|
||||
|
||||
## 1. Context
|
||||
|
||||
The BFLD pipeline (ADR-118) emits an over-the-wire `BfldFrame` consumed by the RuView aggregator, HA bridge, and witness bundle. The frame must be:
|
||||
|
||||
1. **Deterministic** — identical input ⇒ bit-identical output, so witness hashes survive verification (ADR-028 pattern).
|
||||
2. **Self-describing** — magic + version so future BFLD revisions don't silently corrupt aggregator state.
|
||||
3. **Privacy-classified at the byte level** — the receiver must know the data class before it even parses the payload, so it can drop frames it isn't authorized to handle.
|
||||
4. **Compact** — BFLD nodes may emit at up to 10 Hz; the frame must be small enough for unsharded MQTT and ESP-NOW transport.
|
||||
5. **Endianness-stable** — captures from x86_64 (ruvultra), aarch64 (cognitum-v0, Pi 5 cluster), and Xtensa (ESP32-S3) must produce identical bytes.
|
||||
|
||||
The existing rvCSI `CsiFrame` (ADR-095) is the closest precedent. BFLD reuses the same little-endian convention and the same "validate-before-FFI" posture.
|
||||
|
||||
---
|
||||
|
||||
## 2. Decision
|
||||
|
||||
### 2.1 `BfldFrame` header (40 bytes, little-endian, packed)
|
||||
|
||||
```rust
|
||||
#[repr(C, packed)]
|
||||
pub struct BfldFrameHeader {
|
||||
pub magic: u32, // 0xBF1D_0001
|
||||
pub version: u16, // 1
|
||||
pub flags: u16, // bit0=has_csi_delta, bit1=privacy_mode, bit2-15 reserved
|
||||
pub timestamp_ns: u64, // monotonic capture clock
|
||||
|
||||
pub ap_hash: [u8; 16], // BLAKE3-keyed(site_salt, ap_mac)[0..16]
|
||||
pub sta_hash: [u8; 16], // BLAKE3-keyed(site_salt ‖ day_epoch, sta_mac)[0..16]
|
||||
pub session_id: [u8; 16], // ephemeral, rotated on capture-session boundary
|
||||
|
||||
pub channel: u16, // 802.11 channel number
|
||||
pub bandwidth_mhz: u16, // 20 | 40 | 80 | 160
|
||||
pub rssi_dbm: i16,
|
||||
pub noise_floor_dbm: i16,
|
||||
|
||||
pub n_subcarriers: u16,
|
||||
pub n_tx: u8,
|
||||
pub n_rx: u8,
|
||||
pub quantization: u8, // 0=f32, 1=i16, 2=i8, 3=packed (4-bit nibbles)
|
||||
pub privacy_class: u8, // 0=raw, 1=derived, 2=anonymous, 3=restricted (default 2)
|
||||
|
||||
pub payload_len: u32,
|
||||
pub payload_crc32: u32, // CRC-32/ISO-HDLC over payload bytes only
|
||||
}
|
||||
```
|
||||
|
||||
Total header size: **86 bytes packed** (validated by `static_assertions::const_assert_eq!` in `wifi-densepose-bfld/src/frame.rs`). Earlier drafts stated 40 bytes — that was a counting error caught during P1 scaffold; see AC1 below.
|
||||
|
||||
### 2.2 Payload structure
|
||||
|
||||
Payload is a length-prefixed sequence of typed sections in this exact order:
|
||||
|
||||
```
|
||||
payload = compressed_angle_matrix
|
||||
‖ amplitude_proxy
|
||||
‖ phase_proxy
|
||||
‖ snr_vector
|
||||
‖ optional_csi_delta (present iff flags.bit0 set)
|
||||
‖ optional_vendor_extension (length 0 allowed)
|
||||
```
|
||||
|
||||
Each section is `[u32 len_le][bytes...]`. The CRC32 covers all section bytes including length prefixes, but **not** the header.
|
||||
|
||||
### 2.3 Privacy-class gating at serialization
|
||||
|
||||
The serializer enforces these rules **before** writing any payload bytes:
|
||||
|
||||
| `privacy_class` | `compressed_angle_matrix` | Identity-derived fields | Notes |
|
||||
|-----------------|---------------------------|-------------------------|-------|
|
||||
| 0 (`raw`) | full | full | **Local-only**, never serialized to a network sink |
|
||||
| 1 (`derived`) | downsampled to 8-bit, top-k subcarriers | full | Operator-acknowledged research mode |
|
||||
| 2 (`anonymous`, **default**) | absent (zero-length section) | absent | Production default |
|
||||
| 3 (`restricted`) | absent | absent + diagnostic-only | Equivalent to class 2 + suppresses `identity_risk_score` on the bus |
|
||||
|
||||
The serializer returns `Err(BfldError::PrivacyViolation)` if the caller attempts to publish a class-0 frame through a network sink. This is enforced by a sink-type marker trait (`LocalSink` vs `NetworkSink`).
|
||||
|
||||
### 2.4 Deterministic serialization
|
||||
|
||||
Three guarantees:
|
||||
|
||||
1. **Field order is fixed** by `#[repr(C, packed)]`.
|
||||
2. **Float quantization is canonical** — `quantization` byte values 1/2/3 use specified round-half-to-even with documented saturation; f32 (value 0) is forbidden over the wire (local-only).
|
||||
3. **CRC32 is computed last**, after all section bytes are placed.
|
||||
|
||||
The witness test in `tests/determinism.rs` captures a 200-frame BFI fixture, serializes it 1,000 times across two threads, and verifies the BLAKE3 of the resulting byte stream is bit-identical.
|
||||
|
||||
### 2.5 Magic value rationale
|
||||
|
||||
`0xBF1D_0001` is chosen so that `bf1d` reads as "BFLD" in hex-dump output, easing wireshark / xxd debugging. The final `0001` is the major version; minor revisions bump `version` field.
|
||||
|
||||
---
|
||||
|
||||
## 3. Consequences
|
||||
|
||||
### Positive
|
||||
|
||||
- 40-byte header + compact payload fits comfortably in a 1500-byte MTU even at 4×4 MIMO with 256 subcarriers.
|
||||
- Serialization is `#[no_std]` compatible — same code can run on ESP32-S3 (when ESP-NOW transport is added under ADR-123 P2).
|
||||
- Witness-bundle integration is direct: the existing `archive/v1/data/proof/verify.py` pattern extends to a `bfld_verify.py` that consumes the same SHA-256 expected-hash file format.
|
||||
|
||||
### Negative
|
||||
|
||||
- `#[repr(C, packed)]` on the header means consumers must use `read_unaligned` — small ergonomic cost, mitigated by a `#[derive(BfldFrameAccess)]` proc-macro.
|
||||
- Reserved flag bits 2-15 lock in future-extension order; any new bit assignment is a version bump.
|
||||
|
||||
### Neutral
|
||||
|
||||
- The vendor-extension section allows downstream RuView cogs (e.g., `cog-pose-estimation`) to attach metadata without a header change, at the cost of CRC scope creep. Vendor sections are explicitly outside the witness hash.
|
||||
|
||||
---
|
||||
|
||||
## 4. Alternatives Considered
|
||||
|
||||
### Alt 1: Protobuf / FlatBuffers
|
||||
|
||||
Rejected: schema evolution overhead, witness-hash instability across protoc versions, ~3× wire bloat for the small fixed-shape fields.
|
||||
|
||||
### Alt 2: CBOR
|
||||
|
||||
Rejected: deterministic CBOR (RFC 8949 §4.2) is achievable but the parser surface is large and tag handling is a footgun for the `no_std` ESP32 path.
|
||||
|
||||
### Alt 3: Variable-width magic / no magic
|
||||
|
||||
Rejected: receivers must distinguish BFLD frames from rvCSI `CsiFrame` and other RuView payloads on shared transports.
|
||||
|
||||
### Alt 4: Move CRC32 to header
|
||||
|
||||
Rejected: CRC must be computed after the payload, so its value would otherwise force a header rewrite; placing it last avoids a buffer-pass-back.
|
||||
|
||||
---
|
||||
|
||||
## 5. Acceptance Criteria
|
||||
|
||||
- [ ] **AC1**: `BfldFrameHeader` size is exactly **86 bytes** (packed) on x86_64, aarch64, and xtensa-esp32s3. The size was initially documented as 40 bytes during ADR drafting — that was a counting error; the implementation in `wifi-densepose-bfld/src/frame.rs` enforces the correct value via `const_assert_eq!`.
|
||||
- [ ] **AC2**: 1,000 serializations of a fixed `BfiCapture` fixture produce a bit-identical BLAKE3 hash.
|
||||
- [ ] **AC3**: `privacy_class = 0` frame returned through `NetworkSink::publish()` returns `Err(BfldError::PrivacyViolation)`.
|
||||
- [ ] **AC4**: Payload CRC32 mismatch causes `BfldFrame::parse()` to return `Err(BfldError::Crc)` without exposing partial payload state.
|
||||
- [ ] **AC5**: Round-trip serialize/parse preserves all header fields exactly.
|
||||
- [ ] **AC6**: A frame with `flags.bit0 = 0` (no CSI delta) and an unexpected CSI-delta section is rejected.
|
||||
- [ ] **AC7**: Bench: serialization throughput ≥ 50k frames/sec on a 2025-era M1/M2 / Pi 5 core.
|
||||
|
||||
---
|
||||
|
||||
## 6. References
|
||||
|
||||
- ADR-118 §2 (umbrella decision)
|
||||
- ADR-095 `CsiFrame` (`vendor/rvcsi/crates/rvcsi-core/src/frame.rs`)
|
||||
- CRC-32/ISO-HDLC: `crc = "3"` crate
|
||||
- BLAKE3 keyed mode: `blake3 = "1.5"`
|
||||
- IEEE 802.11-2020 §19.3.12 (Compressed Beamforming Report)
|
||||
@@ -1,192 +0,0 @@
|
||||
# ADR-120: BFLD Privacy Class and Hash Rotation
|
||||
|
||||
| Field | Value |
|
||||
|-------|-------|
|
||||
| **Status** | Proposed |
|
||||
| **Date** | 2026-05-24 |
|
||||
| **Deciders** | ruv |
|
||||
| **Parent** | [ADR-118](ADR-118-bfld-beamforming-feedback-layer-for-detection.md) |
|
||||
| **Relates to** | [ADR-027](ADR-027-cross-environment-domain-generalization.md) (MERIDIAN no-cross-site), [ADR-032](ADR-032-multistatic-mesh-security-hardening.md) (mesh security), [ADR-106](ADR-106-dp-sgd-and-primitive-isolation.md) (primitive isolation), [ADR-115](ADR-115-home-assistant-integration.md) (privacy mode) |
|
||||
| **Companion research** | [`docs/research/soul/`](../research/soul/) — Soul Signature operates at `privacy_class = 1` (derived). §2.7 defines the dual-ID-space contract. |
|
||||
| **Tracking issue** | TBD |
|
||||
|
||||
---
|
||||
|
||||
## 1. Context
|
||||
|
||||
ADR-118 declares three structural invariants for BFLD:
|
||||
|
||||
- **I1**: Raw BFI never exits the node.
|
||||
- **I2**: Identity embedding is in-RAM-only.
|
||||
- **I3**: Cross-site identity correlation is cryptographically impossible.
|
||||
|
||||
I1/I2 are enforced by sink typing and module visibility (ADR-119 §2.3). I3 requires a hash-rotation scheme that makes the same physical person produce **different** `rf_signature_hash` values across sites and across day boundaries, without any out-of-band coordination between sites.
|
||||
|
||||
The existing `HA-PRIVACY` mode in ADR-115 already toggles between "full" and "anonymous" surfaces, but at a per-event granularity — not at a per-byte-field granularity. BFLD requires the latter because the `BfldFrame` payload mixes sensing data (publishable) and identity-derived data (non-publishable) in the same struct.
|
||||
|
||||
The BFId paper (KIT, ACM CCS 2025) demonstrates that even a few minutes of BFI capture across the same site is sufficient to build a persistent biometric. The mitigation must be **structural**, not policy-dependent.
|
||||
|
||||
---
|
||||
|
||||
## 2. Decision
|
||||
|
||||
### 2.1 The four privacy classes
|
||||
|
||||
A single `privacy_class: u8` byte in the `BfldFrame` header (ADR-119 §2.1) selects one of four classes. The crate enforces field availability statically through marker types.
|
||||
|
||||
| Class | Name | Use case | Available fields |
|
||||
|-------|------|----------|------------------|
|
||||
| **0** | `raw` | Local-only research, never networked | All fields, full-precision BFI matrix, identity embedding |
|
||||
| **1** | `derived` | Operator-acknowledged research over LAN | Downsampled angle matrix, full features, identity_risk_score, identity_embedding |
|
||||
| **2** | `anonymous` (**default**) | Production deployment | Aggregate sensing only: presence, motion, person_count, zone_id, confidence |
|
||||
| **3** | `restricted` | Care-home / regulated deployment | Class 2 minus `identity_risk_score` and `rf_signature_hash` |
|
||||
|
||||
Default for new RuView nodes is class **2**. Operators must explicitly opt-down to class 1 via the existing `--research-mode` flag (ADR-115 §7); class 0 is reserved for `cargo test` and is unreachable from `wifi-densepose-sensing-server`.
|
||||
|
||||
### 2.2 Enforcement via marker types
|
||||
|
||||
```rust
|
||||
pub trait Sink {}
|
||||
|
||||
pub trait LocalSink: Sink {} // Allowed: classes 0,1,2,3
|
||||
pub trait NetworkSink: Sink {} // Allowed: classes 1,2,3 (NOT class 0)
|
||||
pub trait MatterSink: NetworkSink {} // Allowed: class 2,3 + cluster-filter (ADR-122)
|
||||
|
||||
impl Emitter {
|
||||
pub fn publish<S: NetworkSink>(&self, sink: &S, frame: BfldFrame)
|
||||
-> Result<(), BfldError>
|
||||
{
|
||||
if frame.header.privacy_class == 0 {
|
||||
return Err(BfldError::PrivacyViolation {
|
||||
reason: "class 0 to NetworkSink",
|
||||
});
|
||||
}
|
||||
// ... serialize and write
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
The compiler refuses to call `publish` on a sink that doesn't impl `NetworkSink` with a class-0 frame because the runtime check is paired with a sink-marker check. Cross-sink frame routing requires an explicit class transition (see §2.4).
|
||||
|
||||
### 2.3 BLAKE3 keyed hash rotation for `rf_signature_hash`
|
||||
|
||||
The signature hash is computed as:
|
||||
|
||||
```rust
|
||||
pub fn rf_signature_hash(
|
||||
site_salt: &[u8; 32], // generated on first boot, persisted in TPM/KMS
|
||||
day_epoch: u32, // floor(unix_time_utc / 86400)
|
||||
features: &IdentityFeatures,
|
||||
) -> Hash {
|
||||
let mut hasher = blake3::Hasher::new_keyed(site_salt);
|
||||
hasher.update(&day_epoch.to_le_bytes());
|
||||
hasher.update(&features.canonical_bytes());
|
||||
hasher.finalize()
|
||||
}
|
||||
```
|
||||
|
||||
**Structural cross-site isolation**: because `site_salt` is a 256-bit random secret unique to each node and never transmitted, two sites observing the same physical person produce uncorrelated hashes. There is no key the operator (or an attacker who compromises one node) can use to bridge sites. This is stronger than a policy-based "do not share" rule because the bridge **cannot be computed**.
|
||||
|
||||
**Daily rotation**: `day_epoch` flipping at UTC midnight forces the hash of the same person to change once per day. Multi-day correlation requires re-acquiring the biometric, which the rotation actively breaks.
|
||||
|
||||
### 2.4 Class-transition transformer
|
||||
|
||||
The only way a high-class frame becomes a lower-class frame is through `PrivacyGate::demote(frame, target_class)`. This function:
|
||||
|
||||
1. Asserts the target class is strictly higher number than (or equal to) the input class.
|
||||
2. Zeroes the disallowed fields with `subtle::Zeroize`.
|
||||
3. Re-computes `payload_crc32`.
|
||||
4. Returns the new frame.
|
||||
|
||||
There is no `promote` operation — a class-2 frame cannot be turned back into a class-1 frame, because the dropped fields were not retained anywhere reachable from the gate.
|
||||
|
||||
### 2.5 `identity_embedding` lifecycle
|
||||
|
||||
The embedding (output of the AETHER encoder, ADR-024) is held in a `subtle::Zeroizing<[f32; 128]>` ring buffer of 64 entries (≈30 KB). Entries are:
|
||||
|
||||
1. Written by the encoder on each capture window.
|
||||
2. Consumed by `identity_risk_score` computation (ADR-121).
|
||||
3. **Never** written to disk, MQTT, or any other I/O sink — there is no `Serialize` impl on the type.
|
||||
4. Overwritten by the ring (FIFO).
|
||||
|
||||
A compile-time `#[forbid(serde::Serialize)]` lint on `IdentityEmbedding` ensures a future PR cannot accidentally add a `Serialize` derive.
|
||||
|
||||
### 2.6 Default-deny field classification
|
||||
|
||||
Every new field added to `BfldFrame` or `BfldEvent` must be tagged with `#[must_classify]` (a custom attribute macro). The macro fails compilation if the field is not listed in the per-class allow-list table. This forces future contributors to make an explicit privacy decision on every new field.
|
||||
|
||||
### 2.7 Dual-ID-space contract for Soul Signature deployments
|
||||
|
||||
Soul Signature (`docs/research/soul/`) is a consent-based biometric system that *intentionally* produces long-lived per-person identity. It cannot operate at the default class 2 — the identity_embedding it needs is structurally absent there. The contract:
|
||||
|
||||
| Deployment mode | `privacy_class` | ID space for unenrolled bystanders | ID space for enrolled persons |
|
||||
|---|---|---|---|
|
||||
| Default BFLD-only | 2 (anonymous) | Daily-rotated `rf_signature_hash` | n/a — no enrollment |
|
||||
| Soul Signature opt-in | **1 (derived)** | Daily-rotated `rf_signature_hash` (unchanged) | Long-lived opaque `person_id` from Soul Signature graph |
|
||||
| Restricted / care-home | 3 (restricted) | Suppressed | n/a — Soul Signature **disabled** at class 3 |
|
||||
|
||||
Two ID spaces coexist with **no collision**: the rotating hash is the privacy-preserving identifier for everyone *not* on the consent roster; the stable `person_id` is reserved for enrolled subjects under their own GDPR/HIPAA mode. Soul Signature's `match_against_enrolled()` function consumes only the in-RAM `identity_embedding` (I2 still holds) and emits a `person_id` plus a calibrated similarity score; it never writes the embedding to disk or the wire. The class-1 requirement is enforced statically: the Soul Signature match API takes a `&IdentityEmbedding` parameter, which is only constructible when the BFLD crate is compiled with `--features soul-signature` against a class-1 frame.
|
||||
|
||||
---
|
||||
|
||||
## 3. Consequences
|
||||
|
||||
### Positive
|
||||
|
||||
- Cross-site identity correlation is **computationally impossible**, not merely "prohibited by policy". This is the strongest form of privacy guarantee available without a TEE.
|
||||
- Default-deny via `#[must_classify]` prevents the common pattern of "a new field shipped, then six months later we noticed it was identity-leaky".
|
||||
- `identity_embedding` cannot be serialized by accident — the type system carries the constraint.
|
||||
- The class transition transformer makes the data lifecycle explicit and auditable.
|
||||
|
||||
### Negative
|
||||
|
||||
- `site_salt` storage requires either a TPM (ADR-095/096 rvCSI platform feature gap) or a secrets file with strict mode. Loss of `site_salt` makes historical witness comparisons impossible — by design, but a documentation hazard.
|
||||
- `#[must_classify]` is a custom proc-macro; another moving part in the build.
|
||||
- Operators wanting multi-day analytics must work in aggregates only, not on per-individual signatures.
|
||||
|
||||
### Neutral
|
||||
|
||||
- Class 0 is `cargo test`-only. Some CI runners may need an explicit feature flag to compile class-0 paths.
|
||||
|
||||
---
|
||||
|
||||
## 4. Alternatives Considered
|
||||
|
||||
### Alt 1: Single boolean `privacy_mode` flag (status quo from ADR-115)
|
||||
|
||||
Rejected: insufficient granularity. The frame mixes publishable sensing with non-publishable identity, so the gate must operate at field-level, not event-level.
|
||||
|
||||
### Alt 2: SHA-256 instead of BLAKE3
|
||||
|
||||
Rejected: BLAKE3 keyed-hash mode is ~5× faster on the ESP32-S3 / Cortex-M cores and the security margin is equivalent for this use case. SHA-256 has no keyed-hash mode (HMAC-SHA256 is the alternative; works but is slower).
|
||||
|
||||
### Alt 3: Hash rotation on the hour, not the day
|
||||
|
||||
Rejected: hourly rotation breaks legitimate "person was here in the morning, came back in the afternoon" use-cases that operators may want. Day boundary is the compromise.
|
||||
|
||||
### Alt 4: Per-event nonces instead of daily epoch
|
||||
|
||||
Rejected: per-event nonces would force the consumer to track which events came from the same person within a session, which leaks identity information by structure. The day epoch preserves a coarse temporal grouping without leaking finer-grained identity.
|
||||
|
||||
---
|
||||
|
||||
## 5. Acceptance Criteria
|
||||
|
||||
- [ ] **AC1**: Calling `Emitter::publish` with a `privacy_class = 0` frame on a `NetworkSink` returns `BfldError::PrivacyViolation`.
|
||||
- [ ] **AC2**: Two BFLD nodes with different `site_salt` values observing the same simulated person produce `rf_signature_hash` values whose Hamming distance is ≥ 120 bits over 100 trials (statistical isolation test).
|
||||
- [ ] **AC3**: A frame with `privacy_class = 3` has both `identity_risk_score` and `rf_signature_hash` absent from the serialized payload.
|
||||
- [ ] **AC4**: `PrivacyGate::demote(class_1_frame, target=0)` fails to compile (compile-fail test).
|
||||
- [ ] **AC5**: A PR adding a new field to `BfldEvent` without `#[must_classify]` fails the build.
|
||||
- [ ] **AC6**: `IdentityEmbedding` has no `Serialize` impl reachable from any public function.
|
||||
- [ ] **AC7**: Dropping an `IdentityEmbedding` value zeroizes its memory (verified by a debugger-readable test under `cargo test --features zeroize-validation`).
|
||||
|
||||
---
|
||||
|
||||
## 6. References
|
||||
|
||||
- ADR-118 (umbrella)
|
||||
- ADR-119 (frame format; `privacy_class` byte location)
|
||||
- KIT BFId (ACM CCS 2025): https://publikationen.bibliothek.kit.edu/1000185756
|
||||
- NDSS LeakyBeam (2025): https://www.ndss-symposium.org/wp-content/uploads/2025-5-paper.pdf
|
||||
- BLAKE3 keyed-hash: https://github.com/BLAKE3-team/BLAKE3
|
||||
- `subtle::Zeroize` for memory hygiene
|
||||
@@ -1,182 +0,0 @@
|
||||
# ADR-121: BFLD Identity Risk Scoring and Coherence Gate
|
||||
|
||||
| Field | Value |
|
||||
|-------|-------|
|
||||
| **Status** | Proposed |
|
||||
| **Date** | 2026-05-24 |
|
||||
| **Deciders** | ruv |
|
||||
| **Parent** | [ADR-118](ADR-118-bfld-beamforming-feedback-layer-for-detection.md) |
|
||||
| **Relates to** | [ADR-024](ADR-024-contrastive-csi-embedding-model.md) (AETHER), [ADR-027](ADR-027-cross-environment-domain-generalization.md) (MERIDIAN), [ADR-029](ADR-029-ruvsense-multistatic-sensing-mode.md) (multistatic fusion), [ADR-086](ADR-086-edge-novelty-gate.md) (novelty gate precedent), [ADR-120](ADR-120-bfld-privacy-class-and-hash-rotation.md) (privacy class) |
|
||||
| **Companion research** | [`docs/research/soul/`](../research/soul/) — risk score doubles as Soul Signature enrollment-quality signal; §2.7 defines the Recalibrate exemption. |
|
||||
| **Tracking issue** | TBD |
|
||||
|
||||
---
|
||||
|
||||
## 1. Context
|
||||
|
||||
BFLD's distinguishing primitive is the `identity_risk_score` — a scalar that says **"is this capture window currently capable of identifying a specific person?"**. The score has two consumers:
|
||||
|
||||
1. **The operator** — exposed as an HA diagnostic sensor (ADR-122). A spike from the long-term baseline indicates the RF environment has shifted toward a higher-leakage regime (new AP firmware, denser MIMO, attacker-grade sniffer in range).
|
||||
2. **The privacy gate** (ADR-120) — when the score crosses a configurable threshold, the gate downgrades the active `privacy_class` automatically (e.g., 2 → 3) until the score recovers.
|
||||
|
||||
The score must be:
|
||||
- **Bounded** in `[0, 1]` for HA gauge entities.
|
||||
- **Calibrated** against actual re-ID success rate, ideally on the KIT BFId dataset.
|
||||
- **Computable on-device** at ≥ 1 Hz on a Pi 5 core or an aarch64 cognitum-v0.
|
||||
- **Stable** — small environmental changes should not produce wild swings; the score is for slow-moving regime detection, not per-frame chatter.
|
||||
|
||||
ADR-086 (edge novelty gate) establishes a precedent for an on-device gate primitive. BFLD's risk scoring borrows the gate-pattern but with identity leakage as the trigger condition.
|
||||
|
||||
---
|
||||
|
||||
## 2. Decision
|
||||
|
||||
### 2.1 Nine features (from BFLD spec §5)
|
||||
|
||||
The features are computed over a sliding window of `W = 32` BFI frames (≈3 s at 10 Hz):
|
||||
|
||||
| Feature | Definition | Source |
|
||||
|---------|------------|--------|
|
||||
| `mean_angle_delta` | mean( ‖ Φ_t − Φ_{t-1} ‖ over subcarriers ) | extractor |
|
||||
| `subcarrier_variance` | var( ‖ Φ ‖ over subcarrier axis ) | extractor |
|
||||
| `temporal_entropy` | Shannon entropy of angle-bin histogram over W | extractor |
|
||||
| `doppler_proxy` | FFT peak magnitude of mean-angle time series | features.rs |
|
||||
| `path_stability` | 1 − ‖ Φ_t − median(Φ_{t-W..t}) ‖ / scale | features.rs |
|
||||
| `cross_antenna_correlation` | mean Pearson correlation across n_tx × n_rx pairs | features.rs |
|
||||
| `burst_motion_score` | high-pass-filtered angular velocity, soft-thresholded | features.rs |
|
||||
| `stationarity_score` | 1 − rolling KL divergence over W/2 vs W | features.rs |
|
||||
| `identity_separability_score` | top-1 cosine to nearest AETHER cluster centroid | identity_risk.rs |
|
||||
|
||||
The first eight are sensing features (also used by the presence/motion pipeline). Only the ninth depends on the AETHER embedding and therefore on `identity_class >= 1`.
|
||||
|
||||
### 2.2 Identity risk formula
|
||||
|
||||
```rust
|
||||
pub fn identity_risk_score(
|
||||
sep: f32, // identity_separability_score, [0, 1]
|
||||
stab: f32, // temporal_stability, [0, 1] = ema(path_stability, alpha=0.1)
|
||||
consist: f32,// cross_perspective_consistency, [0, 1] = multistatic.rs
|
||||
conf: f32, // sample_confidence, [0, 1] = f(SNR, n_subcarriers, n_rx)
|
||||
) -> f32 {
|
||||
// Clamp inputs, then multiplicative combination — any factor near 0 dominates.
|
||||
let s = sep.clamp(0.0, 1.0);
|
||||
let t = stab.clamp(0.0, 1.0);
|
||||
let p = consist.clamp(0.0, 1.0);
|
||||
let c = conf.clamp(0.0, 1.0);
|
||||
(s * t * p * c).clamp(0.0, 1.0)
|
||||
}
|
||||
```
|
||||
|
||||
Multiplicative combination is chosen so that **any** weak factor (e.g., very low SNR ⇒ low `conf`) collapses the score toward 0. This matches the privacy intent: when the system is uncertain, the score should be low and the operator should not be alarmed.
|
||||
|
||||
### 2.3 Calibration target
|
||||
|
||||
The score is calibrated against re-ID success rate on a held-out test split of the KIT BFId dataset. A piecewise-linear isotonic regression maps raw scores into a calibrated `[0, 1]` band where `score ≥ 0.8` corresponds to `>80%` re-ID accuracy on a 5-second window in the calibration dataset.
|
||||
|
||||
Calibration parameters live in `v2/crates/wifi-densepose-bfld/data/risk_calibration.toml` and are versioned independently of the code. A regression update is a content-only PR.
|
||||
|
||||
### 2.4 Coherence gate
|
||||
|
||||
The coherence gate (per ADR-029 `coherence_gate.rs` pattern) consumes the risk score and emits one of four actions:
|
||||
|
||||
```rust
|
||||
pub enum GateAction {
|
||||
Accept, // score < 0.5, publish normally
|
||||
PredictOnly, // 0.5 <= score < 0.7, publish but flag confidence
|
||||
Reject, // 0.7 <= score < 0.9, drop the event
|
||||
Recalibrate, // score >= 0.9, drop AND rotate site_salt
|
||||
}
|
||||
```
|
||||
|
||||
The `Recalibrate` action triggers a forced site-salt rotation — an aggressive response to a sustained high-risk regime. It costs the operator continuity of long-term aggregate analytics but is the right answer to an attacker-grade sniffer arriving in range.
|
||||
|
||||
### 2.5 Hysteresis
|
||||
|
||||
To prevent oscillation around the gate thresholds, the gate uses ±0.05 hysteresis and a 5-second debounce. A score must cross the boundary by the hysteresis margin and persist for the debounce window before the gate action changes.
|
||||
|
||||
### 2.6 Soul Signature interaction — Recalibrate exemption and enrollment-quality gate
|
||||
|
||||
Soul Signature (`docs/research/soul/`) intentionally exists in a high-separability regime — the whole point of its 60-second enrollment protocol is to push `identity_separability_score` toward 1.0. The default coherence gate (§2.4) would therefore fire `Recalibrate` constantly inside Soul Signature zones, rotating `site_salt` every few seconds and breaking enrollment.
|
||||
|
||||
Two integrations resolve this:
|
||||
|
||||
1. **Recalibrate exemption.** When the gate is about to fire `Recalibrate`, it consults a `SoulMatchOracle` (provided by the Soul Signature crate when compiled with `--features soul-signature`). If the oracle reports that the current high-separability cluster matches an enrolled `person_id` above the Soul Signature acceptance threshold, the gate downgrades to `PredictOnly` instead. The high score is the *intended* outcome of a successful match, not an attack indicator. Without the `soul-signature` feature, the oracle is a no-op stub returning `MatchOutcome::NotEnrolled`, so the gate behaves exactly per §2.4.
|
||||
|
||||
2. **Enrollment-quality gate.** Soul Signature's enrollment protocol (`scanning-process.md` §3) requires that the sensing zone meet a minimum identity-leakage regime — too low, and the resulting signature is unreliable. The BFLD `identity_risk_score` is exactly the right signal. Soul Signature gates enrollment on `score >= ENROLL_MIN` (default `0.65`) sustained over the 60-second window. If the score drops below threshold mid-enrollment, the protocol aborts and the operator is prompted to re-attempt in better RF conditions.
|
||||
|
||||
The exemption is asymmetric: it suppresses `Recalibrate` only for known-enrolled matches. Unknown high-separability clusters (a real attacker-grade sniffer, or an unenrolled person whose identity is unexpectedly leaky) still trigger `Recalibrate` as designed.
|
||||
|
||||
### 2.7 Compute budget
|
||||
|
||||
| Stage | Target latency | Implementation |
|
||||
|-------|----------------|----------------|
|
||||
| Feature extraction (8 features) | < 3 ms per window | ndarray + nalgebra; vectorized over subcarriers |
|
||||
| Separability (cosine to centroids) | < 5 ms per window | RuVector RaBitQ index (ADR-085) over ≤ 1k centroids |
|
||||
| Risk score | < 0.1 ms | scalar multiplicative |
|
||||
| Gate decision + hysteresis | < 0.1 ms | scalar |
|
||||
|
||||
Total p95 ≤ 10 ms per window on a Pi 5 core (8 ms target). Headroom on cognitum-v0 (Pi 5 + Hailo) is ample; ESP32-S3 hosts only the extraction stage (features computed; risk score is host-side per ADR-123). The `SoulMatchOracle` lookup (§2.6) adds < 1 ms when the `soul-signature` feature is enabled (RaBitQ index over enrolled centroids).
|
||||
|
||||
---
|
||||
|
||||
## 3. Consequences
|
||||
|
||||
### Positive
|
||||
|
||||
- The risk score becomes a first-class diagnostic surface for operators and a structural input to the privacy gate — both consumers from a single computation.
|
||||
- Multiplicative combination is conservative under uncertainty; the system is biased toward "report low risk when unsure", which is the right default.
|
||||
- Calibration is a content-only update — no recompile needed when the calibration file changes.
|
||||
- The recalibration gate action gives the system a self-healing response to a sniffer arrival without operator intervention.
|
||||
|
||||
### Negative
|
||||
|
||||
- Calibration requires the KIT BFId dataset; without it the score is uncalibrated and serves only as an internal trigger, not a publishable signal.
|
||||
- Multiplicative scoring can be dominated by `sample_confidence`, which is sensitive to channel conditions. A persistent low-SNR environment will keep the published score near 0 even when the underlying separability is high — an under-reporting failure mode that the documentation must call out.
|
||||
- The recalibrate action breaks historical hash continuity by design; an operator who wants long-term aggregates needs to know they will see a discontinuity on recalibrate events.
|
||||
|
||||
### Neutral
|
||||
|
||||
- The nine features overlap with the existing CSI pipeline. BFLD computes them on BFI; the CSI pipeline computes them on CSI. Both can be fused via `cross_perspective_consistency`.
|
||||
|
||||
---
|
||||
|
||||
## 4. Alternatives Considered
|
||||
|
||||
### Alt 1: Additive scoring (`(s + t + p + c) / 4`)
|
||||
|
||||
Rejected: a sample with high separability but very low confidence would still produce a moderate score, which over-reports risk in degraded RF conditions.
|
||||
|
||||
### Alt 2: Maximum scoring (`max(s, t, p, c)`)
|
||||
|
||||
Rejected: over-reports risk because any single high factor pins the output, even if the others contradict it.
|
||||
|
||||
### Alt 3: Learned scoring (a small MLP)
|
||||
|
||||
Rejected for this ADR: introduces an opaque model whose output cannot be audited from first principles. The multiplicative formula is simple, conservative, and directly explainable to operators. A learned model is a future option once enough calibration data is in hand.
|
||||
|
||||
### Alt 4: Per-feature thresholds instead of a continuous score
|
||||
|
||||
Rejected: continuous score is needed for the HA gauge entity and for downstream calibration. Per-feature thresholds would force operators to interpret nine separate binaries.
|
||||
|
||||
---
|
||||
|
||||
## 5. Acceptance Criteria
|
||||
|
||||
- [ ] **AC1**: All nine features are computed in `< 8 ms` p95 per window on a Pi 5 core.
|
||||
- [ ] **AC2**: `identity_risk_score` is monotonic non-decreasing in any single input when the other three are held constant.
|
||||
- [ ] **AC3**: Calibration regression on the KIT BFId test split: `score ≥ 0.8` corresponds to ≥ 80% re-ID accuracy ± 5%.
|
||||
- [ ] **AC4**: The coherence gate emits `Recalibrate` if score is ≥ 0.9 for ≥ 5 seconds.
|
||||
- [ ] **AC5**: Hysteresis prevents action oscillation across ± 0.05 of a threshold within a 5-second window.
|
||||
- [ ] **AC6**: At `privacy_class = 3`, the risk score is computed but not published to MQTT (kept local for the gate only).
|
||||
- [ ] **AC7**: A reproducible 1,000-frame synthetic fixture produces a deterministic score sequence (bit-identical across runs).
|
||||
|
||||
---
|
||||
|
||||
## 6. References
|
||||
|
||||
- ADR-118 (umbrella)
|
||||
- ADR-024 (AETHER encoder for separability)
|
||||
- ADR-029 (`coherence_gate.rs` precedent)
|
||||
- ADR-086 (edge novelty gate pattern)
|
||||
- ADR-120 §2.4 (class transition consumed by gate)
|
||||
- KIT BFId dataset: https://publikationen.bibliothek.kit.edu/1000185756
|
||||
@@ -1,210 +0,0 @@
|
||||
# ADR-122: BFLD RuView Surface — Home Assistant, Matter, MQTT Exposure
|
||||
|
||||
| Field | Value |
|
||||
|-------|-------|
|
||||
| **Status** | Proposed |
|
||||
| **Date** | 2026-05-24 |
|
||||
| **Deciders** | ruv |
|
||||
| **Parent** | [ADR-118](ADR-118-bfld-beamforming-feedback-layer-for-detection.md) |
|
||||
| **Relates to** | [ADR-031](ADR-031-ruview-sensing-first-rf-mode.md) (sensing-first), [ADR-100](ADR-100-cog-packaging-specification.md) (cog packaging), [ADR-115](ADR-115-home-assistant-integration.md) (HA-DISCO + HA-MIND), [ADR-116](ADR-116-cog-ha-matter-seed.md) (Matter cog), [ADR-120](ADR-120-bfld-privacy-class-and-hash-rotation.md) (privacy class) |
|
||||
| **Companion research** | [`docs/research/soul/`](../research/soul/) — Soul Signature deployments expose enrolled-match diagnostics only over HA, never Matter. See §2.7. |
|
||||
| **Tracking issue** | TBD |
|
||||
|
||||
---
|
||||
|
||||
## 1. Context
|
||||
|
||||
ADR-115 shipped the RuView Home Assistant surface (21 entities, MQTT auto-discovery, mTLS, privacy mode) on the `wifi-densepose-sensing-server` Rust binary. ADR-116 is packaging this as the `cog-ha-matter` Cognitum Seed cog. BFLD must integrate into this surface without expanding the privacy-sensitive footprint already in production.
|
||||
|
||||
The integration must:
|
||||
|
||||
1. **Extend HA-DISCO** to advertise BFLD entities via the existing MQTT-discovery scheme.
|
||||
2. **Reject identity fields at the Matter boundary** — Matter exposes occupancy/motion/people-count only, never `identity_risk_score` or `rf_signature_hash`.
|
||||
3. **Route MQTT topics by privacy class** — class-2/3 events on the public topic tree, class-1 events on a gated `research/` subtree, class-0 events nowhere.
|
||||
4. **Federate cleanly into cognitum-v0** — BFLD events from multiple nodes flow through `cognitum-rvf-agent` (port 9004 per CLAUDE.local.md) for cross-node analytics, but identity-derived fields are stripped at the **publishing-node boundary**, not at the federation hub.
|
||||
|
||||
---
|
||||
|
||||
## 2. Decision
|
||||
|
||||
### 2.1 HA entity surface (six new entities per node)
|
||||
|
||||
The cog republishes the existing 21 ADR-115 entities and adds:
|
||||
|
||||
| Entity ID | Type | Source field | Class gate | Diagnostic |
|
||||
|-----------|------|--------------|------------|------------|
|
||||
| `binary_sensor.<node>_bfld_presence` | occupancy | `BfldEvent.presence` | ≥ 2 | no |
|
||||
| `sensor.<node>_bfld_motion` | gauge `[0,1]` | `BfldEvent.motion` | ≥ 2 | no |
|
||||
| `sensor.<node>_bfld_person_count` | int | `BfldEvent.person_count` | ≥ 2 | no |
|
||||
| `sensor.<node>_bfld_zone_activity` | enum | `BfldEvent.zone_activity` | ≥ 2 | no |
|
||||
| `sensor.<node>_bfld_identity_risk` | gauge `[0,1]` | `BfldEvent.identity_risk_score` | == 2 only | **yes** |
|
||||
| `sensor.<node>_bfld_confidence` | gauge `[0,1]` | `BfldEvent.confidence` | ≥ 2 | yes |
|
||||
|
||||
The `identity_risk` entity is exposed only under privacy class 2 and is flagged `entity_category: diagnostic` so HA dashboards do not promote it to a main-card sensor by default. Under class 3 it is computed but not published (per ADR-121 §2.4).
|
||||
|
||||
MQTT discovery payload follows the ADR-115 schema, plus a `bfld_version` attribute matching the `BfldFrameHeader::version` field.
|
||||
|
||||
### 2.2 MQTT topic tree
|
||||
|
||||
```
|
||||
ruview/<node_id>/bfld/presence/state # class >= 2
|
||||
ruview/<node_id>/bfld/motion/state # class >= 2
|
||||
ruview/<node_id>/bfld/person_count/state # class >= 2
|
||||
ruview/<node_id>/bfld/zone_activity/state # class >= 2
|
||||
ruview/<node_id>/bfld/confidence/state # class >= 2
|
||||
ruview/<node_id>/bfld/identity_risk/state # class == 2 only
|
||||
ruview/<node_id>/bfld/raw # class 1, OFF by default
|
||||
ruview/<node_id>/bfld/availability # online/offline marker
|
||||
```
|
||||
|
||||
`raw` (class-1 derived BFI) is **not present** in the discovery payload at all — operators must explicitly subscribe and acknowledge the research-mode caveat. The publishing crate emits `MQTT_RAW_DISABLED` to availability when `privacy_class < 1`.
|
||||
|
||||
### 2.3 Mosquitto ACL example
|
||||
|
||||
```
|
||||
# Default-deny everything not explicitly granted
|
||||
pattern read ruview/+/bfld/+/state
|
||||
pattern read ruview/+/bfld/availability
|
||||
|
||||
# Public roles cannot read identity_risk or raw
|
||||
user public
|
||||
deny read ruview/+/bfld/identity_risk/state
|
||||
deny read ruview/+/bfld/raw
|
||||
|
||||
# Operator role can read identity_risk for diagnostics
|
||||
user operator
|
||||
allow read ruview/+/bfld/identity_risk/state
|
||||
|
||||
# Research role can read raw (requires class-1 operation)
|
||||
user research
|
||||
allow read ruview/+/bfld/raw
|
||||
```
|
||||
|
||||
The cog ships a default ACL template under `cog-ha-matter/etc/mosquitto.acl.d/bfld.conf` for operators who use the embedded broker (ADR-116 §2.2).
|
||||
|
||||
### 2.4 Matter cluster boundary
|
||||
|
||||
`cog-ha-matter` exposes BFLD via **three Matter clusters** only:
|
||||
|
||||
| Matter cluster | Source entity | Notes |
|
||||
|---|---|---|
|
||||
| Occupancy Sensing (0x0406) | `binary_sensor.<node>_bfld_presence` | reports binary occupancy + uncertainty (mapped from `confidence`) |
|
||||
| Boolean State (0x0045) | `sensor.<node>_bfld_motion >= 0.3` | thresholded; raw motion not exposed |
|
||||
| Occupancy Sensing extension | `sensor.<node>_bfld_person_count` | uses occupancy-sensor count where Matter spec supports |
|
||||
|
||||
**Explicitly NOT exposed via Matter**:
|
||||
|
||||
- `identity_risk_score`
|
||||
- `rf_signature_hash`
|
||||
- `identity_embedding`
|
||||
- `raw` BFI
|
||||
- `zone_activity` (zone IDs are site-specific and Matter is a cross-site surface)
|
||||
- `confidence` (HA-only diagnostic)
|
||||
|
||||
The Matter filter is implemented in `cog-ha-matter/src/matter/bfld_filter.rs` as a `MatterSink` trait impl that rejects classes 0 and 1 at compile time (via ADR-120 §2.2 marker types).
|
||||
|
||||
### 2.5 Federation with cognitum-v0
|
||||
|
||||
`cognitum-rvf-agent` (port 9004) receives BFLD events from multiple nodes. The events arriving at the federation hub are **already class-2/3** — identity-derived fields were stripped at each publishing node. The hub does not see and cannot reconstruct raw BFI or identity embeddings.
|
||||
|
||||
The federation contract:
|
||||
|
||||
| At publishing node | At cognitum-rvf-agent |
|
||||
|---|---|
|
||||
| Strip class-0/1 fields per ADR-120 | Receive class-2/3 events only |
|
||||
| Rotate `rf_signature_hash` per ADR-120 §2.3 | Aggregate counts; **do not** correlate hashes across sites |
|
||||
| Sign event with node Ed25519 key | Verify signature; reject unsigned events |
|
||||
|
||||
A `federation-witness` script (extending ADR-028) runs nightly on the hub and proves that no class-0/1 fields appeared in any received event over the previous 24 h.
|
||||
|
||||
### 2.6 HA blueprints (shipped with the cog)
|
||||
|
||||
Three operator-ready blueprints under `cog-ha-matter/blueprints/`:
|
||||
|
||||
1. **Presence-driven lighting** — `binary_sensor.*_bfld_presence` ⇒ `light.turn_on/off` with configurable hold time.
|
||||
2. **Motion-aware HVAC** — `sensor.*_bfld_motion > 0.3` ⇒ raise HVAC setpoint by ΔT.
|
||||
3. **Identity-risk anomaly notification** — `sensor.*_bfld_identity_risk` exceeds rolling z-score threshold ⇒ HA `notify.*` to the operator with the originating node and the 7-day baseline.
|
||||
|
||||
### 2.7 Soul Signature deployment posture
|
||||
|
||||
When the cog is compiled with `--features soul-signature`, two additional HA entities are exposed **at class 1 only**, and **never** over Matter:
|
||||
|
||||
| Entity ID | Type | Source | Class gate | Matter |
|
||||
|-----------|------|--------|------------|--------|
|
||||
| `sensor.<node>_soul_match_id` | string (opaque `person_id`) | Soul Signature match oracle | == 1 only | **rejected** |
|
||||
| `sensor.<node>_soul_match_score` | gauge `[0,1]` | Match similarity | == 1 only | **rejected** |
|
||||
| `sensor.<node>_soul_enrollment_quality` | gauge `[0,1]` | Mirror of `identity_risk_score` during enrollment | == 1 only | **rejected** |
|
||||
|
||||
These entities are part of the consent-based diagnostic surface for operators running Soul Signature deployments (care homes with explicit GDPR Art. 9 basis, employment with consent, etc.). The Matter cluster boundary in §2.4 already rejects them by type — the `MatterSink` impl only accepts class-2/3 frames, so `soul_match_id` is structurally unreachable through Matter.
|
||||
|
||||
Class-3 deployments **disable Soul Signature** entirely: the `match_against_enrolled()` call returns `MatchOutcome::Suppressed` and no soul entities are published. This makes class 3 the correct setting for any deployment where consent is uncertain or where regulators require Soul Signature to be unavailable.
|
||||
|
||||
A fourth blueprint ships only when `--features soul-signature` is enabled:
|
||||
|
||||
4. **Enrolled-person arrival notification** — `sensor.*_soul_match_id` transitions to a non-null value ⇒ HA `notify.*` to the enrolled person's configured contact (typically themselves or a designated caregiver). Default off; operator must opt in per enrolled person.
|
||||
|
||||
---
|
||||
|
||||
## 3. Consequences
|
||||
|
||||
### Positive
|
||||
|
||||
- Six new HA entities give operators a complete BFLD diagnostic dashboard without leaking identity.
|
||||
- Matter exposure is structurally narrow — the cluster-filter implementation cannot accidentally expose identity fields because the type system rejects them.
|
||||
- The default ACL template gives operators a working privacy posture out of the box.
|
||||
- The federation contract makes it explicit that the hub cannot reconstruct identity even from the union of all node events.
|
||||
|
||||
### Negative
|
||||
|
||||
- The `identity_risk` HA entity exists only under class 2. Operators who run class 3 deployments cannot see the score even in their own dashboard. This is correct but may surprise care-home installers; documentation must be clear.
|
||||
- Three Matter clusters is conservative — some HA users may want the count exposed as a percentage or rate, which Matter does not support natively.
|
||||
- HA-blueprint coverage is intentionally small; operators wanting custom automations must work through the YAML surface.
|
||||
|
||||
### Neutral
|
||||
|
||||
- The federation witness script runs nightly. A short-duration leak between witnesses is possible but bounded — any successful exfiltration of class-1 fields would still need to be reconstructed into identity, which the daily hash rotation breaks.
|
||||
|
||||
---
|
||||
|
||||
## 4. Alternatives Considered
|
||||
|
||||
### Alt 1: Expose `identity_risk` over Matter (Generic Sensor cluster)
|
||||
|
||||
Rejected: Matter is a cross-vendor surface; exposing identity-risk there leaks the score to every Matter controller in the home, including third-party hubs the operator may not control. Keep it HA-internal.
|
||||
|
||||
### Alt 2: One unified MQTT topic `ruview/<node>/bfld` with JSON payload
|
||||
|
||||
Rejected: per-entity topics are the HA-DISCO convention (ADR-115) and let ACLs be field-specific. A unified topic forces an all-or-nothing read policy.
|
||||
|
||||
### Alt 3: Federate raw BFI to cognitum-v0 for cross-node analytics
|
||||
|
||||
Rejected: violates ADR-120 I1 (raw never leaves the node). Aggregates are sufficient for cross-node analytics; raw centralization is a hard no.
|
||||
|
||||
### Alt 4: Default `entity_category: diagnostic = false` for `identity_risk`
|
||||
|
||||
Rejected: promoting `identity_risk` to a main-card sensor would surprise operators with an identity-adjacent gauge on their main dashboard. Diagnostic category is the right default.
|
||||
|
||||
---
|
||||
|
||||
## 5. Acceptance Criteria
|
||||
|
||||
- [ ] **AC1**: HA auto-discovery publishes six new entities per node on first connect; HA recognizes all six.
|
||||
- [ ] **AC2**: Under privacy class 3, `sensor.<node>_bfld_identity_risk` is absent from the MQTT discovery payload.
|
||||
- [ ] **AC3**: `MatterSink::publish` rejects any frame at compile time when the source has `privacy_class < 2`.
|
||||
- [ ] **AC4**: The default mosquitto ACL denies `read ruview/+/bfld/identity_risk/state` to the `public` user role.
|
||||
- [ ] **AC5**: Three HA blueprints install cleanly into a fresh HA install and trigger their configured actions against a mock BFLD event stream.
|
||||
- [ ] **AC6**: The federation-witness script detects an injected class-1 field in a synthetic event and exits non-zero.
|
||||
- [ ] **AC7**: Matter occupancy-sensing cluster reports presence within 1 s of an HA `binary_sensor.*_bfld_presence` state change.
|
||||
|
||||
---
|
||||
|
||||
## 6. References
|
||||
|
||||
- ADR-115 (HA-DISCO entity scheme)
|
||||
- ADR-116 (`cog-ha-matter` cog packaging)
|
||||
- ADR-120 (privacy class enforcement)
|
||||
- ADR-121 (identity risk source)
|
||||
- ADR-100 (cog packaging spec)
|
||||
- Mosquitto ACL reference: https://mosquitto.org/man/mosquitto-conf-5.html
|
||||
- Matter spec — Occupancy Sensing cluster (0x0406)
|
||||
- Cognitum V0 appliance dashboard: `http://cognitum-v0:9000/`
|
||||
@@ -1,186 +0,0 @@
|
||||
# ADR-123: BFLD Capture Path — Pi 5 / Nexmon Adapter and ESP32-S3 Feasibility
|
||||
|
||||
| Field | Value |
|
||||
|-------|-------|
|
||||
| **Status** | Proposed |
|
||||
| **Date** | 2026-05-24 |
|
||||
| **Deciders** | ruv |
|
||||
| **Parent** | [ADR-118](ADR-118-bfld-beamforming-feedback-layer-for-detection.md) |
|
||||
| **Relates to** | [ADR-022](ADR-022-multi-bssid-wifi-scanning.md) (multi-BSSID scan), [ADR-028](ADR-028-esp32-capability-audit.md) (capability audit), [ADR-095](ADR-095-rvcsi-edge-rf-sensing-platform.md) (rvCSI), [ADR-096](ADR-096-rvcsi-ffi-crate-layout.md) (rvCSI FFI), [ADR-110](ADR-110-esp32-c6-firmware-extension.md) (C6 firmware), [ADR-119](ADR-119-bfld-frame-format-and-wire-protocol.md) (BfldFrame) |
|
||||
| **Tracking issue** | TBD |
|
||||
|
||||
---
|
||||
|
||||
## 1. Context
|
||||
|
||||
ADR-118 declares that BFLD captures BFI from commodity WiFi 5/6 traffic. The question this sub-ADR answers is: **on which hardware, with which adapter, and against which firmware limitations**.
|
||||
|
||||
### 1.1 ESP32-S3 BFI capability gap
|
||||
|
||||
The ESP32 capability audit (ADR-028) and the ESP32-S3 / C6 firmware (`firmware/esp32-csi-node/`, ADR-110) confirm that the Espressif WiFi API exposes **CSI** capture (`esp_wifi_set_csi_*`) but does not expose **raw 802.11 management-frame capture** in monitor mode for non-self-addressed CBFR reports. The S3 sees the CBFR frames its own AP-link generates (when it acts as a beamformer), but it cannot promiscuously sniff CBFR frames between other STA/AP pairs in the neighborhood.
|
||||
|
||||
The C6 (ESP32-C6 with RISC-V + Wi-Fi 6) has a more flexible RF subsystem but the same software-API constraint at the time of writing.
|
||||
|
||||
### 1.2 Pi 5 / Nexmon as the production capture host
|
||||
|
||||
The rvCSI platform (ADR-095/096) already vendors a Nexmon-based adapter (`rvcsi-adapter-nexmon`) that captures CSI from BCM43455c0 chips (Pi 5 / Pi 4 / Pi 3B+). Nexmon patches the firmware to surface CSI to userspace and **also surface CBFR frames** — the BFI extension is the same code path with a different filter.
|
||||
|
||||
cognitum-v0 (Pi 5 in the fleet, per CLAUDE.local.md) is already running Nexmon + the rvCSI runtime. It is the natural BFLD capture host.
|
||||
|
||||
### 1.3 What we need from each hardware tier
|
||||
|
||||
| Tier | Role | BFI capture | CSI capture | Notes |
|
||||
|------|------|-------------|-------------|-------|
|
||||
| ESP32-S3 / C6 | Sensing leaf | **no** | yes | Continues providing CSI to the existing pipeline |
|
||||
| Pi 5 / Nexmon | BFLD host | **yes** | yes (via Nexmon) | Primary BFLD capture |
|
||||
| ruvultra (RTX 5080 + AX210) | Training / dev | yes (via AX210 monitor mode) | yes | Dev capture; not production |
|
||||
| cognitum-v0 (Pi 5) | Appliance | **yes** (production) | yes | Production BFLD host |
|
||||
|
||||
---
|
||||
|
||||
## 2. Decision
|
||||
|
||||
### 2.1 Production capture path: Pi 5 / Nexmon
|
||||
|
||||
The BFLD production capture path is implemented as a new module in the vendored rvCSI submodule:
|
||||
|
||||
```
|
||||
vendor/rvcsi/crates/rvcsi-adapter-nexmon/
|
||||
└── src/
|
||||
├── lib.rs
|
||||
├── csi.rs # existing CSI capture
|
||||
└── bfi.rs # NEW — CBFR capture, exports BfiCapture
|
||||
```
|
||||
|
||||
The new `bfi.rs` parses CBFR frames (VHT or HE) from the Nexmon-patched firmware's userspace stream, extracts Φ/ψ angle matrices, and emits a `BfiCapture` struct that feeds the BFLD crate's extractor (ADR-118 §2.1, ADR-119).
|
||||
|
||||
The patch lives in the rvcsi submodule (`github.com/ruvnet/rvcsi`) and is shipped as `rvcsi-adapter-nexmon ^0.3.5` to crates.io. The wifi-densepose workspace consumes the published crate (or the submodule path during development).
|
||||
|
||||
### 2.2 BFLD crate adapter trait
|
||||
|
||||
`wifi-densepose-bfld` defines a `BfiCaptureAdapter` trait:
|
||||
|
||||
```rust
|
||||
pub trait BfiCaptureAdapter: Send + 'static {
|
||||
type Error: std::error::Error + Send + Sync + 'static;
|
||||
fn capture(&mut self) -> Result<Option<BfiCapture>, Self::Error>;
|
||||
fn capabilities(&self) -> AdapterCapabilities;
|
||||
}
|
||||
|
||||
pub struct AdapterCapabilities {
|
||||
pub supports_he: bool, // 802.11ax (Wi-Fi 6)
|
||||
pub supports_160mhz: bool,
|
||||
pub max_n_rx: u8,
|
||||
pub host_kind: HostKind, // Pi5Nexmon | Ax210Linux | EspS3Local | Mock
|
||||
}
|
||||
```
|
||||
|
||||
Three impls ship initially:
|
||||
|
||||
- `NexmonBfiAdapter` — Pi 5 / Nexmon (production)
|
||||
- `Ax210BfiAdapter` — Linux + AX210 in monitor mode (dev / training, ruvultra)
|
||||
- `MockBfiAdapter` — replay fixture for tests and CI
|
||||
|
||||
A future fourth impl (`EspS3LocalAdapter`) is reserved for the day Espressif exposes promiscuous CBFR — it captures only the S3's own AP-link BFI for local self-reporting.
|
||||
|
||||
### 2.3 Capture-side privacy boundary
|
||||
|
||||
Per ADR-120 I1, raw BFI never leaves the capturing host. The adapter must therefore live on **the same physical box** as the BFLD crate's extractor and privacy gate. The architecture pattern:
|
||||
|
||||
```
|
||||
[ Pi 5 / cognitum-v0 ]
|
||||
├── nexmon firmware (kernel)
|
||||
├── rvcsi-adapter-nexmon (userspace, captures BFI)
|
||||
├── wifi-densepose-bfld (extracts, scores, gates)
|
||||
│ └── privacy_gate → class-2/3 frames only
|
||||
└── wifi-densepose-sensing-server (publishes MQTT + Matter)
|
||||
```
|
||||
|
||||
A network-mode adapter that streams raw BFI from a remote capture host is **explicitly forbidden**. The adapter trait does not include any "remote URL" parameter.
|
||||
|
||||
### 2.4 Channel / bandwidth coverage
|
||||
|
||||
The Nexmon adapter is configured by the existing `rvcsi-adapter-nexmon` channel-hopping schedule (ADR-095 §3.2). For BFLD it adds:
|
||||
|
||||
- Filter for VHT CBFR (action frame, category 21, action 0) and HE CBFR (category 30, action 0).
|
||||
- Per-channel BFI session-tracking — the same beamformer/beamformee pair across a channel hop is reconciled by AP MAC + STA MAC.
|
||||
|
||||
### 2.5 ESP32-S3 local self-reporting (deferred)
|
||||
|
||||
For deployments without a Pi 5 / cognitum-v0 nearby, a degraded BFLD mode runs on the ESP32-S3 itself:
|
||||
|
||||
- Captures only its own AP-link CBFR (self-addressed).
|
||||
- Computes features over the limited window.
|
||||
- Reports a coarsened `presence` + `motion` only — no `identity_risk_score` (insufficient sample diversity).
|
||||
- Emits `BfldFrame` at `privacy_class = 2` with a `flags.bit3 = self_only` marker.
|
||||
|
||||
This path is implemented in firmware as part of P2 / P3 of the ADR-118 rollout, after the Pi 5 path is stable. Effort is small (firmware path reuses the existing CSI capture loop) but the value is also low until ESP32 firmware exposes promiscuous CBFR — which is a Espressif-IDF roadmap item, not under project control.
|
||||
|
||||
### 2.6 Dev path: ruvultra / AX210
|
||||
|
||||
For local dev iteration on the Windows / ruvultra box, the AX210 adapter provides a workable capture path on Linux (ruvultra is Ubuntu 6.17 per CLAUDE.local.md). The AX210 supports 802.11ax + monitor mode with the `iwlwifi` driver patches that have landed upstream. This path is for training-data collection and dev testing, not production.
|
||||
|
||||
---
|
||||
|
||||
## 3. Consequences
|
||||
|
||||
### Positive
|
||||
|
||||
- BFLD ships as a production-ready surface on cognitum-v0 day one — no new hardware procurement.
|
||||
- The adapter-trait design lets new capture paths (AX211, MediaTek Filogic, etc.) slot in without changes to the BFLD crate.
|
||||
- The capture-side privacy boundary is structural: there is no remote-capture code path, so a future PR cannot accidentally introduce one.
|
||||
- ruvultra's AX210 path unblocks training and dev iteration on Linux without depending on the Pi 5 fleet.
|
||||
|
||||
### Negative
|
||||
|
||||
- BFLD's full pipeline depends on cognitum-v0 (or another Pi 5 / Nexmon host) being present in the deployment. Operators without a Pi 5 get only the degraded ESP32-S3 self-reporting path (limited utility).
|
||||
- Nexmon is a third-party kernel module; tracking upstream patches is ongoing maintenance.
|
||||
- The CBFR frame format differs between VHT (802.11ac) and HE (802.11ax); the parser must support both, and any 802.11be (Wi-Fi 7) deployment will require an additional parser path.
|
||||
|
||||
### Neutral
|
||||
|
||||
- ruvultra dev path uses AX210; the AX210 is not the production NIC, so dev/prod parity is via the fixture replay + the Nexmon adapter on cognitum-v0.
|
||||
|
||||
---
|
||||
|
||||
## 4. Alternatives Considered
|
||||
|
||||
### Alt 1: Centralized capture host streams raw BFI to RuView nodes
|
||||
|
||||
Rejected: violates ADR-120 I1 (raw never leaves the capture host). The capture host **is** the BFLD node; there is no separation.
|
||||
|
||||
### Alt 2: Wait for Espressif promiscuous CBFR support
|
||||
|
||||
Rejected: indefinite timeline outside project control. The Pi 5 / Nexmon path is shippable today.
|
||||
|
||||
### Alt 3: Custom Pi 5 firmware fork instead of Nexmon
|
||||
|
||||
Rejected: forking BCM firmware is a huge maintenance burden and Nexmon already does what we need.
|
||||
|
||||
### Alt 4: Only ship the ESP32-S3 self-reporting path
|
||||
|
||||
Rejected: insufficient sample diversity for `identity_risk_score`. The whole point of BFLD is to measure identity leakage; a self-only path cannot do that meaningfully.
|
||||
|
||||
---
|
||||
|
||||
## 5. Acceptance Criteria
|
||||
|
||||
- [ ] **AC1**: `NexmonBfiAdapter` captures ≥ 100 valid CBFR frames per minute from a 2-AP-3-STA test bench on a Pi 5 (cognitum-v0).
|
||||
- [ ] **AC2**: VHT (802.11ac) and HE (802.11ax) CBFR frames are both parsed; mixed-PHY captures produce correctly-typed `BfiCapture` outputs.
|
||||
- [ ] **AC3**: 20/40/80/160 MHz channel widths are all supported (one fixture each in `tests/`).
|
||||
- [ ] **AC4**: `BfiCaptureAdapter` trait has no method accepting a remote URL or socket address.
|
||||
- [ ] **AC5**: ESP32-S3 self-only adapter compiles `#[no_std]` and produces a `BfldFrame` with `flags.bit3 = self_only` set, no `identity_risk_score` field.
|
||||
- [ ] **AC6**: AX210 adapter on ruvultra captures CBFR for at least one fixture-generating dev session.
|
||||
- [ ] **AC7**: Capture loop sustains 10 Hz BFI frame rate on cognitum-v0 without dropping frames over a 10-minute soak test.
|
||||
|
||||
---
|
||||
|
||||
## 6. References
|
||||
|
||||
- ADR-095 / ADR-096 (rvCSI Nexmon adapter)
|
||||
- ADR-028 (ESP32 capability audit)
|
||||
- ADR-110 (ESP32-C6 firmware)
|
||||
- Nexmon BCM43455c0 patches: https://github.com/seemoo-lab/nexmon
|
||||
- Wi-BFI: https://arxiv.org/abs/2309.04408
|
||||
- IEEE 802.11-2020 §19.3.12 (VHT CBFR), §27.3.11 (HE CBFR)
|
||||
- cognitum-v0 fleet entry: `CLAUDE.local.md` (Tailscale fleet table)
|
||||
@@ -1,466 +0,0 @@
|
||||
# ADR-124: rvagent — MCP (stdio + Streamable HTTP) + ruvector npm/TypeScript library for RuView with ruflo integration
|
||||
|
||||
| Field | Value |
|
||||
|-------|-------|
|
||||
| **Status** | Proposed |
|
||||
| **Date** | 2026-05-24 |
|
||||
| **Deciders** | ruv |
|
||||
| **Codename** | **SENSE-BRIDGE** — a typed bridge between the RuView sensing stack and the MCP agent ecosystem |
|
||||
| **Relates to** | [ADR-055](ADR-055-integrated-sensing-server.md) (sensing-server), [ADR-095](ADR-095-rvcsi-edge-rf-sensing-platform.md) (rvCSI), [ADR-097](ADR-097-adopt-rvcsi-as-ruview-csi-runtime.md) (rvCSI adoption), [ADR-115](ADR-115-home-assistant-integration.md) (HA-DISCO), [ADR-116](ADR-116-cog-ha-matter-seed.md) (Seed cog), [ADR-117](ADR-117-pip-wifi-densepose-modernization.md) (PIP-PHOENIX), [ADR-118](ADR-118-bfld-beamforming-feedback-layer-for-detection.md) (BFLD) |
|
||||
| **Tracking issue** | TBD |
|
||||
|
||||
---
|
||||
|
||||
## 1. Context
|
||||
|
||||
### 1.1 The access-layer gap
|
||||
|
||||
The RuView / wifi-densepose Rust stack exposes sensing data through three surfaces: a Tokio/Axum HTTP REST API and WebSocket at `wifi-densepose-sensing-server` (ADR-055); an MQTT namespace under `ruview/<node_id>/*` (ADR-115); and an rvCSI edge runtime (ADR-095/096). None of these surfaces speaks Model Context Protocol (MCP).
|
||||
|
||||
MCP is the dominant inter-process contract through which AI assistants (Claude, GPT, Codex) invoke external capabilities in 2026. Without an MCP bridge, RuView's sensing primitives are invisible to AI-driven automation workflows. An agent cannot ask "who is in the room?" or "subscribe me to fall alerts" without bespoke HTTP integration code in every consuming agent.
|
||||
|
||||
Two concrete user stories that SENSE-BRIDGE resolves:
|
||||
|
||||
1. A developer has a Claude Code session and wants to call `vitals.get_heart_rate` from a prompt — today this requires them to write an HTTP fetch, parse JSON, and handle WebSocket reconnect logic; with SENSE-BRIDGE they install `@ruvnet/rvagent` and the tool is available immediately via `claude mcp add rvagent`.
|
||||
2. A ruflo-orchestrated multi-agent swarm needs real-world presence data to gate a workflow: SENSE-BRIDGE gives the swarm an MCP tool call with the same `mcp__claude-flow__*` signature pattern already used for all other ruflo tools (CLAUDE.md §Ruflo Automation Primitives).
|
||||
|
||||
### 1.2 What rvagent is today
|
||||
|
||||
Research of the ruvnet npm registry profile and the ruflo GitHub repository (issue #1689) establishes that **rvagent is not yet a published standalone npm package** as of 2026-05-24. The name "rvagent" appears in the ruflo project exclusively as a WASM artifact (`rvagent_wasm_bg.wasm`, 588 KB) bundled with the RuFlo Web UI (PR #1687). That artifact exports 13 WASM functions including `callMcp`, `executeTool`, `listTools`, `listGalleryTemplates`, `searchGalleryTemplates`, and `loadGalleryTemplate`. It is an in-browser MCP client runner, not a RuView-specific MCP server.
|
||||
|
||||
There is no `rvagent` package on the npm registry as of this writing. The npm name is therefore available (Q1 in §8). The package name to register is `@ruvnet/rvagent` (scoped form, reduces name-squatting risk) or `rvagent` (unscoped form, simpler `npx` invocation). This ADR proposes `@ruvnet/rvagent`.
|
||||
|
||||
The WASM `callMcp` / `executeTool` surface of the existing ruflo rvagent is the functional model for what the new npm package should expose in TypeScript — but the new package is a **server**, not a client, and its tools are RuView-domain-specific rather than general ruflo-gallery tools.
|
||||
|
||||
### 1.3 MCP transport landscape as of 2026-05-24
|
||||
|
||||
The MCP specification shipped version `2025-03-26` (Streamable HTTP) and `2025-06-18` (current stable) replacing the legacy `2024-11-05` HTTP+SSE transport. Key facts relevant to this ADR:
|
||||
|
||||
- **stdio** remains the recommended local transport. Clients launch the MCP server as a subprocess; the server reads JSON-RPC from stdin and writes to stdout. This is the path `claude mcp add <name> -- npx @ruvnet/rvagent stdio` uses (CLAUDE.md §Quick Setup mirrors this pattern for the claude-flow MCP server).
|
||||
- **Streamable HTTP** (colloquially "SSE" in earlier documentation) replaces the deprecated pure-SSE transport. A single HTTP endpoint at e.g. `POST /mcp` accepts JSON-RPC requests and may respond with `Content-Type: text/event-stream` for streaming, or `application/json` for single-turn responses. The server must validate `Origin` headers and bind to `127.0.0.1` by default (MCP spec security requirement).
|
||||
- The `@modelcontextprotocol/sdk` npm package (latest stable at time of writing) ships `Server`, `StdioServerTransport`, and `StreamableHTTPServerTransport`. A single `Server` instance can be connected to both transports simultaneously by calling `server.connect(transport)` for each.
|
||||
- The legacy `SSEServerTransport` from protocol version `2024-11-05` is deprecated but still ship-able for backwards compatibility with older Claude desktop clients. SENSE-BRIDGE will support it behind an `--legacy-sse` flag for a single release cycle, then remove it.
|
||||
|
||||
### 1.4 ruvector npm surface
|
||||
|
||||
The `ruvector` npm package (version 0.2.x, latest 0.2.25 as of ~2026-05-01) is a napi-rs WASM/Node.js binding of the RuVector Rust crate. It provides:
|
||||
|
||||
- HNSW in-memory vector index (sub-0.5 ms query latency, 50 K+ QPS single-threaded)
|
||||
- 50+ attention mechanisms from the RuVector Rust crate
|
||||
- FlashAttention-3 SIMD path
|
||||
- Graph Neural Network support via `@ruvector/gnn`
|
||||
- Full TypeScript types; ships both ESM and CJS
|
||||
|
||||
The `ruvector` package is already a dependency in the existing Rust workspace's napi-rs node bindings (`ruvector-node` crate, version 0.1.29 on crates.io). The npm package and the Rust crate are developed in the same repository (`github.com/ruvnet/ruvector`). SENSE-BRIDGE can depend on `ruvector` directly without needing to add new Rust FFI — the vector ops needed (HNSW index of pose keypoints, embedding storage for AETHER person re-ID) are already exposed in the npm package's public surface.
|
||||
|
||||
### 1.5 ruflo integration context
|
||||
|
||||
The project's `CLAUDE.md` documents the 3-tier model routing (ADR-026) and the `mcp__claude-flow__*` tool namespace. ruflo exposes 314 native MCP tools. SENSE-BRIDGE adds a new domain namespace `mcp__rvagent__*` that represents RuView sensing capabilities, parallel to but separate from the ruflo tools. The boundary is:
|
||||
- **ruflo**: agent orchestration, memory, swarm coordination, hooks, task management
|
||||
- **rvagent / SENSE-BRIDGE**: RuView-specific sensing — presence, vitals, pose, BFLD, semantic primitives
|
||||
|
||||
ruflo can call rvagent tools via the standard MCP tool-call mechanism; rvagent does not depend on ruflo at runtime (but may optionally use ruflo memory namespaces for persistence).
|
||||
|
||||
---
|
||||
|
||||
## 2. Decision
|
||||
|
||||
Ship `@ruvnet/rvagent` as a standalone npm TypeScript library that:
|
||||
|
||||
1. Exposes a **dual-transport MCP server** (stdio + Streamable HTTP) wrapping RuView sensing primitives.
|
||||
2. Uses `ruvector` (npm) as the vector storage layer for pose embeddings and AETHER-class semantic search, with no reimplementation of vector ops in TypeScript.
|
||||
3. Mirrors the Python `wifi_densepose.client.*` surface (ADR-117 P4 — `python/wifi_densepose/client/ws.py`, `mqtt.py`, `primitives.py`) in TypeScript for parity across runtimes.
|
||||
4. Integrates as a ruflo plugin via the `ruflo-plugin` manifest convention, exposing tools in the `mcp__rvagent__*` namespace callable by ruflo agents.
|
||||
5. Ships strict TypeScript source, ESM + CJS dual output, Node.js 20+ minimum, type definitions in the tarball, zero bundler required.
|
||||
|
||||
---
|
||||
|
||||
## 3. Transport comparison
|
||||
|
||||
| Dimension | stdio | Streamable HTTP |
|
||||
|---|---|---|
|
||||
| **Launch mechanism** | Client forks `npx @ruvnet/rvagent stdio` as subprocess | Client POSTs to `http://host:port/mcp` |
|
||||
| **Primary use case** | Claude Code, Cursor, IDE plugins — local developer flow | Remote agents, ruflo swarms on separate hosts, browser-based dashboards |
|
||||
| **Connection state** | One client per server process; process dies with client | Multiple clients per server process; stateless or session-keyed |
|
||||
| **Streaming** | Newline-delimited JSON on stdout | `text/event-stream` response body |
|
||||
| **Auth** | None needed (process-level isolation) | Bearer token or mTLS required (per MCP spec security rules) |
|
||||
| **RuView sensing-server connectivity** | Server process holds a single WebSocket + MQTT connection to sensing-server; results forwarded to client via JSON-RPC | Server process holds a connection pool; session affinity via `Mcp-Session-Id` header |
|
||||
| **Tailscale fleet** | Works on local node only | Works across Tailscale fleet (cognitum-v0, cognitum-seed-1, ruvultra) with DNS name |
|
||||
| **Origin validation** | Not applicable | Required; server MUST reject cross-origin requests unless CORS policy explicitly permits |
|
||||
| **Resumability** | Not applicable (process is co-located) | Optional `Last-Event-ID` header for stream resumption after reconnect |
|
||||
| **Logging** | stderr — captured by Claude Code, displayed in conversation | Structured JSON to stdout, shipped to ruflo observability (ADR-observability) |
|
||||
| **Process lifecycle** | Ephemeral — exits when Claude Code session ends | Long-lived — suitable for always-on sensing daemon |
|
||||
| **When to choose** | Single developer, local ESP32 (COM9), quick scripting | Fleet deployment, multi-agent ruflo swarms, web dashboards |
|
||||
|
||||
Both transports are served by the same `Server` instance from `@modelcontextprotocol/sdk`. The only difference is the `Transport` class passed to `server.connect()`.
|
||||
|
||||
---
|
||||
|
||||
## 4. MCP tool catalog
|
||||
|
||||
All tools are in the `ruview` namespace. Input schemas below are TypeScript interface stubs; output types mirror the Python dataclasses from `python/wifi_densepose/client/ws.py` and `primitives.py`.
|
||||
|
||||
### 4.1 Tool catalog table
|
||||
|
||||
| Tool name | Input interface | Return shape | RuView surface wrapped |
|
||||
|---|---|---|---|
|
||||
| `ruview.presence.now` | `{ node_id?: string }` | `{ node_id: string; present: boolean; n_persons: number; confidence: number; timestamp_ms: number }` | `EdgeVitalsMessage.presence` / `EdgeVitalsMessage.n_persons` (ws.py:74-88) |
|
||||
| `ruview.vitals.get_breathing` | `{ node_id?: string; window_s?: number }` | `{ node_id: string; breathing_rate_bpm: number \| null; confidence: number; timestamp_ms: number }` | `EdgeVitalsMessage.breathing_rate_bpm` (ws.py:82) |
|
||||
| `ruview.vitals.get_heart_rate` | `{ node_id?: string; window_s?: number }` | `{ node_id: string; heartrate_bpm: number \| null; confidence: number; timestamp_ms: number }` | `EdgeVitalsMessage.heartrate_bpm` (ws.py:83) |
|
||||
| `ruview.vitals.get_all` | `{ node_id?: string }` | `EdgeVitalsResult` (all fields of `EdgeVitalsMessage` except `raw`) | Full `EdgeVitalsMessage` (ws.py:74-88) |
|
||||
| `ruview.pose.latest` | `{ node_id?: string }` | `{ node_id: string; persons: PosePersonResult[]; confidence: number; timestamp_ms: number }` | `PoseDataMessage` (ws.py:91-98) |
|
||||
| `ruview.pose.subscribe` | `{ node_id?: string; duration_s: number; callback_url?: string }` | `{ subscription_id: string; started_at: number; expires_at: number }` | WS stream — streams `PoseDataMessage` events for `duration_s` seconds |
|
||||
| `ruview.primitives.get` | `{ node_id?: string; primitive: SemanticPrimitiveKind }` | `SemanticPrimitiveResult` | `SemanticPrimitive` + `SemanticPrimitiveEvent` (primitives.py:36-75) |
|
||||
| `ruview.primitives.list_active` | `{ node_id?: string }` | `{ primitives: SemanticPrimitiveResult[] }` | All 10 ADR-115 semantic primitives (primitives.py:36-45) |
|
||||
| `ruview.primitives.subscribe` | `{ node_id?: string; primitive?: SemanticPrimitiveKind; duration_s: number }` | `{ subscription_id: string; expires_at: number }` | MQTT topic `homeassistant/+/wifi_densepose_<node>/+/state` (mqtt.py:8-9) |
|
||||
| `ruview.bfld.last_scan` | `{ node_id?: string }` | `{ node_id: string; identity_risk_score: number; privacy_class: number; n_frames: number; timestamp_ms: number }` | MQTT `ruview/<node_id>/bfld/scan_result` (ADR-118/ADR-121) |
|
||||
| `ruview.bfld.subscribe` | `{ node_id?: string; duration_s: number }` | `{ subscription_id: string; expires_at: number }` | MQTT `ruview/<node_id>/bfld/*` |
|
||||
| `ruview.node.list` | `{ }` | `{ nodes: NodeInfo[] }` | MQTT discovery + REST `/api/nodes` |
|
||||
| `ruview.node.status` | `{ node_id: string }` | `NodeStatusResult` | REST `/api/status` or MQTT will-message |
|
||||
| `ruview.vector.search_pose` | `{ query_embedding: number[]; k?: number; node_id?: string }` | `{ matches: VectorMatch[] }` | `ruvector` HNSW index of stored pose keypoints (ADR-016) |
|
||||
| `ruview.vector.store_pose` | `{ pose: PosePersonResult; node_id: string }` | `{ vector_id: string }` | `ruvector` HNSW upsert |
|
||||
|
||||
### 4.1a Policy / governance tools (RUVIEW-POLICY)
|
||||
|
||||
**Added 2026-05-24 per maintainer review.** Once tools can answer "who is in the room?", the library is no longer middleware — it is environmental intelligence infrastructure, and that changes the trust model. Every sensing tool above MUST route through this policy layer before returning data. The layer is enforced server-side in the MCP server, not client-side, so a malicious or misconfigured agent cannot bypass it.
|
||||
|
||||
| Tool name | Input interface | Return shape | Purpose |
|
||||
|---|---|---|---|
|
||||
| `ruview.policy.can_access_vitals` | `{ agent_id: string; node_id: string; vital: "breathing" \| "heart_rate" \| "all" }` | `{ allowed: boolean; reason: string; expires_at?: number }` | Gate every `ruview.vitals.*` call. Default-deny when no policy is registered for the (agent_id, node_id) pair. |
|
||||
| `ruview.policy.can_query_presence` | `{ agent_id: string; scope: "node" \| "fleet"; node_id?: string; zone?: string }` | `{ allowed: boolean; reason: string; redactions?: string[] }` | Fleet-scope presence queries (e.g. "is anyone home?") require explicit scope grant; node-scope is the safer default. |
|
||||
| `ruview.policy.can_subscribe` | `{ agent_id: string; topic: string; duration_s: number }` | `{ allowed: boolean; max_duration_s: number; reason: string }` | Subscriptions can be denied entirely or capped to a shorter duration than requested (e.g. agent asks for 1 h, policy returns 5 min). |
|
||||
| `ruview.policy.redact_identity_fields` | `{ payload: Record<string, unknown>; agent_id: string }` | `{ payload: Record<string, unknown>; redacted_fields: string[] }` | Server-side redaction pass applied to every tool return value. Strips `sta_mac`, raw BFLD matrices, and any keypoint set marked `privacy_class >= 2` per ADR-120. Called automatically by the MCP server; agents never see the un-redacted payload. |
|
||||
| `ruview.policy.audit_log` | `{ agent_id?: string; since_ts?: number }` | `{ events: PolicyAuditEvent[] }` | Returns the policy-decision audit trail for a maintainer-tier agent. Other agents are denied even if they hold valid tool grants — auditability of the auditor is itself a policy decision. |
|
||||
|
||||
Policy storage is a local JSON file (`~/.config/rvagent/policy.json` on Unix, `%APPDATA%\rvagent\policy.json` on Windows) backed by a CLI editor (`npx @ruvnet/rvagent policy grant ...`). Schema mirrors the ADR-010 claims-based authorization model where it exists in the Rust workspace, but the npm library keeps a self-contained store so SENSE-BRIDGE can ship without the full claims infrastructure on day one.
|
||||
|
||||
**Default policy when no file exists**: deny `ruview.vitals.*` and `ruview.policy.audit_log`; allow `ruview.presence.now` and `ruview.node.list` (coarse, non-biometric); allow `ruview.primitives.list_active` with `redact_identity_fields` applied. This is the "explore safely" default so a new install can sanity-check the agent is wired up without leaking biometric data.
|
||||
|
||||
### 4.2 MCP resource catalog
|
||||
|
||||
Resources provide read-only data that can be embedded in the LLM context window.
|
||||
|
||||
| Resource URI | Description | MIME type |
|
||||
|---|---|---|
|
||||
| `ruview://nodes` | JSON list of all discovered nodes (IP, firmware version, capabilities) | `application/json` |
|
||||
| `ruview://nodes/{node_id}/config` | Node configuration (channel, MAC filter, privacy class) | `application/json` |
|
||||
| `ruview://nodes/{node_id}/vitals/latest` | Latest `EdgeVitalsMessage` for the node | `application/json` |
|
||||
| `ruview://nodes/{node_id}/pose/latest` | Latest `PoseDataMessage` | `application/json` |
|
||||
| `ruview://nodes/{node_id}/bfld/latest` | Latest BFLD scan result | `application/json` |
|
||||
| `ruview://primitives/schema` | JSON schema for the 10 semantic primitives (ADR-115) | `application/json` |
|
||||
| `ruview://fleet/topology` | Tailscale-fleet topology (host, TS IP, role) — sourced from local CLAUDE.local.md fleet table | `text/markdown` |
|
||||
|
||||
### 4.3 MCP prompt templates
|
||||
|
||||
| Prompt name | Description | Arguments |
|
||||
|---|---|---|
|
||||
| `ruview.diagnose_node` | Walk the user through node connectivity check, firmware version, and live vitals stream | `{ node_id: string }` |
|
||||
| `ruview.presence_report` | Summarize presence + persons over a time window in natural language | `{ node_id: string; window_s: number }` |
|
||||
| `ruview.vitals_alert_rule` | Generate an HA automation YAML fragment for a vitals threshold alert | `{ primitive: SemanticPrimitiveKind; threshold: number }` |
|
||||
| `ruview.bfld_privacy_audit` | Produce a compliance-ready privacy audit paragraph from the last BFLD scan | `{ node_id: string }` |
|
||||
|
||||
---
|
||||
|
||||
## 5. Dependency graph
|
||||
|
||||
```
|
||||
@ruvnet/rvagent (npm / TypeScript)
|
||||
├── @modelcontextprotocol/sdk ^1.x — MCP Server, StdioServerTransport,
|
||||
│ StreamableHTTPServerTransport, McpError
|
||||
├── ruvector ^0.2 — HNSW vector index, embedding storage
|
||||
│ (napi-rs native bindings; NO reimplementation)
|
||||
├── zod ^3.x — Input schema validation for all tool inputs
|
||||
├── ws ^8.x — WebSocket client to sensing-server /ws/sensing
|
||||
│ └── @types/ws
|
||||
├── mqtt ^5.x — MQTT client for ruview/<node_id>/* topics
|
||||
│ (replaces paho-mqtt; mqtt.js is the npm standard)
|
||||
├── node-fetch / undici — — HTTP client for REST endpoints on sensing-server
|
||||
└── tsup (dev) — ESM + CJS dual build
|
||||
|
||||
Runtime back-ends (NOT bundled — must be reachable at runtime):
|
||||
├── wifi-densepose-sensing-server (Rust binary)
|
||||
│ ├── REST API :3000 /api/*
|
||||
│ ├── WebSocket :8765 /ws/sensing
|
||||
│ └── MQTT via local broker or ruview/<node_id>/*
|
||||
├── MQTT broker (mosquitto or broker at cognitum-v0:1883)
|
||||
└── ruvector HNSW index (in-process via napi-rs; no separate service)
|
||||
```
|
||||
|
||||
Key integration boundary: **ruvector is purely in-process**. The HNSW index lives in the `@ruvnet/rvagent` Node.js process memory, populated from pose keypoints received over the sensing-server WebSocket. There is no separate vector service. This matches the architecture of `wifi-densepose-ruvector` (Rust crate in the workspace) which is also in-process.
|
||||
|
||||
---
|
||||
|
||||
## 6. Python client surface parity table
|
||||
|
||||
The Python client in `python/wifi_densepose/client/` (ADR-117 P4) is the canonical reference for the TS surface. TypeScript should mirror it so users see the same domain model across runtimes.
|
||||
|
||||
| Python class / enum | File | TypeScript equivalent in @ruvnet/rvagent |
|
||||
|---|---|---|
|
||||
| `SensingMessage` | `ws.py:54-60` | `interface SensingMessage` |
|
||||
| `ConnectionEstablishedMessage` | `ws.py:63-70` | `interface ConnectionEstablishedMessage extends SensingMessage` |
|
||||
| `EdgeVitalsMessage` | `ws.py:74-88` | `interface EdgeVitalsMessage extends SensingMessage` |
|
||||
| `PoseDataMessage` | `ws.py:91-98` | `interface PoseDataMessage extends SensingMessage` |
|
||||
| `SensingClient` (asyncio) | `ws.py:160` | `class SensingClient` (EventEmitter-based, async iterator) |
|
||||
| `SemanticPrimitive` (enum) | `primitives.py:36-45` | `enum SemanticPrimitive` |
|
||||
| `SemanticPrimitiveEvent` | `primitives.py:60-75` | `interface SemanticPrimitiveEvent` |
|
||||
| `SemanticPrimitiveListener` | `primitives.py:84-155` | `class SemanticPrimitiveListener` |
|
||||
| `RuViewMqttClient` | `mqtt.py:56` | `class RuViewMqttClient` (wraps mqtt.js `MqttClient`) |
|
||||
| `_topic_matches` | `mqtt.py:237-257` | `function topicMatches(pattern, topic)` |
|
||||
|
||||
---
|
||||
|
||||
## 7. Implementation plan
|
||||
|
||||
```
|
||||
P1 ──► P2 ──► P3 ──► P4 ──► P5
|
||||
npm MCP MCP ruvector npm
|
||||
scaffold stdio SSE integration publish + ruflo bridge
|
||||
```
|
||||
|
||||
### P1 — Scaffold (1 week)
|
||||
|
||||
**Goal**: an installable npm package skeleton that compiles and passes CI.
|
||||
|
||||
- [ ] Create `npm/rvagent/` directory in the repo (mirrors `python/wifi_densepose/`). Do not add to `v2/` Rust workspace.
|
||||
- [ ] `package.json`: name `@ruvnet/rvagent`, version `0.1.0-alpha.1`, `type: "module"`, exports map with `./package.json`, `.` (ESM + CJS), `./stdio`, `./http`.
|
||||
- [ ] `tsconfig.json`: `strict: true`, `target: ES2022`, `module: NodeNext`, `moduleResolution: NodeNext`.
|
||||
- [ ] `tsup.config.ts`: dual `esm + cjs` build, `dts: true`.
|
||||
- [ ] Add `@modelcontextprotocol/sdk`, `ruvector`, `zod`, `ws`, `mqtt`, `tsup` as deps / devDeps.
|
||||
- [ ] CI job: `npm ci && npm run build` on `ubuntu-latest` with Node 20, 22.
|
||||
- [ ] Stub `src/index.ts` that exports package version string. Import succeeds.
|
||||
|
||||
### P2 — MCP stdio server (2 weeks)
|
||||
|
||||
**Goal**: `npx @ruvnet/rvagent stdio` connects to a running sensing-server over WebSocket + MQTT and exposes the tool catalog from §4.1 over stdio transport.
|
||||
|
||||
- [ ] `src/server.ts` — create `McpServer` instance, register all tools from §4.1 with Zod input schemas. Tools that require a live sensing-server connection return a structured error `{ error: "SENSING_SERVER_UNAVAILABLE" }` rather than throwing, so the LLM gets useful context.
|
||||
- [ ] `src/transports/stdio.ts` — `StdioServerTransport` entrypoint. Reads `RUVIEW_HOST` and `RUVIEW_PORT` env vars (default `localhost:8765` WS, `localhost:3000` REST, `localhost:1883` MQTT).
|
||||
- [ ] `src/sensing/ws-client.ts` — TypeScript port of `python/wifi_densepose/client/ws.py`. Async generator yielding `SensingMessage` variants. Reconnect with exponential back-off (the Python client explicitly does not reconnect — the TS one should, because the stdio process is long-lived).
|
||||
- [ ] `src/sensing/mqtt-client.ts` — TypeScript port of `python/wifi_densepose/client/mqtt.py` using `mqtt.js ^5`. Per-pattern callbacks, `topicMatches` wildcard helper.
|
||||
- [ ] `src/sensing/primitives.ts` — `SemanticPrimitive` enum + `SemanticPrimitiveListener`. Mirror of `primitives.py`.
|
||||
- [ ] Tool implementations for the 5 highest-priority tools: `ruview.presence.now`, `ruview.vitals.get_all`, `ruview.pose.latest`, `ruview.primitives.get`, `ruview.node.list`.
|
||||
- [ ] Resource implementations: `ruview://nodes`, `ruview://nodes/{node_id}/vitals/latest`.
|
||||
- [ ] Integration test: spin up `sensing-server --mock-frames` in Docker; assert `npx @ruvnet/rvagent stdio` receives a `ruview.vitals.get_all` tool call response with non-null `breathing_rate_bpm`.
|
||||
- [ ] `claude mcp add rvagent -- npx @ruvnet/rvagent stdio` smoke-test (manual).
|
||||
|
||||
### P3 — MCP Streamable HTTP server (2 weeks)
|
||||
|
||||
**Goal**: `npx @ruvnet/rvagent serve --port 3100` starts an HTTP server that serves the full MCP tool catalog over Streamable HTTP (and optionally legacy SSE for backwards compat).
|
||||
|
||||
- [ ] `src/transports/http.ts` — `StreamableHTTPServerTransport` backed by an Express 5 or Hono app (Hono preferred for lightweight edge deployability).
|
||||
- [ ] Session management: issue `Mcp-Session-Id` UUIDs on `POST /mcp` initialize; reject subsequent requests without session header with HTTP 400.
|
||||
- [ ] Origin validation: configurable `RUVIEW_ALLOWED_ORIGINS` env var; default reject all cross-origin requests (MCP spec security requirement §Streamable HTTP §Security Warning).
|
||||
- [ ] Auth: optional `RUVIEW_BEARER_TOKEN` env var. If set, require `Authorization: Bearer <token>` on all requests. This mirrors `v2/crates/wifi-densepose-sensing-server/src/bearer_auth.rs`.
|
||||
- [ ] Legacy SSE compatibility: `--legacy-sse` flag mounts the deprecated `SSEServerTransport` on `/sse` + `/message` for Claude Desktop clients on protocol version `2024-11-05`. Document this as a single-release compat shim.
|
||||
- [ ] Remaining tools from §4.1: `ruview.vitals.get_breathing`, `ruview.vitals.get_heart_rate`, `ruview.pose.subscribe`, `ruview.primitives.list_active`, `ruview.primitives.subscribe`, `ruview.bfld.last_scan`, `ruview.bfld.subscribe`, `ruview.node.status`.
|
||||
- [ ] Prompt template registrations from §4.3.
|
||||
- [ ] Integration test: `curl -X POST http://localhost:3100/mcp` with a `tools/list` request; assert the response lists all 15 tools.
|
||||
- [ ] Docker Compose entry for local fleet testing: `rvagent` HTTP container talking to `sensing-server` and `mosquitto` containers.
|
||||
|
||||
### P4 — ruvector integration (1 week)
|
||||
|
||||
**Goal**: `ruview.vector.search_pose` and `ruview.vector.store_pose` tools work end-to-end with a live HNSW index.
|
||||
|
||||
- [ ] `src/vector/index.ts` — wrapper around `ruvector` napi-rs bindings. Initialise an HNSW index at server startup; expose `store(id, embedding)` and `search(embedding, k)`.
|
||||
- [ ] Pose-to-embedding pipeline: when a `PoseDataMessage` arrives from the WS client, extract the 17-keypoint array, normalise to `[-1, 1]` per keypoint coordinate, flatten to a 34-dimensional float vector, store in HNSW with `node_id:person_index:timestamp_ms` as the ID.
|
||||
- [ ] `src/vector/aether.ts` — AETHER-style cross-viewpoint search (ADR-024): given a pose embedding query, search HNSW index across all stored poses and return the top-k matches with their source node IDs. This enables cross-node person re-identification via the MCP tool without any network call between nodes.
|
||||
- [ ] Verify that the `ruvector` napi-rs binary loads correctly on Node 20 linux/x86_64, macos/arm64, and windows/amd64. Document any platform-specific caveats.
|
||||
- [ ] Index persistence: optional `RUVIEW_VECTOR_DB_PATH` env var. If set, persist the HNSW index to disk using `ruvector`'s serialise API. If unset, in-memory only (default for stdio transport).
|
||||
- [ ] Integration test: feed 100 synthetic pose frames with known clustering, assert `ruview.vector.search_pose` retrieves nearest neighbours with recall >0.9.
|
||||
|
||||
### P5 — npm publish + ruflo bridge (1 week)
|
||||
|
||||
**Goal**: `npm install @ruvnet/rvagent` works for consumers; ruflo agents can call `mcp__rvagent__*` tools through the standard claude-flow MCP registration.
|
||||
|
||||
- [ ] Populate `package.json` with `publishConfig: { access: "public" }`, `engines: { node: ">=20" }`, `files` whitelist (`dist/`, `src/`, `README.md`).
|
||||
- [ ] Publish `@ruvnet/rvagent@0.1.0-alpha.1` to npm under the `@ruvnet` scope.
|
||||
- [ ] ruflo plugin manifest: create `.claude/plugins/rvagent/plugin.json` following the ruflo `plugin/` convention in the ruflo repo. The manifest registers the HTTP transport URL (configurable) and maps `mcp__rvagent__*` tool calls to the rvagent MCP server.
|
||||
- [ ] `ruview` skill in `.claude/agents/` (CLAUDE.md §Available Agents): an agent description that documents the rvagent tool namespace for ruflo orchestration.
|
||||
- [ ] `claude mcp add rvagent -- npx @ruvnet/rvagent stdio` tested against claude-flow MCP server on the local dev machine (ruvzen host on CLAUDE.local.md fleet).
|
||||
- [ ] Document the fleet deployment pattern: run `npx @ruvnet/rvagent serve` on cognitum-v0 (Tailscale IP 100.77.59.83, port 50060 range to avoid conflict with existing services; see CLAUDE.local.md services table). Register the URL as a remote MCP server in `.claude/settings.json`.
|
||||
- [ ] Publish announcement: link from project README (`docs/` link, not root README per CLAUDE.md rules).
|
||||
|
||||
---
|
||||
|
||||
## 8. Open questions
|
||||
|
||||
**Q1. npm package name availability**
|
||||
`rvagent` (unscoped) does not appear in the npm registry as of 2026-05-24 based on search results. `@ruvnet/rvagent` is definitely available (the `@ruvnet` scope is owned by ruvnet per the npm profile page). Should the package be published unscoped (`rvagent`) for simpler `npx rvagent stdio` invocation, or scoped (`@ruvnet/rvagent`) for namespace clarity? The decision should be made before P5 because the npm name is permanent.
|
||||
|
||||
**Q2. ruvector binary compatibility on Windows**
|
||||
The `ruvector` npm package is a napi-rs native addon. The project's primary development machine (ruvzen) is Windows 11. It is not confirmed whether `ruvector@0.2.25` ships a prebuilt Windows binary in its npm tarball or requires a Rust toolchain to compile. If no Windows binary is shipped, developers on ruvzen would need the Rust toolchain installed to use `@ruvnet/rvagent`. This must be confirmed before P5 by running `npm install ruvector` on ruvzen.
|
||||
|
||||
**Q3. ruvector TypeScript API stability**
|
||||
ruvector `0.2.x` is not a 1.0 release. The HNSW insert and search API surface may change between minor versions. SENSE-BRIDGE P4 should pin `ruvector@~0.2.25` and document the version constraint explicitly. The question is whether ruvector publishes a changelog with breaking-change notices.
|
||||
|
||||
**Q4. MCP tool call latency budget — RESOLVED**
|
||||
Raw sensing frequency ≠ agent interaction frequency. If a tool call ever waits on the next CSI frame, agent orchestration latency becomes physically coupled to RF acquisition jitter, which is unacceptable at scale. The library MUST take option (a) — return from a continuous local cache:
|
||||
|
||||
1. **Continuous local cache**: on startup the rvagent MCP server opens one WebSocket + one MQTT subscription per configured sensing-server endpoint and ingests every frame into an in-memory `Map<node_id, EdgeVitalsMessage>` (plus parallel maps for `PoseDataMessage` and BFLD). Cache hits return in <1 ms regardless of CSI frame rate.
|
||||
2. **Event-driven invalidation**: the cache entry's `received_at` timestamp is bumped on every received frame. The cache itself is never purged on a timer — only overwritten when fresh data lands, so a node that went quiet still serves its last-known value.
|
||||
3. **Bounded freshness windows**: each tool accepts an optional `max_age_ms` argument (default 1000). If the cached `received_at` is older than `max_age_ms`, the tool returns `{ value: null, reason: "stale", last_seen_ms: N, threshold_ms: max_age_ms }` rather than blocking. The agent decides whether to accept the staleness, raise to the user, or escalate to a `ruview.node.status` health check.
|
||||
|
||||
This pattern is required because P3's Streamable HTTP transport may serve dozens of concurrent agent sessions — see Q8. A shared cache + per-session freshness contract scales; per-session WS connections do not.
|
||||
|
||||
P2 must implement this cache; P3 must verify that fanning the same cache to N concurrent HTTP sessions still maintains <1 ms median tool-call latency under load.
|
||||
|
||||
**Q5. Subscription tool lifetime management**
|
||||
Tools `ruview.pose.subscribe`, `ruview.primitives.subscribe`, and `ruview.bfld.subscribe` return a `subscription_id` and stream events. In the stdio transport there is one client, so this is straightforward. In the HTTP transport with multiple sessions, subscription state must be tracked per `Mcp-Session-Id`. When a session expires (HTTP 404) or is deleted via HTTP DELETE, the subscription must be cleaned up. The lifecycle mechanism is not fully designed — this is a known gap that P3 must close.
|
||||
|
||||
**Q6. AETHER embedding dimension**
|
||||
The ADR proposes a 34-dimensional pose embedding (17 keypoints × 2 coordinates). The actual AETHER embedding model (ADR-024) uses a learned contrastive encoder, not raw keypoints. If the AETHER ONNX model is available in the Rust workspace at P4 time, the embedding should use it. If not, the raw-keypoint approach is a reasonable placeholder. The question is whether `wifi-densepose-nn` exposes the AETHER encoder in a form that can be called from Node.js without bundling libtorch in the npm package.
|
||||
|
||||
**Q7. ruflo plugin manifest format**
|
||||
The ruflo plugin convention (`plugin/` directory in the ruflo repo) is not fully documented in a public spec as of this writing. The manifest format was inferred from the `ruflo-plugins.gif` directory listing and referenced in issue #952. Before P5, the actual plugin manifest schema must be confirmed from the ruflo repo so SENSE-BRIDGE does not ship an incompatible manifest.
|
||||
|
||||
**Q8. MQTT vs direct WebSocket for Streamable HTTP transport**
|
||||
In the stdio transport, rvagent holds a single WebSocket + single MQTT connection to the sensing-server. In the Streamable HTTP transport (potentially serving dozens of agent sessions), maintaining one connection per session is not scalable. The recommended pattern is a single shared connection per (sensing-server endpoint), multiplexed to all sessions. The implementation complexity of this fan-out is non-trivial and is not fully specified here.
|
||||
|
||||
**Q9. Legacy SSE deprecation timeline**
|
||||
The MCP `2024-11-05` SSE transport is deprecated in the current spec but Claude Desktop versions prior to the spec `2025-03-26` update still use it. SENSE-BRIDGE proposes `--legacy-sse` for one release cycle. The question is which specific Claude Desktop version drops legacy SSE support, and whether any of the active fleet nodes (cognitum-v0, cognitum-seed-1) run a Claude Desktop version old enough to need it.
|
||||
|
||||
**Q10. Node.js vs Bun runtime**
|
||||
The ruflo monorepo uses `bun` as the primary runtime (per `bunfig.toml` in `v3/`). Should `@ruvnet/rvagent` also support Bun? Bun's napi-rs compatibility for native addons like `ruvector` is improving but not guaranteed for 0.2.x. The P1 CI should test on Node 20 first; Bun support can be declared as a stretch goal for P5.
|
||||
|
||||
---
|
||||
|
||||
## 9. Alternatives considered
|
||||
|
||||
### Alt-A — Python-only client (extend ADR-117 with MCP bindings)
|
||||
|
||||
Add `wifi_densepose.mcp` as a P6 module in the PIP-PHOENIX wheel (ADR-117). The Python MCP SDK (`mcp[cli]`) supports both stdio and HTTP transports and the PyO3 bindings give direct access to the sensing types.
|
||||
|
||||
**Rejected because**: Python is not the dominant runtime for MCP server hosting in 2026 — the ecosystem tooling (Claude Desktop, Claude Code `mcp add`, ruflo) is TypeScript-first. A Python MCP server requires the full pip install including PyO3 bindings, which is a heavier install than `npx @ruvnet/rvagent stdio`. The ruflo plugin format is TypeScript. ADR-117 is already sizeable; adding MCP to it conflates two distinct concerns (Python developer library vs. AI agent interface). Python MCP remains a viable future addition (Q10 for a future ADR) but is not the right first-ship target.
|
||||
|
||||
### Alt-B — Pure WebSocket/REST client without MCP framing
|
||||
|
||||
Ship a TypeScript client library `@ruvnet/ruview-client` that wraps the sensing-server WebSocket and REST API without the MCP layer. Consumers who want MCP integration would wrap it themselves.
|
||||
|
||||
**Rejected because**: it solves the connectivity problem but not the agent integration problem. Without MCP framing, Claude Code and ruflo agents cannot discover or call RuView capabilities through the standard `mcp__*` namespace — they would need custom prompt injection or bespoke tool definitions per agent. The whole value proposition of this ADR is that a single `claude mcp add rvagent` command makes all RuView primitives discoverable to any MCP-capable AI assistant. Splitting the library forces every consumer to re-add the MCP layer.
|
||||
|
||||
### Alt-C — Embed MCP server inside the existing wifi-densepose-sensing-server Rust binary
|
||||
|
||||
Add an MCP endpoint to the existing Axum server in `v2/crates/wifi-densepose-sensing-server/` (`v2/crates/wifi-densepose-sensing-server/src/main.rs`). This would use the `rmcp` Rust crate (Model Context Protocol SDK for Rust) and expose MCP over an additional port.
|
||||
|
||||
**Rejected because**: (a) it couples the release cycle of the npm-hosted MCP interface to the firmware/Rust release cycle, which are on separate cadences — a new MCP tool that merely adds a JSON field should not require a firmware rebuild; (b) the ruflo plugin ecosystem is TypeScript and expects npm packages, not Rust binaries; (c) the ruvector vector layer is a napi-rs Node.js native module and cannot be called directly from a Rust process without going through the napi-rs server-side API, adding unnecessary complexity; (d) the sensing-server binary is already 15-30 MB stripped — adding the MCP endpoint and its JSON-RPC machinery would further bloat it. This alternative is worth revisiting if the Rust `rmcp` crate matures and the vector layer migrates fully to native Rust, but it is not appropriate for the first implementation.
|
||||
|
||||
### Alt-D — Wrapping the existing ruflo WASM rvagent in a RuView shim
|
||||
|
||||
The ruflo WASM rvagent (`rvagent_wasm_bg.wasm`) already exports `callMcp` / `executeTool` / `listTools`. One could define a RuView shim that registers custom tools into the ruflo WASM rvagent gallery.
|
||||
|
||||
**Rejected because**: the ruflo WASM rvagent is an in-browser MCP *client* runner for the ruflo gallery, not a general-purpose MCP server that can expose sensing data. Its 13 exported functions are focused on template management and ruflo-gallery operations. Patching sensing tools into a browser WASM module is the wrong architecture for a server-side sensing bridge. The naming overlap is a reason to publish the new package promptly and clearly document the distinction.
|
||||
|
||||
---
|
||||
|
||||
## 10. Compatibility
|
||||
|
||||
### 10.1 Backwards compatibility with ADR-117 (PIP-PHOENIX) Python client
|
||||
|
||||
SENSE-BRIDGE does not replace the Python client. Both can coexist:
|
||||
- Python integrators use `from wifi_densepose.client import SensingClient` (ADR-117).
|
||||
- TypeScript / MCP integrators use `import { SensingClient } from "@ruvnet/rvagent"`.
|
||||
- MCP-capable AI assistants use `claude mcp add rvagent -- npx @ruvnet/rvagent stdio`.
|
||||
|
||||
All three talk to the same sensing-server backend; there is no shared state between the Python and TypeScript clients beyond what the sensing-server itself maintains.
|
||||
|
||||
### 10.2 Sensing-server API contract
|
||||
|
||||
SENSE-BRIDGE depends on the sensing-server WebSocket protocol documented in `v2/crates/wifi-densepose-sensing-server/src/main.rs` (referenced in `python/wifi_densepose/client/ws.py:6-13`). The three message types (`connection_established`, `pose_data`, `edge_vitals`) are stable across v0.7.x releases. If the sensing-server adds new message types, SENSE-BRIDGE follows the same pattern as the Python client: unknown `type` values yield a plain `SensingMessage` rather than an error, ensuring forward compatibility.
|
||||
|
||||
### 10.3 MCP protocol version
|
||||
|
||||
SENSE-BRIDGE targets MCP protocol version `2025-06-18` (current stable). It will include backwards compatibility with `2025-03-26` (Streamable HTTP without session management) and optionally `2024-11-05` (legacy SSE via `--legacy-sse` flag). Protocol version `2025-06-18` requires the `MCP-Protocol-Version` header on HTTP requests; SENSE-BRIDGE validates this per spec.
|
||||
|
||||
### 10.4 Node.js version
|
||||
|
||||
Minimum Node.js 20 LTS. Node 22 is supported and recommended for production (active LTS as of 2026). The `ruvector` napi-rs bindings must be confirmed compatible with both (Q2). Node 18 is EOL and explicitly not supported.
|
||||
|
||||
### 10.5 MQTT broker compatibility
|
||||
|
||||
SENSE-BRIDGE uses `mqtt.js ^5` which implements MQTT 3.1.1 and MQTT 5.0. The `mosquitto` local broker (CLAUDE.local.md §Local mosquitto) and cognitum-v0's MQTT stack (CLAUDE.local.md fleet table) are both compatible. TLS mode is optional via `RUVIEW_MQTT_TLS=1` env var.
|
||||
|
||||
---
|
||||
|
||||
## 11. Consequences
|
||||
|
||||
### 11.1 Positive consequences
|
||||
|
||||
- Any MCP-capable AI assistant can query RuView presence, vitals, pose, and BFLD data with zero custom integration code after `claude mcp add rvagent`.
|
||||
- ruflo multi-agent swarms gain first-class access to real-world sensing data, enabling swarms to gate decisions on physical events (fall detected → page caregiver workflow).
|
||||
- The TypeScript surface provides a second reference implementation of the sensing-server client protocol alongside the Python client (ADR-117), validating the protocol design against two independent consumers.
|
||||
- The ruvector HNSW integration enables cross-node person re-identification entirely within the rvagent process — no additional network calls between sensing nodes.
|
||||
|
||||
### 11.2 Negative consequences / risks
|
||||
|
||||
| Risk | Likelihood | Severity | Mitigation |
|
||||
|---|---|---|---|
|
||||
| **ruvector napi-rs not building on Windows** | Medium | Medium | Confirm in P1 CI; if binaries not prebuilt, document requirement of Rust toolchain on Windows |
|
||||
| **MCP protocol churn** — spec updated twice in 2025; another update in 2026 possible | Medium | Low | Pin `@modelcontextprotocol/sdk` to a minor range; wrap SDK calls behind an internal `transport.ts` abstraction so changes are isolated |
|
||||
| **Subscription lifecycle bugs** — zombie subscriptions if session cleanup is missed | High | Medium | Implement per-session resource registry with TTL; all subscriptions auto-expire after `duration_s` even if session is not explicitly deleted |
|
||||
| **sensing-server WS disconnect** — stdio process dies if not reconnecting | Low | High | Implement exponential back-off reconnect in `ws-client.ts`; emit `{ error: "RECONNECTING" }` tool responses during gap |
|
||||
| **npm name collision** — `rvagent` taken by another publisher before P5 | Low | Medium | Publish `@ruvnet/rvagent` scoped; use that name throughout |
|
||||
| **ruflo plugin manifest incompatibility** — format not publicly specced | Medium | Medium | Confirm format in P5 preparation; use the minimal required fields only |
|
||||
| **Sensing-tool surface becomes a surveillance API** — "who is in the room" is a privacy-charged primitive | High | High | RUVIEW-POLICY layer (§4.1a) gates every sensing call; default-deny for biometric tools; redaction applied server-side so agents cannot opt out |
|
||||
|
||||
### 11.3 Strategic implication: ambient-sensing normalization layer
|
||||
|
||||
The MCP tool catalog in §4 is RuView-WiFi-CSI-specific today. The shape of the catalog — `presence.now`, `vitals.get_*`, `pose.latest`, `primitives.*`, `bfld.*` — is **modality-agnostic at the semantic layer**: the same tools could be backed by any sensing modality that produces the same questions.
|
||||
|
||||
If the project later adds BLE, mmWave (e.g. the ESP32-C6 + Seeed MR60BHA2 already on COM4 per CLAUDE.md), LiDAR, thermal, camera, radar, or UWB inputs, the rvagent MCP surface stays the same. Only the source-multiplexer behind `cache.ts` changes — it now ingests from multiple modalities and resolves conflicts (e.g. WiFi CSI says "presence: true" but mmWave says "presence: false" → fusion policy decides; this is the kind of decision the RUVIEW-POLICY layer can also gate).
|
||||
|
||||
This positions the npm package not as "a WiFi client" but as the **semantic-environment API**: agents ask "is anyone here?" without caring which radio answered. The competitive landscape (Aqara FP2, ESPHome LD2410) exposes raw telemetry; SENSE-BRIDGE exposes environmental cognition.
|
||||
|
||||
The follow-on ADR (call it ADR-13x — RUVIEW-FUSION) would formalize the per-modality adapter contract. It is intentionally out of scope for ADR-124 — this ADR ships the WiFi-CSI path only — but the tool catalog and policy layer are designed to absorb additional modalities without API churn.
|
||||
|
||||
---
|
||||
|
||||
## 12. Acceptance criteria
|
||||
|
||||
The following must all pass before ADR-124 is considered Accepted:
|
||||
|
||||
- [ ] `npm install @ruvnet/rvagent` succeeds on Node 20/22, linux/x86_64, macos/arm64, windows/amd64 with no Rust toolchain required (ruvector prebuilts must ship).
|
||||
- [ ] `npx @ruvnet/rvagent stdio` starts and responds to a `tools/list` JSON-RPC request with the 15 tools from §4.1.
|
||||
- [ ] `npx @ruvnet/rvagent serve --port 3100` starts; `curl -X POST http://localhost:3100/mcp -H "Content-Type: application/json" -d '{"jsonrpc":"2.0","method":"tools/list","id":1}'` returns the tool list.
|
||||
- [ ] `ruview.vitals.get_all` with a running `sensing-server --mock-frames` returns `breathing_rate_bpm` and `heartrate_bpm` values within 5 seconds.
|
||||
- [ ] `ruview.vector.store_pose` followed by `ruview.vector.search_pose` with the same embedding returns the stored pose as the top-1 match.
|
||||
- [ ] `claude mcp add rvagent -- npx @ruvnet/rvagent stdio` followed by `/mcp` in a Claude Code session shows the rvagent tools listed.
|
||||
- [ ] All MCP tool input schemas are validated via Zod; an invalid input returns an MCP `INVALID_PARAMS` error, not an unhandled exception.
|
||||
- [ ] TypeScript strict-mode compilation (`tsc --noEmit`) passes with zero errors.
|
||||
- [ ] `npm run build` produces both ESM (`dist/esm/`) and CJS (`dist/cjs/`) outputs with `.d.ts` type declarations.
|
||||
- [ ] The published npm tarball size is `≤ 10 MB` including the ruvector napi-rs binary for the current platform.
|
||||
|
||||
---
|
||||
|
||||
## 13. References
|
||||
|
||||
### This repo
|
||||
|
||||
- `python/wifi_densepose/client/ws.py` — WebSocket client (ADR-117 P4): connection protocol, message types `connection_established`, `pose_data`, `edge_vitals`
|
||||
- `python/wifi_densepose/client/mqtt.py` — MQTT client (ADR-117 P4): topic namespaces, wildcard matching
|
||||
- `python/wifi_densepose/client/primitives.py` — Semantic primitive enum and listener (ADR-117 P4): 10 ADR-115 primitives
|
||||
- `v2/crates/wifi-densepose-sensing-server/src/main.rs` — Axum server: REST API, WebSocket endpoint `/ws/sensing`
|
||||
- `v2/crates/wifi-densepose-sensing-server/src/bearer_auth.rs` — Bearer token auth pattern for HTTP server
|
||||
- `v2/crates/wifi-densepose-sensing-server/src/semantic/` — 10 semantic primitive modules
|
||||
- `v2/crates/wifi-densepose-sensing-server/src/mqtt/` — MQTT publisher, discovery, topic routing
|
||||
- `docs/adr/ADR-055-integrated-sensing-server.md` — Sensing-server architectural context
|
||||
- `docs/adr/ADR-095-rvcsi-edge-rf-sensing-platform.md` — rvCSI edge runtime
|
||||
- `docs/adr/ADR-115-home-assistant-integration.md` — MQTT topic structure, 10 semantic primitives, 21 HA entities
|
||||
- `docs/adr/ADR-117-pip-wifi-densepose-modernization.md` — PIP-PHOENIX: Python client and PyO3 bindings (the Python-runtime parallel to this ADR)
|
||||
- `docs/adr/ADR-118-bfld-beamforming-feedback-layer-for-detection.md` — BFLD crate: `BfldEvent` MQTT topics
|
||||
- `docs/adr/ADR-024-contrastive-csi-embedding-model.md` — AETHER person re-ID embeddings
|
||||
- `docs/adr/ADR-016-ruvector-integration.md` — RuVector integration in the Rust workspace
|
||||
- `CLAUDE.md` — Project config: 3-tier model routing (ADR-026), ruflo MCP tools, `mcp__claude-flow__*` namespace
|
||||
- `CLAUDE.local.md` — Fleet table: Tailscale hosts, cognitum-v0 services table, local mosquitto pattern
|
||||
|
||||
### External
|
||||
|
||||
- [Model Context Protocol specification 2025-06-18](https://modelcontextprotocol.io/specification/2025-06-18/basic/transports) — Transports: stdio and Streamable HTTP
|
||||
- [MCP TypeScript SDK — github.com/modelcontextprotocol/typescript-sdk](https://github.com/modelcontextprotocol/typescript-sdk) — `Server`, `StdioServerTransport`, `StreamableHTTPServerTransport`
|
||||
- [@modelcontextprotocol/sdk on npm](https://www.npmjs.com/package/@modelcontextprotocol/sdk)
|
||||
- [ruvector on npm](https://www.npmjs.com/package/ruvector) — v0.2.25, napi-rs HNSW vector DB
|
||||
- [ruvnet npm profile](https://www.npmjs.com/~ruvnet) — confirms `@ruvnet` scope ownership
|
||||
- [RuVector GitHub](https://github.com/ruvnet/ruvector) — Rust source + napi-rs node bindings
|
||||
- [ruflo (claude-flow) GitHub](https://github.com/ruvnet/ruflo) — ruflo plugin manifest convention, `v3/` structure
|
||||
- [ruflo issue #1689](https://github.com/ruvnet/ruflo/issues/1689) — documents existing rvagent WASM exports (`callMcp`, `executeTool`, `listTools`) and distinguishes them from this ADR's server-side rvagent
|
||||
- [Why MCP Deprecated SSE — fka.dev](https://blog.fka.dev/blog/2025-06-06-why-mcp-deprecated-sse-and-go-with-streamable-http/) — rationale for Streamable HTTP over legacy SSE
|
||||
- [MCP TypeScript SDK dual-transport patterns — dev.to](https://dev.to/zoricic/understanding-mcp-server-transports-stdio-sse-and-http-streamable-5b1p)
|
||||
@@ -1,285 +0,0 @@
|
||||
# ADR-125: RuView ↔ Apple Home native HAP bridge — direct HomeKit accessory advertisement from the Seed
|
||||
|
||||
| Field | Value |
|
||||
|-------|-------|
|
||||
| **Status** | Proposed |
|
||||
| **Date** | 2026-05-25 |
|
||||
| **Deciders** | ruv |
|
||||
| **Codename** | **APPLE-FABRIC** — RuView speaks HomeKit directly so Apple HomePod / Apple TV act as the discovery + automation surface with zero Home-Assistant middle layer |
|
||||
| **Relates to** | [ADR-115](ADR-115-home-assistant-integration.md) (HA-DISCO MQTT publisher), [ADR-116](ADR-116-cog-ha-matter-seed.md) (cog-ha-matter §P7 left HAP/Matter as a feature-flag stub), [ADR-118](ADR-118-bfld-beamforming-feedback-layer-for-detection.md) (BFLD presence + identity-risk events), [ADR-122](ADR-122-bfld-ruview-ha-matter-exposure.md) (BFLD HA/Matter exposure) |
|
||||
| **Tracking issue** | TBD |
|
||||
|
||||
---
|
||||
|
||||
## 1. Context
|
||||
|
||||
### 1.1 The misunderstanding worth correcting once
|
||||
|
||||
A naive integration tries to **push** data to a HomePod — open a socket, send a JSON-RPC, call an MQTT topic on `homepod.local`. Apple intentionally does not expose that surface. The HomePod is not an endpoint; it is the **Home Hub + Matter Controller + HomeKit Controller + Siri endpoint** for the Apple Home ecosystem on the LAN. It **discovers** accessories that advertise themselves on the local network via Bonjour/mDNS using the HomeKit Accessory Protocol (HAP) or Matter.
|
||||
|
||||
The correct direction of flow is therefore:
|
||||
|
||||
```text
|
||||
RuView / Seed
|
||||
↓ (advertise HAP / Matter accessory on LAN)
|
||||
HomeKit / Matter accessory
|
||||
↓ (mDNS discovery)
|
||||
HomePod
|
||||
↓ (forwards to Apple Home automation graph)
|
||||
Apple Home ecosystem (iPhone, Watch, Mac, Siri, automations)
|
||||
```
|
||||
|
||||
### 1.2 What we ship today and where it stops
|
||||
|
||||
ADR-115 ships an **MQTT auto-discovery publisher** that talks to Home Assistant. ADR-116's `cog-ha-matter` Cognitum cog wraps that publisher into a Seed-installable artifact with mDNS, an embedded rumqttd broker, RuVector-backed thresholds, and an Ed25519 witness chain. ADR-122 explicitly extends the same publisher with the BFLD presence / identity-risk / Soul-Match topics so a Home Assistant install sees them as auto-discovered entities. The current path to HomePod therefore runs:
|
||||
|
||||
```text
|
||||
RuView sensing-server ──► cog-ha-matter (MQTT HA-DISCO + HA-MIND)
|
||||
↓
|
||||
Home Assistant broker
|
||||
↓
|
||||
Home Assistant HomeKit Bridge add-on
|
||||
↓
|
||||
HomePod
|
||||
```
|
||||
|
||||
This works and the auto-discovery is real, but it introduces a hard dependency: an operator must run Home Assistant, install its HomeKit Bridge integration, and pair the bridge in the Apple Home app. The Seed alone does not appear in Apple Home.
|
||||
|
||||
ADR-116 §P7 anticipated this — the `cog-ha-matter` `Cargo.toml` already carries a `matter = []` feature stub with the comment "matter-rs is added in P7; intentionally absent in P1 to keep the dep surface small until the SDK choice is validated." This ADR closes that box.
|
||||
|
||||
### 1.3 Why now
|
||||
|
||||
Three forces line up in 2026-05:
|
||||
|
||||
1. **The BFLD privacy gate (ADR-118 / 120 / 121) is shipped.** Class-2 and class-3 frames are the only ones eligible to cross the Matter boundary (ADR-122 §2.4). Without that gate we could not safely expose RuView signals to a consumer ecosystem. With it, every Anonymous / Restricted event is safe to advertise as a HomeKit sensor.
|
||||
2. **`@ruvnet/rvagent` (ADR-124) is on npm.** The MCP surface that lets agents query RuView is live. A first-class Apple-Home presence widens RuView's reach from "agents that speak MCP" to "anyone with an iPhone and a HomePod" — the consumer wedge.
|
||||
3. **The Cognitum Seed Docker image now bundles `cog-ha-matter`** (this branch's `Dockerfile.rust` change, see #794) — the runtime where a HAP advertiser would live is finally a single-image deployment.
|
||||
|
||||
### 1.4 Strategic framing
|
||||
|
||||
The combination is asymmetric:
|
||||
|
||||
| Layer | RuView contributes | Apple Home contributes |
|
||||
|-------|---------------------|------------------------|
|
||||
| Sensing | Passive RF presence, breathing, heart rate, fall risk, BFLD identity-risk, through-wall occupancy, longitudinal wellness | (none — Apple has no native RF sensing surface) |
|
||||
| Adoption | (limited — researcher-grade hardware today) | iPhone, Watch, Mac, HomePod, Apple TV installed base; consumer trust; voice; on-device intelligence |
|
||||
| UX | (utility CLI + a Web UI) | Home app, Siri, automation engine, notifications, accessibility |
|
||||
| Trust | Ed25519 witness chain, privacy class gate, local-first | Apple HomeKit local pairing, end-to-end encrypted, no cloud requirement |
|
||||
|
||||
RuView supplies the **invisible cognition layer** Apple cannot provide on its own; Apple supplies the **distribution and UX** that an open sensing stack cannot bootstrap. Direct HAP integration removes the only structural barrier between those two layers — Home Assistant as a mandatory intermediary.
|
||||
|
||||
---
|
||||
|
||||
## 2. Decision
|
||||
|
||||
Ship a **native HomeKit / Matter accessory** in the Seed runtime so a freshly-imaged Cognitum Seed appears in the Apple Home app under `Add Accessory → More Options` with **zero Home-Assistant dependency**.
|
||||
|
||||
Concretely:
|
||||
|
||||
1. Add a `hap-accessory` workspace component that advertises a set of HomeKit characteristics over mDNS using HAP-1.1 (HomeKit Accessory Protocol).
|
||||
2. The component subscribes to `wifi-densepose-sensing-server`'s WebSocket / BFLD `MqttEvent` stream and maps each privacy-class-2/3 event onto a HomeKit characteristic update.
|
||||
3. The same Docker image that ships `sensing-server` and `cog-ha-matter` ships the new advertiser as a third entrypoint:
|
||||
|
||||
```bash
|
||||
docker run --network host ruvnet/wifi-densepose:latest hap-accessory --privacy-mode
|
||||
```
|
||||
|
||||
`--network host` (or a macvlan bridge) is required because HAP pairing depends on the accessory and the controller seeing each other's mDNS broadcasts on the same L2 segment — same constraint Home Assistant's HomeKit Bridge has.
|
||||
|
||||
### 2.1 Two implementation tracks (decided here together; ship 2.1.a first)
|
||||
|
||||
#### 2.1.a — **HAP-python sidecar** (fastest to ship, lands first)
|
||||
|
||||
Add a tiny Python entrypoint `bridges/hap-python/ruview_hap.py` using the well-maintained [`HAP-python`](https://github.com/ikalchev/HAP-python) library. The Dockerfile gets a thin Python runtime stage; the entrypoint script polls `sensing-server` over HTTP and pushes characteristic updates into the HAP loop.
|
||||
|
||||
```python
|
||||
# bridges/hap-python/ruview_hap.py (≈80 LOC)
|
||||
from pyhap.accessory import Accessory
|
||||
from pyhap.accessory_driver import AccessoryDriver
|
||||
from pyhap.const import CATEGORY_SENSOR
|
||||
import urllib.request, json, threading, time
|
||||
|
||||
SENSING_URL = "http://127.0.0.1:3000/api/v1"
|
||||
|
||||
class RuViewSensor(Accessory):
|
||||
category = CATEGORY_SENSOR
|
||||
|
||||
def __init__(self, *args, **kwargs):
|
||||
super().__init__(*args, **kwargs)
|
||||
s_motion = self.add_preload_service('MotionSensor')
|
||||
self.c_motion = s_motion.configure_char('MotionDetected')
|
||||
s_occ = self.add_preload_service('OccupancySensor')
|
||||
self.c_occ = s_occ.configure_char('OccupancyDetected')
|
||||
s_temp = self.add_preload_service('TemperatureSensor')
|
||||
self.c_temp = s_temp.configure_char('CurrentTemperature')
|
||||
threading.Thread(target=self._poll, daemon=True).start()
|
||||
|
||||
def _poll(self):
|
||||
while True:
|
||||
try:
|
||||
v = json.loads(urllib.request.urlopen(f"{SENSING_URL}/vitals").read())
|
||||
self.c_motion.set_value(bool(v.get("motion_present")))
|
||||
self.c_occ.set_value(int(bool(v.get("occupancy"))))
|
||||
if "ambient_temp_c" in v:
|
||||
self.c_temp.set_value(v["ambient_temp_c"])
|
||||
except Exception:
|
||||
pass
|
||||
time.sleep(1.0)
|
||||
|
||||
driver = AccessoryDriver(port=51826)
|
||||
driver.add_accessory(accessory=RuViewSensor(driver, 'RuView Sense'))
|
||||
driver.start()
|
||||
```
|
||||
|
||||
Pairing flow on the operator's iPhone:
|
||||
|
||||
1. Open Apple Home → `Add Accessory` → `More Options`
|
||||
2. Tap `RuView Sense` (appears via mDNS automatically)
|
||||
3. Enter the setup code shown in `docker logs` (or pinned in env)
|
||||
4. Done — Siri can say "Hey Siri, is anyone in the living room?"
|
||||
|
||||
Replace the `motion_present` / `occupancy` mappings progressively as RuView capabilities mature: BFLD class-2 `presence` event → `OccupancyDetected`; BFLD class-3 `identity_risk_score > threshold` → `SecuritySystemCurrentState`; `breathing_present` → `OccupancyDetected` (sleep room); `fall_risk` → a programmable switch that fires an Apple Home automation.
|
||||
|
||||
Acceptance criteria for 2.1.a:
|
||||
|
||||
- A1: `docker run ... hap-accessory --privacy-mode` advertises an `_hap._tcp` service that the HomePod sees within 30s (`dns-sd -B _hap._tcp local.` on a peer Mac shows `RuView Sense`).
|
||||
- A2: Pairing from Apple Home succeeds and the entity appears in the Home app under the configured room.
|
||||
- A3: `MotionDetected` flips within 2 s of an actual RF presence detection from a calibrated ESP32 source (`CSI_SOURCE=esp32`).
|
||||
- A4: Restarting the container preserves the pairing (HAP state persisted under `/var/lib/ruview-hap/`).
|
||||
- A5: Privacy: the entrypoint refuses to launch without `--privacy-mode` when `RUVIEW_BFLD_PRIVACY_CLASS` is unset, matching the structural invariant I1 (Raw BFI never exits the node — ADR-118 §2.2).
|
||||
|
||||
#### 2.1.b — **Rust-native HAP** (single binary, closes ADR-116 P7)
|
||||
|
||||
Wire one of the maintained Rust HAP crates into `cog-ha-matter` so the Python sidecar can be removed. Candidate crates:
|
||||
|
||||
- [`hap`](https://crates.io/crates/hap) (Sebastian Schmidt) — last published 0.1.0-pre.16, MIT, active in 2024, supports HAP-1.1, has examples for `MotionSensor`, `LightBulb`, `OccupancySensor`. **First choice.**
|
||||
- [`accessory-server`](https://crates.io/crates/accessory-server) — narrower scope, fewer services
|
||||
- A future `matter-rs` crate from project-chip — once stable (CHIP SDK Rust bindings are still emerging in 2026-05)
|
||||
|
||||
The `matter = []` feature stub in `cog-ha-matter/Cargo.toml` (added in ADR-116 P1) becomes:
|
||||
|
||||
```toml
|
||||
[features]
|
||||
default = []
|
||||
mqtt = ["dep:rumqttc"]
|
||||
matter = ["dep:hap"] # ADR-125 §2.1.b
|
||||
```
|
||||
|
||||
with a runtime subcommand `cog-ha-matter --mode hap` that mirrors the Python advertiser's accessory set. Single binary, no Python interpreter in the image, matches the all-Rust ethos of the Cognitum Seed (ADR-116 §1.4).
|
||||
|
||||
### 2.1.c — **Topology: one HAP bridge, N child accessories** (decided)
|
||||
|
||||
The advertiser publishes a **single HAP bridge** (`RuView Sense`) that owns N child accessories — one per logical sensor surface (presence-bedroom, presence-office, vitals-bedroom, semantic-events, …). Operators pair the bridge once; child accessories appear automatically and can be re-assigned to rooms in the Apple Home app.
|
||||
|
||||
The alternative — N independent accessories each advertised separately — was rejected. It forces operators to pair RuView once per room (`RuView Bedroom`, `RuView Office`, `RuView Wellness`, `RuView Presence`, …), which becomes messy after the second or third room, and diverges from how every reference HomeKit accessory in the Home app behaves (a Hue bridge with bulbs, an Eve Energy bridge, etc.). Single pairing also makes container restart / re-image trivial — one persisted pairing key, not N.
|
||||
|
||||
### 2.1.d — **Identity-risk mapping: semantic events, not probabilistic surveillance** (decided)
|
||||
|
||||
`identity_risk_score` is a continuous 0..1 confidence from the BFLD identity-features pipeline (ADR-121 §2.6). It must NOT cross the HomeKit boundary as a raw value, and must NOT be wired to `SecuritySystemCurrentState`. Apple-Home users read security-system state as **"intruder detected"** — exposing a probability there turns RuView into surveillance UX with all the false-positive blame that entails.
|
||||
|
||||
Instead, the bridge exposes **thresholded semantic events** that read like ambient awareness, not threat detection:
|
||||
|
||||
| Semantic event | HomeKit primitive | Trigger (illustrative) |
|
||||
|----------------|--------------------|-------------------------|
|
||||
| `Unknown Presence` | `MotionSensor` (programmable; stateful) | BFLD class-2 presence + no matching SoulMatch oracle hit (ADR-121 §2.6) for > 30 s |
|
||||
| `Unexpected Occupancy` | `OccupancySensor` (programmable) | Occupancy in a room outside its operator-defined "expected schedule" window |
|
||||
| `Unrecognized Activity Pattern` | Programmable `Switch` (stateful, momentary) | BFLD longitudinal drift gate (ADR-118 §2.3 / ADR-122 §2.7) fires Reject or Recalibrate |
|
||||
|
||||
What stays internal:
|
||||
|
||||
- Raw `identity_risk_score` (numeric 0..1) — never published
|
||||
- Soul-Signature match probability — never published
|
||||
- `rf_signature_hash` — never published (already enforced by ADR-118 §2.5 / ADR-122 §2.4 — this is the structural invariant restated at the HAP boundary)
|
||||
|
||||
The naming is the contract. "Unknown Presence" is *who's-here-and-it's-fine-but-worth-noting*; an end user will write an automation ("turn on the porch light when Unknown Presence is detected after 9pm") without ever thinking it accuses anyone of being an intruder. That semantic framing is the difference between RuView becoming the calm-tech ambient substrate Apple Home needs vs. another paranoid surveillance widget.
|
||||
|
||||
This is the part of the ADR that determines whether RuView's HomeKit story ages well or generates the wrong kind of headlines.
|
||||
|
||||
### 2.2 What we DO NOT do in 2.1.a or 2.1.b
|
||||
|
||||
- **No Matter (CHIP) controller code.** Matter is the long-term play but its SDK in Rust is not yet stable and the certificate provisioning is heavy. HAP-1.1 over Bonjour gives 95% of the UX for 10% of the complexity, today.
|
||||
- **No direct connection to the HomePod.** As the framing in §1.1 makes explicit, RuView never opens a socket to the HomePod. It advertises; the HomePod discovers.
|
||||
- **No iCloud account binding.** HAP pairing is local-network-only by design — RuView gets adoption without ever touching Apple ID, which is a privacy story we keep cleanly.
|
||||
- **No Class-0 (`Raw`) BFI exposure.** Structural invariant I1 (ADR-118 §2.2) holds. Only privacy-class-2 (Anonymous) and class-3 (Restricted) frames may be mapped onto HomeKit characteristics. The advertiser refuses to start in any other mode.
|
||||
|
||||
### 2.3 Sequencing
|
||||
|
||||
1. **P1** (this ADR-125 + 1 PR) — HAP-python sidecar (§2.1.a) lands as a separate entrypoint in the same Docker image. AC A1–A5 are gates.
|
||||
2. **P2** (follow-up PR after operator feedback from 5+ Apple Home pairings) — Rust-native HAP (§2.1.b). Replaces P1; P1's `bridges/hap-python/` becomes an archived reference implementation.
|
||||
3. **P3** (when matter-rs stabilizes) — Matter Controller path (still RuView-as-accessory, but using the Matter clusters rather than HAP-1.1 services). The Cognitum Cog gains a Matter QR code; pairing flow widens to "any Matter-capable controller, not just Apple."
|
||||
|
||||
---
|
||||
|
||||
## 3. Consequences
|
||||
|
||||
### 3.1 Wins
|
||||
|
||||
- **Direct discoverability on Apple Home.** A Seed in the kitchen appears as `RuView Sense` in the Home app within seconds of `docker run`. No HA, no MQTT broker, no Home-Assistant HomeKit Bridge add-on.
|
||||
- **Siri natively answers RuView questions.** "Hey Siri, is anyone in the kitchen?" — the question reaches the HomeKit characteristic without any custom skill or HA template sensor.
|
||||
- **Apple-Home automations gain ambient triggers** RuView already produces (presence, breathing, fall, identity-risk) for free — they become first-class automation triggers in the Home app's UI.
|
||||
- **Strategically corrects RuView's distribution problem.** The Apple Home installed base is the largest consumer surface for HomeKit-grade accessories. RuView's sensing IP becomes addressable to that base without an SDK port.
|
||||
- **Closes ADR-116 §P7** — the long-flagged matter / HAP gap is now scheduled, not deferred indefinitely.
|
||||
|
||||
### 3.2 Costs
|
||||
|
||||
- **Python runtime in the Docker image (only for 2.1.a, until 2.1.b lands).** Adds ~30 MB to the runtime layer. Mitigation: P2 removes it; P1 isolates the Python dep in a side-stage so the sensing-server / cog-ha-matter layers stay clean.
|
||||
- **Network-mode constraint.** HAP pairing needs the controller and accessory on the same L2 segment (mDNS broadcasts). Operators who run RuView in a container behind a NAT/bridge need `--network host` or a macvlan — same constraint HA's HomeKit Bridge has, but worth documenting.
|
||||
- **Pairing state persistence.** HAP-python stores pairing data in a local file; that state must survive container restarts. Volume-mount `/var/lib/ruview-hap/` to a persistent location.
|
||||
|
||||
### 3.3 Risks
|
||||
|
||||
- **HAP-python maintenance.** The library is community-maintained; if it goes stale, P2 (Rust-native) absorbs the risk. 2.1.a is explicitly a stepping stone, not a long-term commitment.
|
||||
- **Apple's evolving requirements.** HomeKit Accessory Certification is required to put a HAP logo on hardware, not to ship a software accessory that pairs locally. RuView's container deployment is squarely in the "uncertified developer accessory" lane, which Apple explicitly permits for local pairing. Worth restating in the operator README.
|
||||
- **Privacy-class enforcement at the bridge boundary.** A bug that lets a class-0 BFI frame's data influence a HAP characteristic update would violate I1. Mitigation: the bridge consumes only the BFLD `MqttEvent` stream (which is already gated by `PrivacyGate` per ADR-120), never raw BFI; tests assert this in the same style as ADR-122 §4.3.
|
||||
|
||||
### 3.4 Reversibility
|
||||
|
||||
The advertiser is a separate entrypoint — pulling it out is `docker run` without the `hap-accessory` first-arg, identical to today's behavior. Zero impact on `sensing-server` and `cog-ha-matter` operations.
|
||||
|
||||
---
|
||||
|
||||
## 4. Acceptance test (P1 / §2.1.a)
|
||||
|
||||
```bash
|
||||
# 1. Start a sensing server (simulated source so the test runs anywhere)
|
||||
docker run -d --name rs -p 3000:3000 -e CSI_SOURCE=simulated \
|
||||
ruvnet/wifi-densepose:latest
|
||||
|
||||
# 2. Launch the HAP advertiser sidecar in privacy mode
|
||||
docker run -d --name hap --network host \
|
||||
-v /var/lib/ruview-hap:/var/lib/ruview-hap \
|
||||
-e RUVIEW_BFLD_PRIVACY_CLASS=2 \
|
||||
ruvnet/wifi-densepose:latest hap-accessory --privacy-mode
|
||||
|
||||
# 3. From a Mac on the same LAN: should see RuView Sense as HAP
|
||||
dns-sd -B _hap._tcp local. # expect: "RuView Sense" within 30 s
|
||||
|
||||
# 4. From iPhone Home app: Add Accessory → More Options → RuView Sense
|
||||
# Enter setup code from `docker logs hap`
|
||||
# Expect: pairing completes, entity appears in selected Room
|
||||
|
||||
# 5. Cycle the container; re-open Home app: entity is still paired
|
||||
docker restart hap
|
||||
# Expect: no re-pairing prompt; characteristic updates resume
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 5. Open questions
|
||||
|
||||
Two questions from the original draft were resolved during review (§2.1.c and §2.1.d). Genuinely-open questions that follow-up PRs will close:
|
||||
|
||||
- **Setup-code derivation.** Derived deterministically from the Seed's Ed25519 witness key (so reinstalls re-use the same code, operator never re-enters), or random per launch (slightly better security, worse UX on container restarts)? Leaning deterministic + witness-key-derived; verify against Apple's HomeKit Accessory Protocol §5.6.5 (setup-code uniqueness) before committing.
|
||||
- **ESP32 / Cognitum-Seed-class hardware as a direct HAP advertiser** (not via the host appliance). The current decision parks the bridge on the host runtime; a future ADR can evaluate whether an ESP32-S3 with 8MB flash has enough headroom to run HAP-1.1 directly, which would remove the host appliance from the path entirely for single-room deployments.
|
||||
|
||||
---
|
||||
|
||||
## 6. References
|
||||
|
||||
- ADR-115 — Home-Assistant integration (HA-DISCO MQTT publisher)
|
||||
- ADR-116 — `cog-ha-matter` Seed cog (this is where the `matter` feature stub lives)
|
||||
- ADR-118 — BFLD beamforming-feedback layer (privacy gate + class invariants)
|
||||
- ADR-122 — BFLD RuView HA/Matter exposure (current MQTT-based bridge that this ADR's HAP-native path complements)
|
||||
- HomeKit Accessory Protocol Specification (Non-Commercial Version), Apple — https://developer.apple.com/apple-home/
|
||||
- HAP-python — https://github.com/ikalchev/HAP-python
|
||||
- `hap` (Rust) — https://crates.io/crates/hap
|
||||
@@ -1,362 +0,0 @@
|
||||
# ADR-126: HOMECORE — Native Rust + WASM + TypeScript port of Home Assistant
|
||||
|
||||
| Field | Value |
|
||||
|-------|-------|
|
||||
| **Status** | Proposed |
|
||||
| **Date** | 2026-05-25 |
|
||||
| **Deciders** | ruv |
|
||||
| **Codename** | **HOMECORE** — native hub, RuView-first, WASM-safe, semantically aware |
|
||||
| **Relates to** | [ADR-115](ADR-115-home-assistant-integration.md) (HA-DISCO), [ADR-116](ADR-116-cog-ha-matter-seed.md) (HA-COG), [ADR-117](ADR-117-pip-wifi-densepose-modernization.md) (PIP-PHOENIX), [ADR-118](ADR-118-bfld-beamforming-feedback-layer-for-detection.md) (BFLD), [ADR-124](ADR-124-rvagent-mcp-ruvector-npm-integration.md) (SENSE-BRIDGE), [ADR-125](ADR-125-ruview-apple-home-native-hap-bridge.md) (APPLE-FABRIC) |
|
||||
| **Tracking issue** | TBD |
|
||||
| **Sub-ADRs** | ADR-127 through ADR-134 |
|
||||
|
||||
---
|
||||
|
||||
## 1. Context
|
||||
|
||||
### 1.1 Strategic position in 2026
|
||||
|
||||
Home Assistant (HA) is the dominant open-source home automation hub with more than 500,000 active installs (ADR-115 §1.2 competitive scan). Every prior RuView integration decision has been made with HA as a given constraint: ADR-115 built an MQTT auto-discovery publisher to fit inside HA, ADR-116 packaged it as a Cognitum Seed cog, ADR-122 extended it with BFLD presence events, and ADR-125 layered a native HAP bridge on top of the same stack.
|
||||
|
||||
This approach yields functioning integrations, but it positions RuView permanently as a **guest in someone else's hub**. The architectural limits of Python HA are not just cosmetic:
|
||||
|
||||
| Limit | Impact on RuView's roadmap |
|
||||
|---|---|
|
||||
| **Single-process Python GIL** | CSI DSP pipeline, BFLD analysis, and ruvector semantic search cannot run concurrently inside the HA process; they must run as external services connected over MQTT or WebSocket, introducing a round-trip on every sensor update |
|
||||
| **Startup time (15–30 s on a Pi 5)** | The Cognitum Seed appliance restarts firmware-update-by-firmware-update; a 30 s hub startup on every OTA cycle is user-visible latency |
|
||||
| **Memory footprint (300 MB+ idle)** | On a Pi 5 with 8 GB this is tolerable; on a Pi Zero 2 W or an embedded board with 512 MB it precludes co-location with the sensing stack |
|
||||
| **No WASM safety boundary for integrations** | HA's 2,000+ community integrations are Python modules loaded directly into the HA process — one buggy integration can crash the hub or read arbitrary memory |
|
||||
| **Recorder is structural only** | SQLite + InfluxDB store state history as rows; there is no semantic search. "Show me when the porch light correlated with the bedroom CSI anomaly last week" requires manual SQL |
|
||||
| **Voice assistant is additive** | Assist (`homeassistant/components/assist_pipeline/`) was added in 2022–2023 and is well-designed, but intent matching is keyword-based, not embedding-based; ruflo LLM pipelines cannot natively plug in |
|
||||
| **Frontend is a 5 MB Lit-element bundle** | The dashboard compiles to ~5 MB of JavaScript; on low-bandwidth appliance UIs or Progressive-Web-App installs, this is perceptible load time |
|
||||
|
||||
These are not HA's failures — they are Python architectural realities. For a generic home automation hub they are acceptable. For a hub where the core value proposition is **real-time RF sensing, AI-augmented automation, and edge-native deployment on constrained hardware**, they are ceilings.
|
||||
|
||||
### 1.2 The opportunity
|
||||
|
||||
Three recent ADR shipments create the inflection point:
|
||||
|
||||
1. **ADR-117 (PIP-PHOENIX)** — `wifi-densepose==2.0.0a1` + `ruview==2.0.0a1` on PyPI as PyO3/maturin wheels, providing a Python developer surface over the Rust sensing core.
|
||||
2. **ADR-118 (BFLD)** — a complete beamforming feedback capture and privacy-risk scoring layer, proving that RuView's sensing stack can be a compliance instrument, not just a sensor.
|
||||
3. **ADR-124 (SENSE-BRIDGE)** — `@ruvnet/rvagent` on npm as a dual-transport MCP server, proving that the sensing stack can be expressed as a first-class AI-agent tool surface.
|
||||
|
||||
The gap that remains: there is no hub that treats all of these as **native first-class features** rather than bolt-on integrations. HOMECORE fills that gap by porting the HA data model and API surface to Rust, replacing HA's Python internals with the RuView Rust crates, and wrapping community integrations in WASM sandboxes.
|
||||
|
||||
### 1.3 What this ADR is *not*
|
||||
|
||||
- Not a fork of the Python HA codebase. HOMECORE is a **clean-room Rust implementation** of HA's public API contracts and data model, not a line-by-line port.
|
||||
- Not a replacement of the existing sensing stack. `v2/crates/wifi-densepose-*` remain authoritative.
|
||||
- Not a deprecation of ADR-115/116/117/124/125. Those integrations continue to work with Python HA installs. HOMECORE is an additional deployment target, not a replacement mandate.
|
||||
- Not a Matter SDK full-implementation. ADR-125 handles Matter; HOMECORE consumes the Matter bridge via the existing `cog-ha-matter` surface.
|
||||
- Not a target for this quarter's sprint. HOMECORE is a multi-quarter initiative. This master ADR and its sub-ADRs define the architecture; implementation begins in P1.
|
||||
|
||||
---
|
||||
|
||||
## 2. Decision
|
||||
|
||||
Build **HOMECORE**: a native Rust + WASM + TypeScript implementation of the Home Assistant hub contract, integrated with the RuView sensing platform, the ruflo agent toolchain, and the ruvector vector layer.
|
||||
|
||||
HOMECORE is wire-compatible with HA's REST and WebSocket APIs so that existing HA-native clients (the iOS/Android Home Assistant companion apps, HACS, Nabu Casa Cloud, and the HA voice satellite stack) operate without modification against a HOMECORE instance.
|
||||
|
||||
HOMECORE is NOT a drop-in replacement on day one. The compatibility contract is phased (§6). The architecture is designed so that clients that work with HA today work with HOMECORE P3+.
|
||||
|
||||
### 2.1 Codename rationale
|
||||
|
||||
**HOMECORE** — the `core` of HA reimplemented at native speed, with the sensing stack at the center rather than at the periphery.
|
||||
|
||||
---
|
||||
|
||||
## 3. Architecture overview
|
||||
|
||||
```
|
||||
┌──────────────────────────────────────────────────────────────┐
|
||||
│ HOMECORE process │
|
||||
│ │
|
||||
│ ┌─────────────┐ ┌──────────────┐ ┌───────────────────┐ │
|
||||
│ │ homecore │ │ homecore- │ │ homecore- │ │
|
||||
│ │ state │ │ automation │ │ recorder │ │
|
||||
│ │ machine │ │ engine │ │ (SQLite + │ │
|
||||
│ │ (ADR-127) │ │ (ADR-129) │ │ ruvector) │ │
|
||||
│ └──────┬──────┘ └──────┬───────┘ │ (ADR-132) │ │
|
||||
│ │ │ └───────────────────┘ │
|
||||
│ ┌──────▼──────────────────────────────────┐ │
|
||||
│ │ Event Bus (Tokio broadcast) │ │
|
||||
│ └──────┬──────────────────────────────────┘ │
|
||||
│ │ │
|
||||
│ ┌──────▼──────────────────────────────────┐ │
|
||||
│ │ homecore-rest-websocket-api (ADR-130)│ │
|
||||
│ │ Axum server — HA wire-compat API │ │
|
||||
│ └──────────────────────────────────────────┘ │
|
||||
│ │
|
||||
│ ┌──────────────┐ ┌──────────────────────────────────────┐ │
|
||||
│ │ Integration │ │ homecore-assist-ruflo (ADR-133) │ │
|
||||
│ │ Plugin System│ │ ruflo agent orchestration │ │
|
||||
│ │ (ADR-128) │ │ ruvector intent embeddings │ │
|
||||
│ │ WASM sandbox │ │ Wyoming protocol edge │ │
|
||||
│ └──────────────┘ └──────────────────────────────────────┘ │
|
||||
│ │
|
||||
│ ┌──────────────────────────────────────────────────────┐ │
|
||||
│ │ RuView sensing core (wifi-densepose-sensing-server) │ │
|
||||
│ │ CSI → presence / vitals / pose / BFLD / semantic │ │
|
||||
│ └──────────────────────────────────────────────────────┘ │
|
||||
└──────────────────────────────────────────────────────────────┘
|
||||
│ HA-compatible REST + WebSocket
|
||||
▼
|
||||
┌──────────────────────────┐
|
||||
│ homecore-frontend-ts-wasm │ (ADR-131)
|
||||
│ TypeScript + Rust→WASM │
|
||||
│ SharedWorker state sync │
|
||||
└──────────────────────────┘
|
||||
```
|
||||
|
||||
The HOMECORE process is a single Tokio-based async Rust binary. The state machine and event bus are the authoritative core (ADR-127). Integrations run in WASM sandboxes that communicate with the core via a defined ABI (ADR-128). The automation engine runs Rust-native trigger evaluation with a WASM expression evaluator for templates (ADR-129). The REST/WebSocket API layer is Axum-based and wire-compatible with HA (ADR-130). The frontend is TypeScript with the state machine compiled to WASM running in a SharedWorker (ADR-131). Historical state is stored in SQLite with ruvector for semantic search (ADR-132). Voice/text assistance uses ruflo agent orchestration (ADR-133).
|
||||
|
||||
---
|
||||
|
||||
## 4. Series map
|
||||
|
||||
| ADR | Codename | Scope | Critical path? | Estimated P5-completion |
|
||||
|---|---|---|---|---|
|
||||
| **ADR-127** | HOMECORE-CORE | Rust state machine, entity registry, event bus, service registry (`homecore` crate) | **Yes — all others depend on it** | Q3 2026 |
|
||||
| **ADR-128** | HOMECORE-PLUGINS | WASM integration plugin system, cog substrate, manifest schema, hot-load | **Yes — needed before any integration can run** | Q3 2026 |
|
||||
| **ADR-129** | HOMECORE-AUTO | Automation engine, YAML parser, Jinja2-equivalent WASM evaluator, blueprints | Yes (automation is core to HA UX) | Q4 2026 |
|
||||
| **ADR-130** | HOMECORE-API | REST + WebSocket wire-compat API, Axum server, HA companion app support | **Yes — needed for client compat** | Q3 2026 |
|
||||
| **ADR-131** | HOMECORE-UI | TS + Rust→WASM frontend, SharedWorker state sync, Material 3 design lang | No (can run alongside Python HA UI initially) | Q1 2027 |
|
||||
| **ADR-132** | HOMECORE-RECORDER | SQLite recorder + ruvector semantic history, schema migration | No (structural recorder ships before ruvector layer) | Q4 2026 |
|
||||
| **ADR-133** | HOMECORE-ASSIST | ruflo agent voice assistant, ruvector intent matching, Wyoming edge path | No | Q4 2026 |
|
||||
| **ADR-134** | HOMECORE-MIGRATE | Migration tooling from Python HA, config-entry parser, side-by-side mode | No (needed for user adoption) | Q1 2027 |
|
||||
|
||||
**Critical path**: ADR-127 → ADR-128 → ADR-130 must land in that order. ADR-129, ADR-132, ADR-133, ADR-131, ADR-134 can proceed in parallel once the core triad is stable.
|
||||
|
||||
---
|
||||
|
||||
## 5. Cross-cutting decisions
|
||||
|
||||
The following decisions govern all 8 sub-ADRs and are not repeated in each.
|
||||
|
||||
### 5.1 Governance via RUVIEW-POLICY (ADR-124 §4.1a)
|
||||
|
||||
Every HOMECORE component that returns biometric data (presence, HR/BR, pose keypoints, BFLD identity-risk) MUST route through the RUVIEW-POLICY layer defined in ADR-124 §4.1a. The policy store is the same `~/.config/rvagent/policy.json` used by `@ruvnet/rvagent`. HOMECORE is a first-class policy principal — its agent ID in the policy store is `homecore`.
|
||||
|
||||
### 5.2 Semantic memory via ruvector
|
||||
|
||||
Historical state is not only stored in SQLite rows (structural). Every state-changed event is also embedded via ruvector (using the same napi-rs bindings as ADR-124) and indexed in an HNSW store for semantic search. The `homecore-recorder` crate (ADR-132) owns this dual-write. Queries like "when did the living room motion last exceed baseline?" become vector-nearest-neighbour searches, not SQL BETWEEN clauses.
|
||||
|
||||
### 5.3 Agent orchestration via ruflo
|
||||
|
||||
The automation engine (ADR-129) and the assist pipeline (ADR-133) both have an optional ruflo-agent mode where complex conditions or voice intents are routed to a ruflo agent (using the `mcp__claude-flow__*` tool namespace) for LLM-backed resolution. This is gated by RUVIEW-POLICY: a policy grant is required before HOMECORE sends any state-history context to a ruflo agent.
|
||||
|
||||
### 5.4 Witness and audit via Ed25519 chain (ADR-028 pattern)
|
||||
|
||||
Every state transition that crosses a privacy boundary (e.g. BFLD identity-risk score elevated, a biometric entity state published) is logged to an Ed25519 witness chain using the same structure as ADR-028 §3. The witness bundle is exportable for regulated deployments (care homes, hotels, shared offices).
|
||||
|
||||
### 5.5 Crate naming and workspace placement
|
||||
|
||||
All HOMECORE crates live in `v2/crates/homecore-*/`:
|
||||
|
||||
| Crate | ADR |
|
||||
|---|---|
|
||||
| `homecore` | ADR-127 |
|
||||
| `homecore-plugins` | ADR-128 |
|
||||
| `homecore-automation` | ADR-129 |
|
||||
| `homecore-api` | ADR-130 |
|
||||
| `homecore-recorder` | ADR-132 |
|
||||
| `homecore-assist` | ADR-133 |
|
||||
| `homecore-migrate` | ADR-134 |
|
||||
|
||||
The frontend (`homecore-frontend`) is not a Rust crate — it is an npm package at `npm/homecore-frontend/`, mirroring the `npm/rvagent/` pattern from ADR-124.
|
||||
|
||||
### 5.6 HA wire-compatibility baseline
|
||||
|
||||
The HOMECORE REST and WebSocket API must be **compatible with HA 2025.1** as the baseline. HA 2025.1 introduced schema version 48 in the recorder. The API surface to replicate is:
|
||||
|
||||
- REST: `homeassistant/components/api/__init__.py` — 24 endpoints
|
||||
- WebSocket: `homeassistant/components/websocket_api/` — the `connection.py` + `commands.py` handler pattern, the auth handshake, and the `subscribe_events` / `subscribe_trigger` / `call_service` commands
|
||||
- Auth: `homeassistant/auth/` — the long-lived access token model
|
||||
- Config entries: `.storage/core.config_entries` JSON schema (versioned, auto-migrated)
|
||||
|
||||
### 5.7 "Do not port" list
|
||||
|
||||
The following HA subsystems are explicitly **not** ported to HOMECORE:
|
||||
|
||||
| HA subsystem | Reason not ported | HOMECORE replacement |
|
||||
|---|---|---|
|
||||
| **SUPERVISOR** (`homeassistant/supervisor/`) | Manages add-on containers and OS upgrades. HOMECORE runs on a standard Linux/Pi OS managed by systemd. | ruflo + systemd service units + OTA via the existing Cognitum Seed OTA registry (ADR-116 §2.2) |
|
||||
| **Home Assistant OS** (HAOS) | A custom embedded Linux image. HOMECORE targets standard Debian/Ubuntu on Pi 5 and standard Docker. | Standard OS + Docker Compose or systemd |
|
||||
| **Nabu Casa Cloud** | Paid remote-access and Alexa/Google integration service. HOMECORE uses Tailscale for remote access and `@ruvnet/rvagent` for AI integration. | Tailscale + ADR-107 federation + SENSE-BRIDGE |
|
||||
| **Add-on store** (Supervisor add-ons) | Docker container management. | Cognitum Seed cog registry (ADR-102) |
|
||||
| **Legacy YAML-only integrations** (pre-config-flow, ~500 of 2,000) | These require Python `setup_platform` (deprecated in HA 2024.x). Only config-flow integrations (`async_setup_entry`) are ported. | Document upgrade path; unported integrations can run via `homecore-migrate` bridge mode |
|
||||
| **Analytics / Nabu Casa telemetry** | Optional cloud telemetry. | Not replicated. HOMECORE is local-only. |
|
||||
| **Home Assistant Yellow / Green hardware** | Specific hardware. HOMECORE targets Cognitum Seed, Pi 5, and x86_64. | Cognitum Seed hardware |
|
||||
|
||||
---
|
||||
|
||||
## 6. Compatibility contract
|
||||
|
||||
### 6.1 What works on day one (P3, wire-compat API stable)
|
||||
|
||||
| Client | Works? | Notes |
|
||||
|---|---|---|
|
||||
| **HA iOS companion app** | Yes | Connects to `/api/websocket`; authenticates with long-lived token; subscribes to state events |
|
||||
| **HA Android companion app** | Yes | Same as iOS |
|
||||
| **Home Assistant Dashboard (frontend)** | Yes (HA frontend served against HOMECORE API) | Until HOMECORE-UI (ADR-131) ships, serve the Python HA frontend binary against the HOMECORE API |
|
||||
| **HACS** | Partial | HACS uses the WS API for integration management; custom component loading requires HOMECORE-PLUGINS (ADR-128) |
|
||||
| **Node-RED HA integration** | Yes | Uses REST + WS API; wire-compat |
|
||||
| **`homeassistant` Python client library** | Yes | Pure REST/WS client |
|
||||
| **`ha-mqtt-discoverable` Python library** | Yes | Publishes MQTT discovery; HOMECORE consumes the same topics |
|
||||
| **ESPHome devices** | Yes | ESPHome native API or MQTT; HOMECORE speaks both |
|
||||
| **Nabu Casa Cloud** | **No** | Nabu Casa uses a proprietary remote-access tunnel to `nabucasa.com`. HOMECORE does not integrate with the Nabu Casa cloud proxy. Replace with Tailscale. |
|
||||
| **M5Stack ATOM Echo / voice satellites** | Yes (P4) | Wyoming protocol is HOMECORE-ASSIST (ADR-133) scope |
|
||||
| **HACS custom cards** | Yes (after ADR-131 P3) | Custom cards are served via the same `/hacsfiles/` static route |
|
||||
|
||||
### 6.2 What breaks and why
|
||||
|
||||
| HA feature | HOMECORE status | Reason |
|
||||
|---|---|---|
|
||||
| Nabu Casa remote access | Not supported | Proprietary tunnel; replace with Tailscale |
|
||||
| HA Supervisor add-ons | Not supported | No container manager in HOMECORE |
|
||||
| HAOS OTA updates | Not supported | HOMECORE runs on standard OS |
|
||||
| Python custom integrations (non-WASM) | Not supported | WASM sandbox only; Python integrations cannot run natively |
|
||||
| Legacy `setup_platform` integrations | Not supported | Config-flow (`async_setup_entry`) only |
|
||||
| HA Cloud TTS/STT (Nabu Casa) | Not supported | Use Whisper + Piper locally |
|
||||
| HA Cloud Alexa/Google skill | Not supported | Use ruflo agent instead |
|
||||
|
||||
---
|
||||
|
||||
## 7. Phase roadmap
|
||||
|
||||
```
|
||||
Q3 2026 Q4 2026 Q1 2027 Q2 2027
|
||||
P1 P2 P3 P4 P5
|
||||
scaffold state+API wire-compat plugins+ full
|
||||
core HA clients automation HOMECORE
|
||||
```
|
||||
|
||||
### P1 — Scaffold (Q3 2026, 2 weeks)
|
||||
|
||||
- [ ] Create `v2/crates/homecore/` workspace member, empty state machine skeleton.
|
||||
- [ ] Create `v2/crates/homecore-api/` skeleton, Axum server on port 8123 (HA default).
|
||||
- [ ] Create `npm/homecore-frontend/` skeleton.
|
||||
- [ ] CI: `cargo check -p homecore -p homecore-api --no-default-features` green.
|
||||
- [ ] ADR-134 migration tool parses one `.storage/core.config_entries` fixture.
|
||||
|
||||
### P2 — State machine + API core (Q3 2026, 4 weeks)
|
||||
|
||||
- [ ] ADR-127 state machine: entity registry, state machine, event bus (Tokio broadcast), service registry.
|
||||
- [ ] ADR-130 API: REST endpoints, WebSocket auth handshake, `subscribe_events`, `call_service`.
|
||||
- [ ] ADR-132 recorder: SQLite schema (HA schema version 48 compatible), state write path.
|
||||
- [ ] Integration test: HA companion app authenticates and receives state updates.
|
||||
|
||||
### P3 — Wire-compat + plugin scaffold (Q3–Q4 2026, 6 weeks)
|
||||
|
||||
- [ ] ADR-128 plugin system: WASM sandbox, manifest schema, first ported integrations (MQTT, HTTP).
|
||||
- [ ] ADR-130 API: remaining WS commands, HACS support.
|
||||
- [ ] ADR-134 migration: reads `automations.yaml`, `secrets.yaml`, config entries.
|
||||
- [ ] ADR-132 recorder: ruvector dual-write, semantic search API.
|
||||
|
||||
### P4 — Automation + assist (Q4 2026, 4 weeks)
|
||||
|
||||
- [ ] ADR-129 automation engine: YAML parser, trigger evaluation, WASM expression evaluator.
|
||||
- [ ] ADR-133 assist: ruflo agent orchestration, ruvector intent matching.
|
||||
- [ ] ADR-131 frontend P1: TypeScript shell, WASM state machine in SharedWorker.
|
||||
|
||||
### P5 — Full HOMECORE (Q1 2027, 6 weeks)
|
||||
|
||||
- [ ] ADR-131 frontend: complete UI parity with HA Lovelace, custom cards.
|
||||
- [ ] ADR-134 migration: side-by-side mode, one-click cutover.
|
||||
- [ ] Full compatibility test suite against HA iOS/Android companion apps.
|
||||
- [ ] Pi 5 performance benchmarks: startup < 1 s, idle < 50 MB RAM.
|
||||
|
||||
---
|
||||
|
||||
## 8. Alternatives rejected
|
||||
|
||||
### Alt-A: Contribute RuView sensing features upstream to Python HA
|
||||
|
||||
Add the HOMECORE features (WASM plugins, ruvector recorder, ruflo assist) as Python HA components via PRs to `home-assistant/core`.
|
||||
|
||||
**Rejected because**: HA's architecture board has strict policies against adding new runtimes (WASM, Rust FFI) to the core process. The GIL bottleneck cannot be resolved from within Python HA. CSI DSP at 100 Hz frame rate inside a Python process is not feasible. This path cedes architectural control permanently.
|
||||
|
||||
### Alt-B: Thin Rust wrapper that calls into Python HA via PyO3
|
||||
|
||||
Keep Python HA as the runtime; expose RuView sensing primitives via PyO3 bindings so they run at native speed inside the Python HA process.
|
||||
|
||||
**Rejected because**: the GIL is not resolved by PyO3 calls — the HA event loop still serialises all state changes. Startup time and memory footprint are unchanged. WASM plugin safety is unchanged. This is a tactical optimisation, not an architectural solution.
|
||||
|
||||
### Alt-C: OpenHAB or Domoticz as the base
|
||||
|
||||
Port RuView's sensing stack on top of an alternative hub (openHAB/Java, Domoticz/C++).
|
||||
|
||||
**Rejected because**: neither has HA's community network effects, companion app ecosystem, or HACS plugin catalog. A clean-room Rust implementation preserves the HA compatibility contract (the most valuable asset) without inheriting the Python runtime limitations.
|
||||
|
||||
### Alt-D: Extend the existing `wifi-densepose-sensing-server` into a full hub
|
||||
|
||||
Add automation, entity registry, and recorder features directly to the existing Axum sensing server.
|
||||
|
||||
**Rejected because**: the sensing server is a purpose-built single-concern binary (CSI → MQTT/WebSocket). Expanding it into a hub would violate the single-responsibility principle and couple hub release cycles to firmware release cycles. HOMECORE is a separate crate family that depends on but does not modify the sensing server.
|
||||
|
||||
---
|
||||
|
||||
## 9. Top-level risks
|
||||
|
||||
| Risk | Likelihood | Severity | Mitigation |
|
||||
|---|---|---|---|
|
||||
| **API drift** — HA's REST/WS API evolves; HOMECORE must track it | High | High | Pin to HA 2025.1 baseline (schema 48); run the HA companion app integration tests against every HOMECORE release; ADR-130 owns the compat matrix |
|
||||
| **WASM sandbox performance** — plugin calls through the WASM boundary add latency | Medium | Medium | Benchmark plugin roundtrip on Pi 5 before P3; reject if >5 ms; WASM3/Wasmtime both have sub-1 ms call overhead for compute-light integrations |
|
||||
| **Core triad dependency** — ADR-128 and ADR-130 cannot start until ADR-127 is stable | High | High | ADR-127 is P2 start; freeze the state machine public API (entity_id, state, attributes, last_changed) before ADR-128 begins |
|
||||
| **ruvector semantic recorder** — dual-write to SQLite + HNSW may impact write throughput under high-frequency sensing | Medium | High | ruvector writes are async (non-blocking tokio task); SQLite write is the hot path; benchmark at 100 state/s on Pi 5 before ADR-132 ships |
|
||||
| **Nabu Casa gap** — users who depend on HA Cloud remote access have no HOMECORE replacement at P3 | High | Medium | Document Tailscale as the replacement prominently; provide ADR-134 migration wizard that detects Nabu Casa usage and offers Tailscale setup |
|
||||
| **Frontend bundle size** — replicating the HA Lovelace card ecosystem in TS+WASM is a significant engineering effort | High | High | ADR-131 is off-critical-path; serve HA's Python frontend against the HOMECORE API until ADR-131 P3 ships |
|
||||
| **License** — HA is Apache 2.0; the wire protocol is unencumbered; HA's UI assets and card components have separate licenses | Low | High | Clean-room Rust implementation does not use HA source; HA frontend is served as a binary (not embedded); review license before ADR-131 ships any reimplemented component |
|
||||
|
||||
---
|
||||
|
||||
## 10. Open questions
|
||||
|
||||
**Q1** (ADR-127): Should the HOMECORE state machine use a `DashMap<EntityId, State>` for lock-free concurrent reads, or a `RwLock<HashMap<EntityId, State>>` for simpler reasoning? The answer affects every integration's write pattern.
|
||||
|
||||
**Q2** (ADR-128): Does the WASM sandbox use Wasmtime (Cranelift JIT, ~5 MB binary) or WASM3 (interpreter, ~50 kB binary)? On a Pi 5 WASM3 is sufficient for integration logic; Wasmtime matters if integrations need near-native DSP speed.
|
||||
|
||||
**Q3** (ADR-130): The HA WebSocket API uses numeric IDs for command/response correlation. The HA 2025.1 baseline adds `subscribe_trigger` as a first-class WS command. Are there any commands in the HA companion app that require a newer baseline?
|
||||
|
||||
**Q4** (ADR-132): The ruvector HNSW index for state history — what embedding dimension represents a state snapshot? Options: (a) embed only numeric sensor states (scalar embedding), (b) embed `{entity_id, state, attributes}` as a text embedding via a local small model, (c) use a fixed schema encoding. The answer determines the semantic query fidelity.
|
||||
|
||||
**Q5** (ADR-134): HA's `.storage/core.config_entries` format is versioned but undocumented; it is hand-engineered from reverse-engineering the Python `StorageCollection` class in `homeassistant/helpers/storage.py`. Is this format stable enough to parse without upstream documentation, or does HOMECORE need to maintain a version matrix?
|
||||
|
||||
---
|
||||
|
||||
## 11. References
|
||||
|
||||
### This repo
|
||||
|
||||
- `docs/adr/ADR-115-home-assistant-integration.md` — HA-DISCO MQTT publisher; 21-entity surface; semantic primitives; competitive comparison table
|
||||
- `docs/adr/ADR-116-cog-ha-matter-seed.md` — HA-COG Seed cog; cog packaging precedent (ADR-101)
|
||||
- `docs/adr/ADR-117-pip-wifi-densepose-modernization.md` — PIP-PHOENIX PyO3 bindings; Python client surface
|
||||
- `docs/adr/ADR-118-bfld-beamforming-feedback-layer-for-detection.md` — BFLD master; privacy class enforcement
|
||||
- `docs/adr/ADR-124-rvagent-mcp-ruvector-npm-integration.md` — SENSE-BRIDGE; RUVIEW-POLICY §4.1a; multi-modal normalization §11.3
|
||||
- `docs/adr/ADR-125-ruview-apple-home-native-hap-bridge.md` — APPLE-FABRIC HAP bridge
|
||||
- `v2/crates/wifi-densepose-sensing-server/src/main.rs` — Axum server architecture; bearer auth pattern
|
||||
- `v2/crates/wifi-densepose-ruvector/src/viewpoint/` — cross-viewpoint fusion (attention, coherence, geometry, fusion modules)
|
||||
- `CLAUDE.md` — Project topology (hierarchical-mesh, 15 agents), ESP32 hardware table, crate publishing order
|
||||
|
||||
### HA upstream
|
||||
|
||||
- `homeassistant/core.py` — `HomeAssistant`, `StateMachine`, `EventBus`, `ServiceRegistry`, `Config`
|
||||
- `homeassistant/helpers/entity_registry.py` — `EntityRegistry`, `RegistryEntry`
|
||||
- `homeassistant/helpers/entity.py` — `Entity`, `async_write_ha_state`, entity lifecycle
|
||||
- `homeassistant/components/api/__init__.py` — REST API handler (24 routes)
|
||||
- `homeassistant/components/websocket_api/` — `connection.py` auth handshake; `commands.py` WS commands
|
||||
- `homeassistant/components/recorder/` — SQLite schema; `migration.py` schema version 48
|
||||
- `homeassistant/components/assist_pipeline/` — voice/text pipeline; Wyoming protocol
|
||||
- `homeassistant/helpers/template.py` — Jinja2 template engine customisation
|
||||
- `homeassistant/components/automation/__init__.py` — automation trigger/condition/action model
|
||||
- `homeassistant/helpers/storage.py` — `.storage/*.json` persistence; `StorageCollection`
|
||||
- `homeassistant/auth/` — long-lived access token model; `AuthManager`
|
||||
|
||||
### External
|
||||
|
||||
- [HA Developer Docs — Core Architecture](https://developers.home-assistant.io/docs/architecture/core/) — state machine, event bus, service registry overview
|
||||
- [HA Developer Docs — WebSocket API](https://developers.home-assistant.io/docs/api/websocket/) — WS command catalog
|
||||
- [DeepWiki HA core — Entity and Registry Management](https://deepwiki.com/home-assistant/core/2.2-entity-and-registry-management) — entity lifecycle
|
||||
- [DeepWiki HA core — Data Management](https://deepwiki.com/home-assistant/core/3-data-management) — recorder schema version 48
|
||||
- [HA recorder integration](https://www.home-assistant.io/integrations/recorder/) — SQLite default; schema migration overview
|
||||
@@ -1,193 +0,0 @@
|
||||
# ADR-127: HOMECORE-CORE — Rust state machine, entity registry, event bus, service registry
|
||||
|
||||
| Field | Value |
|
||||
|-------|-------|
|
||||
| **Status** | Proposed |
|
||||
| **Date** | 2026-05-25 |
|
||||
| **Deciders** | ruv |
|
||||
| **Codename** | **HOMECORE-CORE** |
|
||||
| **Relates to** | [ADR-126](ADR-126-ruview-native-ha-port-master.md) (HOMECORE master), [ADR-028](ADR-028-esp32-capability-audit.md) (witness chain), [ADR-124](ADR-124-rvagent-mcp-ruvector-npm-integration.md) (RUVIEW-POLICY) |
|
||||
| **Tracking issue** | TBD |
|
||||
|
||||
---
|
||||
|
||||
## 1. Context
|
||||
|
||||
`homeassistant/core.py` is the 3,200-line heart of Python Home Assistant. It defines five objects that every other HA component depends on:
|
||||
|
||||
1. **`HomeAssistant`** — the runtime coordinator, event loop holder, and service locator. Contains `bus` (EventBus), `states` (StateMachine), `services` (ServiceRegistry), `config` (Config), `components` (loaded component set).
|
||||
2. **`EventBus`** — publish/subscribe event dispatch. `async_fire(event_type, event_data)` dispatches to all registered listeners. Listener registration is `async_listen(event_type, callback)`. Wildcard listener is `MATCH_ALL`. Event data is a plain Python dict.
|
||||
3. **`StateMachine`** — an in-memory dictionary from `entity_id` (str) to `State`. `async_set(entity_id, new_state, attributes)` writes and fires `state_changed`. `get(entity_id)` reads. `async_remove(entity_id)` fires `state_removed`. States are immutable snapshots with `last_changed`, `last_updated`, `context`.
|
||||
4. **`ServiceRegistry`** — maps `(domain, service_name)` → async handler function. `async_call(domain, service, data)` fires a `call_service` event, waits for the registered handler. `async_register(domain, service, handler, schema)` registers a handler with optional voluptuous schema validation.
|
||||
5. **`EntityRegistry`** (`homeassistant/helpers/entity_registry.py`) — persists metadata (enabled/disabled, name override, area assignment, device ID, unique ID, entity category) across restarts. Stored in `.storage/core.entity_registry`. Loaded at startup; written on every change.
|
||||
|
||||
The **DeviceRegistry** (`homeassistant/helpers/device_registry.py`, stored in `.storage/core.device_registry`) tracks physical devices that entities belong to. Entities link to devices via `device_id`; devices link to config entries via `config_entry_id`.
|
||||
|
||||
### 1.1 Why these specific files matter
|
||||
|
||||
Python HA's `core.py` is a single-process Python 3.12 module that:
|
||||
- Holds the asyncio event loop directly
|
||||
- Serialises all state-changed writes through `asyncio.Lock`
|
||||
- Fires event listeners in the same event loop iteration that fired the event (listeners cannot block)
|
||||
- Is single-threaded by design — concurrent writes to the state machine are impossible without explicit async primitives
|
||||
|
||||
For HOMECORE the same semantic requirements apply, but the implementation must support:
|
||||
- **Concurrent reads** from dozens of integration WASM sandboxes polling current state
|
||||
- **High-frequency writes** from the RuView sensing stack (CSI at 100 Hz; state updates at up to 20 Hz per entity)
|
||||
- **Ordered delivery** of state_changed events to automation triggers (ADR-129) and recorder (ADR-132) subscribers
|
||||
- **Zero-copy reads** where possible for the REST API (ADR-130) path
|
||||
|
||||
---
|
||||
|
||||
## 2. Decision
|
||||
|
||||
Implement the `homecore` Rust crate at `v2/crates/homecore/` with the following design.
|
||||
|
||||
### 2.1 State machine: `DashMap` + Tokio broadcast
|
||||
|
||||
The primary state store is a `DashMap<EntityId, Arc<State>>` where:
|
||||
- `EntityId` is a validated newtype around `String` (validated format: `domain.name`)
|
||||
- `State` is a frozen struct: `entity_id`, `state` (String), `attributes` (serde_json::Value), `last_changed` (DateTime<Utc>), `last_updated` (DateTime<Utc>), `context` (Context)
|
||||
- `Arc<State>` allows zero-copy cloning for readers while the writer atomically replaces the map entry
|
||||
|
||||
State changes are published to a `tokio::sync::broadcast::Sender<StateChangedEvent>` channel (capacity: 4,096 events). Any number of receivers subscribe — the recorder, automation engine, WebSocket subscriber handler, and ruvector dual-write task all hold independent receivers. Slow receivers that fall behind by 4,096 events receive a `RecvError::Lagged` and must re-sync from the current state map.
|
||||
|
||||
### 2.2 Event bus: typed + untyped channels
|
||||
|
||||
HOMECORE distinguishes two event categories:
|
||||
|
||||
1. **System events** (typed): `StateChanged`, `ServiceCall`, `ComponentLoaded`, `PlatformDiscovered`, `HomeAssistantStart`, `HomeAssistantStop`. These use Tokio typed broadcast channels with zero allocation on the read path.
|
||||
2. **Integration events** (untyped): integrations fire arbitrary event types (`event_type: String`, `event_data: serde_json::Value`). These use a single `broadcast::Sender<DomainEvent>` where `DomainEvent` carries the type string and data blob. This mirrors HA's `EventBus.async_fire()`.
|
||||
|
||||
### 2.3 Service registry: `HashMap` + mpsc dispatch
|
||||
|
||||
Services are registered as `(Domain, ServiceName) → ServiceHandler` where `ServiceHandler` is a `Box<dyn Fn(ServiceCall) -> BoxFuture<ServiceResponse> + Send + Sync>`. The registry lives in a `tokio::sync::RwLock<HashMap<(Domain, ServiceName), ServiceHandler>>`. Service calls go through the event bus (fire `call_service`) and are dispatched to the handler by an internal router task. This matches HA's indirection: `hass.services.async_call(domain, service, data)` does not call the handler directly; it fires an event.
|
||||
|
||||
### 2.4 Entity registry: persisted metadata sidecar
|
||||
|
||||
The entity registry is a `RwLock<HashMap<EntityId, EntityEntry>>` backed by an async JSON writer that flushes to `.homecore/storage/core.entity_registry` on every write. The schema matches HA's `core.entity_registry` schema (version 13 as of HA 2025.1) so ADR-134 migration can read both formats interchangeably.
|
||||
|
||||
`EntityEntry` fields mirrored from HA:
|
||||
- `entity_id: EntityId`
|
||||
- `unique_id: Option<String>`
|
||||
- `platform: String`
|
||||
- `name: Option<String>` (user override)
|
||||
- `disabled_by: Option<DisabledBy>` (user, integration, config_entry)
|
||||
- `area_id: Option<AreaId>`
|
||||
- `device_id: Option<DeviceId>`
|
||||
- `entity_category: Option<EntityCategory>` (config, diagnostic)
|
||||
- `config_entry_id: Option<ConfigEntryId>`
|
||||
|
||||
### 2.5 Device registry: parallel sidecar
|
||||
|
||||
`DeviceRegistry` mirrors HA's `core.device_registry` schema (version 13). Devices are identified by a set of `(id_type, id_value)` tuples (the `identifiers` field), which matches HA's pattern of accepting multiple identifier types per device (MAC address, serial number, integration-specific ID).
|
||||
|
||||
---
|
||||
|
||||
## 3. HA-side reference table
|
||||
|
||||
| HA module / file | What it does | HOMECORE preserves | Changes | Drops |
|
||||
|---|---|---|---|---|
|
||||
| `homeassistant/core.py` `StateMachine` | In-memory state store, fire `state_changed` | Same semantics: immutable snapshots, `last_changed`, `last_updated`, `context` | `DashMap` instead of asyncio-locked `dict`; `broadcast::Sender` instead of asyncio callbacks | Python asyncio coupling |
|
||||
| `homeassistant/core.py` `EventBus` | Pub/sub event dispatch | `MATCH_ALL` listener; per-type listener; event data dict | Typed system events + untyped domain events; no Python dict — use `serde_json::Value` | `@callback` decorator, HassJob abstraction |
|
||||
| `homeassistant/core.py` `ServiceRegistry` | Register/call services | Same `(domain, service)` key structure; schema validation | Schema validation via `serde` `Deserialize` trait instead of voluptuous | voluptuous, Python type coercions |
|
||||
| `homeassistant/core.py` `HomeAssistant` | Runtime coordinator / service locator | State machine + event bus + services accessible on one struct | Struct with `Arc<HomeCoreInner>` for cheap cloning across tasks | asyncio event loop holder, Python executor |
|
||||
| `homeassistant/helpers/entity_registry.py` | Persist entity metadata | All fields listed in §2.4; file format compatible | Async tokio I/O; no Python pickle | Python-specific persistence helpers |
|
||||
| `homeassistant/helpers/device_registry.py` | Persist device metadata | `identifiers`, `connections`, `manufacturer`, `model`, `name`, `via_device_id` | Async tokio I/O | — |
|
||||
| `homeassistant/helpers/entity.py` | Entity base class | `entity_id`, `state`, `attributes`, `unique_id`, `device_info`, async_write_ha_state semantics | Trait `HomeCoreEntity` instead of class | Python MRO, `@property` decorators |
|
||||
| `homeassistant/helpers/event.py` | Convenience event helpers | `async_track_state_change`, `async_track_time_interval` (as Rust timer tasks) | Rust closures / async tasks | Python asyncio task wrappers |
|
||||
|
||||
---
|
||||
|
||||
## 4. Public API parity table
|
||||
|
||||
| HA Python surface | HOMECORE Rust equivalent |
|
||||
|---|---|
|
||||
| `hass.states.get(entity_id)` | `hass.states.get(&entity_id) -> Option<Arc<State>>` |
|
||||
| `hass.states.async_set(entity_id, state, attributes)` | `hass.states.set(entity_id, state, attributes).await` |
|
||||
| `hass.states.async_remove(entity_id)` | `hass.states.remove(&entity_id).await` |
|
||||
| `hass.states.async_all(domain_filter)` | `hass.states.all(domain_filter) -> Vec<Arc<State>>` |
|
||||
| `hass.bus.async_fire(event_type, data)` | `hass.bus.fire(event_type, data).await` |
|
||||
| `hass.bus.async_listen(event_type, callback)` | `hass.bus.subscribe(event_type) -> broadcast::Receiver<DomainEvent>` |
|
||||
| `hass.services.async_call(domain, service, data)` | `hass.services.call(domain, service, data).await -> ServiceResponse` |
|
||||
| `hass.services.async_register(domain, service, handler, schema)` | `hass.services.register(domain, service, handler)` |
|
||||
| `hass.services.has_service(domain, service)` | `hass.services.has(domain, service) -> bool` |
|
||||
| `entity_registry.async_get(entity_id)` | `entity_registry.get(&entity_id) -> Option<&EntityEntry>` |
|
||||
| `entity_registry.async_update_entity(entity_id, **kwargs)` | `entity_registry.update(entity_id, patch).await` |
|
||||
| `device_registry.async_get_device(identifiers)` | `device_registry.get_by_identifiers(identifiers) -> Option<&DeviceEntry>` |
|
||||
| `Context(user_id, parent_id)` | `Context { id: Uuid, parent_id: Option<Uuid>, user_id: Option<UserId> }` |
|
||||
|
||||
---
|
||||
|
||||
## 5. Phased implementation plan
|
||||
|
||||
### P1 — Skeleton (2 weeks)
|
||||
|
||||
- [ ] Create `v2/crates/homecore/` workspace member with `Cargo.toml`.
|
||||
- [ ] Define `State`, `EntityId`, `Domain`, `ServiceName`, `Context`, `DomainEvent` types.
|
||||
- [ ] `StateMachine`: `DashMap` + broadcast channel; `set()`, `get()`, `remove()`, `all()`.
|
||||
- [ ] `EventBus`: typed broadcast for system events + untyped broadcast for domain events.
|
||||
- [ ] Unit tests: 50 state writes/reads with concurrent readers; verify broadcast delivery.
|
||||
|
||||
### P2 — Service registry + entity registry (2 weeks)
|
||||
|
||||
- [ ] `ServiceRegistry`: `RwLock<HashMap>` + mpsc dispatch task.
|
||||
- [ ] `EntityRegistry`: in-memory + JSON async writer to `.homecore/storage/core.entity_registry`.
|
||||
- [ ] `DeviceRegistry`: in-memory + JSON async writer to `.homecore/storage/core.device_registry`.
|
||||
- [ ] Serialization: `serde` with `#[serde(rename_all = "snake_case")]`; schema version 13 header written to match HA format.
|
||||
- [ ] Unit tests: register service, call service, verify handler invoked; persist and reload entity registry.
|
||||
|
||||
### P3 — Trait surface for integrations (1 week)
|
||||
|
||||
- [ ] `HomeCoreEntity` trait: `entity_id()`, `unique_id()`, `name()`, `device_info()`, `state()`, `attributes()`, `async_write_ha_state(&hass)`.
|
||||
- [ ] `Platform` trait: `async_setup_entry(hass, config_entry) -> Result<()>`.
|
||||
- [ ] `ConfigEntry` struct mirroring HA's `ConfigEntry` fields.
|
||||
- [ ] Integration test: a minimal test integration registers an entity, writes a state, reads it back from the state machine.
|
||||
|
||||
### P4 — Performance validation (1 week)
|
||||
|
||||
- [ ] Benchmark: 1,000 state writes/s on Pi 5; measure latency at p50/p95/p99.
|
||||
- [ ] Benchmark: 100 concurrent WS subscribers each receiving all state_changed events; measure delivery lag.
|
||||
- [ ] Benchmark: broadcast channel saturation test at 4,096 capacity; verify `RecvError::Lagged` handling.
|
||||
- [ ] Acceptance criterion: p99 state write latency < 1 ms on Pi 5 (8 GB, 4 cores).
|
||||
|
||||
---
|
||||
|
||||
## 6. Risks
|
||||
|
||||
| Risk | Likelihood | Severity | Mitigation | Cross-ADR impact |
|
||||
|---|---|---|---|---|
|
||||
| **Broadcast channel lag** — a slow subscriber (e.g. ruvector recorder write) lags behind and drops events | Medium | High | Give recorder its own channel separate from WS subscribers; recorder is the hot path, give it highest priority | ADR-132: recorder write path must be designed to keep up with 100 Hz state writes |
|
||||
| **DashMap contention** — shard count default (16) may be too low for 100 Hz writes on a single entity | Low | Medium | Increase DashMap shard count to 64; benchmark before ADR-130 integration | ADR-130: REST API reads state directly from DashMap — must be lock-free |
|
||||
| **Entity registry format drift** — HA updates `.storage/core.entity_registry` schema; HOMECORE falls behind | Medium | Medium | Pin to schema version 13; version-check on load; fail loudly on unknown version | ADR-134: migration tool reads HA entity registry — must support the same schema version |
|
||||
| **Context propagation** — HA's `Context` is used for audit trails (which automation triggered which service call). HOMECORE must propagate it correctly or automation audits break | High | Low | Derive `Context` from source event at every service call; thread through `ServiceCall.context` field | ADR-129: automation engine must supply context when calling services |
|
||||
|
||||
---
|
||||
|
||||
## 7. Open questions
|
||||
|
||||
**Q1**: Should `EntityId` validation be strict (reject anything that doesn't match `[a-z0-9_]+\.[a-z0-9_]+`) or lenient (accept any UTF-8 string)? HA itself accepts unicode entity IDs since 2024.3. Strict validation simplifies routing; lenient matches HA's actual behaviour.
|
||||
|
||||
**Q2**: The `broadcast::Sender` capacity of 4,096 is chosen based on a worst-case of 100 state writes/s × 40 s of acceptable lag before a slow receiver is declared dead. Is 40 s the right threshold, or should it be configurable per receiver?
|
||||
|
||||
**Q3**: Should the `HomeCoreEntity` trait be object-safe (enabling `Vec<Box<dyn HomeCoreEntity>>`) or use associated types (enabling monomorphisation)? Object safety is required for the WASM plugin boundary (ADR-128); monomorphisation is faster for built-in integrations.
|
||||
|
||||
**Q4**: HA's `State.context` carries a `user_id` that traces which user or automation initiated a state change. HOMECORE uses `UserId` from the auth layer (ADR-130). Is the auth layer a dependency of the core state machine, or should `user_id` be an optional opaque string to avoid circular deps?
|
||||
|
||||
---
|
||||
|
||||
## 8. References
|
||||
|
||||
### HA upstream
|
||||
|
||||
- `homeassistant/core.py` — `HomeAssistant`, `StateMachine` (lines 1–800), `EventBus` (lines 800–1100), `ServiceRegistry` (lines 1100–1500), `Config` (lines 1500–2000)
|
||||
- `homeassistant/helpers/entity_registry.py` — `EntityRegistry`, `RegistryEntry` (all ~1,900 lines); schema version constant `STORAGE_VERSION`
|
||||
- `homeassistant/helpers/device_registry.py` — `DeviceRegistry`, `DeviceEntry`; schema version
|
||||
- `homeassistant/helpers/entity.py` — `Entity` base class; `async_write_ha_state`; entity lifecycle hooks
|
||||
- `homeassistant/helpers/event.py` — `async_track_state_change`, `async_track_time_interval`
|
||||
|
||||
### This repo
|
||||
|
||||
- `v2/crates/wifi-densepose-sensing-server/src/main.rs` — Axum + Tokio architecture pattern used throughout the existing server stack
|
||||
- `docs/adr/ADR-126-ruview-native-ha-port-master.md` — HOMECORE master; §5.5 crate naming; §6 compatibility contract; §5.1 RUVIEW-POLICY
|
||||
- `docs/adr/ADR-028-esp32-capability-audit.md` — witness chain pattern (Ed25519 per state transition)
|
||||
@@ -1,270 +0,0 @@
|
||||
# ADR-128: HOMECORE-PLUGINS — WASM integration plugin system
|
||||
|
||||
| Field | Value |
|
||||
|-------|-------|
|
||||
| **Status** | Proposed |
|
||||
| **Date** | 2026-05-25 |
|
||||
| **Deciders** | ruv |
|
||||
| **Codename** | **HOMECORE-PLUGINS** |
|
||||
| **Relates to** | [ADR-126](ADR-126-ruview-native-ha-port-master.md) (HOMECORE master), [ADR-127](ADR-127-homecore-state-machine-rust.md) (HOMECORE-CORE), [ADR-102](ADR-102-edge-module-registry.md) (cog registry), [ADR-100](ADR-100-cog-packaging-specification.md) (cog packaging spec) |
|
||||
| **Tracking issue** | TBD |
|
||||
|
||||
---
|
||||
|
||||
## 1. Context
|
||||
|
||||
Home Assistant ships approximately 2,000 integrations, each a Python module in `homeassistant/components/<domain>/`. Each integration:
|
||||
|
||||
1. Declares a **manifest** (`manifest.json`) with `domain`, `name`, `version`, `requirements` (pip packages), `dependencies` (other HA integrations), `codeowners`, `iot_class`, `config_flow` (bool), and `quality_scale`.
|
||||
2. Provides **`async_setup`** (global domain setup, called once at HA startup) and/or **`async_setup_entry`** (per-config-entry setup, called when a user adds an integration via the UI).
|
||||
3. Imports Python packages from `requirements` at load time — these are installed into HA's Python environment by the loader at first run.
|
||||
4. Communicates with the HA core exclusively through the `hass` object (the `HomeAssistant` instance) — setting states, calling services, registering services, subscribing to events.
|
||||
|
||||
In Python HA, integrations run **in-process** with the hub. A buggy integration can crash the event loop, read arbitrary HA memory, or import packages that conflict with other integrations. HA mitigates this via code review and quality scale requirements, but there is no runtime isolation boundary.
|
||||
|
||||
### 1.1 The Cognitum Seed cog system
|
||||
|
||||
The project already has a cog system (ADR-102, ADR-100) for the Cognitum Seed appliance. A **cog** is a signed, sandboxed module that installs from the Seed app registry. ADR-101 (`cog-pose-estimation`) shipped signed aarch64/x86_64 binaries with a model weight blob. ADR-116 (`cog-ha-matter`) shipped HA+Matter integration as a cog.
|
||||
|
||||
The cog system uses a different packaging model from HA integrations (binary artifacts vs Python packages), but the same conceptual pattern: a manifest, a lifecycle hook, and communication through a defined interface.
|
||||
|
||||
HOMECORE-PLUGINS unifies these two patterns: every HOMECORE integration is a **WASM module** that speaks the cog ABI, can be hot-loaded without restarting the hub, and is sandboxed by the WASM runtime.
|
||||
|
||||
---
|
||||
|
||||
## 2. Decision
|
||||
|
||||
HOMECORE integrations are **WASM modules** loaded by a Rust host runtime (`homecore-plugins` crate). Each plugin:
|
||||
|
||||
1. Compiles to a `.wasm` binary (from Rust, AssemblyScript, Go, or any WASM-targeting language).
|
||||
2. Declares a `manifest.json` (superset of HA's manifest schema — see §3).
|
||||
3. Exports exactly three WASM functions: `setup_entry(config_entry_ptr, config_entry_len) → i32`, `call_service(call_ptr, call_len) → i32`, and `receive_event(event_ptr, event_len) → i32`.
|
||||
4. Imports a set of **host functions** from the HOMECORE host runtime: `hc_state_get`, `hc_state_set`, `hc_event_fire`, `hc_service_call`, `hc_log`, `hc_entity_register`.
|
||||
5. Communicates with the host exclusively through those imports — no direct memory access outside its own linear memory.
|
||||
|
||||
The WASM runtime is **Wasmtime** (Cranelift JIT on Pi 5 and x86_64; interpretation mode available for low-memory targets via `--features wasm3`).
|
||||
|
||||
### 2.1 Why WASM over Python-in-process
|
||||
|
||||
| Criterion | Python in-process (HA today) | WASM sandbox (HOMECORE) |
|
||||
|---|---|---|
|
||||
| Memory isolation | None — any integration can read any HA object | WASM linear memory; host allocates shared buffer only for ABI calls |
|
||||
| Crash isolation | Integration panic = HA event loop crash | WASM trap = plugin terminated, hub continues |
|
||||
| Language support | Python only | Any WASM-targeting language: Rust, Go, AssemblyScript, C, Zig |
|
||||
| Hot-load without restart | No — requires `asyncio.run_coroutine_threadsafe` patching | Yes — Wasmtime `Engine` + `Module::deserialize` from compiled `.cwasm` cache |
|
||||
| Dependency conflicts | pip requirements collide across integrations | Each WASM module carries its own static dependencies (no runtime pip) |
|
||||
| Startup cost per integration | Python import + pip install | Wasmtime JIT compile (~5 ms for a typical 200 kB WASM module); cached to `.cwasm` |
|
||||
|
||||
### 2.2 Cog system as the plugin substrate
|
||||
|
||||
The existing cog system (ADR-102) is the distribution and lifecycle layer. HOMECORE-PLUGINS extends it:
|
||||
|
||||
- **Distribution**: cogs are fetched from the Seed app registry (`app-registry.json`) or from a HOMECORE plugin registry (superset of the cog registry, same JSON schema + a `wasm_module` field).
|
||||
- **Lifecycle**: `cognitum-agent` (ADR-116) already handles OTA update, signature verification, and sandboxed execution. HOMECORE-PLUGINS reuses this lifecycle by treating each HOMECORE integration as a cog with a WASM payload.
|
||||
- **Ed25519 signatures**: every plugin `.wasm` is signed with the publisher's Ed25519 key. The HOMECORE host verifies the signature before compiling the module (same pattern as ADR-028 witness chain).
|
||||
|
||||
---
|
||||
|
||||
## 3. Manifest schema
|
||||
|
||||
HOMECORE's manifest is a superset of HA's `manifest.json`. Fields not present in HA are marked **[HOMECORE]**.
|
||||
|
||||
```json
|
||||
{
|
||||
"domain": "mqtt",
|
||||
"name": "MQTT",
|
||||
"version": "2025.1.0",
|
||||
"documentation": "https://www.home-assistant.io/integrations/mqtt/",
|
||||
"iot_class": "local_push",
|
||||
"config_flow": true,
|
||||
"dependencies": [],
|
||||
"quality_scale": "platinum",
|
||||
"wasm_module": "mqtt.wasm",
|
||||
"wasm_module_hash": "sha256:abcdef...",
|
||||
"wasm_module_sig": "ed25519:<base64>",
|
||||
"publisher_key": "<base64 Ed25519 public key>",
|
||||
"min_homecore_version": "0.1.0",
|
||||
"host_imports_required": ["hc_state_get", "hc_state_set", "hc_event_fire", "hc_service_call"],
|
||||
"homecore_permissions": ["state:write:sensor.*", "state:read:*", "service:call:homeassistant.*"],
|
||||
"cog_id": "homecore-mqtt-2025.1.0"
|
||||
}
|
||||
```
|
||||
|
||||
**[HOMECORE]** fields:
|
||||
- `wasm_module` — relative path to the `.wasm` binary
|
||||
- `wasm_module_hash` — SHA-256 of the wasm binary; verified before execution
|
||||
- `wasm_module_sig` — Ed25519 signature of the wasm binary hash
|
||||
- `publisher_key` — Ed25519 public key of the publisher
|
||||
- `min_homecore_version` — minimum HOMECORE version required
|
||||
- `host_imports_required` — subset of host functions the module needs (security auditable)
|
||||
- `homecore_permissions` — coarse-grained permission claims (glob patterns); future: enforcement via RUVIEW-POLICY layer (ADR-124 §4.1a)
|
||||
- `cog_id` — Seed app registry ID for the cog distribution
|
||||
|
||||
---
|
||||
|
||||
## 4. HA-side reference table
|
||||
|
||||
| HA module / file | What it does | HOMECORE preserves | Changes | Drops |
|
||||
|---|---|---|---|---|
|
||||
| `homeassistant/components/<domain>/manifest.json` | Integration metadata | `domain`, `name`, `version`, `iot_class`, `config_flow`, `dependencies`, `quality_scale`, `documentation` | Add WASM fields; remove `requirements` (no pip) | `requirements` (pip packages) |
|
||||
| `homeassistant/loader.py` | Loads Python modules; installs pip requirements | Manifest parsing; dependency resolution between cogs | WASM module loading via Wasmtime; no pip | Python `importlib`, pip subprocess |
|
||||
| `homeassistant/components/<domain>/__init__.py` | `async_setup` + `async_setup_entry` | `setup_entry` hook (per config entry) | WASM export function instead of Python async function | Python module structure |
|
||||
| `homeassistant/config_entries.py` | Config entry lifecycle management | `ConfigEntry` struct: `entry_id`, `domain`, `title`, `data`, `options`, `state`, `version` | Rust struct; async state machine | Python class hierarchy; `FlowManager` |
|
||||
| `homeassistant/components/<domain>/config_flow.py` | UI configuration flow | Config flow metadata (steps, schemas) | JSON-schema-based flow descriptor shipped in manifest | `voluptuous`, Python UI flow runtime |
|
||||
|
||||
---
|
||||
|
||||
## 5. WASM ABI specification
|
||||
|
||||
### 5.1 Host functions imported by plugins
|
||||
|
||||
```
|
||||
hc_state_get(key_ptr: i32, key_len: i32, out_ptr: i32, out_cap: i32) → i32
|
||||
// Returns JSON-encoded State into out_ptr buffer; returns bytes written or -1 if not found.
|
||||
|
||||
hc_state_set(entity_ptr: i32, entity_len: i32, state_ptr: i32, state_len: i32,
|
||||
attrs_ptr: i32, attrs_len: i32) → i32
|
||||
// Sets state for entity_id; returns 0 on success, negative on error.
|
||||
|
||||
hc_event_fire(event_type_ptr: i32, event_type_len: i32,
|
||||
event_data_ptr: i32, event_data_len: i32) → i32
|
||||
// Fires a domain event.
|
||||
|
||||
hc_service_call(domain_ptr: i32, domain_len: i32,
|
||||
service_ptr: i32, service_len: i32,
|
||||
data_ptr: i32, data_len: i32) → i32
|
||||
// Calls a service synchronously from the plugin's perspective (async on the host).
|
||||
|
||||
hc_entity_register(entry_ptr: i32, entry_len: i32) → i32
|
||||
// Registers an entity with the entity registry; entry is JSON-encoded EntityEntry.
|
||||
|
||||
hc_log(level: i32, msg_ptr: i32, msg_len: i32) → void
|
||||
// Structured log output; level: 0=debug, 1=info, 2=warn, 3=error.
|
||||
```
|
||||
|
||||
### 5.2 WASM exports required by host
|
||||
|
||||
```
|
||||
setup_entry(config_entry_ptr: i32, config_entry_len: i32) → i32
|
||||
// Called when a config entry is set up. config_entry is JSON-encoded ConfigEntry.
|
||||
// Returns 0 on success, negative error code on failure.
|
||||
|
||||
call_service_handler(domain_ptr: i32, domain_len: i32,
|
||||
service_ptr: i32, service_len: i32,
|
||||
data_ptr: i32, data_len: i32) → i32
|
||||
// Called when a service registered by this plugin is invoked.
|
||||
|
||||
receive_event(event_type_ptr: i32, event_type_len: i32,
|
||||
event_data_ptr: i32, event_data_len: i32) → i32
|
||||
// Called when an event type the plugin subscribed to fires.
|
||||
// Subscription is declared in manifest `subscribed_events` array.
|
||||
|
||||
alloc(size: i32) → i32
|
||||
// Host calls this to allocate a buffer inside the WASM linear memory
|
||||
// before writing data for a callback. Required for ABI memory passing.
|
||||
|
||||
dealloc(ptr: i32, size: i32) → void
|
||||
// Host calls this to free a previously allocated buffer.
|
||||
```
|
||||
|
||||
### 5.3 Execution model
|
||||
|
||||
Each WASM module instance runs in its own Wasmtime `Store`. The host calls WASM exports from a dedicated Tokio task per plugin. Incoming events are queued in an `mpsc::Sender<PluginEvent>` per plugin; the plugin task drains the queue and calls `receive_event`. This isolates plugin execution from the hot state-machine path.
|
||||
|
||||
---
|
||||
|
||||
## 6. Public API parity table
|
||||
|
||||
| HA integration pattern | HOMECORE WASM equivalent |
|
||||
|---|---|
|
||||
| `async_setup_entry(hass, entry)` Python async function | `setup_entry(config_entry_json)` WASM export |
|
||||
| `hass.states.async_set(entity_id, state, attrs)` | `hc_state_set(...)` host import |
|
||||
| `hass.states.get(entity_id)` | `hc_state_get(...)` host import |
|
||||
| `hass.bus.async_fire(event_type, data)` | `hc_event_fire(...)` host import |
|
||||
| `hass.services.async_call(domain, service, data)` | `hc_service_call(...)` host import |
|
||||
| `hass.services.async_register(domain, service, handler)` | Declared in manifest `registered_services`; `call_service_handler` WASM export handles all |
|
||||
| `async_track_state_change(hass, entity_ids, callback)` | Declared in manifest `subscribed_state_entities`; `receive_event` called with `state_changed` events |
|
||||
| Config flow `FlowManager.async_init()` | Config flow metadata in manifest; UI calls HOMECORE-API `/config/config_entries/flow` |
|
||||
| `ConfigEntry.entry_id`, `.domain`, `.data`, `.options` | Same fields in `ConfigEntry` JSON passed to `setup_entry` |
|
||||
|
||||
---
|
||||
|
||||
## 7. Phased implementation plan
|
||||
|
||||
### P1 — WASM host skeleton (2 weeks)
|
||||
|
||||
- [ ] Create `v2/crates/homecore-plugins/` workspace member.
|
||||
- [ ] Wasmtime dependency; compile a trivial WASM module that calls `hc_log` and verify it runs.
|
||||
- [ ] Define the host function ABI in a `host_api.rs` module; write the Wasmtime `Linker` registration for all 6 host functions.
|
||||
- [ ] Manifest schema: `serde`-deserialised `Manifest` struct; validate required fields.
|
||||
- [ ] Hash + Ed25519 signature verification of `.wasm` bytes before compilation.
|
||||
|
||||
### P2 — State machine bridge (2 weeks)
|
||||
|
||||
- [ ] Wire `hc_state_get` and `hc_state_set` to the `homecore` state machine (ADR-127).
|
||||
- [ ] Wire `hc_event_fire` to the event bus.
|
||||
- [ ] Wire `hc_service_call` to the service registry.
|
||||
- [ ] Wire `hc_entity_register` to the entity registry.
|
||||
- [ ] Write a test plugin in Rust compiled to WASM: registers one entity, writes its state via host imports, verifies the state machine sees the update.
|
||||
|
||||
### P3 — Config entry lifecycle + hot-load (2 weeks)
|
||||
|
||||
- [ ] `ConfigEntryManager` — tracks loaded plugins, calls `setup_entry` on new config entries, handles teardown.
|
||||
- [ ] Hot-load: watch a directory for new `.wasm` + `manifest.json` pairs; load without hub restart.
|
||||
- [ ] Wasmtime compiled module cache: serialize to `.cwasm` after first JIT compile; deserialize on subsequent loads (sub-1 ms plugin restart).
|
||||
- [ ] Integration test: MQTT plugin loaded at runtime, registers `sensor.test` entity, state readable via HOMECORE-API.
|
||||
|
||||
### P4 — Cog registry integration (1 week)
|
||||
|
||||
- [ ] Fetch plugin from Seed app registry `app-registry.json`; verify Ed25519 signature against publisher key.
|
||||
- [ ] Expose `/api/homecore/plugins` REST endpoint (HOMECORE-API ADR-130 extension): list loaded plugins, load new plugin by URL, unload plugin.
|
||||
- [ ] First-party plugin: ship an MQTT plugin WASM module that provides the same function as HA's `homeassistant/components/mqtt/`.
|
||||
|
||||
### P5 — Permission enforcement (1 week)
|
||||
|
||||
- [ ] Enforce `homecore_permissions` claims: reject `hc_state_set` calls that write to entities outside the plugin's declared `state:write:*` pattern.
|
||||
- [ ] Log all permission denials to the Ed25519 witness chain.
|
||||
- [ ] Expose permission audit via `/api/homecore/plugins/<domain>/audit`.
|
||||
|
||||
---
|
||||
|
||||
## 8. Risks
|
||||
|
||||
| Risk | Likelihood | Severity | Mitigation | Cross-ADR impact |
|
||||
|---|---|---|---|---|
|
||||
| **ADR-127 state machine not stable** — plugin ABI calls into the state machine; if the API changes, all plugins break | High (early phase) | High | Freeze the `hc_state_get`/`hc_state_set` ABI in P1; never change pointer/length convention; version the host ABI in the manifest `min_homecore_version` | ADR-127 must freeze public API before ADR-128 P2 begins |
|
||||
| **Wasmtime binary size** — adding Wasmtime to HOMECORE adds ~15 MB to the binary on Pi 5 | Medium | Medium | Use Cranelift JIT only; skip LLVM optimizer. Alternative: `wasm3` feature flag (~50 kB) for constrained hardware | ADR-126: binary size target < 50 MB idle RAM; Wasmtime itself uses ~5 MB RAM at runtime |
|
||||
| **ABI memory overhead** — every state read/write from a plugin must JSON-encode/decode through shared memory | Medium | Medium | Cap state value size at 64 kB; use a pool allocator for ABI buffers; profile on Pi 5 at 10 state writes/s per plugin | ADR-130: REST API reads state from DashMap directly, bypassing plugin ABI — no overhead there |
|
||||
| **Community plugin trust** — WASM sandbox prevents crashes but cannot prevent malicious plugins from calling `hc_service_call` to turn off all lights | Medium | High | `homecore_permissions` permission claims (P5); future: RUVIEW-POLICY enforcement (ADR-124 §4.1a) for biometric data access | ADR-124 RUVIEW-POLICY must be made aware of HOMECORE as a policy principal |
|
||||
|
||||
---
|
||||
|
||||
## 9. Open questions
|
||||
|
||||
**Q1**: Should the WASM module ABI use JSON-over-shared-memory (current proposal) or a more compact binary encoding (MessagePack, FlatBuffers)? JSON is simpler to debug and matches HA's existing JSON-everywhere convention; MessagePack cuts ABI overhead by ~4×. Decide before P2 implementation.
|
||||
|
||||
**Q2**: HA's `config_flow.py` is a multi-step UI wizard with voluptuous schema validation. HOMECORE's config flow is described in the manifest JSON. Is a JSON-schema-based config flow sufficient for the 100 most popular integrations, or do some require imperative step logic that can't be expressed declaratively?
|
||||
|
||||
**Q3**: Should existing Python HA community integrations be automatically compilable to WASM via a transpilation layer (e.g. CPython compiled to WASM via Pyodide), or should HOMECORE accept only natively compiled WASM modules? Pyodide+WASM would make migration easier but adds ~25 MB per plugin and loses the performance argument.
|
||||
|
||||
**Q4**: The `host_imports_required` manifest field lists which host functions the plugin needs. Should this be verified at load time (reject plugin that imports undeclared functions) or only advisory? Strict enforcement prevents surprises; advisory aids migration.
|
||||
|
||||
---
|
||||
|
||||
## 10. References
|
||||
|
||||
### HA upstream
|
||||
|
||||
- `homeassistant/loader.py` — integration loader; pip requirement installation; `async_setup_entry` invocation
|
||||
- `homeassistant/config_entries.py` — `ConfigEntry`, `ConfigEntryState`, `ConfigEntriesError`, `FlowManager`
|
||||
- `homeassistant/components/mqtt/manifest.json` — canonical example of HA manifest structure
|
||||
- `homeassistant/components/mqtt/__init__.py` — `async_setup_entry` pattern for a complex integration with services
|
||||
- `homeassistant/components/mqtt/config_flow.py` — multi-step config flow example
|
||||
|
||||
### This repo
|
||||
|
||||
- `docs/adr/ADR-102-edge-module-registry.md` — cog registry architecture; `app-registry.json` schema
|
||||
- `docs/adr/ADR-100-cog-packaging-specification.md` — cog packaging spec; Ed25519 signing
|
||||
- `docs/adr/ADR-101-pose-estimation-cog.md` — cog lifecycle precedent
|
||||
- `docs/adr/ADR-127-homecore-state-machine-rust.md` — state machine ABI that plugins call
|
||||
- `docs/adr/ADR-126-ruview-native-ha-port-master.md` — §5.7 "do not port" list (legacy Python integrations)
|
||||
@@ -1,212 +0,0 @@
|
||||
# ADR-129: HOMECORE-AUTO — Automation engine, script runner, and template evaluator
|
||||
|
||||
| Field | Value |
|
||||
|-------|-------|
|
||||
| **Status** | Proposed |
|
||||
| **Date** | 2026-05-25 |
|
||||
| **Deciders** | ruv |
|
||||
| **Codename** | **HOMECORE-AUTO** |
|
||||
| **Relates to** | [ADR-126](ADR-126-ruview-native-ha-port-master.md) (HOMECORE master), [ADR-127](ADR-127-homecore-state-machine-rust.md) (HOMECORE-CORE), [ADR-129 implicit](ADR-129-homecore-automation-engine.md), [ADR-133](ADR-133-homecore-assist-ruflo.md) (HOMECORE-ASSIST) |
|
||||
| **Tracking issue** | TBD |
|
||||
|
||||
---
|
||||
|
||||
## 1. Context
|
||||
|
||||
Home Assistant's automation system is defined across three components:
|
||||
|
||||
1. **`homeassistant/components/automation/__init__.py`** — the automation manager: loads automation YAML, evaluates trigger platforms, calls the script executor when conditions pass. The core class is `AutomationEntity` which extends `ToggleEntity`. Automations are themselves HA entities with `state = on/off`.
|
||||
|
||||
2. **`homeassistant/components/script/__init__.py`** — the script executor: a sequence of actions (service calls, conditions, delays, events, template variables, `choose`, `parallel`, `repeat`, `wait_for_trigger`). Scripts are entities too (`ScriptEntity` extends `ToggleEntity`). The execution engine supports five run modes: `single`, `restart`, `queued`, `parallel`, `ignore_first`.
|
||||
|
||||
3. **`homeassistant/helpers/template.py`** — HA's Jinja2 customisation layer: wraps the upstream `jinja2` Python library with HA-specific globals (`states()`, `is_state()`, `state_attr()`, `now()`, `utcnow()`, `as_timestamp()`, `distance()`, `closest()`, etc.), custom filters (`regex_match`, `round`, `timestamp_local`), and a sandboxed `Environment` that prevents file I/O and dangerous evaluations.
|
||||
|
||||
### 1.1 Scale and surface
|
||||
|
||||
HA's automation YAML supports:
|
||||
- **17 trigger platforms** (state, time, numeric_state, template, event, homeassistant, zone, geo_location, device, calendar, conversation, mqtt, webhook, tag, sun, time_pattern, persistent_notification)
|
||||
- **7 condition types** (state, numeric_state, time, template, zone, sun, device)
|
||||
- **22+ action types** (call_service, delay, wait_template, fire_event, device_action, choose, if, parallel, repeat, sequence, stop, set_conversation_response, ...)
|
||||
|
||||
The YAML schema is validated by `voluptuous` schemas defined in `homeassistant/helpers/config_validation.py` (~5,000 lines).
|
||||
|
||||
### 1.2 Jinja2 is the critical surface
|
||||
|
||||
HA templates are used not only in automations but in dashboard cards, notification messages, and script variables. The HA frontend sends template strings to the API's `POST /api/template` endpoint for server-side evaluation. Any HOMECORE instance that claims API compatibility must execute Jinja2-compatible templates or existing automations will break.
|
||||
|
||||
Full Jinja2 support in Rust without Python is non-trivial. The approach chosen here uses a **WASM-compiled MiniJinja** (the `minijinja` Rust crate compiled with HA-specific extension functions) rather than a full Python Jinja2 re-implementation.
|
||||
|
||||
---
|
||||
|
||||
## 2. Decision
|
||||
|
||||
Build the `homecore-automation` crate with three components:
|
||||
|
||||
1. **YAML parser**: `serde_yaml` + custom validator that parses HA's automation and script YAML into typed Rust structs. Validates trigger, condition, and action schemas at load time.
|
||||
2. **Trigger evaluator**: a Tokio task per loaded automation that subscribes to the HOMECORE event bus (ADR-127) and evaluates trigger conditions in Rust. When a trigger fires and conditions pass, it enqueues the automation action sequence.
|
||||
3. **Action executor**: a script runner that processes action sequences. Service calls go to the HOMECORE service registry. Delays use `tokio::time::sleep`. Template evaluation uses MiniJinja. Complex conditions (optional) can route to a ruflo agent (ADR-133).
|
||||
|
||||
### 2.1 Template evaluator: MiniJinja + HA-compatible extension functions
|
||||
|
||||
`minijinja` (crates.io version 2.x) is a production-quality Jinja2 implementation in pure Rust. It is missing 5–10% of Jinja2's surface area (notably: `{% block %}` / `{% extends %}` template inheritance, and some Jinja2 Python-specific filters), but covers 100% of HA's automation template usage.
|
||||
|
||||
HA-specific globals added on top of MiniJinja:
|
||||
|
||||
```rust
|
||||
env.add_global("states", minijinja::Value::from_function(ha_states_global));
|
||||
env.add_global("is_state", minijinja::Value::from_function(ha_is_state_global));
|
||||
env.add_global("state_attr", minijinja::Value::from_function(ha_state_attr_global));
|
||||
env.add_global("now", minijinja::Value::from_function(ha_now_global));
|
||||
env.add_global("utcnow", minijinja::Value::from_function(ha_utcnow_global));
|
||||
env.add_global("as_timestamp", minijinja::Value::from_function(ha_as_timestamp_global));
|
||||
env.add_global("distance", minijinja::Value::from_function(ha_distance_global));
|
||||
env.add_global("iif", minijinja::Value::from_function(ha_iif_global));
|
||||
```
|
||||
|
||||
Each global function reads from the HOMECORE state machine (ADR-127) via an `Arc<StateMachine>` captured at environment construction time. Template evaluation is synchronous (MiniJinja is sync) but runs in a `tokio::task::spawn_blocking` wrapper to avoid blocking the async executor.
|
||||
|
||||
### 2.2 WASM evaluator for untrusted template strings
|
||||
|
||||
Dashboard card templates submitted via `POST /api/template` come from user-authored YAML, not first-party code. HA evaluates these in the same Python process, relying on Jinja2's `SandboxedEnvironment` for safety. HOMECORE uses a **WASM-sandboxed MiniJinja** evaluator:
|
||||
|
||||
- A single WASM module (`homecore-template-eval.wasm`) is compiled from the MiniJinja crate with the HA extension globals stubbed to call host functions.
|
||||
- Template strings are passed into the WASM module via the HOMECORE plugin ABI (ADR-128 §5.1).
|
||||
- The WASM sandbox prevents file I/O, network access, and infinite loops (via Wasmtime fuel metering — 100,000 instructions per template evaluation).
|
||||
- Result is returned as a string to the HOMECORE API.
|
||||
|
||||
This is the same Wasmtime host already used for integration plugins (ADR-128) — no additional WASM runtime dependency.
|
||||
|
||||
---
|
||||
|
||||
## 3. HA-side reference table
|
||||
|
||||
| HA module / file | What it does | HOMECORE preserves | Changes | Drops |
|
||||
|---|---|---|---|---|
|
||||
| `automation/__init__.py` `AutomationEntity` | Automation as a toggle entity (on/off) with triggers/conditions/actions | Automation is a HOMECORE entity with same on/off state semantics | Rust struct `AutomationEntity` implementing `HomeCoreEntity` trait | Python class hierarchy, voluptuous schema |
|
||||
| `automation/__init__.py` `TriggerActionConfig` | Trigger → condition → action pipeline | Full trigger/condition/action pipeline | Typed Rust enums per trigger platform | Python dict-based config |
|
||||
| `automation/trigger.py` | Delegates to per-platform trigger modules (`homeassistant/components/<platform>/trigger.py`) | Same per-platform dispatch | Rust match arm per trigger type | Python dynamic module import |
|
||||
| `script/__init__.py` `Script` | Script entity + action sequence executor | Same 22 action types | Rust enum `Action` with all variants | Python asyncio coroutines |
|
||||
| `script/__init__.py` run modes | `single`, `restart`, `queued`, `parallel`, `ignore_first` | All 5 run modes | Tokio-based concurrency control (semaphore for `queued`, `parallel`) | Python asyncio task management |
|
||||
| `helpers/template.py` `Template` | Jinja2 evaluation + HA globals | Same HA global function names and signatures | MiniJinja instead of Python Jinja2; WASM sandbox for user templates | Python `jinja2` library; `voluptuous` coercions in templates |
|
||||
| `helpers/config_validation.py` | `cv.template`, `cv.entity_id`, time period validators | Same validation semantics | Rust custom deserializers implementing `serde::Deserialize` | voluptuous; Python regex |
|
||||
| `components/automation/blueprint.py` | Blueprint system (reusable automation templates with input variables) | Blueprint YAML schema + variable substitution | Pure Rust YAML substitution | Python Blueprint class hierarchy |
|
||||
|
||||
---
|
||||
|
||||
## 4. Public API parity table
|
||||
|
||||
| HA automation surface | HOMECORE equivalent |
|
||||
|---|---|
|
||||
| `automation.trigger` (state, time, numeric_state, template, event, ...) | `Trigger` enum with variants for all 17 HA trigger platforms |
|
||||
| `automation.condition` (state, numeric_state, time, template, zone, sun, device) | `Condition` enum with variants for all 7 condition types |
|
||||
| `automation.action` — call_service, delay, fire_event, choose, if, parallel, repeat, wait_template, stop | `Action` enum with variants for all 22 action types |
|
||||
| `script.run_mode` — single, restart, queued, parallel | `RunMode` enum with 5 variants |
|
||||
| `POST /api/template` (REST eval of a template string) | Same endpoint in HOMECORE-API (ADR-130); backed by WASM-sandboxed MiniJinja |
|
||||
| Automation entity: `state = on|off`, `attributes.last_triggered`, `attributes.id` | `AutomationEntity` struct with same attribute names |
|
||||
| `automation.trigger` service (manually trigger an automation) | `homecore.automation.trigger` service; same service call data schema |
|
||||
| `automation.reload` service (reload automations.yaml) | `homecore.automation.reload` service |
|
||||
| `automation.toggle` service | Standard `HomeCoreEntity` toggle service |
|
||||
| Blueprint YAML with `blueprint:` key and `input:` variables | Blueprint parsed by HOMECORE YAML parser; same substitution semantics |
|
||||
|
||||
---
|
||||
|
||||
## 5. Trigger platform mapping
|
||||
|
||||
| HA trigger platform | HOMECORE implementation |
|
||||
|---|---|
|
||||
| `state` | Subscribe to `state_changed` broadcast; match `entity_id`, `from`, `to`, `for` |
|
||||
| `numeric_state` | Subscribe to `state_changed`; parse state as f64; compare against `above`/`below` |
|
||||
| `time` | `tokio::time::sleep_until` to next occurrence; re-arm after fire |
|
||||
| `time_pattern` | Cron-style evaluation using `cron` crate; tokio timer task |
|
||||
| `template` | Re-evaluate template on every `state_changed`; fire when template transitions from false to true |
|
||||
| `event` | Subscribe to named domain event on event bus |
|
||||
| `homeassistant` (start/stop) | Subscribe to `HomeAssistantStart` / `HomeAssistantStop` typed events |
|
||||
| `zone` | Subscribe to `zone.entered` / `zone.left` events from the device tracker integration |
|
||||
| `mqtt` | Subscribe to MQTT topic via the MQTT plugin (ADR-128); fire event when message arrives |
|
||||
| `webhook` | HOMECORE-API registers a webhook path; fires event on POST |
|
||||
| `calendar` | Subscribe to calendar event from calendar integration |
|
||||
| `conversation` | Subscribe to `conversation.user_input` event; match intent/sentence |
|
||||
| `geo_location` | Subscribe to `geo_location.entered` / `geo_location.left` |
|
||||
| `sun` | Compute sunrise/sunset from latitude/longitude in `homecore.config`; tokio timer |
|
||||
| `device` | Delegate to integration-specific device trigger via WASM plugin |
|
||||
| `persistent_notification` | Subscribe to `persistent_notification.create` event |
|
||||
| `tag` | Subscribe to `tag.scanned` event from NFC/QR integration |
|
||||
|
||||
---
|
||||
|
||||
## 6. Phased implementation plan
|
||||
|
||||
### P1 — YAML parser (2 weeks)
|
||||
|
||||
- [ ] Define Rust enums for `Trigger`, `Condition`, `Action`, `RunMode` with `serde` deserialization.
|
||||
- [ ] Parse an existing `automations.yaml` from a real HA install with zero errors (test fixture).
|
||||
- [ ] Validator: reject unknown trigger platforms with a clear error message.
|
||||
- [ ] Unit tests: parse 50 automation fixtures covering all 17 trigger types and 22 action types.
|
||||
|
||||
### P2 — State and event triggers (2 weeks)
|
||||
|
||||
- [ ] Implement `state`, `numeric_state`, `event`, `homeassistant`, `time`, `time_pattern` trigger evaluators.
|
||||
- [ ] `ConditionEvaluator` for `state`, `numeric_state`, `time` conditions.
|
||||
- [ ] `ActionExecutor` for `call_service`, `delay`, `fire_event`, `stop` action types.
|
||||
- [ ] Integration test: load one automation (state trigger → call_service action); verify fires correctly when state changes.
|
||||
|
||||
### P3 — Full action set + MiniJinja (3 weeks)
|
||||
|
||||
- [ ] MiniJinja + HA extension globals; `POST /api/template` endpoint wired to WASM evaluator.
|
||||
- [ ] `template` trigger + `template` condition evaluators.
|
||||
- [ ] `choose`, `if`, `parallel`, `repeat`, `wait_template`, `sequence` action types.
|
||||
- [ ] All 5 `RunMode` variants (concurrency control via Tokio semaphore/mutex).
|
||||
- [ ] Integration test: `automations.yaml` from ADR-134 migration fixture loads and runs correctly.
|
||||
|
||||
### P4 — Blueprint system + ruflo agent condition (1 week)
|
||||
|
||||
- [ ] Blueprint YAML parser + input variable substitution.
|
||||
- [ ] Optional ruflo agent condition: `condition: ruflo_agent` with `query: "..."` routes to ruflo LLM (ADR-133 §3.3); gated by RUVIEW-POLICY.
|
||||
- [ ] `automation.reload` service.
|
||||
- [ ] Performance benchmark: 100 automations loaded; 100 state changes/s; verify trigger evaluation stays < 5 ms per state change.
|
||||
|
||||
---
|
||||
|
||||
## 7. Risks
|
||||
|
||||
| Risk | Likelihood | Severity | Mitigation | Cross-ADR impact |
|
||||
|---|---|---|---|---|
|
||||
| **MiniJinja gaps** — some HA templates use Jinja2 features MiniJinja doesn't support (template inheritance, Python-specific filters) | Medium | Medium | Document the MiniJinja-vs-Jinja2 delta before P3 ships; provide a migration guide for affected templates; defer the 5% of templates that fail to a Python-compat shim (ADR-134) | ADR-134: migration tool must warn on templates that use unsupported Jinja2 features |
|
||||
| **Template performance** — synchronous MiniJinja in `spawn_blocking` adds overhead under high automation fan-out | Low | Low | Benchmark at 50 automations each evaluating a template trigger on every state_changed (worst case); if > 2 ms add a template-evaluation cache keyed by (template_hash, relevant_entity_states) | ADR-127: state machine must expose a "relevant states snapshot" API for caching |
|
||||
| **ADR-127 state machine API not frozen** — trigger evaluators call `hass.states.all()` and subscribe to broadcasts; if those APIs change, trigger code must update | High (early) | High | ADR-127 must freeze its public API before ADR-129 P2 begins; use a `HomeCoreRef` trait (version 1.0 stable) | ADR-127 owns this dependency |
|
||||
| **Complex action YAML** — real-world automations use deeply nested `choose`/`if`/`parallel` blocks; parsing is non-trivial | Medium | Medium | Use a corpus of 500 public HA automations from the HA community (MIT-licensed) as parse-test fixtures in CI | None |
|
||||
|
||||
---
|
||||
|
||||
## 8. Open questions
|
||||
|
||||
**Q1**: MiniJinja does not support all Python-specific Jinja2 filters (e.g. `map`, `select`, `reject` with Python lambda arguments). HA's `homeassistant/helpers/template.py` adds custom equivalents of several of these. How many real-world HA automations use these filters? A corpus analysis of public HA configs on GitHub would answer this before P3 implementation.
|
||||
|
||||
**Q2**: HA's `template` trigger supports a `value_template` that can reference `trigger.to_state`, `trigger.from_state`, and `trigger.for`. This requires passing trigger context into the template evaluation scope. Is this context threading straightforward in MiniJinja, or does it require a custom context type?
|
||||
|
||||
**Q3**: The `conversation` trigger in HA uses the Assist pipeline's intent matching to fire automations based on voice commands. HOMECORE-ASSIST (ADR-133) owns the pipeline. Should the `conversation` trigger be implemented in ADR-129 (automation engine dependency on ADR-133) or in ADR-133 (assist pipeline fires automation events that ADR-129 listens to)?
|
||||
|
||||
**Q4**: HA blueprints have a community sharing mechanism (blueprint.exchange). Should HOMECORE support importing blueprints from HA's blueprint exchange directly, or only local blueprints?
|
||||
|
||||
---
|
||||
|
||||
## 9. References
|
||||
|
||||
### HA upstream
|
||||
|
||||
- `homeassistant/components/automation/__init__.py` — `AutomationEntity`, `AutomationConfig`, trigger/condition/action pipeline
|
||||
- `homeassistant/components/script/__init__.py` — `Script`, `ScriptEntity`, run modes, action sequence execution
|
||||
- `homeassistant/helpers/template.py` — `Template` class, `TemplateEnvironment`, all HA-specific Jinja2 globals and filters
|
||||
- `homeassistant/helpers/config_validation.py` — voluptuous schema definitions for all automation/script YAML elements
|
||||
- `homeassistant/components/automation/blueprint.py` — Blueprint input substitution
|
||||
|
||||
### This repo
|
||||
|
||||
- `docs/adr/ADR-127-homecore-state-machine-rust.md` — state machine and event bus that triggers subscribe to
|
||||
- `docs/adr/ADR-133-homecore-assist-ruflo.md` — ruflo agent condition + conversation trigger dependency
|
||||
- `docs/adr/ADR-134-homecore-migration-from-python-ha.md` — migration tool reads `automations.yaml`
|
||||
|
||||
### External
|
||||
|
||||
- [minijinja crates.io](https://crates.io/crates/minijinja) — Jinja2-compatible template engine in Rust
|
||||
- [HA Automation Templating docs](https://www.home-assistant.io/docs/automation/templating/) — HA-specific template globals reference
|
||||
@@ -1,218 +0,0 @@
|
||||
# ADR-130: HOMECORE-API — Wire-compatible REST and WebSocket API
|
||||
|
||||
| Field | Value |
|
||||
|-------|-------|
|
||||
| **Status** | Proposed |
|
||||
| **Date** | 2026-05-25 |
|
||||
| **Deciders** | ruv |
|
||||
| **Codename** | **HOMECORE-API** |
|
||||
| **Relates to** | [ADR-126](ADR-126-ruview-native-ha-port-master.md) (HOMECORE master), [ADR-127](ADR-127-homecore-state-machine-rust.md) (HOMECORE-CORE), [ADR-055](ADR-055-integrated-sensing-server.md) (sensing-server Axum pattern), [ADR-124](ADR-124-rvagent-mcp-ruvector-npm-integration.md) (SENSE-BRIDGE — bearer auth pattern) |
|
||||
| **Tracking issue** | TBD |
|
||||
|
||||
---
|
||||
|
||||
## 1. Context
|
||||
|
||||
Home Assistant's HTTP and WebSocket APIs are the primary interface for every non-frontend client: the iOS companion app, the Android companion app, HACS, Node-RED, the `homeassistant` Python client library, ESPHome native API clients, external automation scripts, and the hundreds of third-party HA dashboard projects.
|
||||
|
||||
The API surface is defined in two Python modules:
|
||||
|
||||
1. **`homeassistant/components/api/__init__.py`** — 24 REST API routes mounted at `/api/`. Key routes: `GET /api/`, `GET /api/states`, `GET /api/states/<entity_id>`, `POST /api/states/<entity_id>`, `GET /api/events`, `POST /api/events/<event_type>`, `GET /api/services`, `POST /api/services/<domain>/<service>`, `GET /api/error_log`, `GET /api/config`, `POST /api/template`, `POST /api/check_config`, `GET /api/history/period/<datetime>` (deprecated — recorder), `POST /api/logbook/` (deprecated — recorder).
|
||||
|
||||
2. **`homeassistant/components/websocket_api/`** — the WebSocket API handler (`connection.py` handles auth handshake; `commands.py` handles 30+ command types). Key commands: `auth`, `subscribe_events`, `unsubscribe_events`, `call_service`, `get_states`, `get_services`, `get_config`, `subscribe_trigger`, `render_template`, `validate_config`, `subscribe_entities` (entity registry updates), `config/entity_registry/list`, and many more.
|
||||
|
||||
### 1.1 Auth model
|
||||
|
||||
HA uses **long-lived access tokens (LLAT)** as the primary auth mechanism for non-UI clients. Tokens are created in the HA user profile UI and stored in `.storage/auth`. The REST API accepts `Authorization: Bearer <token>` or the `api_password` legacy header (deprecated since HA 2022.x). The WebSocket API requires an `auth` message with `access_token` as the first message after connection.
|
||||
|
||||
### 1.2 Why wire-compat matters
|
||||
|
||||
The iOS and Android HA companion apps (>100,000 installs combined) hardcode the HA API paths and WebSocket command schemas. Any implementation that deviates from the exact JSON schemas causes the apps to fail silently — not with a meaningful error, but by returning empty entity lists or missing state updates. Wire-compat is therefore a hard requirement, not a nice-to-have.
|
||||
|
||||
The baseline for compatibility is **HA 2025.1** (the version that introduced SQLite recorder schema version 48). Any HOMECORE instance claiming compliance with this ADR must pass the companion app integration test suite.
|
||||
|
||||
---
|
||||
|
||||
## 2. Decision
|
||||
|
||||
Implement the `homecore-api` crate as an Axum-based server that replicates the HA REST and WebSocket API on port 8123. The implementation is informed by — but does not copy — `homeassistant/components/api/__init__.py` and `homeassistant/components/websocket_api/`.
|
||||
|
||||
The server reuses the Axum + Tokio architecture established in `v2/crates/wifi-densepose-sensing-server/src/main.rs` and its bearer auth pattern (`v2/crates/wifi-densepose-sensing-server/src/bearer_auth.rs`).
|
||||
|
||||
### 2.1 REST API route table
|
||||
|
||||
| Route | Method | HA source line (approx.) | HOMECORE status |
|
||||
|---|---|---|---|
|
||||
| `/api/` | GET | `api/__init__.py:74` | P2 — returns `{ "message": "API running." }` |
|
||||
| `/api/config` | GET | `api/__init__.py:97` | P2 — returns `homecore.config` as JSON |
|
||||
| `/api/states` | GET | `api/__init__.py:116` | P2 — returns `hass.states.all()` as JSON array |
|
||||
| `/api/states/<entity_id>` | GET | `api/__init__.py:130` | P2 |
|
||||
| `/api/states/<entity_id>` | POST | `api/__init__.py:145` | P2 — writes state; fires `state_changed` |
|
||||
| `/api/events` | GET | `api/__init__.py:168` | P3 |
|
||||
| `/api/events/<event_type>` | POST | `api/__init__.py:180` | P3 — fires domain event |
|
||||
| `/api/services` | GET | `api/__init__.py:192` | P2 |
|
||||
| `/api/services/<domain>/<service>` | POST | `api/__init__.py:206` | P2 |
|
||||
| `/api/template` | POST | `api/__init__.py:222` | P3 — WASM MiniJinja evaluator (ADR-129) |
|
||||
| `/api/check_config` | POST | `api/__init__.py:240` | P4 |
|
||||
| `/api/error_log` | GET | `api/__init__.py:252` | P3 |
|
||||
| `/api/history/period/<datetime>` | GET | `api/__init__.py:270` | P4 — recorder query (ADR-132) |
|
||||
| `/api/logbook/` | POST | `api/__init__.py:310` | P4 — recorder query |
|
||||
| `/api/camera_proxy/<entity_id>` | GET | `api/__init__.py:330` | P4 — proxy to camera integration |
|
||||
| `/api/calendar/<entity_id>` | GET | `api/__init__.py:348` | P4 |
|
||||
| `/api/webhook/<webhook_id>` | POST/GET | `api/__init__.py:368` | P3 — fires `webhook.<id>` event |
|
||||
| `/api/intent/handle` | POST | `api/__init__.py:400` | P4 — HOMECORE-ASSIST (ADR-133) |
|
||||
| `/auth/token` | POST | `auth/providers/__init__.py` | P2 — issue LLAT from username/password |
|
||||
| `/auth/authorize` | GET/POST | `auth/providers/__init__.py` | P3 — OAuth2 flow |
|
||||
| `/frontend/` static assets | GET | `frontend/__init__.py` | P1 — serve HA Python frontend static files until ADR-131 ships |
|
||||
|
||||
### 2.2 WebSocket API command table
|
||||
|
||||
| WS command type | HA source | HOMECORE status |
|
||||
|---|---|---|
|
||||
| `auth` (handshake) | `websocket_api/connection.py:55` | P2 |
|
||||
| `subscribe_events` | `websocket_api/commands.py:120` | P2 |
|
||||
| `unsubscribe_events` | `websocket_api/commands.py:145` | P2 |
|
||||
| `call_service` | `websocket_api/commands.py:160` | P2 |
|
||||
| `get_states` | `websocket_api/commands.py:200` | P2 |
|
||||
| `get_services` | `websocket_api/commands.py:218` | P2 |
|
||||
| `get_config` | `websocket_api/commands.py:230` | P2 |
|
||||
| `subscribe_trigger` | `websocket_api/commands.py:250` | P3 |
|
||||
| `render_template` | `websocket_api/commands.py:280` | P3 |
|
||||
| `validate_config` | `websocket_api/commands.py:300` | P3 |
|
||||
| `subscribe_entities` | `websocket_api/commands.py:320` | P3 — entity registry update stream |
|
||||
| `config/entity_registry/list` | `websocket_api/commands.py:370` | P3 |
|
||||
| `config/entity_registry/update` | `websocket_api/commands.py:400` | P3 |
|
||||
| `config/area_registry/list` | `websocket_api/commands.py:450` | P3 |
|
||||
| `config/device_registry/list` | `websocket_api/commands.py:480` | P3 |
|
||||
| `config/config_entries/list` | `websocket_api/commands.py:510` | P3 |
|
||||
| `lovelace/config` (dashboard) | `lovelace/dashboard.py` | P4 — reads from HOMECORE storage |
|
||||
| `media_player/*` | `websocket_api/commands.py:600` | P4 |
|
||||
|
||||
### 2.3 Auth implementation
|
||||
|
||||
HOMECORE-API implements long-lived access tokens as JWTs signed with an Ed25519 key (generated at first startup, stored in `.homecore/auth_key.pem`). Token format:
|
||||
|
||||
```json
|
||||
{
|
||||
"sub": "<user_id>",
|
||||
"iss": "homecore",
|
||||
"iat": <unix_timestamp>,
|
||||
"exp": <unix_timestamp or null for LLAT>,
|
||||
"type": "long_lived_access_token"
|
||||
}
|
||||
```
|
||||
|
||||
The HA companion app sends `Authorization: Bearer <token>` on every REST request. The WebSocket auth handshake sends `{ "type": "auth", "access_token": "<token>" }`. Both paths validate the JWT against the stored Ed25519 key.
|
||||
|
||||
Legacy `api_password` is deliberately not supported (removed in HA 2022.x and never properly secure).
|
||||
|
||||
---
|
||||
|
||||
## 3. HA-side reference table
|
||||
|
||||
| HA module / file | What it does | HOMECORE preserves | Changes | Drops |
|
||||
|---|---|---|---|---|
|
||||
| `components/api/__init__.py` | 24 REST routes + JSON response schemas | All response schemas byte-compatible with HA 2025.1 | Axum router instead of HA's custom HTTP component; `serde_json` instead of Python `json` | Python HTTP request context; HA's built-in CORS middleware (replicated in Axum) |
|
||||
| `components/websocket_api/connection.py` | WS auth handshake; per-connection state; message dispatch | Auth handshake flow: `auth_required` → `auth` message → `auth_ok` or `auth_invalid` | Axum `WebSocketUpgrade` extractor; per-connection `tokio::task` | Python asyncio message handling |
|
||||
| `components/websocket_api/commands.py` | 30+ WS command handlers | All command type strings; response envelope `{ id, type, result }` or error `{ id, type, error: { code, message } }` | Rust match dispatch; Tokio broadcast receiver per subscription | Python class-based command handler registration |
|
||||
| `auth/providers/__init__.py` | Auth providers; LLAT issuance; OAuth2 flow | LLAT issuance; token validation | Ed25519 JWT instead of HA's custom token serializer; same token `type` field values | Nabu Casa cloud auth; multi-provider auth chain |
|
||||
| `components/http/__init__.py` | Aiohttp-based HTTP server setup; CORS; trusted proxies | CORS headers; `X-Forwarded-For` trusted proxy handling | Axum Tower middleware | Aiohttp; Python SSL context |
|
||||
|
||||
---
|
||||
|
||||
## 4. Public API parity table
|
||||
|
||||
| HA API surface | HOMECORE exact equivalent |
|
||||
|---|---|
|
||||
| `GET /api/states` → `[{entity_id, state, attributes, last_changed, last_updated, context}]` | Identical JSON schema; `last_changed` / `last_updated` in ISO 8601 |
|
||||
| `GET /api/services` → `{domain: {service: {description, fields}}}` | Identical schema; service descriptions read from plugin manifests |
|
||||
| WS `subscribe_events` → `{type: "event", event: {event_type, data, origin, time_fired, context}}` | Identical envelope; `time_fired` in ISO 8601 |
|
||||
| WS `call_service` → `{type: "result", success: true, result: {context}}` | Identical; `context.id` is a UUID |
|
||||
| WS `get_states` → `{type: "result", result: [{entity_id, state, attributes, ...}]}` | Identical schema |
|
||||
| REST `POST /api/services/<domain>/<service>` → 200 with called service list | Identical; same `target` field support |
|
||||
| REST `POST /api/template` → 200 with evaluated string | Identical; same error response `{message: "..."}` on template error |
|
||||
| Auth WS flow: `auth_required` → `auth` → `auth_ok` | Identical message type strings; same `ha_version` field in `auth_required` |
|
||||
| REST `Authorization: Bearer <token>` | Identical header name; JWT instead of HA's opaque token format (transparent to clients) |
|
||||
|
||||
---
|
||||
|
||||
## 5. Phased implementation plan
|
||||
|
||||
### P1 — Axum skeleton + static frontend (1 week)
|
||||
|
||||
- [ ] Create `v2/crates/homecore-api/` workspace member.
|
||||
- [ ] Axum router on port 8123; Tower CORS middleware (allow `http://homeassistant.local:8123`).
|
||||
- [ ] Static file handler: serve HA's Python frontend build from a configurable path (default `./frontend/build/`). This allows using the Python HA frontend as-is until ADR-131 ships.
|
||||
- [ ] `GET /api/` returns `{ "message": "API running." }`.
|
||||
- [ ] CI: `cargo check -p homecore-api`; HTTP smoke test.
|
||||
|
||||
### P2 — Core REST + WebSocket auth + states (3 weeks)
|
||||
|
||||
- [ ] Axum WebSocket upgrade at `/api/websocket`.
|
||||
- [ ] Auth: Ed25519 JWT issuance at `/auth/token`; validation middleware.
|
||||
- [ ] WS auth handshake: `auth_required` → `auth` → `auth_ok` / `auth_invalid`.
|
||||
- [ ] WS commands: `get_states`, `subscribe_events`, `unsubscribe_events`, `call_service`, `get_services`, `get_config`.
|
||||
- [ ] REST: `/api/states`, `/api/states/<entity_id>` (GET + POST), `/api/services`, `/api/services/<domain>/<service>`, `/api/config`.
|
||||
- [ ] Integration test: HA iOS companion app authenticates and displays entity list against HOMECORE.
|
||||
|
||||
### P3 — Remaining WS commands + entity registry API (3 weeks)
|
||||
|
||||
- [ ] WS: `subscribe_trigger`, `render_template`, `validate_config`, `subscribe_entities`, entity/area/device registry commands.
|
||||
- [ ] REST: `/api/template`, `/api/webhook/<id>`, `/api/error_log`, `/api/events`, `/api/events/<type>`.
|
||||
- [ ] `/auth/authorize` OAuth2 flow for UI login.
|
||||
- [ ] HACS smoke test: HACS connects, lists integrations.
|
||||
|
||||
### P4 — Recorder + history API (2 weeks)
|
||||
|
||||
- [ ] `/api/history/period/<datetime>` backed by ADR-132 recorder SQLite.
|
||||
- [ ] `/api/logbook/` backed by ADR-132 recorder.
|
||||
- [ ] `/api/camera_proxy/`, `/api/calendar/`, `/api/intent/handle`.
|
||||
- [ ] Companion app full feature test: automations, notifications, history charts.
|
||||
|
||||
---
|
||||
|
||||
## 6. Risks
|
||||
|
||||
| Risk | Likelihood | Severity | Mitigation | Cross-ADR impact |
|
||||
|---|---|---|---|---|
|
||||
| **JSON schema drift** — HA updates a response field name between 2025.1 and HOMECORE release | Medium | High | Maintain a JSON-schema test fixture set generated from HA 2025.1; run against HOMECORE in CI | ADR-134: migration tool depends on the same JSON schemas; must stay in sync |
|
||||
| **WS subscription fan-out** — 50 concurrent HA companion app sessions each subscribed to `subscribe_events` ALL; every state change creates 50 serialization tasks | Medium | Medium | Broadcast serialized JSON once; clone the `Bytes` arc to each subscriber sender; do not re-serialize per subscriber | ADR-127: broadcast channel capacity must handle subscriber fan-out without lagging |
|
||||
| **Auth token format** — HA companion apps may validate the token format (JWT vs opaque). HOMECORE uses JWT; HA uses a custom opaque token. Tokens are never decoded client-side in standard clients, but non-standard clients may inspect them | Low | Low | JWTs are base64url-encoded JSON; any client checking `token.startsWith("ey")` will see a JWT. HA's own tokens are also base64url but not JWTs. Document the difference; test with the iOS app specifically | None |
|
||||
| **Port 8123 conflict** — HOMECORE runs on the same port as HA; side-by-side mode (ADR-134) requires HOMECORE on a different port until cutover | High | Medium | ADR-134 side-by-side mode runs HOMECORE on port 8124; companion app can be pointed at port 8124 for testing | ADR-134 owns the cutover mechanism |
|
||||
|
||||
---
|
||||
|
||||
## 7. Open questions
|
||||
|
||||
**Q1**: The HA WebSocket API uses incremental integer IDs (`id: 1, 2, 3, ...`) for command/response correlation within a session. HOMECORE uses the same scheme. What is the maximum `id` value the companion app supports before wrapping? If the app doesn't wrap and HOMECORE processes > 2^31 commands per session, this becomes an overflow issue in extremely long-lived sessions.
|
||||
|
||||
**Q2**: The `subscribe_entities` WS command (added in HA 2021.x) sends entity registry change events in addition to state change events. The iOS companion app uses this to maintain a local entity list without polling. Is the full `subscribe_entities` delta schema (including `action: "create" | "update" | "remove"`) fully documented, or must it be reverse-engineered from the companion app source?
|
||||
|
||||
**Q3**: HA's `/auth/token` endpoint accepts `grant_type=password` (username/password) and `grant_type=refresh_token`. HOMECORE's initial implementation supports password grant only. Is refresh token support required for the companion app (it caches tokens between sessions) or does the companion app re-authenticate on each launch?
|
||||
|
||||
**Q4**: CORS policy: HA's default CORS allows `http://localhost:*` and `http://homeassistant.local:*`. The HOMECORE-UI frontend (ADR-131) will be served from a different origin in development. What CORS policy should HOMECORE-API use in production vs development mode?
|
||||
|
||||
---
|
||||
|
||||
## 8. References
|
||||
|
||||
### HA upstream
|
||||
|
||||
- `homeassistant/components/api/__init__.py` — 24 REST routes with exact URL paths, methods, and JSON response schemas
|
||||
- `homeassistant/components/websocket_api/connection.py` — auth handshake protocol; per-connection state management
|
||||
- `homeassistant/components/websocket_api/commands.py` — 30+ command type handlers with exact type strings and result schemas
|
||||
- `homeassistant/components/http/__init__.py` — CORS setup; trusted proxy handling; aiohttp-based server
|
||||
- `homeassistant/auth/providers/__init__.py` — token issuance; `AuthManager`; LLAT format
|
||||
- `homeassistant/auth/__init__.py` — `AuthManager.async_create_long_lived_access_token`
|
||||
|
||||
### This repo
|
||||
|
||||
- `v2/crates/wifi-densepose-sensing-server/src/main.rs` — Axum server architecture (REST + WebSocket); pattern for this ADR
|
||||
- `v2/crates/wifi-densepose-sensing-server/src/bearer_auth.rs` — Bearer auth middleware pattern
|
||||
- `docs/adr/ADR-127-homecore-state-machine-rust.md` — state machine that REST/WS routes read from
|
||||
- `docs/adr/ADR-126-ruview-native-ha-port-master.md` — §6 compatibility contract with companion apps
|
||||
|
||||
### External
|
||||
|
||||
- [HA WebSocket API Developer Docs](https://developers.home-assistant.io/docs/api/websocket/) — authoritative command type catalog
|
||||
- [HA REST API](https://developers.home-assistant.io/docs/api/rest/) — REST endpoint schemas
|
||||
@@ -1,176 +0,0 @@
|
||||
# ADR-133: HOMECORE-ASSIST — Voice/Intent Pipeline + Ruflo Agent Bridge
|
||||
|
||||
| Field | Value |
|
||||
|-------|-------|
|
||||
| **Status** | Proposed |
|
||||
| **Date** | 2026-05-25 |
|
||||
| **Deciders** | ruv |
|
||||
| **Codename** | **HOMECORE-ASSIST** |
|
||||
| **Relates to** | [ADR-126](ADR-126-ruview-native-ha-port-master.md) (HOMECORE master), [ADR-127](ADR-127-homecore-state-machine-rust.md) (HOMECORE-CORE), [ADR-130](ADR-130-homecore-rest-websocket-api.md) (HOMECORE-API), [ADR-124](ADR-124-rvagent-mcp-ruvector-npm-integration.md) (SENSE-BRIDGE) |
|
||||
| **Tracking issue** | TBD |
|
||||
| **Crate** | `v2/crates/homecore-assist` |
|
||||
|
||||
---
|
||||
|
||||
## 1. Context
|
||||
|
||||
Home Assistant's Assist pipeline (`homeassistant/components/assist_pipeline/`) provides
|
||||
voice-to-intent-to-response processing. It chains:
|
||||
|
||||
1. **STT** (speech-to-text) — Whisper, cloud, or satellite
|
||||
2. **NLU** (natural language understanding) — intent recognition via regex/slots
|
||||
3. **Intent handler** — maps intent to a HA service call
|
||||
4. **TTS** (text-to-speech) — synthesises the response for the caller
|
||||
|
||||
HA's intent model (`homeassistant/helpers/intent.py`) is keyword/regex based. Every
|
||||
intent is a named template with slot definitions and a handler that dispatches to HA
|
||||
services. The built-in intents (`homeassistant/components/conversation/default_agent.py`)
|
||||
cover `HassTurnOn`, `HassTurnOff`, `HassLightSet`, `HassNevermind`, `HassCancelAll`,
|
||||
`HassGetState`, `HassGetWeather`, and many others.
|
||||
|
||||
HOMECORE needs a wire-compatible Assist pipeline so that:
|
||||
- The HA iOS/Android companion app's "Assist" button works against HOMECORE.
|
||||
- The HOMECORE-API WebSocket `assist` command (ADR-130 §2.2) has a handler.
|
||||
- The ruflo agent toolchain (ADR-124) can provide LLM-grade intent disambiguation as a
|
||||
drop-in upgrade path for the P1 regex recognizer.
|
||||
|
||||
### 1.1 Ruflo integration approach
|
||||
|
||||
Ruflo's agent runner exposes an MCP-over-stdio interface (`node ruflo-agent.js`).
|
||||
HOMECORE-ASSIST manages a long-lived subprocess (Q3 Windows concern below), sends
|
||||
utterance JSON, and receives intent JSON back. In P1 we ship only the trait surface
|
||||
and a `NoopRunner` stub; the real subprocess management is P2.
|
||||
|
||||
### 1.2 Ruvector semantic intent matching (P2)
|
||||
|
||||
`ruvector-core` provides embedding + cosine-similarity primitives. P2 will add a
|
||||
`SemanticIntentRecognizer` that embeds the utterance and compares it to a HNSW index
|
||||
of intent exemplars, falling back to the P1 regex recognizer when similarity < 0.75.
|
||||
This is the mechanism that allows "dim the lights" to match `HassLightSet` without an
|
||||
explicit regex entry.
|
||||
|
||||
---
|
||||
|
||||
## 2. Design
|
||||
|
||||
### 2.1 Module layout (`v2/crates/homecore-assist/`)
|
||||
|
||||
| Module | Contents |
|
||||
|--------|----------|
|
||||
| `intent` | `IntentName` newtype, `Intent` (name + slots), `IntentResponse` (speech + optional card + optional data) |
|
||||
| `recognizer` | `IntentRecognizer` trait; `RegexIntentRecognizer` (P1); `SemanticIntentRecognizer` stub (P2) |
|
||||
| `handler` | `IntentHandler` trait; built-in handlers: `HassTurnOn`, `HassTurnOff`, `HassLightSet`, `HassNevermind`, `HassCancelAll` |
|
||||
| `runner` | `RufloRunner` trait + `RufloRunnerOpts`; `NoopRunner` (P1 stub); real subprocess runner (P2) |
|
||||
| `pipeline` | `AssistPipeline`: wires recognizer → handler → response; exposes `async fn process(utterance, language) -> IntentResponse` |
|
||||
|
||||
### 2.2 Built-in intent handlers (P1)
|
||||
|
||||
| Handler | HA service call | Slot |
|
||||
|---------|-----------------|------|
|
||||
| `HassTurnOn` | `homeassistant.turn_on` / `light.turn_on` / `switch.turn_on` | `entity_id` |
|
||||
| `HassTurnOff` | `homeassistant.turn_off` / `light.turn_off` / `switch.turn_off` | `entity_id` |
|
||||
| `HassLightSet` | `light.turn_on` | `entity_id`, `brightness` (0–255), `color_name` |
|
||||
| `HassNevermind` | — (no-op, returns acknowledgement) | — |
|
||||
| `HassCancelAll` | — (fires `homeassistant_stop_all_scripts` domain event) | — |
|
||||
|
||||
### 2.3 IntentResponse
|
||||
|
||||
```rust
|
||||
pub struct IntentResponse {
|
||||
pub speech: String,
|
||||
pub card: Option<Card>,
|
||||
pub data: Option<serde_json::Value>,
|
||||
}
|
||||
|
||||
pub struct Card {
|
||||
pub title: String,
|
||||
pub content: String,
|
||||
}
|
||||
```
|
||||
|
||||
### 2.4 RufloRunner trait
|
||||
|
||||
```rust
|
||||
#[async_trait]
|
||||
pub trait RufloRunner: Send + Sync + 'static {
|
||||
async fn spawn(&mut self, opts: RufloRunnerOpts) -> Result<(), AssistError>;
|
||||
async fn send_request(&self, payload: serde_json::Value) -> Result<RufloResponse, AssistError>;
|
||||
async fn shutdown(&mut self) -> Result<(), AssistError>;
|
||||
}
|
||||
```
|
||||
|
||||
`RufloResponse` is `{ intent: Option<Intent>, speech: Option<String> }`.
|
||||
|
||||
### 2.5 Pipeline
|
||||
|
||||
```rust
|
||||
pub struct AssistPipeline<R, H> {
|
||||
recognizer: R,
|
||||
handler: H,
|
||||
runner: Option<Box<dyn RufloRunner>>,
|
||||
}
|
||||
|
||||
impl<R: IntentRecognizer, H: IntentHandler> AssistPipeline<R, H> {
|
||||
pub async fn process(&self, utterance: &str, language: &str, hc: &HomeCore)
|
||||
-> Result<IntentResponse, AssistError>;
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 3. Questions & Answers
|
||||
|
||||
### Q1 — Why not reuse HA's existing `homeassistant.helpers.intent` via PyO3?
|
||||
|
||||
PyO3 bridges add a GIL lock on every cross-language call; the Assist pipeline processes
|
||||
hundreds of short utterances per day from voice satellites. A native Rust recognizer is
|
||||
simpler and faster. Python HA can still connect as an external integration via MQTT or
|
||||
the HOMECORE WebSocket API.
|
||||
|
||||
### Q2 — How does `RegexIntentRecognizer` handle ambiguity?
|
||||
|
||||
Patterns are tried in registration order; the first match wins. Slot extraction uses
|
||||
named capture groups. A future P2 upgrade can run all patterns, score them by slot
|
||||
completeness, and return the highest-scoring match.
|
||||
|
||||
### Q3 — Windows subprocess teardown (ruflo runner subprocess on Windows)
|
||||
|
||||
`tokio::process::Child` on Windows does not automatically kill the child process when
|
||||
the `Child` struct is dropped — `SIGTERM` is not a Windows concept, and `TerminateProcess`
|
||||
is not called automatically. Options for P2:
|
||||
|
||||
1. Call `child.start_kill()` in a `Drop` impl (requires a `Runtime` handle — tricky in sync Drop).
|
||||
2. Wrap `Child` in an `Arc<Mutex<Option<Child>>>` and call `kill()` in an `async fn shutdown()`.
|
||||
3. Use a Windows job object to bind the subprocess lifetime to the parent process.
|
||||
|
||||
**P2 decision**: implement option 2 (explicit `async shutdown()`) + register a `tokio::signal`
|
||||
handler for `Ctrl+C` / `SIGINT` that calls `shutdown()` before exit. Document the Windows caveat
|
||||
in the crate README and in `runner.rs`. Job object approach (option 3) is deferred to P3 only
|
||||
if option 2 proves insufficient in fleet testing.
|
||||
|
||||
### Q4 — Why is `SemanticIntentRecognizer` a P2 stub?
|
||||
|
||||
The ruvector HNSW index requires the vector store to be populated at startup with intent
|
||||
exemplars. That startup path requires deciding on a serialization format (HNSW index files
|
||||
vs. an in-memory array at compile time), which intersects with ADR-084 (RabitQ) and ADR-067
|
||||
(ruvector v2.0.5). P2 will define the exemplar format and populate the index.
|
||||
|
||||
---
|
||||
|
||||
## 4. Consequences
|
||||
|
||||
- **Positive**: HOMECORE-API `assist` WebSocket command gets a functional backend.
|
||||
- **Positive**: Ruflo LLM pipelines can upgrade intent matching by swapping the `RufloRunner` impl.
|
||||
- **Positive**: P1 ships with zero new heavy dependencies (no subprocess spawning, no ML runtime).
|
||||
- **Negative**: Regex matching has limited coverage; long-tail utterances will return "I'm not sure".
|
||||
- **Deferral**: ruvector semantic recognizer and real subprocess runner both land in P2.
|
||||
|
||||
---
|
||||
|
||||
## 5. Implementation phases
|
||||
|
||||
| Phase | Scope |
|
||||
|-------|-------|
|
||||
| **P1** (this ADR) | `intent`, `recognizer` (regex), `handler` (5 built-ins), `runner` (trait + noop), `pipeline` (end-to-end wiring), 10–15 tests |
|
||||
| **P2** | Real `tokio::process::Child` runner with Windows-safe teardown; `SemanticIntentRecognizer` with ruvector HNSW |
|
||||
| **P3** | STT/TTS bridge, satellite protocol, cloud fallback |
|
||||
@@ -1,545 +0,0 @@
|
||||
# ADR-134: First-Class Channel Impulse Response (CIR) Support
|
||||
|
||||
| Field | Value |
|
||||
|-------|-------|
|
||||
| **Status** | Proposed |
|
||||
| **Date** | 2026-05-28 |
|
||||
| **Deciders** | ruv |
|
||||
| **Codebase target** | `wifi-densepose-signal` (new module `ruvsense/cir.rs`) |
|
||||
| **Relates to** | ADR-014 (SOTA Signal Processing), ADR-017 (RuVector Signal+MAT), ADR-029 (RuvSense Multistatic), ADR-030 (Persistent Field Model), ADR-042 (Coherent Human Channel Imaging), ADR-110 (ESP32-C6 Firmware Extension) |
|
||||
|
||||
---
|
||||
|
||||
## 1. Context
|
||||
|
||||
### 1.1 The Gap
|
||||
|
||||
Searching for `CIR`, `channel_impulse`, and `ifft` across the entire Rust workspace (`v2/crates/**`) and Python source (`archive/v1/src/**`) finds zero production code that computes a per-link Channel Impulse Response from CSI. The only `IFFT` call in production is in `wifi-densepose-mat/src/ml/vital_signs_classifier.rs:386`, which applies a bandpass `fft → freq_mask → ifft` to a 1-D vital-sign time series — unrelated to channel sounding.
|
||||
|
||||
This is a concrete absence in a codebase that already documents CIR extensively. Four research documents propose CIR as the next major signal-processing tier:
|
||||
|
||||
- `docs/research/sota-surveys/ruview-multistatic-fidelity-sota-2026.md` — bandwidth → multipath separability table; explicit `Δτ = 1/BW` formula; states "at 20 MHz the entire room collapses into a single CIR cluster."
|
||||
- `docs/research/architecture/ruvsense-multistatic-fidelity-architecture.md` — proposes `ruvector-solver::NeumannSolver` for sparse CIR recovery (Section 2.1); uses `link_gates[i].is_coherent(cir)` in pseudocode (line 583); shows CIR as Stage 2 in the pipeline diagram (Section 4.1).
|
||||
- `docs/research/rf-topological-sensing/02-csi-edge-weight-computation.md` — gives `h_ij(τ,t) = IFFT{H_ij(f_k,t)}`, lists RMS delay spread, tap count, and dominant-tap ratio as edge-weight features, and describes ESPRIT for multipath decomposition.
|
||||
- ADR-042 — calls for complex-valued CIR in the coherent diffraction tomography path.
|
||||
|
||||
Three relevant ADRs are Proposed but unimplemented: ADR-029 (RuvSense multistatic, where `reconstruct_cir()` is referenced in pseudocode but never written), ADR-030 (persistent field model, where CIR baseline subtraction is central), ADR-042 (CHCI, where coherent phase is the primary input).
|
||||
|
||||
### 1.2 Hardware Tiers in Scope
|
||||
|
||||
| Tier | Device | Bandwidth | Usable subcarriers | Native CIR resolution | Min path separation | Ranging |
|
||||
|------|--------|-----------|--------------------|-----------------------|---------------------|---------|
|
||||
| A-HE | ESP32-C6, HE-LTF (802.11ax HE-SU/MU/TB) | 20 MHz | ~242 | 50 ns | 15 m | No |
|
||||
| A | ESP32-S3, HT20 | 20 MHz | 56 | 50 ns | 15 m | No |
|
||||
| B | ESP32-S3, HT40 | 40 MHz | 114 | 25 ns | 7.5 m | Yes |
|
||||
| C | Nexmon BCM43455c0 (Pi 5/4/3B+) via rvCSI | 80 MHz | ≥256 | 12.5 ns | 3.75 m | Yes |
|
||||
|
||||
Sub-Nyquist sparse recovery (see Section 2) can push native resolution by approximately 3× for sufficiently sparse channels. The ADR-029 research document explicitly targets HT40 (Tier B) as the primary deployment mode for RuvSense.
|
||||
|
||||
**Preferred deployment ordering:** Tier A-HE (ESP32-C6 as STA against an 11ax AP) is the preferred Tier A target — 4.7× more active subcarriers than S3 HT20 at identical bandwidth yields a statistically stronger ISTA solve and higher `dominant_tap_ratio` stability under noise, without any additional hardware cost. Tier A (S3 HT20) is the fallback when no 11ax AP is present. Tier B (S3 HT40) is selected when sub-room ranging is required. Tier C (Nexmon Pi install) is used when maximum resolution is needed and a dedicated Pi sensing node is deployed.
|
||||
|
||||
Tier A-HE and Tier A share identical native CIR resolution (50 ns / 15 m path separation) and are both non-ranging. Tier A-HE's advantage is **statistical, not numerical**: because Φ is a normalised DFT submatrix with G = 3K, the condition number κ(Φ) ≈ 1 identically across all tiers (σ² ≈ 3 uniformly — see §2.3 for the derivation). The real gain is measurement SNR: 4.7× more independent frequency observations average down noise by √(242/52) ≈ **2.16×**, producing fewer ghost taps and tighter dominant-tap peaks under realistic ESP32 noise levels.
|
||||
|
||||
### 1.3 Why CIR Now
|
||||
|
||||
The multistatic coherence gate in `ruvsense/multistatic.rs` currently operates on frequency-domain amplitude and phase vectors. The pseudocode in the architecture document calls `link_gates[i].is_coherent(cir)` — passing a CIR, not a raw CSI frame. Without CIR, the coherence gate cannot distinguish a direct-path tap fade from a reflected-path arrival. Without CIR, `ruvsense/tomography.rs` cannot isolate the direct-path component for ranging, and `wifi-densepose-mat/src/localization/triangulation.rs` cannot perform time-of-arrival triangulation. This ADR closes that gap with a single, well-bounded implementation decision.
|
||||
|
||||
---
|
||||
|
||||
## 2. Decision
|
||||
|
||||
### 2.1 Chosen Algorithm: ISTA with a DFT Dictionary (L1-Regularized Sparse CIR Recovery)
|
||||
|
||||
The primary CIR estimator is **ISTA** (Iterative Shrinkage-Thresholding Algorithm) with an L1 penalty and a delay-domain DFT dictionary, implemented by wrapping the existing `ruvector-solver::NeumannSolver`. This is not zero-padded IFFT. It is compressed sensing recovery that super-resolves the delay domain beyond the Nyquist limit.
|
||||
|
||||
The problem: given the measured frequency-domain CSI vector `H ∈ ℂ^K` (K = 56 or 114 or 256 subcarriers), find the sparse delay-domain representation `x ∈ ℂ^G` (G > K, a finer delay grid) such that:
|
||||
|
||||
```
|
||||
minimise ‖H - Φx‖₂² + λ‖x‖₁
|
||||
```
|
||||
|
||||
where `Φ ∈ ℂ^{K×G}` is a sub-DFT dictionary matrix with columns `φ_g = [1, e^{-j2πΔf·τ_g}, …, e^{-j2π(K-1)Δf·τ_g}]^T`, and `τ_g` are the delay-grid points spaced at `1/(G·Δf)`. For ESP32-S3 HT20 with K=56, Δf=312.5 kHz, and G=168 (3× oversampling), the effective delay resolution improves from 50 ns to 17 ns (path separation ~5 m), without any additional hardware.
|
||||
|
||||
ISTA is already the algorithmic pattern used in `ruvsense/tomography.rs` for voxel-space reconstruction. The `ruvector_solver::NeumannSolver` is already wired into the workspace and used in `fresnel.rs:280` and `train/subcarrier.rs:225`. There is no new dependency.
|
||||
|
||||
### 2.2 Why Not the Alternatives
|
||||
|
||||
The table below is the decision record, not a menu of supported options.
|
||||
|
||||
| Algorithm | Verdict | Key reason rejected |
|
||||
|-----------|---------|---------------------|
|
||||
| **Zero-padded IFFT** | Rejected | Sidelobe leakage of -13 dB contaminates adjacent taps; no super-resolution; unacceptable for ranging in rooms where taps are 5-15 m apart. CIRSense (arXiv:2510.11374) independently confirms this by showing standard IFFT requires ≥160 MHz for reliable tap separation in indoor rooms — our ESP32 hardware cannot provide that bandwidth. |
|
||||
| **ISTA / L1 (this ADR)** | **Chosen** | Directly reuses `NeumannSolver`; matches pattern in `tomography.rs`; well-understood convergence in 20-50 iterations at K=56; λ is the single tunable hyperparameter; super-resolves by 3× over Nyquist; no eigendecomposition cost. |
|
||||
| **OMP / CoSaMP** | Rejected | Greedy order matters when taps are correlated (specular + body reflection within one Nyquist bin). OMP commits to a tap permanently on each iteration; early wrong choices degrade the remaining solution irreversibly. ISTA's continuous shrinkage avoids this. ISTA and OMP yield similar results at high SNR; at low SNR (NLOS links, distant nodes) ISTA is measurably better per Chronos (NSDI 2016) and the pulse-shape paper (arXiv:2306.15320). |
|
||||
| **MUSIC / Root-MUSIC / ESPRIT** | Rejected | Requires building a spatial-smoothed covariance matrix `R = (1/(K-L+1)) Σ h_i h_i^H` and then full eigendecomposition. On the aggregator this is O(L³) per link per frame. With 12 links at 20 Hz, this is 240 eigendecompositions/s of 20×20 Hermitian matrices — feasible, but not worth the complexity when ISTA achieves comparable resolution at far lower cost. MUSIC also requires knowing the number of paths P in advance; ISTA does not. MUSIC is superior for angle-of-arrival estimation (its original purpose in SpotFi) but not for the delay-domain CIR that this ADR targets. |
|
||||
| **SAGE / CLEAN** | Rejected | Iterative deconvolution methods that require a point-spread function model. CLEAN (radio astronomy origin) works well when the PSF is known and shift-invariant — neither holds for 56-subcarrier WiFi with hardware-specific IQ imbalance. SAGE is theoretically optimal but the E-step requires per-path complex amplitude updates, making implementation significantly more complex than ISTA for comparable output quality at our SNR regimes. |
|
||||
| **Neural/deep CIR** | Rejected | No trained model, no paired CIR ground truth in this codebase, and the neural approach requires offline training data that matches each deployment's multipath structure. The 2024-2025 literature on neural CIR (arXiv:2601.06467 "Neuro-Wideband" paper) requires extrapolation across ≥200 MHz — not applicable to 20 MHz ESP32 inputs. Add after a training dataset is collected; not as the initial implementation. |
|
||||
| **Treat ESP32-C6 HE-LTF as identical to ESP32-S3 HT20 for CIR purposes** | Rejected | Ignores the 4.7× subcarrier count difference (242 vs 52 K_active). Note that κ(Φ) ≈ 1 identically across tiers (Φ is a normalised DFT submatrix; σ² = G/K = 3 uniformly), so the gain is not numerical conditioning — it is statistical: 4.7× more independent frequency observations suppress noise by 2.16×, producing fewer ghost taps and higher `dominant_tap_ratio` stability. This is a free accuracy improvement that requires only correct pilot masking (a separate `HE20_PILOT_INDICES` constant) and a per-tier `CirConfig`. Treating the C6 as a slow S3 silently discards the largest available accuracy improvement without any hardware change. |
|
||||
|
||||
### 2.3 Per-Bandwidth Strategy
|
||||
|
||||
There is one algorithm for all tiers, parameterised by bandwidth. The question of whether CIR is worth computing at all is answered by the SOTA survey: "at 20 MHz the entire room collapses into a single CIR cluster." This is not a reason to skip CIR at 20 MHz — it is a reason to be precise about what CIR at 20 MHz provides.
|
||||
|
||||
| Tier | K_active subcarriers | G delay bins (3×) | Effective delay res. | Path sep. | Recommended λ | Iterations |
|
||||
|------|---------------------|--------------------|---------------------|-----------|----------------|------------|
|
||||
| A-HE (HE20, ESP32-C6) | 242 | 726 | ~17 ns | ~5 m | 0.03 | 32 |
|
||||
| A (HT20, ESP32-S3) | 52 | 168 | ~17 ns | ~5 m | 0.05 | 30 |
|
||||
| B (HT40, ESP32-S3) | 108 | 342 | ~9 ns | ~2.7 m | 0.03 | 35 |
|
||||
| C (HT80, Nexmon) | 242 | 768 | ~4 ns | ~1.2 m | 0.02 | 40 |
|
||||
|
||||
Tier A-HE uses 802.11ax HE-LTF subcarrier spacing (78.125 kHz in HE-SU 20 MHz) and 802.11ax pilot pattern (8 pilot subcarriers per 802.11ax spec, distinct from the HT20 pilot pattern at ±7, ±21). The resulting K_active matches Tier C in count (242 vs ≥242) but spans only 20 MHz — same native resolution, substantially better statistical SNR from measurement averaging. Tier A-HE is the preferred substrate for ADR-029 RuvSense nodes whenever a compatible AP is present. ADR-110 (Accepted, v0.7.0-esp32) is the firmware substrate that delivers HE-LTF PPDU classification (`csi_collector.c`, frame bytes 18–19), TWT wake slots (`c6_twt.c`), and 802.15.4 epoch timestamps (`c6_timesync_get_epoch_us()`).
|
||||
|
||||
**Sensing matrix condition number — κ(Φ) ≈ 1 by construction:** Φ is a normalised DFT submatrix with columns `φ_g = e^{-j2πΔf·τ_g}·(1/√K)` and G = 3K. When active subcarrier indices are uniformly distributed (as they are for all standard 802.11 tier configurations), Φ Φ^H ≈ (G/K)·I = 3·I. Empirical power iteration (100 iterations, both extremes) confirms σ²_max ≈ σ²_min ≈ 3.000 and κ(Φ) = σ_max/σ_min ≈ **1.00 across all tiers** (HT20, HT40, HE20, HE40). The condition number does not improve with K. The Tier A-HE benefit is therefore purely statistical: 4.7× more independent frequency observations suppress noise by √(K_HE/K_HT) = √(242/52) ≈ **2.16×**, not via a better-conditioned linear system.
|
||||
|
||||
Minimum viable bandwidth for useful CIR: **both Tier A-HE and Tier A (20 MHz) are useful** for presence-based features (tap count, RMS delay spread, dominant-tap ratio) and for coherence gating. Neither is useful for sub-room ranging (>5 m path separation floor). Tier B (40 MHz) opens direct-path triangulation at room scale. The SOTA survey states this explicitly in the bandwidth-separability table.
|
||||
|
||||
The ADR does not gate CIR on bandwidth — it gates downstream consumers. The coherence gate in `multistatic.rs` works at any tier. The ToF triangulation path in `triangulation.rs` is gated behind a minimum bandwidth check (`if cir.bandwidth_hz < 40e6 { return None }`).
|
||||
|
||||
#### 2.3a Soft-AP HE Caveat
|
||||
|
||||
IDF v5.4 soft-AP does **not** advertise HE capabilities. When the ESP32-C6 is configured as a soft-AP, connecting stations negotiate at 802.11bgn rates and the C6 receives HT-LTF frames, not HE-LTF. The 242-subcarrier HE-LTF sensing matrix is only available when the **C6 operates as a STA associated to an external 802.11ax (Wi-Fi 6) AP**.
|
||||
|
||||
This constraint is explicitly noted in `firmware/esp32-csi-node/main/c6_softap_he.c:163`:
|
||||
|
||||
```c
|
||||
// IDF v5.4 soft-AP does not advertise HE; STAs associate at 11bgn.
|
||||
// HE-LTF CSI (242 subcarriers) requires STA mode against an 11ax AP.
|
||||
// See: https://github.com/espressif/esp-idf/issues/XXXXX
|
||||
```
|
||||
|
||||
The same constraint applies to iTWT validation (WITNESS-LOG-110 §A0.6): TWT setup also requires STA mode. Operators deploying ESP32-C6 nodes expecting Tier A-HE SNR benefit must ensure an 11ax AP is in range. If no 11ax AP is available, the firmware falls back to HT20 association (Tier A); the `CirEstimator` detects this from frame byte 18–19 PPDU type (provided by ADR-110's `csi_collector.c`) and selects the appropriate `CirConfig` automatically.
|
||||
|
||||
#### 2.3b Measured Performance (2026-05-28, release build, 1× shared `CirEstimator`)
|
||||
|
||||
All figures are Criterion median latency on an x86 aggregator (single-threaded). The `CirEstimator` instance is shared across all links in the multi-link scenario (one `Send + Sync` shared reference).
|
||||
|
||||
**Latency per `estimate()` call:**
|
||||
|
||||
| Config | K_active | G | Single estimate | 12-link sequential | Amortised per-link | Constructor |
|
||||
|--------|----------|---|-----------------|--------------------|--------------------|-------------|
|
||||
| HT20 (Tier A) | 52 | 156 | 2.72 ms | 17.69 ms | ~1.47 ms | 422 µs |
|
||||
| HT40 (Tier B) | 114 | 342 | 13.43 ms | 74.35 ms | ~6.20 ms | 2.03 ms |
|
||||
| HE20 (Tier A-HE) | 242 | 726 | 3.20 ms | — | est. ~3 ms | — |
|
||||
| HE40 (future) | 484 | 1452 | 9.71 ms | — | est. ~6 ms | — |
|
||||
|
||||
Notable: **HE20 (3.20 ms) is faster than HT40 (13.43 ms)** despite 2.1× higher K. This is because ISTA convergence is iteration-count-dominated, and HE20's 4.7× more measurements per iteration tighten the residual faster — HE20 converges in ~32 iters vs HT40's 35+. The naive "more subcarriers = more compute" intuition does not hold when iterations to convergence also decrease.
|
||||
|
||||
**Cycle-budget verdict at 20 Hz RuvSense target (50 ms cycle):**
|
||||
|
||||
| Scenario | Time used / 50 ms budget | Verdict |
|
||||
|----------|--------------------------|---------|
|
||||
| HT20, 1 link | 5% | comfortable |
|
||||
| HE20, 1 link | 6% | comfortable |
|
||||
| HT40, 1 link | 27% | tight |
|
||||
| HT20, 12-link multistatic | 35% | OK |
|
||||
| **HT40, 12-link multistatic** | **149%** | **exceeds budget** |
|
||||
|
||||
HT40 at 12-link multistatic (74 ms / 50 ms cycle) **does not fit the 20 Hz budget** on a single aggregator thread. Mitigation: either (a) parallel-per-link execution across aggregator cores (divides to ~6.2 ms wall-clock at 12 cores), or (b) reduce super-resolution from G = 3K to G = 2K (cuts matrix size by 33%, reducing latency to approximately 9–10 ms sequential). Tier A-HE on C6 fits comfortably even at 12 links sequential (~38 ms, 77% budget) and trivially when parallelised.
|
||||
|
||||
**Memory — `Vec<Complex32>` allocation per `CirEstimator::new()`:**
|
||||
|
||||
| Config | Φ matrix size |
|
||||
|--------|--------------|
|
||||
| HT20 (Tier A) | 65 KB |
|
||||
| HT40 (Tier B) | 312 KB |
|
||||
| HE20 (Tier A-HE) | 1.4 MB |
|
||||
| HE40 (future) | 5.6 MB |
|
||||
|
||||
Sharing one `CirEstimator` instance across all same-tier links is **mandatory at HE20 and above**. Per-link instantiation at 12 HE20 links would consume 12 × 1.4 MB = 16.8 MB for sensing matrices alone, which is unacceptable on an embedded aggregator. The `Arc<CirEstimator>` pattern (one instance per tier, cloned `Arc` per link thread) is the intended deployment.
|
||||
|
||||
### 2.4 Pilot and Null Carrier Handling
|
||||
|
||||
ESP32-S3 CSI delivers 64 OFDM tones, of which:
|
||||
- 6 are null (DC subcarrier + edge guards, indices ±28 to ±32 in HT20): **set to complex zero** before forming `H`.
|
||||
- 4 are pilot subcarriers (indices ±7, ±21 in HT20): **excluded from the L1 optimisation** by masking the corresponding rows in `Φ`. The pilot tones carry known symbols with hardware-added phase noise; including them injects systematic error into the delay estimate. Their indices are available from `CsiFrame.metadata.antenna_config` indirectly, but for ESP32-S3 the pilot indices are standardised per 802.11n HT20 and are hard-coded as constants in the `CirEstimator`.
|
||||
|
||||
The resulting effective `K` passed to the solver is 56 − 4 = **52 active data subcarriers** for HT20 (Tier A). For HT40, 114 − 6 = **108 active** (Tier B). For Nexmon HT80, pilots are masked per 802.11n spec (≈14 pilots), leaving ≈242 active (Tier C).
|
||||
|
||||
**Tier A-HE (ESP32-C6, HE-LTF):** 802.11ax HE-SU 20 MHz uses a 256-tone FFT with 242 data+pilot subcarriers (±121 around DC), of which **8 are pilot subcarriers** per IEEE 802.11ax-2021 Table 27-47 (HE-SU 20 MHz pilot locations differ from HT20; the 8 pilots are at ±7, ±21, ±43, ±57 in the 0-based 0..255 indexing). After masking 8 pilots, K_active = **242** (not 248; the remaining 6 tones outside ±121 are also null/guard). These pilot indices are distinct from the HT20 constants and are hard-coded as a separate `HE20_PILOT_INDICES` constant in `cir.rs`. The PPDU type field from ADR-110's `csi_collector.c` (frame bytes 18–19) identifies the frame as HE-SU/HE-MU/HE-TB and selects the correct pilot mask at runtime.
|
||||
|
||||
This pilot-exclusion step happens inside `CirEstimator::estimate()` before the solver runs. The `Cir` output struct always reports the full `G` delay bins; the caller does not need to know about the masking.
|
||||
|
||||
### 2.5 Phase Sanitization Order
|
||||
|
||||
**CIR estimation runs after `phase_sanitizer.rs` and after `ruvsense/phase_align.rs`.**
|
||||
|
||||
Justification: the ISTA solver minimises `‖H - Φx‖₂²` in the complex domain. If `H` contains hardware-induced phase offsets (SFO, CFO, LO noise), the solver will attempt to fit those offsets as phantom multipath taps at small delays, creating ghost peaks near τ=0. The `PhaseSanitizer` removes 2π discontinuities and z-score outliers. The `phase_align.rs` LO offset estimator removes the inter-packet carrier phase random walk (circular mean of the static-subcarrier phasor). Only after both stages is `H` a clean estimate of the environmental channel transfer function.
|
||||
|
||||
The ordering is: raw CSI frame → `phase_sanitizer.rs` → `phase_align.rs` (if multi-antenna or multi-packet) → `CirEstimator::estimate()` → `Cir`.
|
||||
|
||||
For single-packet, single-antenna Tier A inputs where `phase_align.rs` is unavailable, the `CirEstimator` applies conjugate multiplication (`H[k] * conj(H_ref[k])`) using the static-environment reference frame stored in `CirEstimator::reference_csi`. This is the same cancellation approach used in `csi_ratio.rs` (ADR-014).
|
||||
|
||||
### 2.6 Proposed Rust API
|
||||
|
||||
The new module is `v2/crates/wifi-densepose-signal/src/ruvsense/cir.rs`. It is exported from `ruvsense/mod.rs` as `pub mod cir`.
|
||||
|
||||
```rust
|
||||
use num_complex::Complex32;
|
||||
use wifi_densepose_core::types::CsiFrame;
|
||||
|
||||
// ---- Configuration ----------------------------------------------------------
|
||||
|
||||
/// Per-bandwidth configuration for CIR estimation.
|
||||
#[derive(Debug, Clone)]
|
||||
pub struct CirConfig {
|
||||
/// Number of delay-domain bins (dictionary columns). Should be 3× K.
|
||||
/// Default: 168 for HT20, 342 for HT40, 768 for HT80.
|
||||
pub delay_bins: usize,
|
||||
/// L1 regularisation strength. Sparser channels → lower λ.
|
||||
/// Default: 0.05 (HT20), 0.03 (HT40), 0.02 (HT80).
|
||||
pub lambda: f32,
|
||||
/// Maximum ISTA iterations. Default: 30 (HT20) / 35 (HT40) / 40 (HT80).
|
||||
pub max_iter: usize,
|
||||
/// ISTA convergence tolerance (‖x_new − x_old‖₂). Default: 1e-4.
|
||||
pub tol: f32,
|
||||
/// Pilot subcarrier indices (0-based within the measured K subcarriers)
|
||||
/// to exclude from the sensing matrix Φ. Hard-coded per 802.11n spec.
|
||||
/// HT20: [7, 21, 35, 49] (±7, ±21 mapped to 0..55). HT40: [11, 25, 89, 103].
|
||||
pub pilot_indices: Vec<usize>,
|
||||
/// Minimum usable bandwidth in Hz before ranging is disabled downstream.
|
||||
/// Default: 40e6 (40 MHz) — Tier A CIR is presence-only.
|
||||
pub ranging_min_bandwidth_hz: f64,
|
||||
}
|
||||
|
||||
impl CirConfig {
|
||||
/// Construct default config for a given bandwidth in MHz.
|
||||
pub fn for_bandwidth_mhz(bw_mhz: u16) -> Self { /* … */ }
|
||||
}
|
||||
|
||||
impl Default for CirConfig {
|
||||
fn default() -> Self { Self::for_bandwidth_mhz(20) }
|
||||
}
|
||||
|
||||
// ---- Output type ------------------------------------------------------------
|
||||
|
||||
/// Channel Impulse Response in the delay domain.
|
||||
#[derive(Debug, Clone)]
|
||||
pub struct Cir {
|
||||
/// Complex tap amplitudes, length = `config.delay_bins`.
|
||||
/// Index 0 = zero-delay (direct path candidate).
|
||||
pub taps: Vec<Complex32>,
|
||||
/// Delay of each tap in seconds. `tap_delay[i] = i / (delay_bins * subcarrier_spacing_hz)`.
|
||||
pub tap_delays_s: Vec<f64>,
|
||||
/// Channel bandwidth that produced this CIR (Hz).
|
||||
pub bandwidth_hz: f64,
|
||||
/// Sub-carrier spacing (Hz). 312_500.0 for 802.11n HT20/HT40.
|
||||
pub subcarrier_spacing_hz: f64,
|
||||
/// RMS delay spread (seconds), weighted by tap power.
|
||||
pub rms_delay_spread_s: f64,
|
||||
/// Index of the dominant tap (highest |tap|²).
|
||||
pub dominant_tap_idx: usize,
|
||||
/// Ratio: dominant-tap power / total power. High (>0.7) = strong LOS.
|
||||
pub dominant_tap_ratio: f32,
|
||||
/// Number of taps above the noise threshold (|tap|² > noise_floor_power).
|
||||
pub active_tap_count: usize,
|
||||
/// Whether ranging is meaningful given the bandwidth.
|
||||
pub ranging_valid: bool,
|
||||
}
|
||||
|
||||
impl Cir {
|
||||
/// ToF of the dominant tap in seconds (proxy for direct-path travel time).
|
||||
/// Returns `None` if `ranging_valid` is false (Tier A, 20 MHz only).
|
||||
pub fn dominant_tap_tof_s(&self) -> Option<f64> {
|
||||
if self.ranging_valid {
|
||||
Some(self.tap_delays_s[self.dominant_tap_idx])
|
||||
} else {
|
||||
None
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
// ---- Estimator --------------------------------------------------------------
|
||||
|
||||
/// Errors from CIR estimation.
|
||||
#[derive(Debug, thiserror::Error)]
|
||||
pub enum CirError {
|
||||
#[error("CsiFrame has no complex data (amplitude-only)")]
|
||||
NoComplexData,
|
||||
#[error("Subcarrier count mismatch: got {got}, expected {expected}")]
|
||||
SubcarrierMismatch { got: usize, expected: usize },
|
||||
#[error("Phase sanitization required before CIR estimation")]
|
||||
UnsanitizedPhase,
|
||||
#[error("ISTA solver failed: {0}")]
|
||||
SolverFailed(String),
|
||||
}
|
||||
|
||||
/// Stateful CIR estimator. Holds a pre-computed sensing matrix Φ and a
|
||||
/// reusable FFT plan for efficient repeated calls.
|
||||
///
|
||||
/// `CirEstimator` is `Send + Sync`: the sensing matrix is immutable after
|
||||
/// construction, and the solver state is stack-local to each `estimate()` call.
|
||||
pub struct CirEstimator {
|
||||
config: CirConfig,
|
||||
/// Sensing matrix Φ ∈ ℂ^{K_active × G}, row-major, pre-computed at construction.
|
||||
sensing_matrix: Vec<Complex32>,
|
||||
/// Number of active (non-pilot) subcarriers.
|
||||
k_active: usize,
|
||||
/// Static-environment reference frame for conjugate-multiplication fallback.
|
||||
/// Set via `set_reference_csi()` after the first quiescent frames.
|
||||
reference_csi: Option<Vec<Complex32>>,
|
||||
}
|
||||
|
||||
impl CirEstimator {
|
||||
/// Construct an estimator for the given config.
|
||||
/// Builds the sensing matrix at construction time; O(K×G) work, done once.
|
||||
pub fn new(config: CirConfig) -> Self { /* … */ }
|
||||
|
||||
/// Update the reference CSI used for single-antenna conjugate-mult fallback.
|
||||
/// Call this with averaged quiescent frames (no motion, no people).
|
||||
pub fn set_reference_csi(&mut self, reference: Vec<Complex32>) { /* … */ }
|
||||
|
||||
/// Estimate the CIR from a single CSI frame.
|
||||
///
|
||||
/// # Phase precondition
|
||||
///
|
||||
/// The caller is responsible for passing a frame whose phase has already
|
||||
/// been processed by `PhaseSanitizer` and, if multi-antenna, by `phase_align.rs`.
|
||||
/// Passing raw hardware phase will produce ghost taps.
|
||||
///
|
||||
/// # Per-antenna strategy
|
||||
///
|
||||
/// For multi-antenna frames (n_spatial_streams > 1), `estimate()` runs the
|
||||
/// solver independently on each row of `frame.data` and returns the
|
||||
/// incoherent-average CIR (tap magnitudes averaged across antennas, phases
|
||||
/// from the highest-amplitude antenna). This matches the approach used in
|
||||
/// the tomography module.
|
||||
pub fn estimate(&self, frame: &CsiFrame) -> Result<Cir, CirError> { /* … */ }
|
||||
}
|
||||
|
||||
// Marker impls — sensing matrix is immutable after construction.
|
||||
unsafe impl Send for CirEstimator {}
|
||||
unsafe impl Sync for CirEstimator {}
|
||||
```
|
||||
|
||||
**Design decisions within the API:**
|
||||
|
||||
- `Vec<Complex32>` not `ndarray`: The sensing matrix and tap vector are kept as flat `Vec<Complex32>` to avoid pulling `ndarray` into the hot path. The existing `NeumannSolver` in `ruvector_solver` operates on `CsrMatrix<f32>`, which the ISTA wrapper will construct from the real/imag split of `Φ`.
|
||||
- **No owned FFT plan**: The 802.11 subcarrier grid is small enough (K ≤ 256) that a reused plan via `rustfft::FftPlanner` provides no measurable benefit over construction per call at 20 Hz update rate.
|
||||
- **`Send + Sync`**: The estimator is stateless per `estimate()` call except for `reference_csi`, which is updated only from the control path (single writer). Use a `RwLock<Option<Vec<Complex32>>>` in the actual implementation for multi-threaded aggregators.
|
||||
- **Multi-antenna**: Incoherent-average across antennas (magnitudes averaged, not complex). Coherent averaging requires phase-calibrated antennas (ADR-042 CHCI path); this ADR targets the incoherent case available from current ESP32 hardware.
|
||||
|
||||
### 2.7 Downstream Consumers
|
||||
|
||||
**`ruvsense/multistatic.rs` — coherence gate moves to tap-delay domain**
|
||||
|
||||
The existing `CoherenceGate` in `ruvsense/coherence_gate.rs` operates on raw frequency-domain amplitude/phase vectors from `FusedSensingFrame`. Add an overload:
|
||||
|
||||
```rust
|
||||
impl CoherenceGate {
|
||||
/// Gate using CIR tap magnitudes instead of raw subcarrier amplitudes.
|
||||
/// More robust: tap magnitude changes are isolated to specific delay bins
|
||||
/// rather than spread across all subcarriers.
|
||||
pub fn update_cir(&mut self, cir: &Cir, pose: &Pose) -> GateDecision { /* … */ }
|
||||
}
|
||||
```
|
||||
|
||||
The coherence metric becomes: compare the tap magnitude vector `|taps|` against the running Welford mean/variance of tap magnitudes. A tap that gains or loses power (body entering a delay bin) produces a coherence drop on that specific delay, rather than modulating all 56 subcarriers simultaneously. This reduces false gates from broadband interference.
|
||||
|
||||
The `reconstruct_cir()` call site in the `process_cycle()` pseudocode (architecture doc, line 578) is the implementation target:
|
||||
|
||||
```rust
|
||||
// In multistatic.rs RuvSenseAggregator::process_cycle():
|
||||
let cirs: Vec<Cir> = self.link_buffers.iter()
|
||||
.map(|buf| self.cir_estimator.estimate(buf.latest_sanitized_frame()))
|
||||
.collect::<Result<Vec<_>, _>>()?;
|
||||
|
||||
let coherent_links: Vec<(usize, &Cir)> = cirs.iter().enumerate()
|
||||
.filter(|(i, cir)| self.link_gates[*i].is_cir_coherent(cir))
|
||||
.collect();
|
||||
```
|
||||
|
||||
**Tier A-HE additional inputs in `multistatic.rs`** (P1 follow-ups, not blocking this ADR):
|
||||
|
||||
- **802.15.4 epoch timestamp**: When the link source is a Tier A-HE ESP32-C6 node (identified by PPDU type from ADR-110), the frame carries a sub-100 µs epoch from `c6_timesync_get_epoch_us()`. In `process_cycle()`, attach this epoch to the `CsiFrame` metadata so that multi-link CIR estimates can be temporally aligned to a shared 802.15.4 reference rather than the aggregator's local clock. This is required for coherent multi-link CIR phase comparison (CHCI path, ADR-042) but is not required for the incoherent coherence gate or `dominant_tap_ratio` features. Mark as `// TODO(ADR-134 P1): attach c6 802.15.4 epoch` in the implementation stub.
|
||||
|
||||
- **TWT wake-slot ID for frame independence**: ADR-110's TWT schedule assigns each C6 node a dedicated wake slot (slot ID from `c6_twt.c`). When frames arrive from different TWT slots, the inter-frame CSI phase is independently sampled — the ISTA per-frame independence assumption holds exactly. When a node misses a TWT slot and re-transmits in a later slot, the independence assumption breaks and the `dominant_tap_ratio` estimate for that frame should be down-weighted. Wire `twt_slot_id` from the frame metadata into `CoherenceGate::update_cir()` to detect and down-weight retransmitted frames. Mark as `// TODO(ADR-134 P1): consume twt_slot_id` in the stub.
|
||||
|
||||
**Cycle-budget constraint on HT40 multi-link (see §2.3b for measurements)**
|
||||
|
||||
Measured latency shows HT40 at 12-link multistatic takes ~74 ms, exceeding the 50 ms cycle budget at 20 Hz. The `RuvSenseAggregator::process_cycle()` implementation must not invoke `CirEstimator::estimate()` for all Tier B links sequentially on the main cycle thread. Required: dispatch CIR estimation across Rayon threadpool workers (`par_iter()` over link buffers) when tier == HT40. Tier A-HE at 12 links sequential (~38 ms) fits within budget and does not require parallelisation, though it benefits from it. Tier A at 12 links sequential (18 ms) has comfortable headroom. Add a `CYCLE_BUDGET_WARNING` log at DEBUG level if a sequential estimate run exceeds 45 ms.
|
||||
|
||||
**`wifi-densepose-ruvector/src/viewpoint/coherence.rs` — no change to phase-phasor logic**
|
||||
|
||||
The existing `CrossViewpointAttention` in `viewpoint/coherence.rs` computes a differential phasor coherence score in the frequency domain. CIR does not replace this — it augments it. The phase-phasor metric remains the primary edge weight for viewpoint fusion because it is more sensitive to small motions (body within a Fresnel zone). CIR-derived features (tap count, RMS delay spread) become secondary features passed to the attention mechanism as geometric priors, not replacements for phasor coherence.
|
||||
|
||||
**`wifi-densepose-mat/src/localization/triangulation.rs` — conditional direct-path ToF**
|
||||
|
||||
When `cir.ranging_valid` is true (Tier B or C), the dominant tap's ToF `cir.dominant_tap_tof_s()` is a candidate direct-path range measurement. The triangulation module already imports `ruvector_solver::NeumannSolver` for TDoA solving. Wire in the CIR ToF as an additional observation:
|
||||
|
||||
```rust
|
||||
// In triangulation.rs, within the TDoA system builder:
|
||||
if let Some(tof) = cir.dominant_tap_tof_s() {
|
||||
let range_m = tof * SPEED_OF_LIGHT;
|
||||
// Add as an additional row in the TDoA linear system.
|
||||
// Weight by dominant_tap_ratio (high ratio = reliable LOS measurement).
|
||||
tdoa_builder.add_range(link_id, range_m, cir.dominant_tap_ratio);
|
||||
}
|
||||
```
|
||||
|
||||
This is a conditional enhancement. Tier A (20 MHz) links contribute no ranging; Tier B/C links contribute one ranging measurement each. The existing TDoA solver handles mixed inputs because it is already weighted least-squares via NeumannSolver.
|
||||
|
||||
**`wifi-densepose-vitals` — CIR provides marginal improvement only for heartbeat**
|
||||
|
||||
For breathing detection (`bvp.rs`, `ruvsense/breathing.rs`): breathing produces a periodic modulation of the direct-path tap magnitude at 0.15–0.5 Hz. Filtering `|cir.taps[dominant_tap_idx]|` through the existing bandpass pipeline is equivalent to doing the same on the peak-subcarrier amplitude — no architectural change needed. The existing Fresnel model (`fresnel.rs`) already models this at the subcarrier level.
|
||||
|
||||
For heartbeat detection at 0.8–2.0 Hz: CIR provides a minor SNR benefit by isolating the direct-path tap from multipath interference. This is a marginal improvement in Tier A/B. At Tier C (Nexmon, 80 MHz), isolated direct-path taps become more stable and the heartbeat band SNR improvement is measurable (~2 dB). CIR integration with vitals is therefore: **pass `cir.taps[cir.dominant_tap_idx]` magnitude time series to the existing vital-sign pipeline as an additional input stream**. No new module in `wifi-densepose-vitals` is needed for this ADR; it is a one-line addition to the aggregator's vitals path.
|
||||
|
||||
### 2.8 Feature Gating
|
||||
|
||||
New Cargo feature: `cir` in `wifi-densepose-signal/Cargo.toml`.
|
||||
|
||||
```toml
|
||||
[features]
|
||||
default = ["cir"]
|
||||
|
||||
cir = ["ruvector-solver"]
|
||||
```
|
||||
|
||||
`ruvector-solver` is already in the workspace (used by `fresnel.rs` and `train/subcarrier.rs`). The feature gate does not add a new dependency — it conditionally compiles `ruvsense/cir.rs`. The feature is **default-on** because:
|
||||
|
||||
1. It adds no new crate dependencies.
|
||||
2. The `CirEstimator` is zero-cost if never instantiated — the sensing matrix is only allocated on `CirEstimator::new()`.
|
||||
3. Downstream consumers (`multistatic.rs`, `triangulation.rs`) will conditionally compile their CIR branches with `#[cfg(feature = "cir")]`.
|
||||
|
||||
### 2.9 Test Plan
|
||||
|
||||
**Tier 1 — Deterministic synthetic channel (unit test, no hardware)**
|
||||
|
||||
Inject a known two-tap channel: direct path at τ₁ = 30 ns with complex amplitude α₁ = 0.8e^{jπ/4}, reflected path at τ₂ = 80 ns with α₂ = 0.3e^{j3π/4}. Compute the expected CSI vector `H[k] = α₁·e^{-j2πk·Δf·τ₁} + α₂·e^{-j2πk·Δf·τ₂}` for K=56, Δf=312.5 kHz. Pass to `CirEstimator::estimate()`. Assert:
|
||||
- `cir.active_tap_count` is 2 (with noise_floor = -25 dB relative to α₁ power).
|
||||
- `cir.tap_delays_s[cir.dominant_tap_idx]` is within one delay bin of τ₁ = 30 ns.
|
||||
- `cir.dominant_tap_ratio` > 0.7 (direct path dominates).
|
||||
- The second peak delay is within one delay bin of τ₂ = 80 ns.
|
||||
|
||||
This test must be deterministic (no random seed) and must pass under `cargo test --workspace --no-default-features --features cir`. It follows the pattern established by `verify.py` for the Python pipeline.
|
||||
|
||||
**Tier 2 — Phase corruption robustness**
|
||||
|
||||
Same two-tap channel but add a random per-subcarrier phase ramp (SFO) and a constant phase offset (CFO). Without sanitization: assert the test fails (ghost tap at τ=0 from CFO). With `phase_sanitizer.rs` applied before `estimate()`: assert the same pass conditions as Tier 1. This validates the ordering decision in Section 2.5.
|
||||
|
||||
**Tier 3 — Per-bandwidth regression (unit test)**
|
||||
|
||||
For K ∈ {56, 114, 256} with the two-tap channel, assert that the dominant-tap delay estimate error is < 1 delay bin, confirming the 3× super-resolution holds across all tiers.
|
||||
|
||||
**Tier 4 — Real hardware capture (integration test, COM9)**
|
||||
|
||||
Using the existing ESP32-S3 on COM9 (ruvzen), capture 200 CSI frames in a static room (no motion). Assert:
|
||||
- `cir.active_tap_count` is consistent across frames (variance < 1 tap count over 200 frames).
|
||||
- `cir.dominant_tap_ratio` > 0.5 (LOS dominant path present).
|
||||
- `cir.rms_delay_spread_s` is in the range [10 ns, 200 ns] (reasonable for a room).
|
||||
|
||||
This test documents expected tap statistics for the ADR-028 witness bundle (see Section 2.10). The test is gated behind `#[cfg(feature = "hardware-test")]` and is not run in CI.
|
||||
|
||||
**Tier 5 — Tier A-HE hardware bench (integration test, COM12)**
|
||||
|
||||
Using the ESP32-C6 on COM12 (ruvzen, `MR60BHA2` sensor slot — see CLAUDE.local.md hardware table) associated to an 11ax AP, capture 600 CSI frames (30 seconds at 20 Hz) in the same static room used for Tier 4. Assert:
|
||||
- `cir.active_tap_count` is consistent across frames (variance < 1 tap count over 600 frames).
|
||||
- `cir.dominant_tap_ratio` > 0.5 (same threshold as Tier 4).
|
||||
- `cir.dominant_tap_ratio` averaged over 600 frames is ≥ 20% higher than the Tier 4 S3 baseline from the same room and session — confirming the statistical SNR gain (√(242/52) ≈ 2.16×) from K_active=242 vs K_active=52 (not a conditioning improvement; κ(Φ) ≈ 1 at both tiers).
|
||||
- Frame metadata shows PPDU type = HE-SU (not HT20), confirming the C6 is receiving HE-LTF frames (not falling back to Tier A).
|
||||
|
||||
This test is gated behind `#[cfg(feature = "hardware-test")]` and is not run in CI. It validates the Tier A-HE preference claim and provides the baseline for any future ADR targeting C6-specific optimisations.
|
||||
|
||||
### 2.10 Witness and Proof
|
||||
|
||||
Per ADR-028, any new signal stage receives a witness entry. The witness additions for CIR:
|
||||
|
||||
**WITNESS-LOG-028.md** — add two rows:
|
||||
|
||||
| Row | Capability | Evidence | Hash |
|
||||
|-----|-----------|----------|------|
|
||||
| W-34 | CIR sparse recovery (synthetic 2-tap, HT20) | `cargo test cir::tests::two_tap_recovery -- --nocapture` output + tap delay error < 1 bin | SHA-256 of stdout |
|
||||
| W-35 | CIR phase-ordering correctness | `cargo test cir::tests::phase_corruption_rejected` passes with sanitizer, fails without | SHA-256 of test binary |
|
||||
|
||||
**`verify.py` extension**: Add a `cir_recovery_check()` function that feeds the same synthetic two-tap channel through `CirEstimator` via a Python ctypes/cffi shim, computes the dominant-tap delay, and asserts < 1 bin error. Hash the function output and compare to `expected_features.sha256`. This integrates CIR into the deterministic proof chain.
|
||||
|
||||
The `source-hashes.txt` in the witness bundle adds the SHA-256 of `ruvsense/cir.rs` alongside the existing firmware binaries.
|
||||
|
||||
---
|
||||
|
||||
## 3. Consequences
|
||||
|
||||
### 3.1 Positive
|
||||
|
||||
- **Coherence gate precision**: The `multistatic.rs` coherence gate can now isolate motion to specific delay bins. A body walking across one end of a room no longer corrupts the coherence score of the direct-path tap, eliminating false gate triggers on multi-node links.
|
||||
- **Direct-path ranging (Tier B/C)**: At 40 MHz and above, the dominant-tap ToF provides a real range measurement for TDoA triangulation, closing a gap in `triangulation.rs` that currently estimates position from angle-of-arrival only.
|
||||
- **Reuses `NeumannSolver`**: Zero new crate dependencies. The ISTA loop wraps the existing solver interface exactly as `fresnel.rs` and `subcarrier.rs` do.
|
||||
- **Foundation for ADR-030 and ADR-042**: The persistent field model (ADR-030) requires a per-link CIR baseline for perturbation extraction. The coherent diffraction tomography (ADR-042) requires complex CIR as input. Both are unblocked by this ADR.
|
||||
- **Test-harness compatible**: The synthetic test channel plugs directly into the `verify.py` proof infrastructure without new tooling.
|
||||
|
||||
### 3.2 Negative
|
||||
|
||||
- **Memory cost**: Measured `Vec<Complex32>` allocation per `CirEstimator::new()`: HT20 = 65 KB, HT40 = 312 KB, HE20 = 1.4 MB (see §2.3b). Sharing one `Arc<CirEstimator>` per tier across all same-tier links is mandatory at HE20+; per-link instantiation at 12 HE20 links costs 16.8 MB for sensing matrices alone.
|
||||
- **Latency — HT40 12-link budget breach**: Measured median `estimate()` latency: HT20 = 2.72 ms, HT40 = 13.43 ms, HE20 = 3.20 ms (see §2.3b for full table). HT40 at 12-link multistatic sequential = 74.35 ms, which exceeds the 50 ms cycle budget at 20 Hz. HT20 (17.69 ms) and HE20 (est. ~38 ms) both fit. CIR runs on the aggregator, not the ESP32. HT40 multistatic requires Rayon parallelisation (see §2.7). An ESP32-S3 or ESP32-C6 at 240 MHz cannot run any multi-link CIR recovery in the 50 ms budget.
|
||||
- **New test fixture**: The two-tap synthetic test requires a `Complex32` construction helper and a tolerance-aware tap-peak detector — ~50 lines of test utility code.
|
||||
- **Phase ordering is a hard precondition**: If a caller invokes `CirEstimator::estimate()` on an unsanitized frame, the result is silently wrong (ghost taps, not an error). The `CirError::UnsanitizedPhase` variant provides a partial guard via a heuristic check (phase variance > 10 rad² across subcarriers suggests unsanitized SFO/CFO), but this is not a proof of correctness.
|
||||
|
||||
### 3.3 Risks
|
||||
|
||||
| Risk | Probability | Impact | Mitigation |
|
||||
|------|-------------|--------|------------|
|
||||
| `NeumannSolver` convergence at low K with high noise | Medium | Ghost taps in HT20 when channel has few paths and low SNR | κ(Φ) ≈ 1 by construction (normalised DFT submatrix, G = 3K), so numerical ill-conditioning is not the risk. The risk is low SNR at K=52 (2.16× weaker than K=242 at same noise floor). Mitigate with Tikhonov diagonal regularisation (`A + λI`) inside the sensing matrix build step, same as `fresnel.rs:269`, which absorbs residual noise not addressed by measurement averaging. |
|
||||
| Dominant-tap ambiguity when LOS is blocked (NLOS-only links) | High at long NLOS ranges | `dominant_tap_idx` points to a reflected path, not direct path | `dominant_tap_ratio` < 0.3 flags this; `ranging_valid` logic gates on ratio > 0.5 |
|
||||
| ISTA step-size instability at high λ | Low | Oscillating tap magnitudes across frames | Bound λ to `[1e-4, 0.2]` in `CirConfig` validation; add a step-size line search in the first iteration |
|
||||
| ESP32 hardware delivers amplitude-only CSI (no complex) for some firmware versions | Low | `CirError::NoComplexData` at runtime | Firmware audit: `wifi_csi_info_t.buf` in ESP-IDF 5.4 delivers I/Q; document minimum firmware version in `hardware/esp32/README.md` |
|
||||
|
||||
---
|
||||
|
||||
## 4. Rationale and Comparison to Alternative Designs
|
||||
|
||||
### 4.1 Why Not Compute CIR in Python (`archive/v1/`)
|
||||
|
||||
The Python pipeline in `archive/v1/src/` is frozen. ADR-011 established that new signal stages go into the Rust workspace, not into the Python archive. The Python proof (`verify.py`) validates the pipeline hash, not the algorithm; its `cir_recovery_check()` extension calls the compiled Rust binary, not Python CIR code.
|
||||
|
||||
### 4.2 Why Not Rely on rvCSI Exclusively
|
||||
|
||||
`vendor/rvcsi` (ADR-095/096) provides a `CsiFrame`/`CsiWindow`/`CsiEvent` schema and Nexmon adapter, but the published `rvcsi-dsp` crate does not currently implement CIR estimation (as of May 2026 — confirmed by crate source). Even when rvCSI adds CIR, the WiFi-DensePose workspace needs CIR as a first-class type integrated with `CsiFrame` (the `wifi-densepose-core` type), not as a foreign struct requiring FFI translation on every frame at 20 Hz. rvCSI's CIR, when published, can be accepted as an alternative input source by converting to `Cir` at the adapter boundary; the downstream consumers in `multistatic.rs` and `triangulation.rs` will not need to change.
|
||||
|
||||
### 4.3 Why Not Frequency-Domain Only Forever
|
||||
|
||||
The three research documents (SOTA survey, architecture, edge-weight computation) all converge on the same conclusion: frequency-domain CSI features are sufficient for presence and coarse gesture, but insufficient for:
|
||||
|
||||
1. **Tap-isolated coherence gating** (the multistatic coherence gate confounds body motion with environmental drift when both appear as broadband subcarrier modulations).
|
||||
2. **Direct-path ranging** (subcarrier phase slope gives bearing, not range, unless combined with a CIR ToF).
|
||||
3. **Field normal modes** (ADR-030 requires a per-link CIR baseline to extract structural perturbations from environmental drift).
|
||||
|
||||
Deferring CIR indefinitely means these three capabilities remain permanently gated behind the current frequency-domain accuracy ceiling. CIRSense (arXiv:2510.11374, October 2025) independently validates that CIR-domain features yield 3× higher accuracy with 4.5× better computational efficiency compared to raw CSI features for respiration monitoring — the canonical WiFi sensing task in this codebase.
|
||||
|
||||
---
|
||||
|
||||
## 5. Related ADRs
|
||||
|
||||
| ADR | Relationship |
|
||||
|-----|-------------|
|
||||
| ADR-014 (SOTA Signal Processing) | **Extended**: CIR adds a 7th signal module alongside the 6 in ADR-014 |
|
||||
| ADR-017 (RuVector Signal+MAT) | **Enables**: ADR-017's coherence gate pseudocode references CIR; now implementable |
|
||||
| ADR-029 (RuvSense Multistatic) | **Unblocks**: `reconstruct_cir()` stub in `process_cycle()` now has a concrete implementation |
|
||||
| ADR-030 (Persistent Field Model) | **Prerequisite fulfilled**: baseline CIR per link is required for perturbation extraction |
|
||||
| ADR-042 (Coherent Human Channel Imaging) | **Foundation layer**: CHCI's coherent diffraction tomography consumes `Cir` as primary input |
|
||||
| ADR-095/096 (rvCSI) | **Complementary**: rvCSI provides the Nexmon adapter for Tier C; CIR estimation runs on top |
|
||||
| ADR-028 (ESP32 Capability Audit) | **Witness extended**: two new rows W-34, W-35 added to `WITNESS-LOG-028.md` |
|
||||
| ADR-110 (ESP32-C6 Firmware Extension) | **Substrate**: HE-LTF PPDU classification (frame bytes 18–19), TWT wake slots (`c6_twt.c`), and 802.15.4 epoch timestamps (`c6_timesync_get_epoch_us()`) — all shipped in v0.7.0-esp32. Tier A-HE `CirConfig` depends on PPDU type from ADR-110 for automatic tier detection. |
|
||||
|
||||
---
|
||||
|
||||
## 6. References
|
||||
|
||||
### Production Code
|
||||
- `v2/crates/wifi-densepose-signal/src/ruvsense/multistatic.rs` — current amplitude/phase coherence gate; `reconstruct_cir()` call site
|
||||
- `v2/crates/wifi-densepose-signal/src/phase_sanitizer.rs` — must run before `CirEstimator::estimate()`
|
||||
- `v2/crates/wifi-densepose-signal/src/fresnel.rs:280` — `NeumannSolver` usage pattern this ADR mirrors
|
||||
- `v2/crates/wifi-densepose-train/src/subcarrier.rs:225` — second `NeumannSolver` usage in workspace
|
||||
- `v2/crates/wifi-densepose-mat/src/ml/vital_signs_classifier.rs:386` — the only IFFT in production (unrelated to CIR)
|
||||
|
||||
### Research Documents
|
||||
- `docs/research/sota-surveys/ruview-multistatic-fidelity-sota-2026.md` — bandwidth table, 20 MHz separability analysis
|
||||
- `docs/research/architecture/ruvsense-multistatic-fidelity-architecture.md` — `NeumannSolver` CIR proposal (§2.1), pipeline diagram (§4.1), `is_coherent(cir)` pseudocode (line 583)
|
||||
- `docs/research/rf-topological-sensing/02-csi-edge-weight-computation.md` — IFFT formula, CIR features, ESPRIT for multipath decomposition
|
||||
|
||||
### External Papers
|
||||
- Kotaru et al., "SpotFi: Decimeter Level Localization Using WiFi," ACM SIGCOMM 2015 — MUSIC for AoA; spatial smoothing from K subcarriers
|
||||
- Vasisht et al., "Decimeter-Level Localization with a Single WiFi Access Point," NSDI 2016 (Chronos) — BPDN for sparse CIR across stitched channels
|
||||
- CIRSense, arXiv:2510.11374 (October 2025) — CIR delay-domain sensing; ISTA sparse recovery; 3× accuracy vs CSI, 4.5× compute efficiency; validated at 160 MHz (informative for Tier C)
|
||||
- "Pulse Shape-Aided Multipath Delay Estimation for Fine-Grained WiFi Sensing," arXiv:2306.15320 — OMP vs ISTA comparison at low SNR
|
||||
- "Neuro-Wideband WiFi Sensing via Self-Conditioned CSI Extrapolation," arXiv:2601.06467 (January 2026) — neural CIR extrapolation requiring ≥200 MHz; explains why neural approach is rejected for this ADR
|
||||
- Zheng et al., "Zero-Effort Cross-Domain Gesture Recognition with Wi-Fi," MobiSys 2019 (Widar 3.0) — BVP as domain-independent alternative to CIR; relevant to vitals-path decision
|
||||
@@ -1,664 +0,0 @@
|
||||
# ADR-135: Empty-Room Baseline Calibration
|
||||
|
||||
| Field | Value |
|
||||
|-------|-------|
|
||||
| **Status** | Proposed |
|
||||
| **Date** | 2026-05-28 |
|
||||
| **Deciders** | ruv |
|
||||
| **Codebase target** | `wifi-densepose-signal` (new module `ruvsense/calibration.rs`); `wifi-densepose-cli` (new `calibrate` subcommand) |
|
||||
| **Relates to** | ADR-014 (SOTA Signal Processing), ADR-028 (ESP32 Capability Audit), ADR-029 (RuvSense Multistatic), ADR-030 (Persistent Field Model), ADR-110 (ESP32-C6 Firmware Extension), ADR-134 (First-Class CIR Support) |
|
||||
|
||||
---
|
||||
|
||||
## 1. Context
|
||||
|
||||
### 1.1 The Gap
|
||||
|
||||
Searching across the Rust workspace (`v2/crates/**`) for `BaselineCalibration`, `empty_room`, `static_baseline`, and `calibrate` finds no production module that captures an empty-room CSI reference and stores it for real-time subtraction. The closest existing code is `ruvsense/field_model.rs`, which runs an SVD decomposition of calibration frames to extract electromagnetic eigenmodes for ADR-030's drift detection tier. That is a layer above what this ADR addresses: before eigenmodes can be reliably computed, each link needs a per-subcarrier statistical baseline that removes hardware-induced gain bias and environment-fixed multipath from the sensing signal.
|
||||
|
||||
The absence is consequential. Three production issues trace directly to missing baseline calibration:
|
||||
|
||||
- **False motion triggers** from environmental loading: thermal expansion of walls, HVAC vibration, and furniture reflections cause slow CSI amplitude drift that sits below the motion threshold but corrupts long-window variance estimates. The `ruvsense/coherence_gate.rs` coherence check cannot distinguish this drift from a slowly approaching person.
|
||||
- **Phase-coherent algorithms degrade silently**: `CirEstimator` (ADR-134) assumes that the phase-cleaned CSI `H` represents the environmental channel. Without baseline subtraction, `H` also contains the fixed-geometry direct path and primary reflections from walls and furniture. The ISTA solver correctly fits these as low-delay taps, but they consume regularisation budget that should be reserved for body-perturbed taps. `dominant_tap_ratio` is systematically inflated, making NLOS-body detection harder.
|
||||
- **Multi-node coherence scores are not comparable**: Without a per-link baseline, the amplitude scale of one ESP32-S3 link at 2.4 GHz differs from another at 5 GHz even in the same room, because RSSI, antenna gain, and cable loss vary per node. Multistatic fusion in `ruvsense/multistatic.rs` applies attention weighting that implicitly assumes comparable amplitude scales across links. Hardware normalization (`hardware_norm.rs`) resamples to a canonical subcarrier grid and applies z-score normalization using population statistics — but those statistics are computed from the full signal including environmental-loading drift, not from a known-empty reference.
|
||||
|
||||
ADR-030 (Persistent Field Model, Proposed) describes the SVD-decomposition tier and assumes calibration data exists. ADR-134 (CIR, Proposed) documents at §2.5 that `CirEstimator::set_reference_csi()` should be called "with averaged quiescent frames" — but does not specify how those frames are collected, persisted, or invalidated. This ADR closes that gap.
|
||||
|
||||
### 1.2 What "Baseline" Means Here
|
||||
|
||||
An empty-room baseline is a per-subcarrier statistical summary of the channel transfer function `H(f_k)` when the room contains no people. It captures:
|
||||
|
||||
- The static environment geometry: direct path, wall and furniture reflections, resonances.
|
||||
- Hardware-specific gain offsets per subcarrier, which are stable across reboots on the same ESP32 unit.
|
||||
- Long-term ambient drift not corrected by `phase_sanitizer.rs` (which operates per-frame, not across frames).
|
||||
|
||||
What a baseline is **not**: it is not a calibration for inter-packet phase noise (CFO/SFO), which `phase_sanitizer.rs` and `phase_align.rs` already handle. Those two stages must run before baseline comparison.
|
||||
|
||||
### 1.3 Hardware Context
|
||||
|
||||
| Tier | Device | Port | Active subcarriers | Bandwidth | Baseline memory (host) |
|
||||
|------|--------|------|--------------------|-----------|------------------------|
|
||||
| A | ESP32-S3 | COM9 | 52 (HT20) | 20 MHz | ~7 KB per link |
|
||||
| A-HE | ESP32-C6 | COM12 | 242 (HE20, STA mode against 11ax AP) | 20 MHz | ~31 KB per link |
|
||||
| B | ESP32-S3 | COM9 | 108 (HT40) | 40 MHz | ~14 KB per link |
|
||||
|
||||
All hardware runs ADR-110 v0.7.0-esp32 firmware. ESP32-C6 on COM12 provides `c6_timesync_get_epoch_us()` (±100 µs 802.15.4 epoch) for multi-node capture synchronization. The C6 falls back to HT20 when no 802.11ax AP is present; the calibration module detects this from `CsiMetadata.bandwidth_mhz` and selects the appropriate subcarrier mask.
|
||||
|
||||
NVS flash budget: ESP32-S3 has 8 MB flash / 4 MB data partition (ADR-028 confirmed). A full Tier A-HE HE20 baseline (242 subcarriers × 4 stats × f32 = ~3.9 KB) fits comfortably in NVS. The NVS key namespace is `ruvcal` with key `b_<link_id>`. Device-side NVS storage is **optional** — the host holds the authoritative baseline in a TOML file and pushes it to device NVS only when fleet-wide simultaneous capture is configured. See Section 2.4.
|
||||
|
||||
### 1.4 Pipeline Position
|
||||
|
||||
```
|
||||
Raw CSI frame
|
||||
→ phase_sanitizer.rs (SFO/CFO removal, per-frame)
|
||||
→ phase_align.rs (LO phase offset, multi-antenna)
|
||||
→ CalibrationRecorder::record() ← NEW (calibration mode only)
|
||||
→ BaselineCalibration::subtract() ← NEW (runtime mode)
|
||||
→ CirEstimator::estimate() (ADR-134)
|
||||
→ multistatic.rs / motion.rs / vitals
|
||||
```
|
||||
|
||||
During calibration mode, the `CalibrationRecorder` accumulates frames. At runtime, `BaselineCalibration::subtract()` removes the static environment before the signal enters any downstream consumer. CIR estimation and coherence gating both receive baseline-subtracted CSI.
|
||||
|
||||
---
|
||||
|
||||
## 2. Decision
|
||||
|
||||
### 2.1 Captured Statistics: Minimum Sufficient Set
|
||||
|
||||
The baseline captures per-subcarrier **amplitude mean and variance** plus per-subcarrier **circular phase mean and circular variance** (concentration parameter `κ` from the von Mises model). No per-link spatial covariance matrix is captured.
|
||||
|
||||
**Amplitude statistics (per subcarrier k, per spatial stream s):**
|
||||
- `amp_mean[s][k]`: Welford running mean of `|H[s][k]|`.
|
||||
- `amp_m2[s][k]`: Welford M2 accumulator for variance. Variance is `m2 / (n - 1)`.
|
||||
|
||||
**Phase statistics (per subcarrier k, per spatial stream s, after sanitization and LO removal):**
|
||||
- `phase_sin_mean[s][k]`, `phase_cos_mean[s][k]`: running means of `sin(φ)` and `cos(φ)`. The circular mean is `atan2(phase_sin_mean, phase_cos_mean)`.
|
||||
- `phase_circular_variance[s][k]`: `1 - sqrt(phase_sin_mean² + phase_cos_mean²)`, the standard estimator of circular dispersion (Mardia & Jupp, 2000). Range is [0, 1]; 0 = perfectly concentrated, 1 = maximally dispersed.
|
||||
|
||||
**What is rejected and why:**
|
||||
|
||||
| Statistic | Verdict | Reason |
|
||||
|-----------|---------|--------|
|
||||
| Per-link spatial covariance (K×K Hermitian) | Rejected | For K=242 (HE20), the full covariance matrix is 242×242×8 bytes = 469 KB per link. Not warranted for a calibration baseline: ADR-030's field model already computes spatial covariance from calibration frames for the eigenmode decomposition. This ADR's baseline is the input to ADR-030, not a substitute for it. |
|
||||
| Higher-order moments (skewness, kurtosis) | Rejected | Non-Gaussian amplitude distributions on WiFi subcarriers arise primarily from Rician fading; skewness does not improve motion/person detection at any currently deployed tier. |
|
||||
| Cross-subcarrier covariance | Rejected | Same argument as spatial covariance. Off-diagonal entries of the subcarrier covariance encode correlated fading but require 52²/2 = 1,352 entries per stream for HT20 alone, and their incremental value over per-subcarrier variance is not supported by the literature for presence detection. |
|
||||
| Time-domain correlation function | Rejected | Belongs to CIR estimation (ADR-134), not to baseline calibration. |
|
||||
|
||||
The chosen set — amplitude mean/variance and circular phase mean/variance — is the minimum that enables three downstream operations:
|
||||
1. Static-environment subtraction for motion detectors (amplitude mean).
|
||||
2. Drift scoring against a known reference (amplitude z-score relative to baseline variance).
|
||||
3. Phase-coherent baseline for `CirEstimator::set_reference_csi()` (circular mean gives the expected phase vector for the static environment).
|
||||
|
||||
### 2.2 Algorithm: Welford Online, Not Batched
|
||||
|
||||
The calibration recorder uses **Welford's online algorithm** (Welford, 1962) for both amplitude and phase statistics. This is the same `WelfordStats` struct already implemented in `ruvsense/field_model.rs` — the calibration module imports it directly.
|
||||
|
||||
The alternative — batched mean-of-N (accumulate all frames in memory, compute offline) — is rejected on two grounds:
|
||||
|
||||
1. **Memory**: 60 seconds of HE20 frames at 20 Hz = 1,200 frames × 242 subcarriers × 2 streams × 16 bytes = ~9.3 MB of raw complex data. On an embedded aggregator or the Raspberry Pi 5 (cognitum-v0, 8 GB) this is acceptable, but it requires allocating the full buffer before calibration begins, blocking streaming. Welford's algorithm requires O(K × S) state regardless of frame count.
|
||||
2. **Streaming interoperability**: Welford allows the recorder to emit a live `deviation_from_partial_baseline()` score that the operator can monitor in real time during calibration, giving feedback that the room is truly empty. Batched computation cannot do this.
|
||||
|
||||
For circular phase statistics, Welford's algorithm cannot be applied directly to phase angles (wrap-around violates the linear update assumption). Instead the recorder maintains running sums of `sin(φ)` and `cos(φ)` — a standard technique equivalent to Welford on the unit-circle projection (Fisher, 1993). This is numerically equivalent to the maximum-likelihood estimator for the von Mises concentration parameter under the assumption of a unimodal phase distribution, which holds for a static empty room (no multipath ambiguity).
|
||||
|
||||
### 2.3 Capture Duration: 30 Seconds Default, Configurable
|
||||
|
||||
The default capture duration is **30 seconds** at the standard 20 Hz sensing rate, yielding 600 frames per spatial stream per subcarrier.
|
||||
|
||||
**Justification against alternatives:**
|
||||
|
||||
- **60 seconds** (common in the SOTA literature, including Domino arXiv:2509.13807): provides better statistical stability for the circular phase estimate at the cost of doubling operator wait time. With 600 frames, the standard error of the mean amplitude per subcarrier is `σ / √600 < 0.002 × σ` — negligible for sensing purposes at any tier.
|
||||
- **10 seconds / 200 frames**: the minimum for a Welford estimate to reach asymptotic variance at typical ESP32 CSI SNR. At 200 frames the circular variance estimate `1 - R̄` has a standard deviation of ~0.04 (Fisher, 1993, Eq. 3.24), corresponding to roughly ±0.04 rad² uncertainty in phase concentration. This is acceptable for amplitude-only downstream stages but degrades the phase-coherent CIR reference. Not the default.
|
||||
- **Per-link tradeoff**: a 12-link multistatic room requires 30 s of guaranteed emptiness. Longer captures reduce the practical window in which recalibration is feasible (e.g., during a 30-minute care visit). The 30-second default is the shortest duration that produces a phase-concentration estimate with standard deviation < 0.02 rad².
|
||||
|
||||
The `--duration` CLI flag accepts any value from 10 to 600 seconds. Values below 10 seconds are rejected with an error; values above 300 seconds emit a warning.
|
||||
|
||||
### 2.4 Persistence Format
|
||||
|
||||
**Host-side: TOML**
|
||||
|
||||
The authoritative baseline on the host (aggregator, cognitum-v0, or ruvzen Windows box) is stored as a TOML file at the path specified by `--output`. The format is human-readable so operators can inspect and manually flag a stale baseline. Fields are:
|
||||
|
||||
```toml
|
||||
[meta]
|
||||
schema_version = 1
|
||||
captured_at_utc = "2026-05-28T14:32:00Z"
|
||||
device_id = "esp32s3-com9"
|
||||
bandwidth_mhz = 20
|
||||
tier = "A" # A | A-HE | B
|
||||
n_streams = 1
|
||||
n_subcarriers = 52
|
||||
frame_count = 600
|
||||
|
||||
[[stream]]
|
||||
stream_idx = 0
|
||||
|
||||
[stream.amp_mean] # length = n_subcarriers
|
||||
values = [0.421, 0.418, ...]
|
||||
|
||||
[stream.amp_variance]
|
||||
values = [0.0012, 0.0009, ...]
|
||||
|
||||
[stream.phase_cos_mean]
|
||||
values = [0.871, 0.864, ...]
|
||||
|
||||
[stream.phase_sin_mean]
|
||||
values = [0.122, 0.134, ...]
|
||||
|
||||
[stream.phase_circular_variance]
|
||||
values = [0.031, 0.028, ...]
|
||||
```
|
||||
|
||||
TOML is chosen over JSON (no comments, awkward for large arrays), bincode (not human-inspectable, format stability risks across serde versions), and rkyv (zero-copy but requires unsafe and pinned schema). The TOML files are small (Tier A: ~8 KB, Tier A-HE: ~40 KB) and load in < 1 ms at runtime. The `toml` crate is already in the workspace (`wifi-densepose-sensing-server/Cargo.toml`).
|
||||
|
||||
**Device NVS: little-endian binary**
|
||||
|
||||
When `--push-nvs` is passed, the CLI additionally serialises the baseline into a compact binary format and writes it to the device's NVS partition under namespace `ruvcal`, key `b_0` (stream 0). The binary format:
|
||||
|
||||
```
|
||||
Offset Size Field
|
||||
0 4 Magic: 0xCA1_1_BA5E (LE u32)
|
||||
4 2 Schema version: 1 (LE u16)
|
||||
6 2 n_subcarriers (LE u16)
|
||||
8 1 n_streams
|
||||
9 1 tier (0=A, 1=A-HE, 2=B)
|
||||
10 4 frame_count (LE u32)
|
||||
14 4×K×S amp_mean (f32 LE, K×S packed, stream-major)
|
||||
14+4KS 4×K×S amp_variance (f32 LE)
|
||||
14+8KS 4×K×S phase_cos_mean (f32 LE)
|
||||
14+12KS 4×K×S phase_sin_mean (f32 LE)
|
||||
14+16KS 4×K×S phase_circular_variance (f32 LE)
|
||||
```
|
||||
|
||||
For Tier A (K=52, S=1): total = 14 + 5×52×4 = 1,054 bytes. Well within NVS single-key limits (4,000 bytes default). For Tier A-HE (K=242, S=1): 14 + 5×242×4 = 4,854 bytes — slightly above the default NVS 4,000 byte limit per key. **Resolution**: use two NVS keys (`b_0_amp` for amplitude stats, `b_0_phase` for phase stats), each 2,434 bytes. The CLI serialises to two keys when K×S×4 > 1,980 bytes.
|
||||
|
||||
Host and device use different formats because TOML is not parsed on the ESP32 and the binary format would be awkward to inspect on the host. The CLI handles both directions; no device code changes are required.
|
||||
|
||||
### 2.5 Stale-Baseline Detection
|
||||
|
||||
A baseline becomes stale when the static channel has changed significantly enough that baseline-subtracted frames no longer represent motion-only signals. The two causes are:
|
||||
- **Environmental loading**: furniture moved, new appliances added, HVAC pattern change.
|
||||
- **Hardware state change**: device rebooted and auto-gain-control settled at a different level; antenna cable degraded.
|
||||
|
||||
Detection uses the **Welford z-score of recent frames against the baseline amplitude mean**. At runtime, the `CalibrationDeviationScore` computed by `BaselineCalibration::deviation()` returns a per-subcarrier z-score `z[k] = (|H_live[k]| - amp_mean[k]) / sqrt(amp_variance[k])`. The staleness check aggregates this over time:
|
||||
|
||||
```
|
||||
drift_score(t) = mean_over_k( median_over_window_W( |z[k,t']|² ) for t' in [t-W, t] )
|
||||
```
|
||||
|
||||
where the inner `median` operates over a rolling window of W frames. `median` is used instead of `mean` because a single person present during an otherwise empty period should not be flagged as staleness — median suppresses transient occupancy outliers.
|
||||
|
||||
**Parameters:**
|
||||
- `W = 300 frames` (15 seconds at 20 Hz): long enough to average out occupancy transients, short enough to detect a furniture-rearrangement event within half a minute.
|
||||
- Staleness threshold: `drift_score > 4.0`. This corresponds to a mean squared z-score of 4 across all subcarriers, i.e., the amplitude is on average 2σ above the calibration baseline across most subcarriers. This threshold was validated by the field_model.rs team: the `BaselineExpired` error in `field_model.rs` fires at a similar magnitude of environmental shift.
|
||||
|
||||
When `drift_score > 4.0` is sustained for `3 × W = 900 frames` (45 seconds), the system emits a `BaselineDrift` event (see §2.6). A single window above threshold triggers a `BaselineWarn` log only.
|
||||
|
||||
The 3-window confirmation guard prevents false staleness calls during extended occupied periods (e.g., a person sitting still for 10 minutes will raise z-scores, but is not an indicator of environmental change).
|
||||
|
||||
### 2.6 Recalibration Trigger
|
||||
|
||||
**Default behaviour: operator-initiated.**
|
||||
|
||||
The system does not recalibrate automatically. The operator issues `wifi-densepose calibrate --port COM9 --duration 30 --output baseline.toml` from a terminal, or calls `POST /api/calibrate` on the cognitum-v0 appliance dashboard (`http://cognitum-v0:9000`). Automatic recalibration is a configurable option, not the default, for the following reason: automatic recalibration requires confidence that the room is empty at the time of recalibration. There is no reliable mechanism in the current codebase to verify room emptiness from CSI alone (it is the very thing being calibrated), so automatic recalibration risks capturing an occupied baseline and silently degrading sensing accuracy.
|
||||
|
||||
**Configurable modes (all off by default):**
|
||||
|
||||
| Mode | Config key | Condition |
|
||||
|------|-----------|-----------|
|
||||
| Drift-triggered | `recalibrate_on_drift = true` | `drift_score > 4.0` sustained 45 s AND `drift_score < drift_score + 2σ` (i.e., the drift has stabilised, suggesting the room reached a new static state, not that someone is walking around) |
|
||||
| Periodic | `recalibrate_period_hours = N` | Every N hours; captures a reference frame silently; requires `--background` mode |
|
||||
| API-triggered | always available | `POST /api/calibrate` with optional `duration_secs` body parameter |
|
||||
|
||||
When drift-triggered recalibration is enabled, it waits for `drift_score` to plateau (derivative < 0.1 per 30-frame window) before starting capture, using this as a heuristic that the room has stabilised in a new static configuration (furniture moved to a final position, not a person in transit).
|
||||
|
||||
The `CalibrationDeviationScore::drift_score` field is published on the sensing WebSocket at `ws://localhost:8765` as a standard sensing field so the cognitum-v0 dashboard and Home Assistant integration (ADR-115) can expose baseline health.
|
||||
|
||||
### 2.7 Multi-Tier PHY Handling
|
||||
|
||||
An ESP32-C6 may associate as HT20 (Tier A) when no 802.11ax AP is in range, or as HE20 (Tier A-HE) when one is available. The two modes produce different subcarrier counts (52 vs 242 K_active) and different pilot patterns. They are **not interchangeable baselines**.
|
||||
|
||||
**Decision: one baseline file per PHY tier per link. Tier change invalidates the existing baseline.**
|
||||
|
||||
When the aggregator receives a frame from a C6 link and `CsiMetadata.bandwidth_mhz` and the PPDU type (from ADR-110's `csi_collector.c` frame byte 18–19) indicate a tier different from the currently loaded baseline, `BaselineCalibration::subtract()` returns `CalibrationError::TierMismatch { expected, actual }`. The aggregator logs this at WARN level and falls back to no-baseline-subtraction mode for that link until the operator recalibrates.
|
||||
|
||||
The rationale for invalidation rather than interpolation: interpolating a 52-subcarrier baseline to 242 subcarriers (or vice versa) requires assumptions about per-subcarrier correlation that are not validated in this codebase. The hardware-norm resample path (`hardware_norm.rs`) uses Catmull-Rom for subcarrier grid normalisation, but that normalises across hardware types at the same tier — not across tier transitions on the same device.
|
||||
|
||||
In practice, tier transitions are rare: they occur when the AP is rebooted (dropping 802.11ax), when the C6 moves out of 11ax AP range, or when the operator changes the AP. The operator is expected to recalibrate after a tier change.
|
||||
|
||||
### 2.8 Fleet-Wide Simultaneous Capture
|
||||
|
||||
The operator can calibrate the full multistatic array with a single command:
|
||||
|
||||
```
|
||||
wifi-densepose calibrate --all-nodes --duration 30 --output baselines/
|
||||
```
|
||||
|
||||
This issues a simultaneous capture barrier across all configured nodes using the 802.15.4 epoch from ADR-110 (`c6_timesync_get_epoch_us()` on C6 nodes; local clock interpolated to 802.15.4 domain for S3 nodes).
|
||||
|
||||
**Protocol skeleton:**
|
||||
|
||||
1. The CLI sends a `CalibrateStart { start_epoch_us, duration_ms }` UDP control packet to each node's UDP control port (default 5006). Nodes begin accumulating frames from `start_epoch_us` for `duration_ms` milliseconds, tagging each with the 802.15.4 epoch. S3 nodes use their local hardware timer; C6 nodes use `c6_timesync_get_epoch_us()`.
|
||||
2. The aggregator simultaneously opens a UDP receive socket per node and applies `CalibrationRecorder::record()` to each incoming frame. Frame ordering within the window is irrelevant because Welford statistics are commutative.
|
||||
3. At `start_epoch_us + duration_ms + 500 ms` (500 ms guard for last-frame arrival), the CLI finalises each `CalibrationRecorder`, serialises each `BaselineCalibration` to `baselines/<device_id>.toml`, and optionally pushes NVS binary to each device.
|
||||
4. A summary JSON `baselines/summary.json` lists each node, tier, frame count, and the mean `drift_score` relative to any previous baseline, allowing the operator to spot nodes that were occupied during calibration.
|
||||
|
||||
Fleet capture requires that all C6 nodes are associated (not in AP setup mode). Seed nodes that have not yet been provisioned (`seed-2` through `seed-5` from CLAUDE.local.md fleet table) are skipped with a warning. `cognitum-seed-1` is the only fully provisioned seed as of this writing.
|
||||
|
||||
The 802.15.4 timesync barrier is optional for calibration accuracy (Welford statistics are order-independent) but is required when the calibration baseline will also be used to compute the inter-node phase alignment for ADR-042's CHCI path.
|
||||
|
||||
### 2.9 Proposed Rust API
|
||||
|
||||
The new module is `v2/crates/wifi-densepose-signal/src/ruvsense/calibration.rs`, exported from `ruvsense/mod.rs` as `pub mod calibration`.
|
||||
|
||||
```rust
|
||||
use num_complex::Complex32;
|
||||
use wifi_densepose_core::types::CsiFrame;
|
||||
|
||||
// ---- Error type -------------------------------------------------------------
|
||||
|
||||
#[derive(Debug, thiserror::Error)]
|
||||
pub enum CalibrationError {
|
||||
#[error("Tier mismatch: baseline is {expected}, frame is {actual}")]
|
||||
TierMismatch { expected: String, actual: String },
|
||||
|
||||
#[error("Subcarrier count mismatch: baseline has {expected}, frame has {got}")]
|
||||
SubcarrierMismatch { expected: usize, got: usize },
|
||||
|
||||
#[error("Stream count mismatch: baseline has {expected}, frame has {got}")]
|
||||
StreamMismatch { expected: usize, got: usize },
|
||||
|
||||
#[error("Insufficient frames: need at least {needed}, recorded {got}")]
|
||||
InsufficientFrames { needed: usize, got: usize },
|
||||
|
||||
#[error("Baseline not yet finalised (still recording)")]
|
||||
NotFinalised,
|
||||
|
||||
#[error("Baseline data corrupted: {0}")]
|
||||
Corrupt(String),
|
||||
|
||||
#[error("Phase precondition violated: frame phase has not been sanitized")]
|
||||
UnsanitizedPhase,
|
||||
|
||||
#[error("TOML serialisation error: {0}")]
|
||||
TomlSerialise(String),
|
||||
|
||||
#[error("TOML deserialisation error: {0}")]
|
||||
TomlDeserialise(String),
|
||||
}
|
||||
|
||||
// ---- Configuration ----------------------------------------------------------
|
||||
|
||||
#[derive(Debug, Clone)]
|
||||
pub struct CalibrationConfig {
|
||||
/// Number of frames to accumulate before finalising. Default: 600 (30 s × 20 Hz).
|
||||
pub target_frames: usize,
|
||||
/// Minimum frames accepted by `finalize()`. Default: 200.
|
||||
pub min_frames: usize,
|
||||
/// Staleness window in frames. Default: 300.
|
||||
pub drift_window_frames: usize,
|
||||
/// Drift score threshold for BaselineDrift event. Default: 4.0.
|
||||
pub drift_threshold: f32,
|
||||
/// Duration (frames) above drift_threshold before emitting BaselineDrift. Default: 900.
|
||||
pub drift_confirm_frames: usize,
|
||||
}
|
||||
|
||||
impl Default for CalibrationConfig {
|
||||
fn default() -> Self {
|
||||
Self {
|
||||
target_frames: 600,
|
||||
min_frames: 200,
|
||||
drift_window_frames: 300,
|
||||
drift_threshold: 4.0,
|
||||
drift_confirm_frames: 900,
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
// ---- Recorder ---------------------------------------------------------------
|
||||
|
||||
/// Accumulates CSI frames from an empty room to build a baseline.
|
||||
///
|
||||
/// # Phase precondition
|
||||
///
|
||||
/// The caller is responsible for passing frames whose phase has been
|
||||
/// processed by `PhaseSanitizer` and `phase_align.rs` before calling
|
||||
/// `record()`. Unsanitized phase will be detected by a heuristic
|
||||
/// (per-subcarrier phase variance > 10 rad²) and rejected with
|
||||
/// `CalibrationError::UnsanitizedPhase`.
|
||||
///
|
||||
/// # Concurrency
|
||||
///
|
||||
/// `CalibrationRecorder` requires `&mut self` for `record()`. It is not
|
||||
/// `Sync`. Wrap in a `Mutex` if shared across threads.
|
||||
pub struct CalibrationRecorder {
|
||||
config: CalibrationConfig,
|
||||
frame_count: usize,
|
||||
n_streams: usize,
|
||||
n_subcarriers: usize,
|
||||
// Amplitude Welford accumulators: [stream][subcarrier]
|
||||
amp_mean: Vec<Vec<f64>>,
|
||||
amp_m2: Vec<Vec<f64>>,
|
||||
// Circular phase accumulators: [stream][subcarrier]
|
||||
phase_sin_sum: Vec<Vec<f64>>,
|
||||
phase_cos_sum: Vec<Vec<f64>>,
|
||||
}
|
||||
|
||||
impl CalibrationRecorder {
|
||||
/// Create a new recorder. The first `record()` call sets the
|
||||
/// expected subcarrier and stream counts.
|
||||
pub fn new(config: CalibrationConfig) -> Self;
|
||||
|
||||
/// Accept one sanitized CSI frame into the running statistics.
|
||||
///
|
||||
/// Returns the current frame count after this update.
|
||||
pub fn record(&mut self, frame: &CsiFrame) -> Result<usize, CalibrationError>;
|
||||
|
||||
/// Returns `true` if `target_frames` have been accumulated.
|
||||
pub fn is_complete(&self) -> bool;
|
||||
|
||||
/// Returns the current frame count.
|
||||
pub fn frame_count(&self) -> usize;
|
||||
|
||||
/// Finalise the baseline from accumulated statistics.
|
||||
///
|
||||
/// Consumes `self`. Returns an error if fewer than `min_frames` were
|
||||
/// recorded.
|
||||
pub fn finalize(self) -> Result<BaselineCalibration, CalibrationError>;
|
||||
}
|
||||
|
||||
// ---- Baseline ---------------------------------------------------------------
|
||||
|
||||
/// A fully finalised empty-room baseline.
|
||||
///
|
||||
/// Stores per-subcarrier amplitude mean/variance and circular phase
|
||||
/// mean/variance for each spatial stream. Immutable after construction.
|
||||
/// `Clone` is cheap (Vec of f32).
|
||||
#[derive(Debug, Clone)]
|
||||
pub struct BaselineCalibration {
|
||||
/// Device ID from which this baseline was captured.
|
||||
pub device_id: String,
|
||||
/// UTC timestamp of calibration (Unix seconds).
|
||||
pub captured_at_unix_s: i64,
|
||||
/// PHY tier string: "A", "A-HE", or "B".
|
||||
pub tier: String,
|
||||
/// Bandwidth in MHz.
|
||||
pub bandwidth_mhz: u16,
|
||||
/// Number of spatial streams.
|
||||
pub n_streams: usize,
|
||||
/// Number of active (non-pilot, non-null) subcarriers.
|
||||
pub n_subcarriers: usize,
|
||||
/// Total frames used to build this baseline.
|
||||
pub frame_count: usize,
|
||||
// Per-stream, per-subcarrier statistics (stream-major layout).
|
||||
pub amp_mean: Vec<Vec<f32>>,
|
||||
pub amp_variance: Vec<Vec<f32>>,
|
||||
pub phase_cos_mean: Vec<Vec<f32>>,
|
||||
pub phase_sin_mean: Vec<Vec<f32>>,
|
||||
/// Circular variance ∈ [0, 1]: 0 = concentrated, 1 = dispersed.
|
||||
pub phase_circular_variance: Vec<Vec<f32>>,
|
||||
}
|
||||
|
||||
impl BaselineCalibration {
|
||||
/// Compute a deviation score for one live frame against this baseline.
|
||||
///
|
||||
/// Returns `CalibrationError::TierMismatch` if the frame's bandwidth
|
||||
/// or subcarrier count do not match the baseline.
|
||||
pub fn deviation(&self, frame: &CsiFrame) -> Result<CalibrationDeviationScore, CalibrationError>;
|
||||
|
||||
/// Subtract the baseline amplitude mean from `frame.data` (in-place,
|
||||
/// stream-by-stream, subcarrier-by-subcarrier).
|
||||
///
|
||||
/// After subtraction, `frame.data[s][k]` represents the perturbation
|
||||
/// from the static environment, suitable for motion detection and CIR
|
||||
/// estimation.
|
||||
///
|
||||
/// Phase is not modified by subtraction; downstream callers that need
|
||||
/// phase-coherent baseline removal should use
|
||||
/// `reference_csi_vector()` to set `CirEstimator::set_reference_csi()`.
|
||||
pub fn subtract(&self, frame: &mut CsiFrame) -> Result<(), CalibrationError>;
|
||||
|
||||
/// Returns the expected complex CSI vector for the static environment
|
||||
/// (amplitude mean × exp(j × circular_mean_phase)), suitable for passing
|
||||
/// to `CirEstimator::set_reference_csi()`.
|
||||
///
|
||||
/// Returns one vector per spatial stream: `Vec<Vec<Complex32>>`.
|
||||
pub fn reference_csi_vector(&self) -> Vec<Vec<Complex32>>;
|
||||
|
||||
/// Serialise to TOML bytes.
|
||||
pub fn to_toml(&self) -> Result<Vec<u8>, CalibrationError>;
|
||||
|
||||
/// Deserialise from TOML bytes.
|
||||
pub fn from_toml(buf: &[u8]) -> Result<Self, CalibrationError>;
|
||||
|
||||
/// Serialise to compact NVS binary (see §2.4 for format).
|
||||
pub fn to_nvs_bytes(&self) -> Vec<u8>;
|
||||
|
||||
/// Deserialise from NVS binary.
|
||||
pub fn from_nvs_bytes(buf: &[u8]) -> Result<Self, CalibrationError>;
|
||||
}
|
||||
|
||||
// ---- Deviation score --------------------------------------------------------
|
||||
|
||||
/// Per-frame deviation from the static baseline.
|
||||
#[derive(Debug, Clone)]
|
||||
pub struct CalibrationDeviationScore {
|
||||
/// Per-subcarrier amplitude z-score: (|H[k]| − mean[k]) / std[k].
|
||||
/// Positive = higher than baseline, negative = lower.
|
||||
pub amplitude_z: Vec<Vec<f32>>,
|
||||
/// RMS amplitude z-score across all subcarriers and streams.
|
||||
/// Motion threshold: > 3.0 = likely occupied frame.
|
||||
pub rms_amplitude_z: f32,
|
||||
/// Per-subcarrier circular phase deviation in radians: |φ_live[k] − φ_baseline[k]|.
|
||||
pub phase_deviation_rad: Vec<Vec<f32>>,
|
||||
/// Mean circular phase deviation across all subcarriers.
|
||||
pub mean_phase_deviation_rad: f32,
|
||||
/// Instantaneous drift score (see §2.5 for definition).
|
||||
pub drift_score: f32,
|
||||
/// Whether the drift_score sustained above threshold (staleness flag).
|
||||
pub baseline_stale: bool,
|
||||
}
|
||||
```
|
||||
|
||||
**Design decisions within the API:**
|
||||
|
||||
- `record()` takes `&mut self`, not `&self` with interior mutability. The recording path is inherently single-threaded (one receiver loop per link). Interior mutability would add `Mutex` overhead for no benefit.
|
||||
- `subtract()` takes `&mut CsiFrame` and modifies `frame.data` in place. It does not modify `frame.amplitude` or `frame.phase` — callers that read `frame.amplitude` downstream are expected to call `CsiFrame::recompute_amplitude_phase()` (a new method to be added to `wifi_densepose_core::types::CsiFrame`) or to use `frame.data` directly.
|
||||
- `to_nvs_bytes()` / `from_nvs_bytes()` are fallible via `panic!` for magic mismatch but return `Result` for truncation. This matches the pattern in `csi.rs::parse_esp32_vitals()`.
|
||||
- `BaselineCalibration` is `Clone` because the CLI needs to hold one copy while pushing NVS and another while writing TOML.
|
||||
|
||||
### 2.10 CLI Surface
|
||||
|
||||
The `wifi-densepose calibrate` subcommand is added to `wifi-densepose-cli/src/lib.rs` as a new `Commands::Calibrate(CalibrateCommand)` variant.
|
||||
|
||||
```
|
||||
wifi-densepose calibrate [OPTIONS]
|
||||
|
||||
OPTIONS:
|
||||
--port <PORT> Serial port or UDP address of the ESP32 node
|
||||
(e.g., COM9 on Windows, /dev/ttyS8 on WSL).
|
||||
For fleet mode, omit and use --all-nodes.
|
||||
--duration <SECS> Capture duration in seconds [default: 30]
|
||||
--output <PATH> Path to write the TOML baseline file
|
||||
[default: baseline_<device_id>.toml]
|
||||
--tier <TIER> Expected PHY tier: A | A-HE | B
|
||||
[default: detected from first frame]
|
||||
--push-nvs After capturing, serialise to NVS binary and
|
||||
write to device flash via the provisioning tool.
|
||||
--all-nodes Fleet mode: capture from all configured nodes
|
||||
simultaneously using 802.15.4 epoch sync.
|
||||
--server <ADDR> Aggregator address for --all-nodes mode
|
||||
[default: 127.0.0.1:5006]
|
||||
--min-frames <N> Minimum frames before finalise() is accepted
|
||||
[default: 200]
|
||||
--drift-check After capturing, compare against an existing
|
||||
baseline at --output and print the drift score.
|
||||
```
|
||||
|
||||
**Defaults justified:**
|
||||
|
||||
- `--duration 30`: justified in §2.3.
|
||||
- `--output baseline_<device_id>.toml`: the device ID is embedded in the first received `CsiMetadata.device_id`. The operator does not need to specify it for single-node mode.
|
||||
- `--tier detected`: the first frame's `bandwidth_mhz` and PPDU type (for C6) determine the tier. The flag exists for cases where the operator wants to force Tier A even if the device is capable of Tier A-HE (e.g., to pre-generate a fallback baseline).
|
||||
|
||||
### 2.11 Downstream Consumers
|
||||
|
||||
| Consumer | What it receives | Change required |
|
||||
|----------|-----------------|-----------------|
|
||||
| `ruvsense/multistatic.rs` | Baseline-subtracted `CsiFrame.data` via `BaselineCalibration::subtract()` | `MultistaticConfig` gains a `baseline: Option<Arc<BaselineCalibration>>` field; `process_cycle()` calls `subtract()` on each node's latest frame before passing to the attention gate |
|
||||
| `ruvsense/cir.rs` (ADR-134) | Static-environment reference via `BaselineCalibration::reference_csi_vector()` passed to `CirEstimator::set_reference_csi()` | No API change to `CirEstimator`; the aggregator setup path calls `set_reference_csi()` at startup if a baseline file is present |
|
||||
| `motion.rs` | `CalibrationDeviationScore.rms_amplitude_z` as a primary motion signal | Replaces the existing amplitude variance threshold with a baseline-relative z-score; threshold changes from an absolute amplitude variance to `rms_amplitude_z > 3.0` |
|
||||
| `features.rs` | `CalibrationDeviationScore` fields available as additional features | `SignalFeatures` gains `baseline_rms_z: Option<f32>` and `baseline_drift_score: Option<f32>` fields; `None` when no baseline is loaded |
|
||||
| `wifi-densepose-vitals` | No change | Breathing and heart-rate detection filters operate in the 0.15–2.0 Hz band; slow baseline drift is below 0.001 Hz and is already filtered. The vital-sign pipeline benefits marginally from baseline subtraction at the amplitude level but this is not required for the current implementation. |
|
||||
| `ruvsense/field_model.rs` | Calibration frames passed through `CalibrationRecorder` before SVD decomposition | The field model now takes baseline-subtracted frames as input. The Welford mean accumulator in `field_model.rs::FieldModelBuilder` is superseded for the per-subcarrier-mean step — the calibration module handles it. `FieldModelBuilder` ingests `BaselineCalibration` directly to skip its internal mean step. |
|
||||
|
||||
**CIR interaction detail**: ADR-134's §2.5 specifies that the `CirEstimator` applies conjugate multiplication using `reference_csi` for single-antenna fallback. `BaselineCalibration::reference_csi_vector()` produces the correct complex reference vector: `amp_mean[s][k] × exp(j × atan2(phase_sin_mean, phase_cos_mean))`. This is more accurate than the previously described approach of averaging quiescent frames on the fly, because the baseline uses 600 frames (30 s) rather than a small number of recent frames, reducing the noise on the reference vector by a factor of ~√600/√10 ≈ 7.7× compared to a 0.5 s on-the-fly average.
|
||||
|
||||
### 2.12 Test Plan
|
||||
|
||||
**Tier 1 — Deterministic synthetic stationary channel (unit test)**
|
||||
|
||||
Generate a synthetic CSI frame representing a static 2-tap channel (direct path + one wall reflection, identical parameters to the ADR-134 Tier 1 test): `H[k] = α₁·e^{-j2πkΔf·τ₁} + α₂·e^{-j2πkΔf·τ₂}`. Add zero-mean Gaussian amplitude noise (σ = 0.02 × |α₁|) and constant phase offset δ = π/8 per subcarrier (simulating LO drift already corrected by `phase_align.rs`). Feed 600 copies of this frame to `CalibrationRecorder`. Call `finalize()`. Assert:
|
||||
|
||||
- `baseline.amp_mean[0][k]` is within 2σ/√600 of `|α₁·e^{-j2πkΔf·τ₁} + α₂·e^{-j2πkΔf·τ₂}|` for all k.
|
||||
- `baseline.phase_circular_variance[0][k]` < 0.005 (highly concentrated — noise σ = 0.02 does not produce meaningful phase variance).
|
||||
- `CalibrationDeviationScore.rms_amplitude_z` for the same static frame is < 1.0 (not flagged as motion).
|
||||
|
||||
**Tier 2 — Perturbation detection (unit test)**
|
||||
|
||||
Same baseline. Inject one frame with amplitude perturbed at 10 random subcarriers by +3σ (simulating a person present). Assert `rms_amplitude_z > 3.0` and that the perturbed subcarrier indices are among the top-10 `|amplitude_z|` entries in `CalibrationDeviationScore`.
|
||||
|
||||
**Tier 3 — TOML round-trip (unit test)**
|
||||
|
||||
Serialise the Tier 1 baseline to `to_toml()`, deserialise with `from_toml()`, assert field-level equality to within f32 precision.
|
||||
|
||||
**Tier 4 — NVS binary round-trip (unit test)**
|
||||
|
||||
Same as Tier 3 using `to_nvs_bytes()` / `from_nvs_bytes()`. Assert magic word `0xCA11BA5E` at offset 0 and schema version = 1.
|
||||
|
||||
**Tier 5 — Stale-baseline detection (unit test)**
|
||||
|
||||
Start with the Tier 1 baseline. Feed 900 frames with amplitude uniformly increased by `5σ` at all subcarriers (simulating furniture moved). Assert that `CalibrationDeviationScore.baseline_stale` becomes `true` at or before frame 900.
|
||||
|
||||
**Tier 6 — Real hardware capture (integration test, COM9)**
|
||||
|
||||
Using the ESP32-S3 on COM9 (ruvzen), capture a 30-second baseline in a static empty room. Then capture 200 live frames in the same room (still empty). Assert:
|
||||
- `CalibrationDeviationScore.rms_amplitude_z` < 2.0 for all 200 frames.
|
||||
- `CalibrationDeviationScore.drift_score` < 1.0.
|
||||
- Walking through the room during the live phase: at least 10 consecutive frames show `rms_amplitude_z > 3.0`.
|
||||
|
||||
This test is gated behind `#[cfg(feature = "hardware-test")]` and is not run in CI.
|
||||
|
||||
**Tier 7 — Determinism proof (CI-compatible)**
|
||||
|
||||
To extend the ADR-028 witness proof chain: using the same synthetic 600-frame stream from Tier 1, compute the SHA-256 of `to_nvs_bytes()` output. Record this hash in `archive/v1/data/proof/expected_features.sha256` under the key `calibration_nvs_baseline_v1`. The `verify.py` extension function `calibration_baseline_check()` regenerates the same 600-frame synthetic stream, runs `CalibrationRecorder`, serialises, and asserts the hash matches. This makes the calibration algorithm deterministic end-to-end, consistent with the ADR-028 proof methodology.
|
||||
|
||||
### 2.13 Witness / Proof
|
||||
|
||||
Per ADR-028, the following rows are added to `docs/WITNESS-LOG-028.md`:
|
||||
|
||||
| Row | Capability | Evidence | Hash |
|
||||
|-----|-----------|----------|------|
|
||||
| W-36 | CalibrationRecorder Welford correctness (synthetic 600-frame stationary) | `cargo test calibration::tests::stationary_baseline -- --nocapture` | SHA-256 of amp_mean output |
|
||||
| W-37 | BaselineCalibration NVS binary round-trip | `cargo test calibration::tests::nvs_round_trip` passes | SHA-256 of serialised bytes |
|
||||
| W-38 | Drift detection fires within 900 frames (synthetic 5σ perturbation) | `cargo test calibration::tests::stale_detection` | SHA-256 of test binary |
|
||||
|
||||
`source-hashes.txt` in the witness bundle gains `SHA-256(ruvsense/calibration.rs)`.
|
||||
|
||||
---
|
||||
|
||||
## 3. Consequences
|
||||
|
||||
### 3.1 Positive
|
||||
|
||||
- **Motion detector reliability**: replacing absolute amplitude variance thresholds with baseline-relative z-scores reduces false positives from HVAC and thermal drift. The `rms_amplitude_z > 3.0` threshold is scale-invariant across hardware tiers.
|
||||
- **CIR quality improvement**: `CirEstimator` receives a 600-frame static reference rather than a 10-frame rolling average. Ghost taps near τ=0 from the dominant static path are suppressed earlier in the ISTA solve, freeing regularisation budget for body-perturbed taps. Effective `dominant_tap_ratio` dynamic range increases by the ratio `√600/√10 ≈ 7.7×` in reference SNR — the ISTA warm-start quality directly improves.
|
||||
- **Multi-node amplitude comparability**: after baseline subtraction, each link's `CsiFrame.data` is zero-centred on the static environment. Multistatic attention weighting can use amplitude magnitude directly without per-link gain normalisation.
|
||||
- **ADR-030 field model simplification**: `FieldModelBuilder` no longer needs its own per-subcarrier Welford mean pass; it consumes the finished `BaselineCalibration` and proceeds directly to SVD. Duplicate code is removed.
|
||||
- **Fleet-wide recalibration is one command**: the `--all-nodes` flag with 802.15.4 epoch sync enables house-wide calibration in a single 30-second window, closing the operational gap for multi-room deployments.
|
||||
|
||||
### 3.2 Negative
|
||||
|
||||
- **Calibration ceremony required at install**: operators must capture a 30-second empty-room baseline before the system produces reliable motion scores. Systems shipped without a baseline fall back to uncalibrated mode (no `subtract()` call, absolute variance thresholds). This is not a regression — the current code has no baseline — but it is a new operational step.
|
||||
- **Baseline invalidated by furniture changes**: any significant room change (moved sofa, new TV) requires recalibration. The `drift_score > 4.0` alarm notifies the operator, but does not self-heal.
|
||||
- **Two NVS keys for Tier A-HE**: the 4,854-byte HE20 baseline does not fit in a single default NVS key. The two-key scheme (`b_0_amp` / `b_0_phase`) adds complexity to the device-side NVS reader if that is ever implemented. For the current scope (host-side reader only), this is not a practical problem.
|
||||
- **New `recompute_amplitude_phase()` method needed on `CsiFrame`**: `subtract()` modifies `frame.data` but `frame.amplitude` and `frame.phase` become stale. The method is simple (`amplitude = data.mapv(|c| c.norm()); phase = data.mapv(|c| c.arg())`) but it adds one public API surface to `wifi-densepose-core`.
|
||||
|
||||
### 3.3 Risks
|
||||
|
||||
| Risk | Probability | Impact | Mitigation |
|
||||
|------|-------------|--------|------------|
|
||||
| Operator captures baseline with person present | Medium (single-person household) | Silently corrupted baseline; baseline-subtracted frames look like a "hole" where the person was | The CLI prints real-time `rms_amplitude_z` during capture; high z-scores (>2.0) during capture trigger a WARNING banner. Post-capture, `--drift-check` compares against a previous baseline to flag anomalies |
|
||||
| Tier change (HT20 → HE20) invalidates baseline mid-session | Medium (C6 nodes near AP boundary) | `TierMismatch` error at runtime; system falls to uncalibrated mode | `TierMismatch` logged at WARN; operator notified via WebSocket event; auto-recalibration configurable |
|
||||
| Phase circular variance underestimated for subcarriers with multimodal phase distribution (two equally strong reflected paths at ±π/2) | Low (requires geometric coincidence) | `phase_circular_variance` near 1.0; phase reference from `reference_csi_vector()` is noisy for those subcarriers | `phase_circular_variance > 0.5` per-subcarrier is flagged in the TOML with a comment; CIR estimator down-weights the corresponding rows in Φ by masking them (same mechanism as pilot exclusion in §2.4 of ADR-134) |
|
||||
| ESP32-S3 auto-gain-control shifts between baseline capture and runtime | Low (AGC settles within 5 frames) | Amplitude mean baseline offset; all `amp_z` scores biased | AGC-locked mode (`esp_wifi_set_csi_config` with `rx_chain` pin) is available in firmware v0.7.0; recommend enabling for dedicated sensing nodes via `provision.py --pin-agc` flag |
|
||||
|
||||
---
|
||||
|
||||
## 4. Rationale and Comparison to Alternative Designs
|
||||
|
||||
### 4.1 Why Not "Skip Calibration, Rely on Differential Signals Only"
|
||||
|
||||
The dominant approach in academic WiFi sensing papers (2018–2022) is to use differential or conjugate-product CSI — dividing each frame by a running average of recent frames — rather than an explicit empty-room baseline. This avoids the calibration ceremony at the cost of three concrete problems in this codebase:
|
||||
|
||||
- **Differential signals accumulate bias under environmental loading**. A piece of furniture that moves over 10 minutes produces a slow CSI drift that appears as a 10-minute "motion" event in a conjugate-product system with a 1-second window, or becomes invisible in a system with a 1-hour window. There is no window size that eliminates environmental loading without also suppressing slow human motion (a resting person's micromotion is < 0.01 Hz). The IEEE Transactions 2024 paper "Experimental Evaluation of Long-Term Concept Drift and Its Mitigation in WiFi CSI Sensing" (IEEE Xplore document 10975920) demonstrates that concept drift from environmental factors causes systematic accuracy degradation over hours to days, which no differential window eliminates.
|
||||
- **Differential signals cannot be compared across nodes**. Multi-node coherence scoring requires a shared zero-mean reference. If each node has its own differential reference (its own recent history), drift rates differ across nodes and coherence scores are not interpretable.
|
||||
- **`CirEstimator` requires an absolute complex reference**. ADR-134 §2.5 describes conjugate multiplication: `H[k] * conj(H_ref[k])`. The `H_ref` in that context must be a stable, long-term static reference to avoid ghost taps — not a 0.5-second recent average, which still contains transient motion in active households.
|
||||
|
||||
### 4.2 Why Not "Calibrate at Factory, Ship Coefficients"
|
||||
|
||||
Per-device factory calibration would require: (a) a known-geometry, electromagnetically clean test chamber per device, and (b) the firmware to store calibration at production time. ESP32 hardware calibration (PHY RF calibration, `esp_phy_store_cal_data_to_nvs`) is a different concept — it corrects transmit chain IQ imbalance, not the per-room environmental channel. Room geometry is not known at factory. Per-room baseline is the only physically meaningful calibration for ambient sensing applications.
|
||||
|
||||
### 4.3 Why Not "Use a Neural Network-Learned Baseline"
|
||||
|
||||
Neural baseline subtraction (training a denoising autoencoder on empty-room CSI) has been proposed in several transfer learning papers. The objection from ADR-134 §2.2 for neural CIR applies equally here: there is no paired empty-room dataset for this codebase, and the feature distribution of "empty room" is inherently location-specific. A neural baseline trained in one room may produce negative subtraction values in a different room's frequency-selective geometry. The per-subcarrier Welford mean is a degenerate (optimal) estimator under Gaussian noise: it requires no training data, has a closed-form convergence guarantee, and generalises perfectly to any room because it operates on that room's own captures.
|
||||
|
||||
### 4.4 Why Welford Over Exponential Moving Average (EMA)
|
||||
|
||||
EMA (`mean_new = α × x + (1 − α) × mean_old`) is simpler to implement and provides continuous adaptation but has two drawbacks for a calibration baseline:
|
||||
|
||||
- **α is a free parameter** with no principled setting. Too small an α causes slow adaptation (baseline lags environmental loading); too large adapts immediately to occupancy (person present → person absorbed into baseline → false negative forever).
|
||||
- **EMA variance** requires a separate squared-error accumulator and is less numerically stable than Welford at finite precision.
|
||||
|
||||
Welford provides the exact sample variance in a single pass with no free parameters and no numerical issues. The existing `WelfordStats` in `field_model.rs` is reused directly. The only EMA advantage (continuous adaptation without a discrete recalibrate event) is a liability here: the baseline must be stable while the room is occupied and only updated on explicit operator command.
|
||||
|
||||
---
|
||||
|
||||
## 5. Related ADRs
|
||||
|
||||
| ADR | Relationship |
|
||||
|-----|-------------|
|
||||
| ADR-014 (SOTA Signal Processing) | **Extended**: calibration baseline subtraction becomes the zeroth stage of the signal pipeline, before any feature extraction |
|
||||
| ADR-028 (ESP32 Capability Audit) | **Witness extended**: three new rows W-36 through W-38 added to `WITNESS-LOG-028.md`; calibration NVS binary hash added to `source-hashes.txt` |
|
||||
| ADR-029 (RuvSense Multistatic) | **Enables**: `MultistaticConfig.baseline` field unblocks amplitude-comparable multi-node coherence scoring |
|
||||
| ADR-030 (Persistent Field Model) | **Simplified**: `FieldModelBuilder` no longer computes its own per-subcarrier Welford mean; it ingests `BaselineCalibration` as input |
|
||||
| ADR-110 (ESP32-C6 Firmware Extension) | **Substrate**: 802.15.4 epoch from `c6_timesync_get_epoch_us()` enables fleet-wide simultaneous capture barrier (§2.8); PPDU type (frame bytes 18–19) enables automatic tier detection for C6 nodes |
|
||||
| ADR-115 (Home Assistant Integration) | **Consumer**: `CalibrationDeviationScore.drift_score` and `baseline_stale` are published on the WebSocket stream and picked up by the HA MQTT publisher as `sensor.wifi_baseline_drift` and `binary_sensor.wifi_baseline_stale` |
|
||||
| ADR-134 (First-Class CIR Support) | **Prerequisite improved**: `BaselineCalibration::reference_csi_vector()` replaces the on-the-fly quiescent-frame average described in ADR-134 §2.5; CIR ghost taps from the static environment are suppressed more reliably |
|
||||
|
||||
---
|
||||
|
||||
## 6. References
|
||||
|
||||
### Production Code
|
||||
|
||||
- `v2/crates/wifi-densepose-signal/src/ruvsense/field_model.rs` — `WelfordStats` struct reused; `FieldModelBuilder` to be simplified
|
||||
- `v2/crates/wifi-densepose-signal/src/ruvsense/cir.rs` — `CirEstimator::set_reference_csi()` call site
|
||||
- `v2/crates/wifi-densepose-signal/src/phase_sanitizer.rs` — runs before calibration recording
|
||||
- `v2/crates/wifi-densepose-signal/src/ruvsense/phase_align.rs` — runs before calibration recording
|
||||
- `v2/crates/wifi-densepose-signal/src/hardware_norm.rs` — cross-hardware amplitude normalisation; operates before baseline for `canonical_grid` resampling, after baseline for `z-score` normalisation
|
||||
- `v2/crates/wifi-densepose-signal/src/ruvsense/multistatic.rs` — primary consumer of `BaselineCalibration::subtract()`
|
||||
- `v2/crates/wifi-densepose-signal/src/motion.rs` — secondary consumer of `CalibrationDeviationScore.rms_amplitude_z`
|
||||
- `v2/crates/wifi-densepose-cli/src/lib.rs` — `Commands::Calibrate` variant to be added
|
||||
- `v2/crates/wifi-densepose-sensing-server/src/cli.rs` — `Args` struct for sensing-server CLI context
|
||||
- `firmware/esp32-csi-node/provision.py` — provisioning tool; `--push-nvs` integration point
|
||||
- `archive/v1/data/proof/verify.py` — deterministic proof chain; `calibration_baseline_check()` extension
|
||||
- `archive/v1/data/proof/expected_features.sha256` — hash entry `calibration_nvs_baseline_v1` to be added
|
||||
|
||||
### External Papers
|
||||
|
||||
- Welford, B.P. (1962). "Note on a Method for Calculating Corrected Sums of Squares and Products." *Technometrics*, 4(3), 419–420. — Online mean/variance algorithm used for both amplitude and (via sin/cos projection) phase statistics.
|
||||
- Mardia, K.V. & Jupp, P.E. (2000). *Directional Statistics*. Wiley. Ch. 2–3. — Circular variance estimator `1 − R̄` and its standard error; von Mises maximum-likelihood estimator for the concentration parameter.
|
||||
- Ma, Y. et al. (2023). "Optimal Preprocessing of WiFi CSI for Sensing Applications." *IEEE Transactions on Wireless Communications* (published 2024, arXiv:2307.12126). — Derives the theoretically optimal gain and phase error correction for commodity WiFi CSI; confirms that a per-subcarrier amplitude model reduces sensing noise by 40% over no-correction baseline. Validates the amplitude-mean-subtraction approach chosen here.
|
||||
- Kong, R. & Chen, H. (2025). "Domino: Dominant Path-based Compensation for Hardware Impairments in Modern WiFi Sensing." arXiv:2509.13807. IEEE ICASSP 2026. — Shows that operating on the dominant static CIR path as a reference achieves >2× accuracy over existing compensation methods for respiration monitoring. Validates the principle that a stable static reference (this ADR's baseline) materially improves sensing over no-reference methods.
|
||||
- IEEE Xplore document 10975920 (2025). "Experimental Evaluation of Long-Term Concept Drift and Its Mitigation in WiFi CSI Sensing." — Demonstrates that environmental loading causes accuracy degradation over hours/days in CSI sensing systems that rely on differential signals only; motivates the explicit operator-initiated recalibration model chosen in §2.6.
|
||||
Some files were not shown because too many files have changed in this diff Show More
Reference in New Issue
Block a user