docs(adr): SOTA research series 0015–0022 — emerging medical breakthroughs#2
Open
ruvnet wants to merge 17 commits into
Open
docs(adr): SOTA research series 0015–0022 — emerging medical breakthroughs#2ruvnet wants to merge 17 commits into
ruvnet wants to merge 17 commits into
Conversation
…oughs Add eight Architecture Decision Records extending the closed-loop neuromodulation ADR series into 2024–2026 state-of-the-art research, applications, and emerging medical breakthroughs. Each records how rUv Neural relates to a frontier while staying inside the ADR-0001 wellness boundary, and carries a References section citing primary literature. - 0015 Neural foundation-model embeddings (optional, pluggable backend; default stays the lightweight/edge-friendly embeddings — compact models match/beat large EEG-FMs; FM inference-only behind a feature flag) - 0016 Invasive BCI landscape & non-invasive scope boundary (interop via NWB/LSL/BIDS, never signal parity) - 0017 Wearable OPM-MEG front-end (driver abstraction; external MSR assumed) - 0018 NV-diamond magnetometry (aspirational front-end; honest ~1000x MEG gap) - 0019 40 Hz GENUS clinical evidence base & claims discipline - 0020 Adaptive/closed-loop *therapeutic* neuromodulation is out of scope (aDBS/RNS are implanted Class III devices) - 0021 Privacy-preserving, on-device & federated personalization - 0022 Neural-data governance & neurorights compliance (FDA general wellness, PCCP/GMLP, CA/CO/MT/CT neural-data laws, UNESCO, EU AI Act/GDPR) Update the ADR index in 0000-template.md.
…ackend Record the integration direction for ruvnet/ruvector as the optional downstream backend for embeddings, grounded in the existing RVF export seam. Maps RuVector capabilities onto prior ADRs: VEC/INDEX (HNSW+GNN ANN) for NeuralEmbedding/ruVector retrieval (0006/0015); PQ/binary quantization for edge storage (0015); WITNESS/CRYPTO + post-quantum/Ed25519 onto the hash-chained audit (0009/0014); FEDERATED_MANIFEST onto federated personalization (0021); WASM/ONNX onto local-first edge + interop (0014/0016). Flags the RVF format divergence (this repo's JSON v1 profile vs upstream's 25-segment binary container) as a prerequisite to reconcile, and the upstream-maturity/coupling risk. Update the ADR index.
Replace the toy single-blob RVF with a faithful, dependency-free port of RuVector's RVFS container framing (verified against ruvnet/ruvector, crates/rvf), realizing ADR-0023 points 1-3. ruv-neural-core: - rvf_container.rs: RVFS magic (0x52564653), 64-byte repr(C) segment headers at the exact upstream offsets, real segment-type codes (VEC=0x01, INDEX=0x02, MANIFEST=0x05, QUANT=0x06, META=0x07, WITNESS=0x0A, CRYPTO=0x0C, ...), 64-byte alignment, CRC32C (Castagnoli) + 128-bit content-hash integrity, and NeuralEmbedding <-> VEC/META mapping. - rvf_quant.rs: VEC quantization codecs (f64 lossless default, plus f32/f16/int8/binary) matching RuVector's temperature-tier dtypes; pure Rust IEEE-754 half conversion, symmetric int8, and binary sign packing. - rvf_witness.rs: 73-byte WITNESS chain entries + Ed25519 CRYPTO segment, tying the ADR-0009 hash-chained audit to the on-disk container. ruv-neural-embed: - rvf_export.rs: .rvf files are now the binary container (was ad-hoc JSON), reconciling the two divergent formats; JSON kept only as a debug form; adds export_rvf_quantized for f16/int8/binary. Profile note: substitutes SHA-256 for upstream SHAKE-256 (same size, same layout) to stay dependency-free; recorded in checksum_algo. Validation: 21 new unit tests (header round-trips, segment-code conformance, quantization error bounds, corruption detection, witness linkage, signature forgery). Full workspace test suite green; new code is clippy-clean.
Add HnswGraph (serializable topology) plus HnswIndex::export_graph/from_graph, and ruv-neural-memory/src/rvf_index.rs with build_indexed_container / load_indexed_container so a single .rvf carries META + VEC + INDEX: vectors and a ready-to-query approximate-nearest-neighbour graph. The graph is built from full-precision vectors so distances stay exact under any VEC quantization. 3 new tests: segment presence, byte round-trip with identical nearest-neighbour vs a freshly built index, and missing-INDEX error.
…DR-0021, ADR-0023.5) Add ruv-neural-loop/src/federated.rs: privacy-preserving federated averaging over PersonalBaseline summary statistics (per-feature mean + count), so raw signals/embeddings never leave a device. Optional differential privacy applies the Gaussian mechanism (L2 clipping + calibrated noise) and reports the spent (epsilon, delta) budget. Rounds are recorded in a self-describing RVF FEDERATED_MANIFEST segment (attach/read helpers). 7 new tests: count-weighted FedAvg, DP budget + perturbation, clipping bound, dim/empty errors, and manifest container round-trip.
Add ruv-neural-embed/src/foundation.rs: the FoundationEmbedder trait (inference- only, method-tagged, per-backend license) producing a standard NeuralEmbedding so downstream stays method-agnostic, plus ReferenceFoundationEmbedder — a dependency- free, deterministic reference scaffold (pooled per-channel stats, L2-normalized). Honestly labeled 'foundation:reference' with no accuracy claim; real LaBraM/REVE backends drop in behind the fm feature with ONNX and must beat baselines out-of- sample before promotion (ADR-0015 point 4). 5 tests: determinism, unit-norm + tagging, signal discrimination, RVF-seam export, degenerate-input error.
Add ruv-neural-viz/src/bids.rs: export_bids_eeg writes a minimal valid BIDS dataset using the BIDS-recommended BrainVision representation (.vhdr/.vmrk/.eeg IEEE-float32 multiplexed) plus dataset_description.json, channels.tsv, and the _eeg.json sidecar, so a recording opens in MNE-Python/EEGLAB/FieldTrip. Maps sensor types to BIDS channel types (EEG / MEGMAG) and units, sanitizes labels. NWB (HDF5) and LSL (live network protocol) need external C runtimes and stay ADR-0016 roadmap, documented as such. 4 tests: layout validity, float32 round-trip, channel-count mismatch error, label sanitization.
… capabilities Update ADR statuses to reflect shipped code: 0015 (FoundationEmbedder seam), 0016 (BIDS-EEG export; NWB/LSL remain roadmap), 0021 (federated averaging + DP + FEDERATED_MANIFEST), 0023 (HNSW INDEX + federation now implemented; ONNX/mincut remain roadmap). Add the four new capabilities to the Ed25519 attestation matrix in witness.rs.
…ta benchmark Add ruv-neural-decoder/src/logistic.rs: the crate's first *learned* model — a binary logistic-regression classifier (full-batch gradient descent, feature standardization, L2), dependency-free, deterministic, and serializable, with BinaryMetrics (accuracy/precision/recall/f1 + confusion counts). 5 unit tests incl. learning a separable problem (>0.95 acc). Add examples/train_eeg_eye_state.rs + docs/benchmarks/eeg-eye-state.md: trains on the public UCI EEG Eye State dataset with multi-protocol evaluation. Honest finding (ADR-0015/0019): with temporal-autocorrelation leakage removed (non-overlapping-window k-fold CV, or a strict chronological split) a linear log-power model is at chance vs the majority baseline — the literature's ~0.98 on this set is largely per-sample-shuffle leakage. Feature optimization (trailing-window log band-power) and balanced-accuracy tuning included.
Add examples/train_seizure.rs on the public Epileptic Seizure Recognition dataset (Bonn EEG, reshaped): 500 recordings x 23 one-second chunks. Every honest protocol is GROUPED by source recording (no recording spans train/test). Result (seizure vs rest, baseline 0.80): the optimized 5-feature band-power model reaches 0.96 accuracy / 0.92 balanced-accuracy under leakage-free grouped 5-fold CV (0.97/0.95 on a held-out grouped split) — a genuine out-of-sample win, in contrast to the eye-state null result. Two honest findings: feature engineering is the optimization (raw amplitude is at chance, bal-acc 0.53), and leakage doesn't help here (grouped ~= random-row) because summary-stat features carry no per-sample autocorrelation. Rename + extend the benchmark doc to cover both datasets.
…023 capstone) Add SegmentType::Model (profile-assigned 0x41) to the RVFS container, and ruv-neural-decoder/src/rvf_model.rs: model_to_container / container_to_model serialize a trained LogisticRegression into a MODEL + META segment. Combined with the existing Ed25519 sign_container/verify_container_signature, a model ships as one self-describing .rvf that is CRC/content-hash- and signature-checked before use. The train_seizure example now closes the loop end-to-end: train -> signed .rvf (832 bytes) -> reload -> verify integrity + signature -> the reloaded model reproduces the held-out accuracy exactly (0.9727). 3 new unit tests (container round-trip, signed verify + tamper-detect, missing-segment error); add the trainable-model and signed-model capabilities to the attestation matrix. 449 workspace tests pass.
Add ruv-neural-core/tests/rvf_fuzz.rs: proptest-driven fuzzing plus targeted adversarial cases for RvfContainer::from_bytes. Properties: never panics on arbitrary or magic-prefixed bytes; every built container round-trips and verifies; first-segment payload corruption is always caught by CRC32C or the content hash; truncation never panics. Targeted: bad magic, oversized/past-buffer payload_length, unknown segment type, truncated header, CRC-field tampering, empty-input-is-empty-container. 13 tests (proptest x256 cases each).
Add a model-lifecycle to the ruv-neural CLI: 'train' fits a logistic-regression classifier from a CSV/ARFF, reports honest holdout metrics (chronological by default; warns on shuffled leakage) and writes a self-signed RVF model; 'model-info' loads a .rvf and reports integrity (CRC32C+content-hash) and Ed25519 signature validity; 'predict' loads+verifies a model and scores feature rows, refusing a model with an invalid signature. Generic numeric-table parser (--skip-cols, --positive), dependency-free LCG shuffle, and a new core::rvf_witness::sign_container_ephemeral helper. 3 parse tests; verified end-to-end on the seizure dataset incl. payload-tamper rejection.
… (ADR-0014/0023) Add ruv-neural-wasm/src/rvf_wasm.rs: verify_rvf inspects a .rvf (segments, CRC32C+content-hash integrity, Ed25519 signature, model presence) and rvf_model_predict_proba/_label verify a signed model then score a feature row entirely client-side — no server round-trip. Pure *_inner logic is unit-tested on the host (5 tests: report, predict, tamper-reject, feature-count, garbage). Also fixes the previously-broken wasm32 build: enable getrandom's js feature for wasm32 so the core rand/ed25519 chain compiles. Verified 'cargo build --target wasm32-unknown-unknown' succeeds. 469 workspace tests pass.
Run rustfmt across the workspace and fix all non-needless_range_loop clippy lints (filter_map->map, clone->slice::from_ref, min/max->clamp, format!-in- println!, approx-PI test literals). needless_range_loop remains allow-listed in CI as idiomatic in the numerical code. No behavioural change; 469 tests still pass and the wasm32 build is unaffected.
Add .github/workflows/ci.yml with five jobs on push/PR: - fmt: cargo fmt --all --check - clippy: --workspace + the excluded wasm crate, -D warnings (needless_range_loop allow-listed as idiomatic in the numerical code) - test: workspace build + test (all targets, incl. examples/benches compile), doc tests, and host tests for the excluded wasm crate - fuzz: extended PROPTEST_CASES=4096 run of the RVF parser property tests - wasm: cargo build --target wasm32-unknown-unknown (guards the browser bindings) RUSTFLAGS=-D warnings denies warnings on our crates (deps capped to allow), concurrency cancels superseded runs, Swatinem/rust-cache speeds rebuilds. All five jobs verified green locally.
…ge caveat - README: adopt current main (open closed-loop OS for gamma-entrainment research); drops this branch's superseded 'Brain Network Topology / Applications' framing so the PR carries no conflicting README change. - benchmark doc + train_seizure.rs: clarify the seizure 'leakage-free' claim is *autocorrelation*-free (grouped by recording), NOT patient-independent — the reshaped CSV has no subject labels, so leave-subjects-out isn't possible. States the clinical gold standard honestly. Co-Authored-By: claude-flow <ruv@ruv.net>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Add eight Architecture Decision Records extending the closed-loop
neuromodulation ADR series into 2024–2026 state-of-the-art research,
applications, and emerging medical breakthroughs. Each records how rUv
Neural relates to a frontier while staying inside the ADR-0001 wellness
boundary, and carries a References section citing primary literature.
default stays the lightweight/edge-friendly embeddings — compact models
match/beat large EEG-FMs; FM inference-only behind a feature flag)
NWB/LSL/BIDS, never signal parity)
(aDBS/RNS are implanted Class III devices)
PCCP/GMLP, CA/CO/MT/CT neural-data laws, UNESCO, EU AI Act/GDPR)
Update the ADR index in 0000-template.md.