docs(gamma): add publication-ready secret-gist writeup (RuView + RuVector)

SEO-optimized, plain-English gist for RuView Gamma referencing the RuView and RuVector projects and branch claude/ruview-beyond-sota-xgv8aq: intro, how it works, supporting research with honest limits, usage (Rust + ESP32), cautions, advanced usages (trials/sham/cohort/HIL), credits, and an SEO FAQ. Includes the gh/curl commands to publish it as a SECRET gist with the user's own token (no token committed). https://claude.ai/code/session_01MjBucx95K4BuUxZi8NWwRH
2026-08-07 20:01:43 +00:00 · 2026-06-10 04:41:07 +00:00
parent 9744d367a2
commit d0cf36a0ba
1 changed files with 298 additions and 0 deletions
@@ -0,0 +1,298 @@
 <!--
  Publication-ready GitHub Gist. Publish as a SECRET gist with your own token:
    gh gist create --desc "RuView Gamma — adaptive sensory neuromodulation" \
      docs/research/ruview-beyond-sota/GAMMA-GIST.md
    # (omit --public for a secret/unlisted gist; gh uses your stored PAT/token)
  Or with curl + a fine-grained PAT that has the "gists" scope:
    curl -H "Authorization: Bearer $GH_TOKEN" \
      -X POST https://api.github.com/gists \
      -d '{"public":false,"files":{"ruview-gamma.md":{"content":"...">}}}'
  Do NOT paste the token into this file or any committed file.
  SEO meta description (use as the gist description):
  "RuView Gamma: an open, governed engine for adaptive 40 Hz light-and-sound
   neuromodulation — personalized entrainment with proof discipline, built on
   RuView WiFi sensing and RuVector learning. Research platform, not a medical
   device."
 -->
 # RuView Gamma — Adaptive Sensory Neuromodulation, Done Honestly
 > **TL;DR** — RuView Gamma is the open-source **control brain** for an adaptive
 > light-and-sound (40 Hz "gamma") neuromodulation device. It personalizes the
 > stimulation to each person, watches the body as feedback, learns what works,
 > and **refuses to advertise any benefit it hasn't measured**. The most valuable
 > thing here is not 40 Hz — it is a governed personalization engine that won't
 > overpromise.
 >
 > **Not a medical device. Not medical advice.** It is a research and engineering
 > platform. It makes no Alzheimer's, disease, or treatment claims.
 **Keywords:** gamma entrainment, 40 Hz stimulation, GENUS, sensory
 neuromodulation, WiFi sensing, adaptive personalization, Bayesian optimization,
 Rust, ESP32, digital therapeutics infrastructure, RuView, RuVector.
 **Projects:** [RuView](https://github.com/ruvnet/ruview) ·
 RuVector (vector learning / response modeling) ·
 Branch: `claude/ruview-beyond-sota-xgv8aq` ·
 Crate: `v2/crates/ruview-gamma` · Firmware: `firmware/esp32-gamma-stim` ·
 Decision record: `docs/adr/ADR-250-adaptive-gamma-entrainment.md`.
 ---
 ## 1. The easy introduction
 Research from MIT and others (the "GENUS" line of work) found that sitting in
 front of a light flickering ~40 times per second, with a matching pulsing
 sound, can drive a brain rhythm called **gamma** — studied for Alzheimer's,
 post-stroke recovery, sleep, focus, and mood.
 Today's devices play a **fixed 40 Hz to everyone**. But brains differ: your best
 frequency might be 38.5, 41.2, or somewhere else, and it changes with how calm,
 tired, or restless you are. There's no off-the-shelf software that personalizes
 this **safely and provably**.
 RuView Gamma is that software. Four parts work together:
 | Part | Role | Plain-English job |
 |------|------|-------------------|
 | **The device** | Actuator | Plays the light + sound |
 | **RuView** | Sensing | Reads the body as feedback (breathing, stillness, restlessness) over WiFi — no camera, no wearable |
 | **RuVector** | Learning | Builds a personal "response map" across sessions |
 | **RuFlo** | Governance | Safety stops, tamper-evident audit log, and the claim boundary |
 The thesis in one line: **RuView turns the body into the feedback signal,
 RuVector turns repeated sessions into a personal response map, the device is the
 actuator, and RuFlo makes the whole loop governed, measurable, and auditable.**
 ---
 ## 2. How it works
 ```
 enroll (consent + epilepsy/photosensitivity screen)
  → start from 40 Hz prior
  → play a short calibration sweep (36–44 Hz)
  → RuView reads body state each session
  → score "safe entrainment" (not raw gamma)
  → RuVector updates the personal response map
  → Bayesian optimizer recommends the next best safe setting
  → every session is witness-hashed into a tamper-evident log
 ```
 Key design choices that make it trustworthy:
 - **40 Hz is a starting guess, not the answer.** A Gaussian-process optimizer
  searches the safe 36–44 Hz band for *your* peak — and proves it can recover a
  known peak within ±1 Hz in tests.
 - **Safety is a hard gate, not a weighted preference.** A latched safety monitor
  stops on adverse symptoms, a stop request, or low sensor confidence — in about
  **9 nanoseconds** per check — and once it fires, the session **cannot silently
  resume**.
 - **A compiled-in safety envelope** (36–44 Hz, capped brightness/volume/
  duration) bounds everything. The optimizer can never widen it.
 - **Cross-person warm-start without identity.** A new user can be seeded from
  anonymized, one-way-hashed profiles of similar responders — but borrowed
  expectations are **down-weighted** and never counted as your measured data.
 - **Tamper-evident proof.** Every session produces a SHA-256 witness over
  exactly what was played and sensed. Re-running the same inputs reproduces the
  identical hash — a regulator, clinician, or trial auditor can verify nothing
  was fudged. The pinned reference witness is `13cb164c…`.
 ### The hard claim gate (the important part)
 A program may surface a benefit claim **only** if all four pass:
 ```
 claim_allowed = entrainment_pass AND safety_pass
             AND adherence_pass  AND repeatability_pass
 ```
 Anything less returns `research use only — no claim`. The marketing claim is
 literally unreadable in the code except through this gate.
 ### It's a platform, not one gadget
 Seven programs ship, each with its own safety envelope, objective, state-gating,
 evidence level, and a single non-disease claim:
 | Program | Evidence | What it tunes for |
 |---------|----------|-------------------|
 | Alzheimer's research | medium preclinical / early human | entrainment + trial monitoring |
 | Post-stroke cognition | early human | gentle, recovery-state tracking |
 | Sleep optimization | early/plausible | audio-only, near-dark, timed to sleep state |
 | Attention / working memory | mixed | personal frequency discovery |
 | Mood / arousal | early human | calming response, avoid overstimulation |
 | Home wellness | speculative | safe personalization, no treatment claim |
 | Drug + device trial infra | strong (as infrastructure) | governed, reproducible measurement |
 ---
 ## 3. Research supporting it (and its honest limits)
 - **Preclinical (strongest):** a 2024 *Nature* paper showed 40 Hz multisensory
  stimulation promoted cerebrospinal-fluid influx and amyloid clearance via the
  glymphatic system in Alzheimer's-model mice; blocking that clearance abolished
  the effect.
 - **Early human:** a 2022 study found 40 Hz sensory stimulation feasible and
  well-tolerated in mild Alzheimer's, with exploratory signals on structure,
  connectivity, sleep, and memory. A small 2025 two-year pilot reported safety
  and feasibility, but the sample was tiny and not definitive.
 - **Frequency is not one-size-fits-all:** a 2025 *PLOS One* study re-evaluated
  gamma frequency across 36–44 Hz — direct motivation for *measuring* the
  individual's frequency rather than assuming 40 Hz.
 - **Adjacent areas (early/mixed):** post-stroke cognition, sleep (40 Hz evoked
  without degrading sleep), attention/working-memory (mixed, protocol-dependent),
  and mood/arousal.
 **Honest limits, encoded as non-goals:** RF sensing does not measure amyloid;
 personalized frequency improving clinical outcomes is unproven; consumer use
 without screening is not safe; 40 Hz is not always optimal. The software makes
 none of these claims.
 ---
 ## 4. How to use it
 ### Run the governed engine (Rust)
 ```bash
 git clone https://github.com/ruvnet/ruview
 cd ruview && git checkout claude/ruview-beyond-sota-xgv8aq
 cd v2
 cargo test -p ruview-gamma --no-default-features      # 97 tests + 1 doctest
 cargo bench -p ruview-gamma --no-default-features      # criterion micro-benchmarks
 ```
 ```rust
 use ruview_gamma::{
    ruflo::{Consent, RufloGovernor},
    program::NeuroProgram,
    response::RuViewState,
    simulator::{LatentPerson, ResponseSimulator},
    stimulus::StimulusParameters,
 };
 let mut gov = RufloGovernor::enroll_program(
    "subject-001", NeuroProgram::sleep_optimization(), &[], Consent::Granted,
 ).expect("cleared to participate");
 let sim = ResponseSimulator::new(42);          // deterministic stand-in for hardware
 let latent = LatentPerson::from_id("subject-001");
 let state = RuViewState::calm_baseline();
 gov.run_calibration(&sim, &latent, &state, 5.0, 0).unwrap();
 let rec = gov.recommend(&gov.prior());          // always inside the safety envelope
 ```
 ### Run the device (ESP32)
 ```bash
 cd firmware/esp32-gamma-stim
 # Host-side safety-core tests — no hardware, no ESP-IDF:
 gcc -Wall -Wextra -Werror -O2 -I main tests/test_stim_core.c main/stim_core.c -o /tmp/t && /tmp/t
 # On hardware (ESP-IDF v5.2+):
 idf.py set-target esp32s3 && idf.py build flash monitor
 ```
 Serial protocol (frequency in millihertz, so 40.0 Hz = `40000`):
 ```
 START 40000 30 28 600   # 40 Hz, 30% brightness, 28% volume, 10 min
 STOP | STATUS | UNLOCK | VERSION
 ```
 ### Benchmarks (indicative)
 | Path | Time | Role |
 |------|------|------|
 | Safety tick | ~8 ns | real-time stop path |
 | Recommendation | ~15 µs | per-session decision |
 | Cohort kNN (500 profiles) | ~15 µs | warm-start matching |
 | Calibration sweep | ~115 µs | setup/tuning |
 | Full acceptance grading | ~425 µs | enrollment only |
 ---
 ## 5. Cautions (read these)
 - ⚠️ **Flicker can trigger seizures.** Epilepsy and photosensitivity are **hard
  exclusions** in software; a hardware e-stop is mandatory for any human-facing
  run. Migraine/psychiatric instability/implanted neuro devices require
  clinical supervision.
 - ⚠️ **Not a treatment.** No Alzheimer's/disease/efficacy claim. The only
  product claim is "personalized entrainment optimization," and even that is
  gated behind measured entrainment + safety + adherence + repeatability.
 - ⚠️ **No hardware actuation in the core crate.** The Rust crate is a validated
  decision/safety/learning/audit engine tested against a simulator; the ESP32
  firmware is the actuator. Real EEG validation is a separate, deferred step.
 - ⚠️ **Optical safety is the integrator's job.** The firmware caps PWM duty, but
  absolute luminance/eye-safety belongs to the LED driver and optical design.
 - ⚠️ **Research/IRB context required** for any study with human subjects,
  especially clinical populations.
 ---
 ## 6. Advanced usages
 - **Drug + device trials (strongest near-term use):** use RuFlo as the governed
  measurement layer — consent, inclusion/exclusion, **sham/blinding**, per-session
  witness hashes, and clinician export — to make *someone else's* therapy trial
  auditable and reproducible. The value is the instrument, not a therapy claim.
 - **Sham-controlled studies:** `TrialMode::Sham` logs the participant-facing
  protocol while delivering no entrainment, for blinded arms.
 - **Cohort transfer learning:** export anonymized response profiles and
  warm-start new participants via RuVector kNN — privacy-preserving, one-way
  hashed, never identity-bearing.
 - **Drift-triggered recalibration:** a Welford-centroid drift detector flags when
  a person's physiology has shifted enough to warrant re-running calibration.
 - **Hardware-in-the-loop acceptance:** capture LED frequency, A/V sync, and stop
  latency on the bench and grade them with `hil::verify_hil` against fixed
  targets (±0.1 Hz, <5 ms, <100 ms, 100% hash reproducibility, ≥20% EEG lift).
 - **Edge deployment:** the engine is dependency-light and deterministic; an HNSW
  (RuVector) backend drops in for cohort search past ~10⁵ profiles.
 ---
 ## 7. Credits
 - **RuView** — WiFi/RF human sensing platform that supplies the passive body
  feedback signal. https://github.com/ruvnet/ruview
 - **RuVector** — vector learning / response-curve modeling (cohort warm-start,
  drift detection, clustering; HNSW-ready).
 - **RuFlo** — governance, audit, consent, and protocol execution layer.
 - Built by the RuView contributors on branch
  `claude/ruview-beyond-sota-xgv8aq`. Decision record: ADR-250.
 - Scientific inspiration: the GENUS / 40 Hz gamma-entrainment research community
  (MIT Tsai/Boyden labs and others). This project implements *engineering and
  governance*, not their clinical findings.
 ---
 ## 8. FAQ (SEO)
 **What is gamma entrainment?** Driving ~40 Hz brain rhythms with rhythmic light
 and/or sound. RuView Gamma personalizes the exact frequency per person.
 **Is RuView Gamma a medical device?** No. It is an open research and engineering
 platform that makes no treatment or disease claims.
 **Does it cure or treat Alzheimer's?** No. It optimizes and audits stimulation
 protocols; clinical outcomes are explicitly out of scope.
 **Can I run it on an ESP32?** Yes — `firmware/esp32-gamma-stim` drives the LED +
 audio flicker with a hardware emergency stop and a compiled-in safety envelope.
 **Why is it "honest"?** A program's benefit claim is unreadable in code until it
 passes measured entrainment, safety, adherence, and repeatability.
 **License / source:** see the RuView repository, branch
 `claude/ruview-beyond-sota-xgv8aq`.
 ---
 *RuView Gamma — personalized neural-rhythm optimization with tamper-evident
 proof. Not a medical claim. Not a consumer miracle device. A tested, safety-first
 engine ready for hardware, EEG validation, and serious clinical research.*