awesome-bookmarks/wifi-ruview
3
0
Fork 0
mirror of https://github.com/ruvnet/RuView.git synced 2026-06-02 00:58:56 +02:00
Code Issues Packages Projects Releases Wiki Activity
Files
85046381872442d277883e7213dd0ca94fee5457
wifi-ruview/archive
T
History
ruv 8504638187 feat(signal): ADR-135 — empty-room baseline calibration 
Operator-initiated calibration that records 30 s of stationary CSI,
emits a per-subcarrier baseline (amplitude mean+variance via Welford,
phase via circular sin/cos sums with von Mises dispersion), and gates
downstream stages on a deviation z-score. Plugs into multistatic
coherence gating, motion/presence detection, and the new ADR-134 CIR
estimator as a reference-subtracted input.

API surface (under wifi_densepose_signal):
  CalibrationConfig::{ht20, ht40, he20, he40}
  CalibrationRecorder { record(), finalize(), frames_recorded() }
  BaselineCalibration {
    subcarriers: Vec<SubcarrierBaseline>,
    deviation(&CsiFrame), subtract_in_place(&mut CsiFrame),
    to_bytes(), from_bytes()
  }
  CalibrationDeviationScore { amplitude_z_median, amplitude_z_max,
                              phase_drift_median, motion_flagged }
  CalibrationError { SubcarrierMismatch, TierMismatch,
                     InsufficientFrames, VersionMismatch, TruncatedBuffer }

Binary baseline format: magic 0xCA1B_0001 + u8 version=1 + u8 tier +
captured_at_unix_s (i64) + frame_count (u64) + num_subcarriers (u32) +
[SubcarrierBaseline; N] as 16 bytes each (amp_mean, amp_variance,
phase_mean, phase_dispersion as f32 LE). Hand-written serialisation so
the format is stable across Rust toolchain versions without serde drift.

CLI: new `wifi-densepose calibrate` subcommand binds a UDP listener
(0xC511_0001 frames), streams them through CalibrationRecorder, prints
a real-time z-score banner per ADR-135 §risk 1 (operator-may-be-moving),
aborts on sustained high deviation, and writes the binary baseline to
disk. Local UDP packet parser duplicated from sensing-server (per ADR
discussion — avoids cross-crate API churn).

Witness: cross-platform-deterministic SHA-256 over the per-subcarrier
quantised baseline profile (u16 LE at 1e-2/1e-4/1e-3, no sort) using
the lesson learnt from the CIR PR #837 libm-jitter fix. Hash:
d6bce07ecb1648e6936561df44bf4a3bfc17bb0ba5f692646b2301d105b52f67

CI guard: new "ADR-135 calibration witness proof (determinism guard)"
step under the Rust Workspace Tests job, adjacent to the existing
ADR-134 CIR guard. Regressions are unambiguously attributable.

Hardware-in-loop validation: full 600-frame capture exercised via the
new scripts/synth-csi-udp.py emitter targeting 127.0.0.1:5005. The CLI
binary received 600 frames at 20 Hz, z_med stable at ~0.7, motion
correctly NOT flagged, finalised baseline written to baseline.bin (860
bytes) with correct magic + version + timestamp in the header. Live
ESP32 capture from COM9 is operator follow-up — requires provisioning
the firmware's UDP target IP to match the host running the CLI.

Test results (cargo test -p wifi-densepose-signal --no-default-features):
  lib:                    382 pass / 0 fail / 1 ignored
  calibration_synthetic:   17 pass / 0 fail
  calibration_drift:        5 pass / 0 fail
  calibration_roundtrip:   10 pass / 0 fail
  cir_*:                    9 pass + 6 documented P2 ignores
  doctest:                 10 pass

Bench: 20 Criterion combinations registered
(recorder_record / recorder_finalize / deviation / record_600 /
to_bytes across HT20/HT40/HE20/HE40 tiers).

Witness: bash scripts/verify-calibration-proof.sh → VERDICT: PASS

Co-Authored-By: claude-flow <ruv@ruv.net>
2026-05-28 18:57:08 -04:00
..
v1
feat(signal): ADR-135 — empty-room baseline calibration
2026-05-28 18:57:08 -04:00
README.md
chore(repo): move v1/ → archive/v1/ + add archive/README.md (#430)
2026-04-25 23:07:52 -04:00

README.md

Archive

Frozen, no-longer-active components of RuView preserved for historical reference, reproducibility, and load-bearing legacy paths the active codebase still depends on.

What lives here

Path What it is Why it's archived Still load-bearing?
v1/ Original Python implementation of RuView (CSI processing, hardware adapters, services, FastAPI) Superseded by the Rust workspace at v2/; ~810× slower in benchmarks. Kept rather than deleted because the deterministic proof bundle (v1/data/proof/) is part of the pre-merge witness verification process per ADR-011 / ADR-028. Yes — for the proof bundle only. Active code lives in v2/.

What "archived" means

  • Do not add new features here. New work goes in v2/.
  • Do not refactor or modernize the archived code beyond what is strictly necessary to keep the load-bearing paths working. The Python proof bundle is intentionally frozen so that its SHA-256 reproducibility holds across releases (per ADR-028's witness verification requirement).
  • Bug fixes inside archived code are allowed when the bug affects a still-load-bearing path (currently: only the Python proof). All other "bugs" in archived code are out-of-scope — they are part of the historical record and any fix would unnecessarily churn the witness hashes.
  • CI continues to verify the load-bearing paths. .github/workflows/verify-pipeline.yml runs the Python proof on every push and PR; if you change anything inside archive/v1/src/ or archive/v1/data/proof/, expect the determinism check to flag it.

Quick reference for the load-bearing paths

# Run the deterministic Python proof (must print VERDICT: PASS)
python archive/v1/data/proof/verify.py

# Regenerate the expected hash (only if numpy/scipy version legitimately changed)
python archive/v1/data/proof/verify.py --generate-hash

# Run the full Python test suite (legacy, still maintained)
cd archive/v1&& python -m pytest tests/ -x -q

Why we keep v1/ rather than delete it

  1. Trust kill-switch. The proof at v1/data/proof/verify.py feeds a known reference signal through the full pipeline and hashes the output. If the active code's behavior drifts, the hash changes and CI fails. This is what stops accidental regression in the science layer of the codebase.

  2. Witness verification. ADR-028's witness-bundle process bundles the proof, the rust workspace test results, and firmware hashes into a tarball recipients can self-verify. Removing v1 would break that chain.

  3. Historical reference. ADR-011 documents the "no mocks in production code" decision; the original violations and their fixes live in this Python codebase. The ADRs reference these paths.

If the time comes to retire the proof bundle (e.g., a Rust port of the proof exists and the Python version is no longer canonical), the right move is a single follow-up that simultaneously: ports the witness-bundle process, updates verify-pipeline.yml, and either deletes archive/v1/ or moves it to a separate read-only repository. That decision belongs in its own ADR.

See also

  • docs/adr/ADR-011-python-proof-of-reality-mock-elimination.md
  • docs/adr/ADR-028-esp32-capability-audit.md
  • archive/v1/data/proof/README.md (if present)
  • docs/WITNESS-LOG-028.md
Reference in New Issue View Git Blame Copy Permalink