From 9a2aacc9e61434f4e75bd58a081964b0f3346af0 Mon Sep 17 00:00:00 2001 From: ruv Date: Tue, 10 Nov 2026 22:54:54 -0500 Subject: [PATCH 1/2] =?UTF-8?q?feat(python):=20ADR-117=20=C2=A711.3=20v2?= =?UTF-8?q?=20witness=20over=20the=20Rust=20vitals=20pipeline=20+=20verify?= =?UTF-8?q?ing=20release=20gate?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - bind CsiVitalPreprocessor (stage 1 of the vitals pipeline) - wifi_densepose.witness: deterministic SHA-256 of the Rust pipeline output over archive/v1/data/proof/sample_csi_data.json; verify_witness() export - python-ci: witness-v2 job builds the release wheel (Rust 1.89), runs the witness twice, asserts equality, uploads the hash, checks the committed file - pip-release: gate now verifies the committed hash against the built manylinux x86_64 wheel, not just that the file is non-empty - SEO (ADR-356): Homepage https://ruv.io, truthful description, runnable README quickstarts; crate version 2.0.0 Co-Authored-By: claude-flow --- .github/workflows/pip-release.yml | 31 +++-- .github/workflows/python-ci.yml | 67 +++++++++++ python/Cargo.lock | 2 +- python/Cargo.toml | 2 +- python/README.md | 59 ++++++++-- python/pyproject.toml | 4 +- python/ruview-meta/README.md | 22 ++-- python/ruview-meta/pyproject.toml | 2 +- python/src/bindings/vitals.rs | 69 ++++++++++- python/tests/test_witness.py | 42 +++++++ python/wifi_densepose/__init__.py | 17 +++ python/wifi_densepose/witness.py | 187 ++++++++++++++++++++++++++++++ 12 files changed, 470 insertions(+), 34 deletions(-) create mode 100644 python/tests/test_witness.py create mode 100644 python/wifi_densepose/witness.py diff --git a/.github/workflows/pip-release.yml b/.github/workflows/pip-release.yml index ef1025ccca..ba9f231483 100644 --- a/.github/workflows/pip-release.yml +++ b/.github/workflows/pip-release.yml @@ -34,8 +34,9 @@ # dedicated follow-up commit (drop `password:`, add the OIDC id-token # permission + `environment: pypi`) so there is no capability gap between. # -# Production publishing fails closed until the ADR-117 §11.3 v2 witness -# hash exists. TestPyPI remains usable to validate release artifacts. +# Every v2 publish (PyPI or TestPyPI) fails closed unless the committed +# ADR-117 §11.3 v2 witness hash exists and matches a fresh witness run of +# the Linux x86_64 wheel being published. name: pip-release @@ -289,15 +290,6 @@ jobs: runs-on: ubuntu-latest steps: - uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 - - name: Enforce production witness gate - if: | - startsWith(github.ref, 'refs/tags/v2.') || - (github.event_name == 'workflow_dispatch' && inputs.publish_to == 'pypi') - run: | - test -s archive/v1/data/proof/expected_features_v2.sha256 || { - echo "::error::ADR-117 §11.3 release gate is incomplete: archive/v1/data/proof/expected_features_v2.sha256 is missing or empty" - exit 1 - } - name: Gather all artifacts into dist/ uses: actions/download-artifact@d3f86a106a0bac45b974a628896c90dbdf5c8093 with: @@ -307,6 +299,23 @@ jobs: mkdir -p dist find dist-staging -type f \( -name '*.whl' -o -name '*.tar.gz' \) -exec cp -v {} dist/ \; ls -lh dist/ + # ADR-117 §11.3 release gate: the committed v2 witness hash must exist + # AND match a fresh run of the exact Linux x86_64 wheel being published + # (python -m wifi_densepose.witness, see python/wifi_densepose/witness.py). + - name: Enforce witness gate (committed hash must match the built wheel) + run: | + set -euo pipefail + EXPECTED="$GITHUB_WORKSPACE/archive/v1/data/proof/expected_features_v2.sha256" + DATA="$GITHUB_WORKSPACE/archive/v1/data/proof/sample_csi_data.json" + test -s "$EXPECTED" || { + echo "::error::ADR-117 §11.3 release gate is incomplete: archive/v1/data/proof/expected_features_v2.sha256 is missing or empty" + exit 1 + } + whl="$(ls dist/*manylinux*x86_64.whl | head -1)" + python3 -m venv "$RUNNER_TEMP/wv" + "$RUNNER_TEMP/wv/bin/pip" install "$whl" + cd "$RUNNER_TEMP" # away from the repo root's stray wifi_densepose/ + "$RUNNER_TEMP/wv/bin/python" -I -m wifi_densepose.witness --data "$DATA" --expected "$EXPECTED" # API-token auth (active path). See TODO(ADR-184 P1b) in the header # before replacing `password:` with the OIDC id-token permission. - name: Publish to TestPyPI (dry-run target) diff --git a/.github/workflows/python-ci.yml b/.github/workflows/python-ci.yml index 39a91be451..fcd11b192d 100644 --- a/.github/workflows/python-ci.yml +++ b/.github/workflows/python-ci.yml @@ -36,6 +36,8 @@ on: - 'v2/crates/wifi-densepose-mat/**' - 'v2/crates/wifi-densepose-train/**' - 'v2/crates/wifi-densepose-signal/**' + - 'archive/v1/data/proof/sample_csi_data.json' + - 'archive/v1/data/proof/expected_features_v2.sha256' - '.github/workflows/python-ci.yml' pull_request: paths: @@ -47,6 +49,8 @@ on: - 'v2/crates/wifi-densepose-mat/**' - 'v2/crates/wifi-densepose-train/**' - 'v2/crates/wifi-densepose-signal/**' + - 'archive/v1/data/proof/sample_csi_data.json' + - 'archive/v1/data/proof/expected_features_v2.sha256' - '.github/workflows/python-ci.yml' workflow_dispatch: @@ -168,3 +172,66 @@ jobs: exit 1 fi echo "Default wheel is within the 5 MiB budget." + + # ADR-117 §11.3 / ADR-028 — v2 witness hash. Builds the release wheel with + # the same Rust pin as pip-release.yml (1.89), feeds the synthetic + # reference signal through the Rust vitals pipeline twice, and requires + # both hashes to agree. The hash is uploaded as an artifact (this is where + # the committed `expected_features_v2.sha256` came from) and, once that + # file is committed, must equal it. + witness-v2: + name: v2 witness hash (ADR-117 §11.3) + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 + with: + submodules: recursive + + - name: Set up Python + uses: actions/setup-python@ece7cb06caefa5fff74198d8649806c4678c61a1 + with: + python-version: '3.12' + + - name: Install Rust 1.89 (same pin as pip-release.yml) + run: | + rustup toolchain install 1.89 --profile minimal + rustup default 1.89 + rustc --version + + - name: Build release wheel + working-directory: python + run: | + python -m pip install --upgrade pip "maturin>=1.7,<2.0" + maturin build --release --out "$RUNNER_TEMP/wheel" + + - name: Generate witness hash twice and compare + run: | + set -euo pipefail + python -m venv "$RUNNER_TEMP/wv" + "$RUNNER_TEMP/wv/bin/pip" install "$RUNNER_TEMP"/wheel/*.whl + DATA="$GITHUB_WORKSPACE/archive/v1/data/proof/sample_csi_data.json" + EXPECTED="$GITHUB_WORKSPACE/archive/v1/data/proof/expected_features_v2.sha256" + # Run outside the checkout: the repo root has a legacy + # wifi_densepose/ directory that would shadow the installed wheel. + cd "$RUNNER_TEMP" + "$RUNNER_TEMP/wv/bin/python" -I -m wifi_densepose.witness --data "$DATA" | tee run1.txt + "$RUNNER_TEMP/wv/bin/python" -I -m wifi_densepose.witness --data "$DATA" | tee run2.txt + h1="$(awk '/^sha256:/ {print $2}' run1.txt)" + h2="$(awk '/^sha256:/ {print $2}' run2.txt)" + if [ -z "$h1" ] || [ "$h1" != "$h2" ]; then + echo "::error::witness is not deterministic: '$h1' vs '$h2'" + exit 1 + fi + mkdir -p "$RUNNER_TEMP/witness" + echo "$h1" > "$RUNNER_TEMP/witness/expected_features_v2.sha256" + if [ -s "$EXPECTED" ]; then + "$RUNNER_TEMP/wv/bin/python" -I -m wifi_densepose.witness --data "$DATA" --expected "$EXPECTED" + else + echo "::warning::expected_features_v2.sha256 not committed yet; generated $h1" + fi + + - uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 + with: + name: witness-v2-hash + path: ${{ runner.temp }}/witness/expected_features_v2.sha256 + if-no-files-found: error diff --git a/python/Cargo.lock b/python/Cargo.lock index 5e544d2931..6c9832db10 100644 --- a/python/Cargo.lock +++ b/python/Cargo.lock @@ -3353,7 +3353,7 @@ dependencies = [ [[package]] name = "wifi-densepose-py" -version = "2.0.0-alpha.1" +version = "2.0.0" dependencies = [ "geo", "numpy", diff --git a/python/Cargo.toml b/python/Cargo.toml index 15745ed23e..ab5dd098c4 100644 --- a/python/Cargo.toml +++ b/python/Cargo.toml @@ -1,6 +1,6 @@ [package] name = "wifi-densepose-py" -version = "2.0.0-alpha.1" +version = "2.0.0" # The `python/` crate is intentionally OUTSIDE the `v2/` Cargo # workspace (ADR-117 §5.2) so maturin's `python-source` + `module-name` # config stays self-contained and `cargo test --workspace` in v2/ diff --git a/python/README.md b/python/README.md index 29287b6888..6924e1a9e5 100644 --- a/python/README.md +++ b/python/README.md @@ -17,21 +17,31 @@ for talking to a live RuView sensing-server over WebSocket or MQTT. ## Features -- **17-keypoint pose** — full-body skeletal estimate from WiFi CSI, no camera -- **Vital signs** — respiratory rate (6–30 BPM) and heart rate (40–120 BPM) - with a confidence score and clinical-grade / degraded / unreliable status -- **Presence, person count, fall detection, motion** — fused outputs from - the same CSI stream -- **10 semantic primitives** (HA-MIND) — someone-sleeping, possible-distress, - room-active, bathroom-occupied, fall-risk-elevated, bed-exit, … — ready - to wire into Home Assistant or Apple Home automations +In the compiled wheel (runs offline, no server needed): + +- **Vital signs** — the Rust 3-stage pipeline: `CsiVitalPreprocessor` + (static-component suppression), `BreathingExtractor` (6–30 BPM) and + `HeartRateExtractor` (40–120 BPM), each estimate carrying a confidence + score and a valid / degraded / unreliable status +- **Pose types** — `Keypoint`, `PoseEstimate`, `PersonPose`, `BoundingBox` + for the 17-keypoint skeletons a RuView sensing-server produces - **Beamforming Feedback (BFLD) support** — 802.11ac/ax/be compressed feedback matrices on top of the receiver-side CSI path +- **Witness check** — `wifi_densepose.verify_witness()` re-runs the published + deterministic pipeline proof (ADR-117 §11.3) - **GIL-releasing DSP** — extract loops run with the GIL released, so a tokio-backed web server can call into the pipeline without stalling its event loop -- **Tiny wheel** — ~240 KB compiled (one binary per OS/arch covers Python - 3.10+ via the stable ABI) +- **Small wheel** — under 400 KB compiled (one binary per OS/arch covers + Python 3.10+ via the stable ABI) + +With the `[client]` extra, from a live RuView sensing-server: + +- **Pose, presence, person count, fall detection, motion** — streamed over + WebSocket (`SensingClient`) or MQTT (`RuViewMqttClient`) +- **10 semantic primitives** (HA-MIND) — someone-sleeping, possible-distress, + room-active, bathroom-occupied, fall-risk-elevated, bed-exit, … — ready + to wire into Home Assistant automations ## Install @@ -66,6 +76,35 @@ Runnable examples: [`examples/reid_from_csi.py`](examples/reid_from_csi.py), [`examples/cross_room_calibrate.py`](examples/cross_room_calibrate.py), [`examples/mat_triage.py`](examples/mat_triage.py). +## Quickstart + +Runs as-is after `pip install wifi-densepose`. It feeds 30 seconds of +synthetic CSI through the Rust pipeline and prints the recovered rates +(about 15 breaths/min and 72 beats/min): + +```python +import math + +from wifi_densepose import BreathingExtractor, CsiVitalPreprocessor, HeartRateExtractor + +pre = CsiVitalPreprocessor.esp32_default() # 56 subcarriers, EMA static suppression +br = BreathingExtractor.esp32_default() # 0.1-0.5 Hz band, 30 s window +hr = HeartRateExtractor.esp32_default() # 0.8-2.0 Hz band, 15 s window + +# 30 s of synthetic CSI at 100 Hz: 15 breaths/min (0.25 Hz) + 72 beats/min (1.2 Hz). +for i in range(3000): + t = i / 100.0 + a = 10.0 + 0.5 * math.sin(2 * math.pi * 0.25 * t) + 0.05 * math.sin(2 * math.pi * 1.2 * t) + residuals = pre.process([a] * 56) + breathing = br.extract(residuals, []) + heart = hr.extract(residuals, []) + +print("breathing:", breathing) +print("heart: ", heart) +``` + +The signal is synthetic; this shows the API, not accuracy on real CSI. + ## Usage ### Extract breathing rate from a CSI stream diff --git a/python/pyproject.toml b/python/pyproject.toml index f7f9a832b7..f53375798f 100644 --- a/python/pyproject.toml +++ b/python/pyproject.toml @@ -11,7 +11,7 @@ build-backend = "maturin" [project] name = "wifi-densepose" version = "2.0.0" -description = "WiFi-based human pose estimation, vital sign extraction, and ambient intelligence from Channel State Information (CSI). PyO3 bindings for the Rust core." +description = "WiFi CSI sensing for Python: Rust-compiled breathing and heart-rate DSP, pose and keypoint types, and WebSocket/MQTT clients for a RuView sensing-server." readme = "README.md" requires-python = ">=3.10" license = { text = "MIT" } @@ -71,7 +71,7 @@ dev = [ ] [project.urls] -Homepage = "https://github.com/ruvnet/RuView" +Homepage = "https://ruv.io" Repository = "https://github.com/ruvnet/RuView" Issues = "https://github.com/ruvnet/RuView/issues" Documentation = "https://github.com/ruvnet/RuView/tree/main/docs" diff --git a/python/ruview-meta/README.md b/python/ruview-meta/README.md index a9c6b69419..31d8ef2664 100644 --- a/python/ruview-meta/README.md +++ b/python/ruview-meta/README.md @@ -13,10 +13,13 @@ re-exports its full API under the `ruview` namespace — so you can write either of these and they do the same thing: ```python -from ruview import BreathingExtractor, SensingClient -from wifi_densepose import BreathingExtractor, SensingClient +from ruview import BreathingExtractor, HeartRateExtractor +from wifi_densepose import BreathingExtractor, HeartRateExtractor ``` +The WebSocket/MQTT clients live in `wifi_densepose.client` (install the +`[client]` extra). + ## Install ```bash @@ -26,14 +29,19 @@ pip install "ruview[client]" # + WebSocket/MQTT clients ## Usage +Runs as-is after `pip install ruview` (synthetic signal, about 15 breaths/min): + ```python -from ruview import BreathingExtractor +import math + +from ruview import BreathingExtractor, CsiVitalPreprocessor +pre = CsiVitalPreprocessor.esp32_default() br = BreathingExtractor.esp32_default() # 56 subcarriers @ 100 Hz, 30s window -for residuals, weights in csi_source: - est = br.extract(residuals=residuals, weights=weights) - if est is not None: - print(f"{est.value_bpm:.1f} BPM (confidence={est.confidence:.2f})") +for i in range(3000): + a = 10.0 + 0.5 * math.sin(2 * math.pi * 0.25 * i / 100.0) + est = br.extract(pre.process([a] * 56), []) +print(est) ``` Full API + WebSocket / MQTT / Home Assistant integration docs: diff --git a/python/ruview-meta/pyproject.toml b/python/ruview-meta/pyproject.toml index 9b971e3cc2..aaf3c4b703 100644 --- a/python/ruview-meta/pyproject.toml +++ b/python/ruview-meta/pyproject.toml @@ -52,7 +52,7 @@ dependencies = [ client = ["wifi-densepose[client]==2.0.0"] [project.urls] -Homepage = "https://github.com/ruvnet/RuView" +Homepage = "https://ruv.io" Repository = "https://github.com/ruvnet/RuView" Issues = "https://github.com/ruvnet/RuView/issues" Documentation = "https://github.com/ruvnet/RuView/tree/main/docs" diff --git a/python/src/bindings/vitals.rs b/python/src/bindings/vitals.rs index 196381c4d0..3a5c07715c 100644 --- a/python/src/bindings/vitals.rs +++ b/python/src/bindings/vitals.rs @@ -20,7 +20,8 @@ use pyo3::prelude::*; use wifi_densepose_vitals::{ - BreathingExtractor, HeartRateExtractor, VitalEstimate, VitalReading, VitalStatus, + BreathingExtractor, CsiFrame, CsiVitalPreprocessor, HeartRateExtractor, VitalEstimate, + VitalReading, VitalStatus, }; // ─── VitalStatus enum ──────────────────────────────────────────────── @@ -182,6 +183,71 @@ impl PyVitalReading { } } +// ─── CsiVitalPreprocessor ──────────────────────────────────────────── + +/// Stage 1 of the vitals pipeline: EMA static-component suppression. +/// Turns raw per-subcarrier amplitudes into body-modulated residuals, +/// which are the input `BreathingExtractor` / `HeartRateExtractor` expect. +/// +/// Python: +/// ```python +/// from wifi_densepose import CsiVitalPreprocessor +/// +/// pre = CsiVitalPreprocessor.esp32_default() # 56 subcarriers, alpha=0.05 +/// residuals = pre.process(amplitudes) # list[float] | None +/// ``` +#[pyclass(name = "CsiVitalPreprocessor")] +pub struct PyCsiVitalPreprocessor { + inner: CsiVitalPreprocessor, +} + +#[pymethods] +impl PyCsiVitalPreprocessor { + /// Construct with explicit parameters. `alpha` is clamped to + /// `[0.001, 0.999]` by the Rust core. + #[new] + #[pyo3(signature = (n_subcarriers, alpha=0.05))] + fn new(n_subcarriers: usize, alpha: f64) -> Self { + Self { inner: CsiVitalPreprocessor::new(n_subcarriers, alpha) } + } + + /// ESP32 defaults: 56 subcarriers, alpha = 0.05. + #[staticmethod] + fn esp32_default() -> Self { + Self { inner: CsiVitalPreprocessor::esp32_default() } + } + + /// Process one frame of per-subcarrier amplitudes and return the + /// residual vector (observed minus EMA prediction). The first frame + /// seeds the EMA and returns zeros. Returns `None` for an empty frame. + fn process(&mut self, py: Python<'_>, amplitudes: Vec) -> Option> { + let n = amplitudes.len(); + // Phases are unused by the preprocessor; CsiFrame::new only checks + // that the lengths agree, so pass a zero vector of matching length. + let frame = CsiFrame::new(amplitudes, vec![0.0; n], n, 0, 0.0)?; + py.detach(|| self.inner.process(&frame)) + } + + /// Clear all EMA state. + fn reset(&mut self) { + self.inner.reset(); + } + + #[getter] + fn alpha(&self) -> f64 { self.inner.alpha() } + + #[getter] + fn n_subcarriers(&self) -> usize { self.inner.n_subcarriers() } + + fn __repr__(&self) -> String { + format!( + "CsiVitalPreprocessor(n_subcarriers={}, alpha={})", + self.inner.n_subcarriers(), + self.inner.alpha(), + ) + } +} + // ─── BreathingExtractor ────────────────────────────────────────────── /// Extracts respiratory rate (6–30 BPM) from per-subcarrier amplitude @@ -306,6 +372,7 @@ pub fn register(m: &Bound<'_, PyModule>) -> PyResult<()> { m.add_class::()?; m.add_class::()?; m.add_class::()?; + m.add_class::()?; m.add_class::()?; m.add_class::()?; Ok(()) diff --git a/python/tests/test_witness.py b/python/tests/test_witness.py new file mode 100644 index 0000000000..75f9dc7929 --- /dev/null +++ b/python/tests/test_witness.py @@ -0,0 +1,42 @@ +"""ADR-117 §11.3 — v2 witness: the Rust vitals pipeline is deterministic and +matches the committed ``expected_features_v2.sha256``.""" + +from __future__ import annotations + +import pathlib + +import pytest + +from wifi_densepose import CsiVitalPreprocessor, verify_witness +from wifi_densepose.witness import compute_witness + +PROOF = pathlib.Path(__file__).resolve().parents[2] / "archive" / "v1" / "data" / "proof" +DATA = PROOF / "sample_csi_data.json" +EXPECTED = PROOF / "expected_features_v2.sha256" + +needs_data = pytest.mark.skipif(not DATA.exists(), reason="reference signal not in this checkout") + + +def test_preprocessor_seeds_then_tracks() -> None: + pre = CsiVitalPreprocessor(4, alpha=0.5) + assert pre.process([1.0, 2.0, 3.0, 4.0]) == [0.0, 0.0, 0.0, 0.0] + assert pre.process([3.0, 2.0, 3.0, 4.0]) == [2.0, 0.0, 0.0, 0.0] + assert pre.process([]) is None + + +@needs_data +def test_witness_is_deterministic() -> None: + a = compute_witness(DATA) + b = compute_witness(DATA) + assert a == b + assert a.frames == 1000 + assert a.heart_rate_estimates > 0 + + +@needs_data +@pytest.mark.skipif( + not EXPECTED.exists() or not EXPECTED.read_text().strip(), + reason="expected_features_v2.sha256 not committed yet", +) +def test_witness_matches_committed_hash() -> None: + assert verify_witness(str(DATA), str(EXPECTED)) diff --git a/python/wifi_densepose/__init__.py b/python/wifi_densepose/__init__.py index 874d44ca8b..d38dd5bded 100644 --- a/python/wifi_densepose/__init__.py +++ b/python/wifi_densepose/__init__.py @@ -49,6 +49,7 @@ VitalStatus = _native.VitalStatus VitalEstimate = _native.VitalEstimate VitalReading = _native.VitalReading +CsiVitalPreprocessor = _native.CsiVitalPreprocessor BreathingExtractor = _native.BreathingExtractor HeartRateExtractor = _native.HeartRateExtractor @@ -68,6 +69,19 @@ """Feature flags the wheel was compiled with.""" +def verify_witness(data_path: str, expected: str) -> bool: + """ADR-117 §11.3 — re-run the v2 witness and compare against ``expected``. + + Feeds ``data_path`` (``archive/v1/data/proof/sample_csi_data.json``) + through the Rust vitals pipeline and returns True if the SHA-256 of the + output matches ``expected`` (a hex digest or a path to + ``expected_features_v2.sha256``). See :mod:`wifi_densepose.witness`. + """ + from wifi_densepose.witness import verify_witness as _verify + + return _verify(data_path, expected) + + def hello() -> str: """Smoke test — confirms the compiled module loads and is callable. @@ -96,10 +110,13 @@ def hello() -> str: "VitalStatus", "VitalEstimate", "VitalReading", + "CsiVitalPreprocessor", "BreathingExtractor", "HeartRateExtractor", # P3.5 — BFLD (forward-compat surface for the future Rust crate) "BfldKind", "BfldFrame", "BfldReport", + # ADR-117 §11.3 — v2 witness + "verify_witness", ] diff --git a/python/wifi_densepose/witness.py b/python/wifi_densepose/witness.py new file mode 100644 index 0000000000..fc25ce3b50 --- /dev/null +++ b/python/wifi_densepose/witness.py @@ -0,0 +1,187 @@ +"""ADR-117 §11.3 / ADR-028 — v2 witness: a deterministic proof run of the +compiled Rust vitals pipeline. + +The v1 proof (``archive/v1/data/proof/verify.py``) hashes the output of the +legacy pure-Python CSI processor. This module is its v2 counterpart: it feeds +the same synthetic reference signal (``sample_csi_data.json``) through the +Rust pipeline bound in ``wifi_densepose._native`` and hashes the output. + +Pipeline (all three stages are Rust, called through the PyO3 bindings): + +1. ``CsiVitalPreprocessor.esp32_default()`` -> per-subcarrier residuals +2. ``BreathingExtractor.esp32_default().extract(residuals, [])`` +3. ``HeartRateExtractor.esp32_default().extract(residuals, phases)`` + +Canonical input: antenna 0 of each frame (56 amplitudes, 56 phases). + +Canonical bytes, in frame order, after the ``SCHEMA`` header: + +* frame index as little-endian ``int64`` +* residual count as ``uint32``, then each residual as ``float64`` +* for breathing, then heart rate: one byte (0 = no estimate, 1 = estimate), + followed, when present, by ``value_bpm`` and ``confidence`` as ``float64`` + and the status code as ``uint8`` + +Every float is rounded to ``DECIMALS`` places and ``-0.0`` is folded into +``0.0`` before packing. The heart-rate stage calls libm ``exp``/``cos``, +whose last bit may differ across platforms; rounding keeps the hash stable +across builds of the same code (the same reason v1 quantizes, RuView#560). +The committed ``expected_features_v2.sha256`` is produced on Linux x86_64. + +Usage:: + + python -I -m wifi_densepose.witness --data sample_csi_data.json + python -I -m wifi_densepose.witness --data sample_csi_data.json \\ + --expected expected_features_v2.sha256 + +Run with ``-I`` (or from outside the RuView checkout): the repository root +contains a legacy ``wifi_densepose/`` directory that would shadow the wheel. +""" + +from __future__ import annotations + +import argparse +import hashlib +import json +import math +import os +import struct +import sys +from dataclasses import dataclass +from typing import Any + +from wifi_densepose._native import ( + BreathingExtractor, + CsiVitalPreprocessor, + HeartRateExtractor, + VitalStatus, +) + +SCHEMA = b"wifi-densepose/witness-v2/1\n" +"""Header hashed before any frame. Bump it if the canonical form changes.""" + +DECIMALS = 6 +"""Decimal places every float is rounded to before hashing.""" + +_STATUS_CODE = { + VitalStatus.Valid: 0, + VitalStatus.Degraded: 1, + VitalStatus.Unreliable: 2, + VitalStatus.Unavailable: 3, +} + + +@dataclass(frozen=True) +class WitnessResult: + """Outcome of one witness run.""" + + sha256: str + frames: int + breathing_estimates: int + heart_rate_estimates: int + + +def _q(x: float) -> bytes: + if not math.isfinite(x): + raise ValueError(f"non-finite value in pipeline output: {x!r}") + # `+ 0.0` folds -0.0 into 0.0 so the sign of zero never changes the hash. + return struct.pack(" bytes: + if est is None: + return b"\x00" + return ( + b"\x01" + + _q(est.value_bpm) + + _q(est.confidence) + + struct.pack(" WitnessResult: + """Run the reference signal through the Rust pipeline and hash the output.""" + with open(data_path, encoding="utf-8") as f: + data = json.load(f) + frames = data["frames"] + if not frames: + raise ValueError(f"{data_path}: no frames") + + pre = CsiVitalPreprocessor.esp32_default() + br = BreathingExtractor.esp32_default() + hr = HeartRateExtractor.esp32_default() + + hasher = hashlib.sha256(SCHEMA) + n_br = n_hr = 0 + for frame in frames: + amplitudes = [float(v) for v in frame["amplitude"][0]] + phases = [float(v) for v in frame["phase"][0]] + residuals = pre.process(amplitudes) + if residuals is None: + raise ValueError(f"frame {frame['frame_index']}: empty amplitude vector") + br_est = br.extract(residuals, []) + hr_est = hr.extract(residuals, phases) + n_br += br_est is not None + n_hr += hr_est is not None + + hasher.update(struct.pack(" str: + text = str(expected) + if len(text) == 64 and all(c in "0123456789abcdef" for c in text.lower()): + return text.lower() + with open(expected, encoding="utf-8") as f: + token = f.read().split() + if not token: + raise ValueError(f"{expected}: empty hash file") + return token[0].lower() + + +def verify_witness( + data_path: str | os.PathLike[str], expected: str | os.PathLike[str] +) -> bool: + """Return True if the pipeline output hash matches ``expected``. + + ``expected`` is either a 64-character hex digest or the path of a file + whose first token is one (e.g. ``expected_features_v2.sha256``). + """ + return compute_witness(data_path).sha256 == _read_expected(expected) + + +def main(argv: list[str] | None = None) -> int: + parser = argparse.ArgumentParser( + prog="python -m wifi_densepose.witness", + description="ADR-117 §11.3 v2 witness: hash the Rust vitals pipeline output.", + ) + parser.add_argument("--data", required=True, help="path to sample_csi_data.json") + parser.add_argument( + "--expected", help="expected hash file (or hex digest); omit to just print the hash" + ) + args = parser.parse_args(argv) + + result = compute_witness(args.data) + print(f"frames: {result.frames}") + print(f"breathing estimates: {result.breathing_estimates}") + print(f"heart-rate estimates: {result.heart_rate_estimates}") + print(f"sha256: {result.sha256}") + if args.expected is None: + return 0 + want = _read_expected(args.expected) + if result.sha256 == want: + print("VERDICT: PASS") + return 0 + print(f"expected: {want}") + print("VERDICT: FAIL") + return 1 + + +if __name__ == "__main__": + sys.exit(main()) From 22944c8db2059eaca89b266b771cabb936a23d75 Mon Sep 17 00:00:00 2001 From: ruv Date: Tue, 10 Nov 2026 23:22:22 -0500 Subject: [PATCH 2/2] chore(proof): commit CI-generated expected_features_v2.sha256; fix macOS wheel builds MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - expected_features_v2.sha256 = witness-v2 artifact of python-ci run 42955822833 (Rust 1.89, Linux x86_64); provenance in ADR-028 §5.3 - pip-release: MACOSX_DEPLOYMENT_TARGET 10.12/11.0 so delocate accepts the rustc-built .so; macos-14 runner label is unsupported, use macos-15 Co-Authored-By: claude-flow --- .github/workflows/pip-release.yml | 8 ++++++- .../v1/data/proof/expected_features_v2.sha256 | 1 + docs/adr/ADR-028-esp32-capability-audit.md | 21 +++++++++++++++++++ ...DR-117-pip-wifi-densepose-modernization.md | 4 +++- docs/integrations/pypi-release.md | 11 ++++++---- 5 files changed, 39 insertions(+), 6 deletions(-) create mode 100644 archive/v1/data/proof/expected_features_v2.sha256 diff --git a/.github/workflows/pip-release.yml b/.github/workflows/pip-release.yml index ba9f231483..e660dc46ab 100644 --- a/.github/workflows/pip-release.yml +++ b/.github/workflows/pip-release.yml @@ -83,10 +83,15 @@ jobs: arch: x86_64 - os: ubuntu-latest arch: aarch64 + # macos_target: rustc's minimum macOS deployment target. Without it + # cibuildwheel tags x86_64 wheels 10.9 and delocate-wheel rejects + # the 10.12 .so that rustc emits. - os: macos-15-intel # x86_64 runner arch: x86_64 - - os: macos-14 # arm64 runner + macos_target: "10.12" + - os: macos-15 # arm64 runner (the macos-14 label is no longer supported) arch: arm64 + macos_target: "11.0" - os: windows-latest arch: AMD64 runs-on: ${{ matrix.os }} @@ -109,6 +114,7 @@ jobs: CIBW_ARCHS_LINUX: ${{ matrix.arch }} CIBW_ARCHS_MACOS: ${{ matrix.arch }} CIBW_ARCHS_WINDOWS: ${{ matrix.arch }} + MACOSX_DEPLOYMENT_TARGET: ${{ matrix.macos_target }} CIBW_BUILD_FRONTEND: "build" CIBW_BEFORE_BUILD: "pip install maturin>=1.7" # The PyO3 sdist landing depends on the cargo/Rust toolchain diff --git a/archive/v1/data/proof/expected_features_v2.sha256 b/archive/v1/data/proof/expected_features_v2.sha256 new file mode 100644 index 0000000000..16cd045995 --- /dev/null +++ b/archive/v1/data/proof/expected_features_v2.sha256 @@ -0,0 +1 @@ +92d867f2ed7ec9a96b4466b26903d81ff544b6d95dfeb71bb79d14ac633cd3cc diff --git a/docs/adr/ADR-028-esp32-capability-audit.md b/docs/adr/ADR-028-esp32-capability-audit.md index 02d037d371..96b7d0a873 100644 --- a/docs/adr/ADR-028-esp32-capability-audit.md +++ b/docs/adr/ADR-028-esp32-capability-audit.md @@ -236,9 +236,30 @@ python scripts/provision.py --port COM7 \ | Generator | `archive/v1/data/proof/generate_reference_signal.py` | Deterministic multipath model | | Verifier | `archive/v1/data/proof/verify.py` | SHA-256 hash comparison | | Expected hash | `archive/v1/data/proof/expected_features.sha256` | `0b82bd45...` | +| v2 verifier (Rust pipeline) | `python/wifi_densepose/witness.py` | `python -I -m wifi_densepose.witness` over the PyO3 wheel | +| v2 expected hash | `archive/v1/data/proof/expected_features_v2.sha256` | `92d867f2...` (ADR-117 §11.3) | **Audit-time result:** PASS. Hash regenerated with numpy 2.4.2 + scipy 1.17.1. Pipeline hash: `8c0680d7d285739ea9597715e84959d9c356c87ee3ad35b5f1e69a4ca41151c6`. +**v2 witness (ADR-117 §11.3, 2026-11-10).** The v2 hash covers the Rust vitals +pipeline, not the v1 Python processor. Antenna 0 of each of the 1,000 reference +frames goes through `CsiVitalPreprocessor`, `BreathingExtractor` and +`HeartRateExtractor` (all `esp32_default()`, called through the PyO3 bindings). +The residuals and estimates are rounded to 6 decimals, packed as little-endian +float64 and hashed with SHA-256; `witness.py` documents the byte layout. The +`witness-v2` job in `python-ci.yml` generated the committed value +`92d867f2ed7ec9a96b4466b26903d81ff544b6d95dfeb71bb79d14ac633cd3cc` +([run 42955822833](https://github.com/ruvnet/RuView/actions/runs/42955822833), +Rust 1.89, Linux x86_64, release wheel). It ran the witness twice, and both runs +agreed. A local Rust 1.89 build on Linux x86_64 gave the same hash. Of the 1,000 +frames, 501 produce a heart-rate estimate and none produce a breathing estimate: +the breathing stage needs 10 s of history, and at the 10 s mark the signal is +out of band. `python-ci.yml` re-checks the committed hash on every +`python/**` PR. `pip-release.yml` re-checks it against the manylinux x86_64 +wheel it is about to publish. The hash is pinned for Linux x86_64 only; other +platforms are expected to match because of the rounding, but they are not +gated. + ### 5.4 Security Posture - JWT authentication (`python-jose[cryptography]`) diff --git a/docs/adr/ADR-117-pip-wifi-densepose-modernization.md b/docs/adr/ADR-117-pip-wifi-densepose-modernization.md index c193aaea0d..5bfe8bfa35 100644 --- a/docs/adr/ADR-117-pip-wifi-densepose-modernization.md +++ b/docs/adr/ADR-117-pip-wifi-densepose-modernization.md @@ -524,9 +524,11 @@ scaffold core vitals+ client publish deferred - [ ] 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 +- [x] 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`. + *Done 2026-11-10:* `python/wifi_densepose/witness.py`, hash generated in CI, + provenance in ADR-028 §5.3. ### P4 — WS/MQTT client layer (1 week) diff --git a/docs/integrations/pypi-release.md b/docs/integrations/pypi-release.md index 802f4bed79..1428f3aa5f 100644 --- a/docs/integrations/pypi-release.md +++ b/docs/integrations/pypi-release.md @@ -51,7 +51,9 @@ Per ADR-117 §7.3, the tombstone publishes first so it claims the 2. Verify: `pip install wifi-densepose==1.99.0; python -c "import wifi_densepose"` → ImportError with migration URL. 3. Confirm `archive/v1/data/proof/expected_features_v2.sha256` is - committed and non-empty. Production publishing fails closed without it. + committed. Every v2 publish fails closed unless it matches a fresh + `python -I -m wifi_densepose.witness` run of the manylinux x86_64 wheel + (see ADR-028 §5.3 for how the hash was generated). 4. `git tag v2.0.0-pip && git push origin v2.0.0-pip` → the v2 `wifi-densepose` wheel matrix and matching `ruview` wheel/sdist are published together. Their versions and dependency pin are checked in CI. @@ -60,9 +62,10 @@ Per ADR-117 §7.3, the tombstone publishes first so it claims the ## Off-loop manual gates -- **Q3** (ADR-117 §11.3) — generate - `archive/v1/data/proof/expected_features_v2.sha256` from the v2 Rust - pipeline before a production v2 publish. The workflow enforces this gate. +- **Q3** (ADR-117 §11.3) — done. `expected_features_v2.sha256` was + generated by the `witness-v2` job in `python-ci.yml`. To regenerate it + after an intentional pipeline change, take the `witness-v2-hash` + artifact from that job, commit it, and record the run in ADR-028 §5.3. - **OIDC Trusted Publisher** — not used. The workflow is token-based; this is a deliberate choice to keep the secret refresh entirely in GCP. If the project migrates to OIDC later, remove `password:`