feat(nvsim): scaffold + scene + frame [nvsim:pass1]
Pass 1 of the NV-diamond magnetometer pipeline simulator per
docs/research/quantum-sensing/15-nvsim-implementation-plan.md.
Standalone leaf crate at v2/crates/nvsim — deliberately NO internal
RuView dependencies. RuView ecosystem integrations
(wifi-densepose-core frame alignment, ruvector trace compression)
are tracked as Optional Integrations in README and land behind
feature flags after the core simulator ships.
Surfaces shipped:
- scene::Scene — aggregate ground-truth scene (dipoles, current loops,
ferrous objects, eddy-current discs, sensor positions, ambient field)
- scene::DipoleSource — point magnetic dipole, SI units
- scene::CurrentLoop — planar current loop with 64-segment default
Biot–Savart discretisation
- scene::FerrousObject — linearly-induced moment from ambient field
(χ_steel ≈ 5000 default per Cullity & Graham 2e §2)
- scene::EddyCurrent — Faraday + Ohm eddy-current disc primitive
- frame::MagFrame — 60-byte fixed-layout binary record, magic
0xC51A_6E70 (distinct from ADR-018 CSI 0xC51F... and ADR-084 sketch
0xC511_0084)
- frame::flag::* — bit-set constants (saturation, ADC clip, heavy
attenuation, shot-noise-disabled). Raw u16 to avoid pulling
bitflags as a workspace dep.
- NvsimError — typed errors for parse / serialisation failures
- MU_0, GAMMA_E, D_GS — shared physics constants
12 unit tests covering:
- scene JSON round-trip preserves all primitive types
- magic locked to documented value (0xC51A_6E70)
- frame size fixed at 60 bytes
- frame round-trip is byte-exact
- frame deserialiser rejects short / bad-magic / bad-version inputs
- byte-order determinism across repeated serialisations
- flag set/check helpers
Acceptance per plan §3 Pass 1:
- cargo check -p nvsim --no-default-features → clean
- cargo test -p nvsim --no-default-features → 12 passed (target ≥6)
- Workspace test count 1,575 → 1,587 (+12)
- ESP32-S3 on COM7 unaffected (cb #625100, alive)
Two research documents committed alongside:
- 14-nv-diamond-sensor-simulator.md (469 lines, SOTA + verdict)
- 15-nvsim-implementation-plan.md (268 lines, 6-pass build spec)
Status: Pass 1 only. Passes 2-6 (source, propagation, sensor,
digitiser+pipeline, proof+bench) ship in subsequent commits per the
implementation plan.
Co-Authored-By: claude-flow <ruv@ruv.net>
9c95bfac0c