diff --git a/CHANGELOG.md b/CHANGELOG.md index 4cb1a638..d46d9714 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -9,7 +9,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 ### Added -- **`wifi-densepose-sar` — coherent wideband RF tomography research crate (ADR-283).** New standalone leaf crate (the `nvsim` pattern; zero coupling to `wifi-densepose-hardware` or any real ingestion path) implementing the synthetic-aperture-radar reconstruction primitive a handheld through-wall RF imaging device would need — motivated by comparison against Applied Electrodynamics' "WaveSight" launch, and explicitly scoped below ADR-278's RISE/DiffRadar/GeRaF reproduction gates. Ships: (1) a stepped-frequency, multi-position complex forward measurement simulator (`y_{m,k} = Σ σ_j/R² · exp(-i·4π·f·R/c) + noise`, deterministic ChaCha20 seeding); (2) delay-and-sum backprojection reconstruction onto a 3D voxel grid, rayon-parallelized over voxels; (3) threshold + local-maximum point-cloud extraction; (4) closed-form range/cross-range resolution and antenna-pose coherence-budget formulas (`ΔR=c/2B`, `δ_CR≈λR/2L`, `Δp≤λ/8`) checked against the reconstruction's *actual* behavior in `tests/physics_validation.rs` rather than merely documented — forward-simulating two targets at controlled separations and proving they resolve or merge exactly where the formulas predict, and that reconstructed focus at a known target degrades as injected antenna-pose error grows. Every number is SYNTHETIC/L0 (ADR-282) — no real wideband RF hardware backs this crate; see the crate README and `docs/tutorials/coherent-rf-tomography-backprojection.md` for the full honesty boundary and a worked walkthrough. `focus_at_point` exploits the evenly-spaced-by-construction frequency sweep (an arithmetic progression in per-term phase) to evaluate each pose's phasor once and advance it by a fixed complex-multiply step per frequency instead of one `sin`/`cos` pair per frequency — **MEASURED ~4.4-4.5x faster** (criterion regression detection, p < 0.001) than the first-shipped direct-computation version, proven equivalent (not just faster) to an independently reimplemented reference across four sweep sizes and on-/off-target points. 25 tests (22 unit + 3 integration), 0 failed, clippy-clean; MEASURED backprojection throughput ~1.7-2.3M voxels/sec (criterion, 21 poses × 32 freq steps). +- **`wifi-densepose-sar` — coherent wideband RF tomography research crate (ADR-287).** New standalone leaf crate (the `nvsim` pattern; zero coupling to `wifi-densepose-hardware` or any real ingestion path) implementing the synthetic-aperture-radar reconstruction primitive a handheld through-wall RF imaging device would need — motivated by comparison against Applied Electrodynamics' "WaveSight" launch, and explicitly scoped below ADR-278's RISE/DiffRadar/GeRaF reproduction gates. Ships: (1) a stepped-frequency, multi-position complex forward measurement simulator (`y_{m,k} = Σ σ_j/R² · exp(-i·4π·f·R/c) + noise`, deterministic ChaCha20 seeding); (2) delay-and-sum backprojection reconstruction onto a 3D voxel grid, rayon-parallelized over voxels; (3) threshold + local-maximum point-cloud extraction; (4) closed-form range/cross-range resolution and antenna-pose coherence-budget formulas (`ΔR=c/2B`, `δ_CR≈λR/2L`, `Δp≤λ/8`) checked against the reconstruction's *actual* behavior in `tests/physics_validation.rs` rather than merely documented — forward-simulating two targets at controlled separations and proving they resolve or merge exactly where the formulas predict, and that reconstructed focus at a known target degrades as injected antenna-pose error grows. Every number is SYNTHETIC/L0 (ADR-282) — no real wideband RF hardware backs this crate; see the crate README and `docs/tutorials/coherent-rf-tomography-backprojection.md` for the full honesty boundary and a worked walkthrough. `focus_at_point` exploits the evenly-spaced-by-construction frequency sweep (an arithmetic progression in per-term phase) to evaluate each pose's phasor once and advance it by a fixed complex-multiply step per frequency instead of one `sin`/`cos` pair per frequency — **MEASURED ~4.4-4.5x faster** (criterion regression detection, p < 0.001) than the first-shipped direct-computation version, proven equivalent (not just faster) to an independently reimplemented reference across four sweep sizes and on-/off-target points. 25 tests (22 unit + 3 integration), 0 failed, clippy-clean; MEASURED backprojection throughput ~1.7-2.3M voxels/sec (criterion, 21 poses × 32 freq steps). - **HOMECORE platform runtime completion — secure native/Wasmtime plugins, authenticated HAP IP, expanded Home Assistant APIs, durable restoration/migration, and voice protocols.** `homecore-server` now owns deterministic compiled-in native plugin registration plus explicitly configured, path-bounded, Ed25519 publisher-verified Wasm packages executed through Wasmtime with setup/state-change/teardown lifecycle; arbitrary native dynamic libraries remain intentionally unsupported. The optional HAP server implements persisted accessory identity and controller records, SRP-6a Pair-Setup M1–M6, X25519/Ed25519 Pair-Verify M1–M4, HKDF-SHA512/ChaCha20-Poly1305 record framing, authenticated/admin endpoint gates, replay/tamper closure, live entity synchronization, and paired-state `_hap._tcp` mDNS updates (45 focused tests; external Apple certification is not claimed). Startup restores device/entity registries and deterministic latest recorder states before plugins, and migration now atomically preserves forward-compatible device/config-entry fields. The HA-compatible surface adds events, templates, config checks, components, registries, history/logbook with SQL-enforced global response bounds, calendar/camera provider routes, and modern WebSocket negotiation while retaining a machine-readable limitations matrix for integration-specific behavior. Assist adds bounded PCM16, async STT/TTS contracts, an end-to-end speech pipeline, and an authenticated satellite session protocol; real deployments still provide the speech engines. - **`ruview-unified` increment 3 — Gaussian update-loop completion, separable delay-Doppler, and property-tested boundary hardening.** (1) `GaussianMap::merge_overlapping` (ADR-275 step 5: mutual-Mahalanobis + semantic-compatibility dedup catching drift the insert-time gate misses) and lifetime-aware decay (`τ_eff = τ·(1+ln(1+lifetime/τ))` — confirmed structures outlive transients at equal nominal τ). (2) `delay_doppler_map` reimplemented separably (`O(B²S+S²B)`), proven equivalent to the direct reference to <1e-10 and **measured 8.3× faster** (520 µs vs 4.34 ms at 56×8). (3) `tests/security_boundaries.rs` — 8 `proptest` properties over the boundary surfaces (arbitrary values incl. NaN/±inf via `f64::from_bits`) that found and fixed three input-controlled defects: a BLE-CS phase-unwrap infinite loop on non-finite phases and an ~1e299-iteration loop on finite-huge phases (now O(1) modular unwrap + plausibility bound), and a subnormal Gaussian scale overflowing `1/σ²` to NaN density (now physical σ/occupancy bounds). (4) New criterion benches for all increment-2 hot paths (`to_canonical` 38 µs, `ble_cs_range` 481 ns, AoI planner 647 ns/200 regions, coherent fusion 1.5 µs/32 members, factorized pose 521 ns). ruview-unified now 98 tests (87 lib + 3 acceptance + 8 security), 0 failed, clippy-clean. - **`ruview-unified` increment 2 — native frame contract + programmable perception (ADR-279..282).** (1) `RfFrameV2` becomes the authoritative RF record: native complex IQ with explicit validity masks, declared `PhaseState`, TX/RX poses + antenna geometry in one building frame, calibration/quality state, and a provenance rule enforced at construction — `Synthetic ⇒ L0Simulation` and `Measured ⇒ ≥ L1CapturedReplay` can never alias (the public L0–L5 evidence ladder is now a type); the 56-bin canonical tensor is demoted to a derived compatibility view (`to_canonical`, mask-aware gap-filling through the same normalization path as every adapter; native samples proven byte-untouched). (2) Active sensing control plane (`control.rs`): ETSI-ISAC-vocabulary `SensingTask` admission (raw export always refused; identity requires consent), `SensingAction`/`InformationGoal`, an age-of-information `ActiveSensingPlanner` (priority = uncertainty × change rate × criticality ÷ cost; **measured 95% sensing-traffic reduction** vs uniform refresh on a 20-region scenario), fail-closed `CoherentSensorGroup` fusion gates (time/phase/geometry bounds; five denial paths tested), policy-authorized RIS/movable-antenna actuation receipts, and purpose-scoped `TaskSufficientRepresentation` leakage validation. (3) New modality surfaces: BLE Channel Sounding adapter + `ble_cs_range` treating phase-slope and RTT as **separate cross-validated evidence** (exact distance recovery on synthetic tones; relay-style divergence flagged, never averaged), delay-Doppler-native `FieldAxis` + `delay_doppler_map` (unit-peak tone test), IEEE P3162 synthetic-aperture import profile. (4) RePos-factorized pose head (relative skeleton on the content representation, root on the geometry-conditioned one, calibrated per-joint uncertainties): held-out-room MPJPE 0.0003 m vs 0.2534 m for the monolithic baseline in the room-shortcut leakage experiment; ≤2% structured-adapter budget (740 params). (5) Age gate input now `log(1+age_ms)` per the age-aware-CSI recipe (gradient check re-proven); Gaussian primitives gained `first_seen_ns`/`doppler_variance`/bounded `source_receipts` lineage; `PartitionKey` gained a `session` dimension and `SplitManifest` certifies disjointness across all seven dimensions. 87 tests, 0 failed; crate clippy-clean. Docker images unaffected (no shipped binary consumes the crate yet); Python proof re-verified PASS. diff --git a/docs/adr/ADR-283-coherent-wideband-rf-tomography-crate.md b/docs/adr/ADR-287-coherent-wideband-rf-tomography-crate.md similarity index 99% rename from docs/adr/ADR-283-coherent-wideband-rf-tomography-crate.md rename to docs/adr/ADR-287-coherent-wideband-rf-tomography-crate.md index cc9b543b..6b377eae 100644 --- a/docs/adr/ADR-283-coherent-wideband-rf-tomography-crate.md +++ b/docs/adr/ADR-287-coherent-wideband-rf-tomography-crate.md @@ -1,4 +1,4 @@ -# ADR-283: `wifi-densepose-sar` — coherent wideband RF tomography research crate +# ADR-287: `wifi-densepose-sar` — coherent wideband RF tomography research crate | Field | Value | |-------|-------| diff --git a/docs/tutorials/coherent-rf-tomography-backprojection.md b/docs/tutorials/coherent-rf-tomography-backprojection.md index 9ca47f15..9215f6ea 100644 --- a/docs/tutorials/coherent-rf-tomography-backprojection.md +++ b/docs/tutorials/coherent-rf-tomography-backprojection.md @@ -1,6 +1,6 @@ # Coherent Wideband RF Tomography: Simulating and Reconstructing with `wifi-densepose-sar` -A walkthrough of the `wifi-densepose-sar` crate (ADR-283): simulating +A walkthrough of the `wifi-densepose-sar` crate (ADR-287): simulating synthetic-aperture radar (SAR) style measurements and reconstructing a 3D reflectivity image from them via delay-and-sum backprojection. @@ -41,7 +41,7 @@ radar-imaging research. This crate exists because of a real question: could this repo build something like [Applied Electrodynamics' WaveSight](https://www.ae-dyn.com/) — a handheld device that images through walls using radio waves? The -honest answer, worked out in ADR-283, is **no, not as a hardware product** +honest answer, worked out in ADR-287, is **no, not as a hardware product** — that needs a custom coherent RF front end, a calibrated antenna array, and real-time reconstruction hardware, which is an 18–36 month, high six-to-seven-figure hardware engineering program, not a software change. @@ -256,7 +256,7 @@ for p in &points { `extract_point_cloud` does threshold + 6-connected local-maximum extraction — a real blob will still yield one point, not one per voxel inside it. There is deliberately no clustering, material classification, -or confidence calibration here (ADR-283 §5): that needs real data to +or confidence calibration here (ADR-287 §5): that needs real data to calibrate against, which this crate does not have. ## 9. Benchmarking Your Own Scenario @@ -273,7 +273,7 @@ recorded MEASURED numbers on the reference machine. ## 10. Where This Could Go Next -This crate deliberately stops short of several things (ADR-283 §5): +This crate deliberately stops short of several things (ADR-287 §5): - It's monostatic (one antenna, both TX and RX) — real handheld SAR/MIMO devices often use multiple simultaneous antenna elements. @@ -284,7 +284,7 @@ This crate deliberately stops short of several things (ADR-283 §5): `GaussianMap` — ADR-278 names that as the eventual integration point, once (and if) a reconstruction system is ready for it. -If you're picking this up to extend it, start with ADR-283's "Follow-up" +If you're picking this up to extend it, start with ADR-287's "Follow-up" section rather than guessing at scope. ## 11. Troubleshooting diff --git a/v2/Cargo.toml b/v2/Cargo.toml index 7fc64b0e..38c0d88a 100644 --- a/v2/Cargo.toml +++ b/v2/Cargo.toml @@ -88,7 +88,7 @@ members = [ # submodule crates (rufield-core/-provenance/-privacy/-fusion); single # coupling point between RuView and the standalone RuField MFS spec. "crates/wifi-densepose-rufield", - # ADR-283 — coherent wideband RF tomography research crate: synthetic + # ADR-287 — coherent wideband RF tomography research crate: synthetic # stepped-frequency multi-position measurement simulation + delay-and-sum # backprojection reconstruction. Standalone leaf (nvsim pattern), zero # hardware coupling, every number SYNTHETIC/L0 until real wideband RF diff --git a/v2/crates/wifi-densepose-sar/Cargo.toml b/v2/crates/wifi-densepose-sar/Cargo.toml index ac6c8a5c..34ed1ae9 100644 --- a/v2/crates/wifi-densepose-sar/Cargo.toml +++ b/v2/crates/wifi-densepose-sar/Cargo.toml @@ -1,6 +1,6 @@ [package] name = "wifi-densepose-sar" -description = "Coherent wideband RF tomography research crate (ADR-283): synthetic stepped-frequency multi-position measurement simulation + delay-and-sum backprojection reconstruction. SYNTHETIC/L0 only -- no wideband RF hardware backs this crate." +description = "Coherent wideband RF tomography research crate (ADR-287): synthetic stepped-frequency multi-position measurement simulation + delay-and-sum backprojection reconstruction. SYNTHETIC/L0 only -- no wideband RF hardware backs this crate." version.workspace = true edition.workspace = true authors.workspace = true @@ -15,7 +15,7 @@ readme = "README.md" # pattern): pure-Rust math, deterministic ChaCha20 randomness (same seed => # byte-identical output on every machine), zero coupling to any hardware # ingestion path. It has NO internal RuView dependency -- see the crate-level -# doc comment in `src/lib.rs` for why (ADR-283 §2): this validates the +# doc comment in `src/lib.rs` for why (ADR-287 §2): this validates the # reconstruction *algorithm* against synthetic ground truth before any # question of wiring it into `ruview-unified`'s `FmcwRadarCube` adapter or # `GaussianMap` is in scope. diff --git a/v2/crates/wifi-densepose-sar/README.md b/v2/crates/wifi-densepose-sar/README.md index abd095f5..77508435 100644 --- a/v2/crates/wifi-densepose-sar/README.md +++ b/v2/crates/wifi-densepose-sar/README.md @@ -1,6 +1,6 @@ # wifi-densepose-sar -Coherent wideband RF tomography research crate (ADR-283): synthetic +Coherent wideband RF tomography research crate (ADR-287): synthetic stepped-frequency multi-position measurement simulation + delay-and-sum backprojection reconstruction of a 3D reflectivity field. diff --git a/v2/crates/wifi-densepose-sar/src/geometry.rs b/v2/crates/wifi-densepose-sar/src/geometry.rs index f60458e4..fc7af20a 100644 --- a/v2/crates/wifi-densepose-sar/src/geometry.rs +++ b/v2/crates/wifi-densepose-sar/src/geometry.rs @@ -53,7 +53,7 @@ impl Point3 { /// A single antenna position along a synthetic-aperture trajectory. /// -/// Only position is modeled (an isotropic-antenna approximation, ADR-283 +/// Only position is modeled (an isotropic-antenna approximation, ADR-287 /// §4) -- no antenna gain pattern / boresight direction is applied to the /// forward measurement model. #[derive(Debug, Clone, Copy, PartialEq, Serialize, Deserialize)] diff --git a/v2/crates/wifi-densepose-sar/src/lib.rs b/v2/crates/wifi-densepose-sar/src/lib.rs index 3a453080..ac6a7f23 100644 --- a/v2/crates/wifi-densepose-sar/src/lib.rs +++ b/v2/crates/wifi-densepose-sar/src/lib.rs @@ -1,4 +1,4 @@ -//! # wifi-densepose-sar — Coherent Wideband RF Tomography (ADR-283) +//! # wifi-densepose-sar — Coherent Wideband RF Tomography (ADR-287) //! //! A research crate implementing the reconstruction primitive that a //! handheld through-wall RF imaging device (the class of product exemplified @@ -20,7 +20,7 @@ //! behavior in `tests/physics_validation.rs` rather than merely asserted. //! - [`geometry`]: antenna poses and synthetic-aperture trajectories. //! -//! ## What this crate is NOT (ADR-283 §1, honesty boundary) +//! ## What this crate is NOT (ADR-287 §1, honesty boundary) //! //! - **Not a hardware driver.** There is no VNA, SDR, or wideband RF //! front-end integration here, and none of `wifi-densepose-hardware`'s diff --git a/v2/crates/wifi-densepose-sar/src/measurement.rs b/v2/crates/wifi-densepose-sar/src/measurement.rs index dfca7e02..b5c6b808 100644 --- a/v2/crates/wifi-densepose-sar/src/measurement.rs +++ b/v2/crates/wifi-densepose-sar/src/measurement.rs @@ -1,6 +1,6 @@ //! Forward measurement model: simulate the complex, stepped-frequency //! returns a monostatic synthetic-aperture radar would record from a set -//! of point scatterers (ADR-283 §2). +//! of point scatterers (ADR-287 §2). //! //! ```text //! y_{m,k} = sum_j sigma_j / R_{m,j}^2 * exp(-i * 4*pi * f_k * R_{m,j} / c) + noise diff --git a/v2/crates/wifi-densepose-sar/src/pointcloud.rs b/v2/crates/wifi-densepose-sar/src/pointcloud.rs index a9c54304..5a7c949f 100644 --- a/v2/crates/wifi-densepose-sar/src/pointcloud.rs +++ b/v2/crates/wifi-densepose-sar/src/pointcloud.rs @@ -5,7 +5,7 @@ //! `GaussianMap`, downstream fusion) want a short list of "here is //! something" points, not every voxel. This module does simple //! threshold + local-maximum extraction: no clustering, no material -//! classification, no confidence calibration against real data (ADR-283 +//! classification, no confidence calibration against real data (ADR-287 //! §5 -- explicitly out of scope for this crate). use crate::geometry::Point3; diff --git a/v2/crates/wifi-densepose-sar/src/reconstruct.rs b/v2/crates/wifi-densepose-sar/src/reconstruct.rs index b0faa887..041becc1 100644 --- a/v2/crates/wifi-densepose-sar/src/reconstruct.rs +++ b/v2/crates/wifi-densepose-sar/src/reconstruct.rs @@ -1,4 +1,4 @@ -//! Delay-and-sum backprojection reconstruction (ADR-283 §2). +//! Delay-and-sum backprojection reconstruction (ADR-287 §2). //! //! Given a [`crate::measurement::Measurement`] recorded from known antenna //! [`AntennaPose`]s across a known [`FrequencySweep`], reconstruct a 3D diff --git a/v2/crates/wifi-densepose-sar/src/resolution.rs b/v2/crates/wifi-densepose-sar/src/resolution.rs index e92c8de0..b22a9d14 100644 --- a/v2/crates/wifi-densepose-sar/src/resolution.rs +++ b/v2/crates/wifi-densepose-sar/src/resolution.rs @@ -1,4 +1,4 @@ -//! Closed-form resolution and coherence-budget formulas (ADR-283 §3). +//! Closed-form resolution and coherence-budget formulas (ADR-287 §3). //! //! These are textbook radar-imaging identities (see e.g. Skolnik, *Radar //! Handbook*, and the standard stripmap-SAR cross-range formula). They are diff --git a/v2/crates/wifi-densepose-sar/tests/physics_validation.rs b/v2/crates/wifi-densepose-sar/tests/physics_validation.rs index b99516ec..5f0e093d 100644 --- a/v2/crates/wifi-densepose-sar/tests/physics_validation.rs +++ b/v2/crates/wifi-densepose-sar/tests/physics_validation.rs @@ -1,6 +1,6 @@ //! Checks the reconstruction's *actual* behavior against the closed-form //! predictions in `wifi_densepose_sar::resolution`, rather than merely -//! asserting the formulas in documentation (ADR-283 §3, the +//! asserting the formulas in documentation (ADR-287 §3, the //! ruview-unified "proven, not asserted" discipline). //! //! Three physical claims are validated end-to-end (forward-simulate ->