From f6014b55261f35f56380872e8a63e489ce629098 Mon Sep 17 00:00:00 2001 From: ruv Date: Mon, 3 Aug 2026 21:34:59 -0400 Subject: [PATCH] docs: document the NeuroSleep ingestion rail and refresh stale counts MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The README described neither the NeuroSleep work nor the crates it added, and its headline counts had drifted: it claimed 22 crates, 153 tests and 30 ADRs against an actual 31, 232 and 43. The new entry in "What's built" states the properties that are enforced rather than asserted — only signed derived features are accepted, Helix verifies the signature itself against a separately enrolled key so a bundle carrying its own trust root is rejected, interpretation abstains below the compatible-night floor, and the research visualisation is a physically separate WASM artifact whose entire dependency tree is serde and serde_json. The closing discipline paragraph is extended because "nothing diagnoses" is now checked by a build gate rather than left as a promise, and because the preclinical limit belongs next to the claim it constrains: these features come from an APP/PS1 mouse study, numeric parity is unproven, and that is why the upstream contract is pinned at an exact alpha and the first deployment is an offline research build. The prohibited-claim gate now scans README.md as well. It is the most public surface here, so an overclaim in it would reach more readers than one inside a crate, and it was the obvious omission once the README started describing this rail. Verified by negative control: an injected "Alzheimer risk is elevated" line makes the gate exit 1. --- README.md | 22 ++++++++++++++++++- .../neurosleep/check_forbidden_claims.sh | 4 ++++ 2 files changed, 25 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index 58b763e..8765427 100644 --- a/README.md +++ b/README.md @@ -63,7 +63,7 @@ and **clinical safety** ([ADR-009](docs/adr/ADR-009-red-flag-escalation-clinicia This is no longer just a spec — the testable core is implemented in Rust and validated. -- **22 crates · 153 tests · 30 ADRs** · clippy/fmt clean · `cargo audit` clean. +- **31 crates · 232 tests · 43 ADRs** · clippy/fmt clean · `cargo audit` and `cargo deny` clean. - **Anti-hallucination core**: provenance grounding (`helix-provenance`), deterministic numerics (`helix-numeric`), evidence tiering (`helix-evidence`), red-flag escalation (`helix-escalation`), verifier (`helix-verifier`), the grounded-answer pipeline @@ -79,11 +79,31 @@ This is no longer just a spec — the testable core is implemented in Rust and v fail-closed `helix-openmed` Rust/WASM gate with artifact pinning, complete-document coverage, deterministic identifier rules, Unicode-safe offsets, and HMAC-only receipts. See the [integration guide](docs/openmed-integration.md). +- **Verified NeuroSleep qEEG research ingestion** (`helix-neurosleep`): accepts only + signed derived nightly features from rUv Neural — never raw EEG — and verifies the + signature itself against a separately enrolled key, so a bundle carrying its own + trust root is rejected. Consent, study/subject binding, replay protection, and atomic + sealing under participant-opaque identifiers all sit on that path. Interpretation + abstains below the compatible-night floor rather than showing a provisional trend, + and nights recorded with incompatible methods are never pooled. The research + visualisation is a **physically separate** WASM artifact (`helix-neurosleep-wasm`) + whose entire dependency tree is `serde` + `serde_json` — it links no attestation or + key-custody code at all. All four research flags default to off. + See [ADR-051](docs/validation/ADR-051-requirement-evidence.md). - **Web console + WASM mobile app** running the real pipeline in-browser — **[live demo](https://ruvnet.github.io/helix/)**. Every integration keeps the discipline: the LLM narrates (never reasons), embeddings/visual are recall (not grounding), genomics/cohort data is privacy-gated, and nothing diagnoses. +That last point is enforced, not just stated. A fail-closed static gate fails the build if +diagnostic or therapeutic language appears in the NeuroSleep crates or their UI, and a second +gate rejects any dependency from that rail onto the score, Focus Area, escalation, LLM, +retrieval, or actuation crates. The NeuroSleep features are associated with a **preclinical +APP/PS1 mouse study** and are not a validated human clinical marker: nothing estimates +Alzheimer's disease, amyloid burden, or microglial activity. Numeric parity with the reference +implementation is still unproven, which is why the upstream contract is pinned at an exact +alpha (`ruv-neural-core =0.2.0-alpha.1`) and the first deployment is an offline research build. + ## Status **v0.1.0 — implemented core, Proposed ADRs.** The Rust core is built, tested, and diff --git a/validation/neurosleep/check_forbidden_claims.sh b/validation/neurosleep/check_forbidden_claims.sh index 2c51e99..4c503e8 100755 --- a/validation/neurosleep/check_forbidden_claims.sh +++ b/validation/neurosleep/check_forbidden_claims.sh @@ -19,6 +19,10 @@ targets=() # The research WASM crate holds the user-facing measurement label and caveat # copy, so it must be scanned alongside the native crate. [[ -d crates/helix-neurosleep-wasm ]] && targets+=(crates/helix-neurosleep-wasm) +# The README is the most public surface this project has. It now describes the +# NeuroSleep rail, so an overclaim there would reach more readers than one +# buried in a crate. +[[ -f README.md ]] && targets+=(README.md) while IFS= read -r file; do targets+=("$file") done < <(find ui -maxdepth 2 -type f -iname '*neurosleep*' -print 2>/dev/null | sort)