Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
6 changes: 3 additions & 3 deletions Evaluation/reports/decision_registry.md
Original file line number Diff line number Diff line change
Expand Up @@ -105,9 +105,9 @@ Each entry:
### 10. Biofeedback egress (ADR-011) : scoped network-egress exception, derived features only

- **Decision:** A new `BCIBiofeedback` target may emit EEG-derived features (per-channel band powers in Bels, per-channel health, Track A blink/clench events, IMU) over two transports: a CoreMIDI virtual source (in-machine, not network) and OSC/UDP to a user-chosen host, loopback `127.0.0.1:7000` by default. This is a deliberate exception to the "No network at runtime" invariant (CLAUDE.md line 3 / PRINCIPLES.md Principle 5) alongside entries 8 (`BCICloudBridge`) and 9 (`BCIPeerBridge`), and the only one that carries EEG-derived numbers. Accepted 2026-11-07; status follows ADR-011.
- **Evidence / rationale:** (a) The inbound half of the Muse-to-DAW chain already exists (`MindMonitorOSCStream`, ADR-004); the outbound half is what makes NeuralCompose usable as an open biofeedback instrument alongside Mind Monitor + Muse Port. (b) The egress is **tightly scoped**: one target, dependencies `BCICore` + `BCIEEG` only, imported only by `NeuralComposeApp`, never a dependency of another `BCI*` target. (c) **Raw EEG never reaches a frame**: the egress boundary is `BiofeedbackFrame`, a function of band powers, health, events and IMU; raw `/muse/eeg` re-broadcast is a separate explicit toggle through the one named helper `MindMonitorMirror.rawEEG(_:)`. (d) **Health gating is mandatory**: every `BiofeedbackMapping` carries a `HealthPolicy` (default `holdLast`); Mind Monitor's behaviour is available only as the explicit `passthrough` policy. (e) **Deterministic**: pure-Swift periodogram and a clock-free mapper, so a recording through a mapping set yields byte-identical outputs for the replay regression. (f) Off by default; while off the app wires `NullBiofeedbackSink`. (g) No third-party dependency; Network and CoreMIDI are system frameworks behind `canImport`.
- **Evidence / rationale:** (a) The inbound half of the Muse-to-DAW chain already exists (`MindMonitorOSCStream`, ADR-004); the outbound half is what makes NeuralCompose usable as an open biofeedback instrument alongside Mind Monitor + Muse Port. (b) The egress is **tightly scoped**: one target, dependencies `BCICore` + `BCIEEG` only, imported only by `NeuralComposeApp`, never a dependency of another `BCI*` target. (c) **Raw EEG never reaches a frame**: the egress boundary is `BiofeedbackFrame`, a function of band powers, health, events and IMU; raw `/muse/eeg` re-broadcast is a separate explicit toggle through the one named helper `MindMonitorMirror.rawEEG(_:)`. (d) **Health gating is mandatory**: every `BiofeedbackMapping` carries a `HealthPolicy` (default `holdLast`); Mind Monitor's behaviour is available only as the explicit `passthrough` policy. (e) **Deterministic**: pure-Swift periodogram and a clock-free mapper, so a recording through a mapping set yields byte-identical outputs for the replay regression. (f) Off by default; while off the app constructs no coordinator and no sink (`AppContainer.biofeedback == nil`; amended 2026-11-07 with the PR 2 wiring, which replaced the earlier null-sink wording). (g) No third-party dependency; Network and CoreMIDI are system frameworks behind `canImport`.
- **Scope guard - what this does NOT do:** it does **not** touch `BCICloudBridge` or `BCIPeerBridge` or widen entries 8 and 9; cloud egress stays exclusively in `BCICloudBridge`. It adds no HTTP client. It does not enable macOS Network MIDI (an OS feature the user controls in Audio MIDI Setup). It does not expose World Model or Laya latents as features; that waits for a benchmarked encoder and its own amendment. The `MindMonitorMirror` compatibility output is ungated by design and says so; gating is the mapper's job.
- **Supporting benchmark(s):** `Tests/BCIBiofeedbackTests/BandPowerEstimatorTests.swift` (A^2/2 physical-unit checks, FFT vs naive DFT), `FeatureMapperTests.swift` (all four health policies, smoothing, rate limit, MIDI quantisation, note gates, determinism), `MindMonitorMirrorTests.swift` (address scheme, payload shapes, bundle round trip through `MuseOSCDecoder`), `Tests/BCIEEGTests/OSCEncoderTests.swift`. Golden-recording replay fixture is a follow-up issue and gates live validation.
- **Confidence:** High for the egress core: the design is isolated and all 64 unit tests across `BCIBiofeedbackTests` and `OSCEncoderTests` (including `OSCUDPSender` and `CoreMIDIVirtualSource` compilation) compiled and passed on M4 under Swift 6.0; the `AppContainer` wiring, settings and privacy-indicator strings are follow-up PRs.
- **Status:** Accepted. Network egress of derived features is possible **exclusively** through `BCIBiofeedback` once wired and enabled; raw EEG egress only through the explicit raw toggle; the invariant otherwise stands.
<!-- Last updated: 2026-11-07T08:45:00-06:00 (entry 10: ADR-011 biofeedback egress - accepted, 64/64 tests green on M4) -->
- **Status:** Accepted. Network egress of derived features is possible **exclusively** through `BCIBiofeedback` once wired and enabled; raw EEG egress only through the explicit raw toggle; the invariant otherwise stands. PR 2 (2026-11-07) wired the coordinator into `AppContainer`/`AppViewModel` behind `NEURALCOMPOSE_BIOFEEDBACK_*` env vars: the raw window (pre-substitution) feeds frames, the classifier tick feeds events, the privacy indicator names the tier. Live DAW acceptance (issues 3 and 4) still pending.
<!-- Last updated: 2026-11-07T16:30:00-06:00 (entry 10: PR 2 wiring; coordinator nil while off; env-var configuration; indicator badge) -->
4 changes: 2 additions & 2 deletions Package.swift
Original file line number Diff line number Diff line change
Expand Up @@ -208,7 +208,7 @@ let package = Package(
// ── Application ──────────────────────────────────────────────────
.executableTarget(
name: "NeuralComposeApp",
dependencies: ["BCICore", "BCIEEG", "BCIBridge", "BCIClassifier", "BCILLM", "BCIVoice", "BCICloudBridge", "BCIPeerBridge", "WorldModelDemo"],
dependencies: ["BCICore", "BCIEEG", "BCIBridge", "BCIClassifier", "BCILLM", "BCIVoice", "BCICloudBridge", "BCIPeerBridge", "BCIBiofeedback", "WorldModelDemo"],
path: "Sources/NeuralComposeApp",
// Info.plist lives in Resources/ for reference / Xcode builds but
// is intentionally NOT declared as a SwiftPM resource: SwiftPM
Expand Down Expand Up @@ -402,7 +402,7 @@ let package = Package(
),
.testTarget(
name: "NeuralComposeAppTests",
dependencies: ["NeuralComposeApp", "BCICore", "BCIEEG", "BCIClassifier", "BCILLM", "BCIVoice", "BCIPeerBridge", "BCICloudBridge"],
dependencies: ["NeuralComposeApp", "BCICore", "BCIEEG", "BCIClassifier", "BCILLM", "BCIVoice", "BCIPeerBridge", "BCICloudBridge", "BCIBiofeedback"],
path: "Tests/NeuralComposeAppTests"
),
],
Expand Down
86 changes: 86 additions & 0 deletions Scripts/run-biofeedback-osc.sh
Original file line number Diff line number Diff line change
@@ -0,0 +1,86 @@
#!/usr/bin/env bash
#
# run-biofeedback-osc.sh - launch NeuralCompose with the biofeedback egress
# on (ADR-011, decision registry entry 10): Mind Monitor-compatible OSC and,
# optionally, a CoreMIDI virtual source, driven by whatever EEG source the
# app is configured for.
#
# What leaves the process is derived features only: per-channel band powers
# (Bels), per-channel contact quality (horseshoe), Track A blink and jaw
# clench events, and IMU readings when the transport has them. Raw EEG is
# never sent unless you pass --raw-eeg, and then only over OSC.
#
# Defaults send to 127.0.0.1:7000, which never leaves this Mac and is the
# port the Muse Port Max for Live device listens on. Any other --host is a
# LAN destination: OSC has no authentication or encryption, so keep that on
# a private network and expect the privacy indicator to show it in red.
#
# Usage:
# ./Scripts/run-biofeedback-osc.sh # synthetic EEG -> OSC loopback 7000 (dry run, no hardware)
# ./Scripts/run-biofeedback-osc.sh --board muses # live Muse S over BLE
# ./Scripts/run-biofeedback-osc.sh --board osc --port 7000 # Mind Monitor in (UDP 5000) -> features out (7000)
# ./Scripts/run-biofeedback-osc.sh --host 192.168.1.20 # send to another machine on the LAN
# ./Scripts/run-biofeedback-osc.sh --midi # also create the "NeuralCompose Biofeedback" MIDI source
# ./Scripts/run-biofeedback-osc.sh --per-channel # 4 floats per band instead of 1 average
# ./Scripts/run-biofeedback-osc.sh --mappings ~/maps.json # load a [BiofeedbackMapping] JSON set
# ./Scripts/run-biofeedback-osc.sh --raw-eeg # explicit raw /muse/eeg re-broadcast
#
# Then point your consumer at the port: Muse Port's UDP port field, Max's
# [udpreceive 7000], TouchDesigner's OSC In CHOP, SuperCollider's
# OSCFunc on NetAddr("127.0.0.1", 7000), or Bitwig's OSC input.
#
set -euo pipefail

REPO_ROOT="$(cd "$(dirname "$0")/.." && pwd)"
cd "$REPO_ROOT"

HOST="127.0.0.1"
PORT="7000"
BOARD="${NEURALCOMPOSE_BOARD_PROFILE:-synthetic}"
MIDI="0"
RAW="0"
PER_CHANNEL="0"
MAPPINGS=""

while [[ $# -gt 0 ]]; do
case "$1" in
--host) HOST="$2"; shift 2 ;;
--port) PORT="$2"; shift 2 ;;
--board) BOARD="$2"; shift 2 ;;
--midi) MIDI="1"; shift ;;
--raw-eeg) RAW="1"; shift ;;
--per-channel) PER_CHANNEL="1"; shift ;;
--mappings) MAPPINGS="$2"; shift 2 ;;
-h|--help)
grep '^#' "$0" | sed 's/^# \{0,1\}//'
exit 0 ;;
*)
echo "Unknown argument: $1" >&2; exit 1 ;;
esac
done

export NEURALCOMPOSE_BOARD_PROFILE="$BOARD"
export NEURALCOMPOSE_BIOFEEDBACK_OSC="${HOST}:${PORT}"
export NEURALCOMPOSE_BIOFEEDBACK_MIDI="$MIDI"
export NEURALCOMPOSE_BIOFEEDBACK_RAW_EEG="$RAW"
export NEURALCOMPOSE_BIOFEEDBACK_PER_CHANNEL="$PER_CHANNEL"
if [[ -n "$MAPPINGS" ]]; then
export NEURALCOMPOSE_BIOFEEDBACK_MAPPINGS="$MAPPINGS"
fi

TIER="loopback (never leaves this Mac)"
case "$HOST" in
127.0.0.1|localhost|::1) ;;
*) TIER="LAN host (unauthenticated UDP; private network only)" ;;
esac

echo "EEG source: $BOARD"
echo "OSC egress: ${HOST}:${PORT} [$TIER]"
echo "MIDI egress: $([[ "$MIDI" == "1" ]] && echo 'virtual source "NeuralCompose Biofeedback"' || echo off)"
echo "Band payload: $([[ "$PER_CHANNEL" == "1" ]] && echo '4 floats per band (per channel)' || echo '1 float per band (average over healthy channels)')"
echo "Raw /muse/eeg: $([[ "$RAW" == "1" ]] && echo 'ON (explicit)' || echo off)"
if [[ -n "$MAPPINGS" ]]; then echo "Mappings: $MAPPINGS"; fi
echo "Derived features only; health-gated mappings per ADR-011."
echo

exec swift run -c debug NeuralCompose
Loading
Loading