diff --git a/Evaluation/reports/decision_registry.md b/Evaluation/reports/decision_registry.md index ff76d57..4a6cdb9 100644 --- a/Evaluation/reports/decision_registry.md +++ b/Evaluation/reports/decision_registry.md @@ -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. - +- **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. + diff --git a/Package.swift b/Package.swift index 355abe1..3a27b58 100644 --- a/Package.swift +++ b/Package.swift @@ -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 @@ -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" ), ], diff --git a/Scripts/run-biofeedback-osc.sh b/Scripts/run-biofeedback-osc.sh new file mode 100755 index 0000000..3188289 --- /dev/null +++ b/Scripts/run-biofeedback-osc.sh @@ -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 diff --git a/Sources/BCIBiofeedback/BiofeedbackCoordinator.swift b/Sources/BCIBiofeedback/BiofeedbackCoordinator.swift new file mode 100644 index 0000000..d30c259 --- /dev/null +++ b/Sources/BCIBiofeedback/BiofeedbackCoordinator.swift @@ -0,0 +1,237 @@ +import Foundation +import BCICore +import BCIEEG + +/// Glue between the live pipeline and the egress. The app owns exactly one +/// of these when biofeedback is enabled (`AppContainer.biofeedback`) and +/// none when it is not; it is the only type that holds a `FeatureMapper` +/// and a `BiofeedbackSink` together. +/// +/// Four inputs, each from the pipeline stage that already produces it, so +/// nothing is re-detected here: +/// +/// - `ingest(window:)` takes the **raw** window from the windowing stage, +/// before `substituteBadChannels` runs. That matters: the cleaned window +/// has a lifted electrode overwritten with its contralateral partner, +/// which would hide the bad contact from both the horseshoe and the +/// mapper's `HealthPolicy`. Health is computed here from the raw window +/// unless the caller passes provider states. +/// - `note(intent:at:)` takes the Track A classifier's decision for the +/// window it just classified. Events (blink, jaw clench) are emitted on +/// that tick rather than attached to the next window, so a blink reaches +/// the DAW with classifier latency, not one stride of lag. +/// - `ingest(movement:)` caches the latest accelerometer and gyroscope +/// readings for the next window's frame. +/// - `ingest(sample:)` is the raw EEG re-broadcast. It is a no-op unless +/// `Options.includeRawEEG` is on, and it is the single call site of +/// `MindMonitorMirror.rawEEG(_:)` in the app's runtime path (ADR-011). +/// +/// Mappings are split by feature: `.blink` and `.jawClench` mappings run on +/// intent ticks, everything else runs on window ticks. Each half has its +/// own `FeatureMapper`, so a window tick never double-emits band mappings +/// and an event tick never re-sends the mirror's band messages. +public actor BiofeedbackCoordinator { + + public struct Options: Sendable { + /// Mind Monitor-compatible output; `nil` disables the mirror and + /// leaves only the user's mappings. + public var mirror: MindMonitorMirror? + /// Raw `/muse/eeg` re-broadcast. Off by default; see ADR-011 §2. + public var includeRawEEG: Bool + public var thresholds: ChannelHealthThresholds + public var estimator: BandPowerEstimator + /// Row-to-channel assignment for incoming windows. + public var channels: [EEGChannel] + + public init( + mirror: MindMonitorMirror? = MindMonitorMirror(), + includeRawEEG: Bool = false, + thresholds: ChannelHealthThresholds = .default, + estimator: BandPowerEstimator = BandPowerEstimator(), + channels: [EEGChannel] = EEGChannel.allCases + ) { + self.mirror = mirror + self.includeRawEEG = includeRawEEG + self.thresholds = thresholds + self.estimator = estimator + self.channels = channels + } + } + + public let options: Options + private let sink: any BiofeedbackSink + private var continuous: FeatureMapper + private var events: FeatureMapper + private var latestAccel: MovementSample? + private var latestGyro: MovementSample? + private var lastFrame: BiofeedbackFrame? + + /// Windows ingested so far (diagnostics and tests). + public private(set) var windowCount = 0 + /// Intent ticks that carried a blink or clench (diagnostics and tests). + public private(set) var eventCount = 0 + + public init( + sink: any BiofeedbackSink, + mappings: [BiofeedbackMapping] = [], + options: Options = Options() + ) { + self.sink = sink + self.options = options + let split = BiofeedbackCoordinator.split(mappings) + self.continuous = FeatureMapper(mappings: split.continuous) + self.events = FeatureMapper(mappings: split.events) + } + + /// Whether `ingest(sample:)` does anything. Read without an actor hop + /// so the 256 Hz sample loop can skip the call entirely when off. + public nonisolated var includesRawEEG: Bool { + options.includeRawEEG + } + + /// All mappings, continuous first then event mappings. + public var mappings: [BiofeedbackMapping] { + continuous.mappings + events.mappings + } + + /// Replace the mapping set; smoother state survives for surviving ids + /// (see `FeatureMapper.replaceMappings`). + public func replaceMappings(_ mappings: [BiofeedbackMapping]) { + let split = BiofeedbackCoordinator.split(mappings) + continuous.replaceMappings(split.continuous) + events.replaceMappings(split.events) + } + + /// Window tick. `health` overrides the raw-window estimate when the + /// caller has provider states (which can carry `.stale`); otherwise + /// per-channel demeaned RMS against `options.thresholds`. + public func ingest(window: EEGWindow, health: [ChannelHealthState]? = nil) async { + let states = health ?? BiofeedbackCoordinator.channelHealth( + for: window, channels: options.channels, thresholds: options.thresholds + ) + let frame = BiofeedbackFrame( + window: window, + channels: options.channels, + health: states, + intent: nil, + accel: latestAccel, + gyro: latestGyro, + estimator: options.estimator + ) + lastFrame = frame + windowCount += 1 + + var outputs: [BiofeedbackOutput] = [] + if let mirror = options.mirror { + outputs += mirror.messages(for: frame).map { .osc($0) } + } + outputs += continuous.step(frame) + if !outputs.isEmpty { + await sink.emit(outputs) + } + } + + /// Classifier tick. Builds an event frame on top of the last window's + /// band powers and health, runs the event mappings and, when the mirror + /// is on, the two Mind Monitor event messages. Called for every + /// classified window, including `.rest`, so open note gates close. + public func note(intent: IntentClass, at timestamp: TimeInterval) async { + let blink: Bool + let jawClench: Bool + switch intent { + case .singleBlink, .doubleBlink: + blink = true + jawClench = false + case .jawClench: + blink = false + jawClench = true + case .rest, .select: + blink = false + jawClench = false + } + + let frame = BiofeedbackFrame( + timestamp: timestamp, + bandPowers: lastFrame?.bandPowers ?? [:], + health: lastFrame?.health ?? [:], + blink: blink, + jawClench: jawClench, + accel: latestAccel, + gyro: latestGyro + ) + if blink || jawClench { eventCount += 1 } + + var outputs: [BiofeedbackOutput] = [] + if options.mirror != nil { + outputs += MindMonitorMirror.eventMessages(blink: blink, jawClench: jawClench).map { .osc($0) } + } + outputs += events.step(frame) + if !outputs.isEmpty { + await sink.emit(outputs) + } + } + + /// IMU tick. Cached; forwarded with the next window frame. + public func ingest(movement: MovementSample) { + switch movement.kind { + case .accel: latestAccel = movement + case .gyro: latestGyro = movement + } + } + + /// Raw EEG re-broadcast. No-op unless `options.includeRawEEG`. + public func ingest(sample: EEGSample) async { + guard options.includeRawEEG else { return } + await sink.emit([.osc(MindMonitorMirror.rawEEG(sample))]) + } + + /// Per-channel health from a raw window: demeaned RMS in Double against + /// `thresholds`. A channel with any non-finite sample reads `.unknown` + /// with an RMS of 0 rather than poisoning the estimate. Mirrors the + /// arithmetic of `AppViewModel.signalQuality(of:)` but keeps the + /// per-channel result instead of bucketing to one quality. + public static func channelHealth( + for window: EEGWindow, + channels: [EEGChannel] = EEGChannel.allCases, + thresholds: ChannelHealthThresholds = .default + ) -> [ChannelHealthState] { + var states: [ChannelHealthState] = [] + for (index, channel) in channels.enumerated() where index < window.samples.count { + let samples = window.samples[index] + let n = samples.count + guard n > 0, samples.allSatisfy(\.isFinite) else { + states.append(ChannelHealthState(channel: channel, status: .unknown, rms: 0, samples: n, timestamp: window.endTimestamp)) + continue + } + var mean = 0.0 + for v in samples { mean += Double(v) } + mean /= Double(n) + var sumSq = 0.0 + for v in samples { + let d = Double(v) - mean + sumSq += d * d + } + let rms = Float((sumSq / Double(n)).squareRoot()) + states.append(ChannelHealthState( + channel: channel, + status: thresholds.status(forRMS: rms, samples: n), + rms: rms, + samples: n, + timestamp: window.endTimestamp + )) + } + return states + } + + private static func split(_ mappings: [BiofeedbackMapping]) -> (continuous: [BiofeedbackMapping], events: [BiofeedbackMapping]) { + var continuous: [BiofeedbackMapping] = [] + var events: [BiofeedbackMapping] = [] + for mapping in mappings { + switch mapping.feature { + case .blink, .jawClench: events.append(mapping) + default: continuous.append(mapping) + } + } + return (continuous, events) + } +} diff --git a/Sources/BCIBiofeedback/MindMonitorMirror.swift b/Sources/BCIBiofeedback/MindMonitorMirror.swift index 054a808..6ce0f2a 100644 --- a/Sources/BCIBiofeedback/MindMonitorMirror.swift +++ b/Sources/BCIBiofeedback/MindMonitorMirror.swift @@ -92,12 +92,7 @@ public struct MindMonitorMirror: Sendable, Hashable, Codable { arguments: MindMonitorMirror.channelOrder.map { .float(MindMonitorMirror.horseshoe(frame.status(of: $0))) } )) - if frame.blink { - messages.append(OSCMessage(address: MindMonitorMirror.blinkAddress, arguments: [.int32(1)])) - } - if frame.jawClench { - messages.append(OSCMessage(address: MindMonitorMirror.jawClenchAddress, arguments: [.int32(1)])) - } + messages += MindMonitorMirror.eventMessages(blink: frame.blink, jawClench: frame.jawClench) if let accel = frame.accel { messages.append(OSCMessage(address: MindMonitorMirror.accelAddress, arguments: [.float(accel.x), .float(accel.y), .float(accel.z)])) } @@ -107,6 +102,22 @@ public struct MindMonitorMirror: Sendable, Hashable, Codable { return messages } + /// The two Track A event messages, sent only when true, in Mind Monitor's + /// shape (one int32 of 1). Split out from `messages(for:)` so + /// `BiofeedbackCoordinator` can emit events on the classifier's tick + /// without re-sending the band and horseshoe messages of the window + /// that preceded it. + public static func eventMessages(blink: Bool, jawClench: Bool) -> [OSCMessage] { + var messages: [OSCMessage] = [] + if blink { + messages.append(OSCMessage(address: blinkAddress, arguments: [.int32(1)])) + } + if jawClench { + messages.append(OSCMessage(address: jawClenchAddress, arguments: [.int32(1)])) + } + return messages + } + /// Raw EEG re-broadcast in Mind Monitor's `/muse/eeg` format: one /// float per channel in microvolts. Only the explicit raw toggle in /// the egress configuration should call this; see ADR-011. diff --git a/Sources/NeuralComposeApp/AppContainer.swift b/Sources/NeuralComposeApp/AppContainer.swift index 061ff46..d3ab21c 100644 --- a/Sources/NeuralComposeApp/AppContainer.swift +++ b/Sources/NeuralComposeApp/AppContainer.swift @@ -5,6 +5,7 @@ import BCIEEG import BCIClassifier import BCILLM import BCIVoice +import BCIBiofeedback import WorldModelDemo /// Composition root. Knows nothing about SwiftUI; constructs the pipeline @@ -65,6 +66,17 @@ public struct AppContainer: Sendable { /// absent or malformed). Kept for the hypnagogic listener, which the view /// model builds lazily and which reads the recognition vocabulary from it. public let voiceProfile: VoiceProfile? + /// Biofeedback egress (ADR-011, registry entry 10). `nil` unless the + /// launch environment enabled at least one transport, so constructing an + /// `AppContainer` directly (tests, previews) never opens a UDP socket or + /// a CoreMIDI port. When present, `AppViewModel` feeds it the raw window + /// (before channel substitution), the classifier's intent, IMU samples, + /// and, only with the explicit raw toggle, raw EEG samples. + public let biofeedback: BiofeedbackCoordinator? + /// The resolved egress configuration, kept beside the coordinator so the + /// privacy indicator can name the tier (MIDI, loopback, LAN) and the raw + /// toggle without reaching into the actor. + public let biofeedbackConfiguration: BiofeedbackConfiguration public var pipelineMode: PipelineMode { PipelineMode( @@ -116,9 +128,13 @@ public struct AppContainer: Sendable { worldModelDemoResolved: WorldModelDemoFactory.Resolved = .init( engine: BaselineWorldModelDemoPlanner(), kind: .baseline, warning: nil ), - voiceProfile: VoiceProfile? = nil + voiceProfile: VoiceProfile? = nil, + biofeedback: BiofeedbackCoordinator? = nil, + biofeedbackConfiguration: BiofeedbackConfiguration = .disabled ) { self.voiceProfile = voiceProfile + self.biofeedback = biofeedback + self.biofeedbackConfiguration = biofeedbackConfiguration self.streamResolved = streamResolved self.classifierResolved = classifierResolved self.predictorResolved = predictorResolved @@ -229,6 +245,12 @@ public struct AppContainer: Sendable { let worldModelDemo = WorldModelDemoFactory.live() BCILog.worldModelDemo.notice("world model demo backend: \(worldModelDemo.kind.rawValue, privacy: .public)") + // Biofeedback egress: off unless the environment says otherwise. + // Resolved last; it depends on nothing above and nothing above may + // depend on it (ADR-011: imported only by the app target). + let biofeedbackConfiguration = BiofeedbackConfiguration.resolve(environment: ProcessInfo.processInfo.environment) + let biofeedback = await makeBiofeedback(configuration: biofeedbackConfiguration) + return AppContainer( streamResolved: stream, classifierResolved: classifier, @@ -244,7 +266,61 @@ public struct AppContainer: Sendable { interactionLogger: interactionLogger, jepaTransitionCapture: jepaTransitionCapture, worldModelDemoResolved: worldModelDemo, - voiceProfile: voiceProfile + voiceProfile: voiceProfile, + biofeedback: biofeedback, + biofeedbackConfiguration: biofeedbackConfiguration + ) + } + + /// Builds the egress coordinator for a configuration, or `nil` when no + /// transport is enabled or every enabled transport failed to open. Each + /// transport logs its destination at `.notice` so a session log always + /// records where features were sent (ADR-011 §3). + static func makeBiofeedback(configuration: BiofeedbackConfiguration) async -> BiofeedbackCoordinator? { + guard configuration.isEnabled else { return nil } + var sinks: [any BiofeedbackSink] = [] + + if let osc = configuration.osc { + let sender = OSCUDPSender(host: osc.host, port: osc.port) + await sender.start() + sinks.append(sender) + BCILog.pipeline.notice("biofeedback OSC egress -> \(osc.endpoint, privacy: .public) (\(osc.isLoopback ? "loopback" : "LAN", privacy: .public))\(configuration.includeRawEEG ? ", raw /muse/eeg ON" : "", privacy: .public)") + } + + if configuration.midi { + #if canImport(CoreMIDI) + do { + let source = try CoreMIDIVirtualSource() + sinks.append(source) + BCILog.pipeline.notice("biofeedback MIDI egress: virtual source \"\(source.name, privacy: .public)\" (in-machine)") + } catch { + BCILog.pipeline.error("biofeedback MIDI egress unavailable: \(String(describing: error), privacy: .public)") + } + #else + BCILog.pipeline.error("biofeedback MIDI egress requested but CoreMIDI is unavailable on this platform") + #endif + } + + guard !sinks.isEmpty else { return nil } + + var mappings: [BiofeedbackMapping] = [] + if let path = configuration.mappingsPath { + do { + mappings = try BiofeedbackConfiguration.loadMappings(at: path) + BCILog.pipeline.notice("biofeedback mappings: \(mappings.count, privacy: .public) from \(path, privacy: .public)") + } catch { + BCILog.pipeline.error("biofeedback mappings not loaded from \(path, privacy: .public): \(String(describing: error), privacy: .public)") + } + } + + let options = BiofeedbackCoordinator.Options( + mirror: MindMonitorMirror(perChannel: configuration.perChannel), + includeRawEEG: configuration.includeRawEEG + ) + return BiofeedbackCoordinator( + sink: sinks.count == 1 ? sinks[0] : CompositeBiofeedbackSink(sinks), + mappings: mappings, + options: options ) } diff --git a/Sources/NeuralComposeApp/AppViewModel.swift b/Sources/NeuralComposeApp/AppViewModel.swift index 5073bcb..7bfe950 100644 --- a/Sources/NeuralComposeApp/AppViewModel.swift +++ b/Sources/NeuralComposeApp/AppViewModel.swift @@ -8,6 +8,7 @@ import BCILLM import BCIVoice import BCICloudBridge import BCIPeerBridge +import BCIBiofeedback public struct CalibrationMetrics: Sendable { public let channelCount: Int @@ -556,8 +557,13 @@ public final class AppViewModel: ObservableObject, AppCommandDispatchTarget { let containerRef = container let spectralEstimatorRef = self.spectralEstimator let jepaTransitionCaptureRef = self.jepaTransitionCapture + // Biofeedback egress (ADR-011): nil unless a transport was enabled at + // launch. `rawEEGEgress` is read once here so the 256 Hz sample loop + // only hops to the actor when raw re-broadcast is actually on. + let biofeedbackRef = container.biofeedback + let rawEEGEgress = biofeedbackRef?.includesRawEEG ?? false streamTask = Task.detached(priority: .userInitiated) { - [weak self, windowing, metrics = metricsRef, channel, samples, spectralEstimatorRef, jepaTransitionCaptureRef] in + [weak self, windowing, metrics = metricsRef, channel, samples, spectralEstimatorRef, jepaTransitionCaptureRef, biofeedbackRef] in var current = initialResolved // Movement (accel/gyro) - parallel to the EEG sample loop, OSC-only. // The IMU channel outlives per-attempt EEG stop()/start() cycles, so @@ -574,6 +580,9 @@ public final class AppViewModel: ObservableObject, AppCommandDispatchTarget { (self?.isCalibrating ?? false) ? self?.calibrationRecorder : nil } await recorder?.recordMovement(movement) + // IMU to the egress: cached, forwarded with the + // next window frame (/muse/acc, /muse/gyro). + await biofeedbackRef?.ingest(movement: movement) } } } @@ -601,6 +610,12 @@ public final class AppViewModel: ObservableObject, AppCommandDispatchTarget { } // Single-owner fan-out (see liveSampleStream()). samples.send(sample) + // Raw EEG egress is the one payload ADR-011 keeps + // behind an explicit toggle. Gated here on a constant + // so the default path pays no actor hop per sample. + if rawEEGEgress { + await biofeedbackRef?.ingest(sample: sample) + } // Record sample if in calibration mode (Track A) or // in imagined-speech recording (Track B). The two @@ -650,6 +665,12 @@ public final class AppViewModel: ObservableObject, AppCommandDispatchTarget { // window. Cheap and avoids needing the full CalibrationMetrics // struct when not recording. let quality = Self.signalQuality(of: window) + // Biofeedback egress reads the RAW window, before the + // substitution below. The cleaned window has a lifted + // electrode overwritten with its contralateral partner, + // which would hide the bad contact from the horseshoe + // and from every mapping's HealthPolicy (ADR-011 §4). + await biofeedbackRef?.ingest(window: window) // Substitute dead/saturated channels with their healthy // contralateral partner (TP9<->TP10, AF7<->AF8) before // downstream spectral estimation, JEPA capture, and @@ -781,7 +802,7 @@ public final class AppViewModel: ObservableObject, AppCommandDispatchTarget { let classifierRef = self.classifier let smootherRef = self.smoother classifyTask = Task.detached(priority: .userInitiated) { - [weak self, metrics = metricsRef, channel, composition, classifications] in + [weak self, metrics = metricsRef, channel, composition, classifications, biofeedbackRef] in for await window in channel.stream { if Task.isCancelled { break } let cStart = DispatchTime.now() @@ -816,6 +837,11 @@ public final class AppViewModel: ObservableObject, AppCommandDispatchTarget { effectiveIntent = prediction.confidence >= 0.60 ? prediction.intent : .rest } await self?.setCurrentIntent(effectiveIntent) + // Track A events to the egress on the classifier's own tick, + // so a blink reaches the DAW with classifier latency rather + // than one window stride later. `.rest` is sent too: it is + // what closes an open note gate. + await biofeedbackRef?.note(intent: effectiveIntent, at: window.endTimestamp) await composition.applyIntent(smoothed) } } diff --git a/Sources/NeuralComposeApp/BiofeedbackConfiguration.swift b/Sources/NeuralComposeApp/BiofeedbackConfiguration.swift new file mode 100644 index 0000000..a83e2bf --- /dev/null +++ b/Sources/NeuralComposeApp/BiofeedbackConfiguration.swift @@ -0,0 +1,165 @@ +import Foundation +import BCIBiofeedback + +/// Launch-environment configuration for the biofeedback egress (ADR-011, +/// `decision_registry.md` entry 10). Mirrors `PeerBridgeConfiguration`: +/// env-var-only resolution, because Finder/DMG launches do not inherit +/// shell variables and this is a scripted-harness affordance until the +/// mapping UI (issue 5) gives it a settings surface. Absent variables mean +/// the feature is off and `AppContainer.biofeedback` is `nil`. +/// +/// Variables: +/// +/// - `NEURALCOMPOSE_BIOFEEDBACK_OSC`: `1` (loopback, port 7000), a bare +/// port (`7001`, loopback), or `host:port` (any other host is the LAN +/// tier and is shown as such in the privacy indicator). `0` or empty +/// disables OSC. Malformed values disable OSC rather than guess a host. +/// - `NEURALCOMPOSE_BIOFEEDBACK_MIDI`: `1` creates the CoreMIDI virtual +/// source "NeuralCompose Biofeedback" (in-machine, not network). +/// - `NEURALCOMPOSE_BIOFEEDBACK_RAW_EEG`: `1` re-broadcasts raw `/muse/eeg` +/// over OSC. Ignored without OSC; MIDI cannot carry it. +/// - `NEURALCOMPOSE_BIOFEEDBACK_PER_CHANNEL`: `1` sends four floats per band +/// (Mind Monitor's "separate values for each sensor") instead of one. +/// - `NEURALCOMPOSE_BIOFEEDBACK_MAPPINGS`: path to a JSON array of +/// `BiofeedbackMapping`. Optional; without it only the Mind Monitor +/// mirror runs. +public struct BiofeedbackConfiguration: Sendable, Equatable { + + public struct OSC: Sendable, Equatable { + public let host: String + public let port: UInt16 + + public static let defaultHost = "127.0.0.1" + public static let defaultPort: UInt16 = 7000 + + public init(host: String = defaultHost, port: UInt16 = defaultPort) { + self.host = host + self.port = port + } + + public var isLoopback: Bool { + host == "127.0.0.1" || host == "localhost" || host == "::1" + } + + public var endpoint: String { "\(host):\(port)" } + } + + /// Which egress tier is active, for the privacy indicator. + public enum Tier: Sendable, Equatable { + case off + /// CoreMIDI only: nothing leaves the machine. + case midiOnly + /// OSC to 127.0.0.1: UDP, but the datagrams never leave the machine. + case loopback + /// OSC to another host on the user's network. + case lan + } + + public let osc: OSC? + public let midi: Bool + public let includeRawEEG: Bool + public let perChannel: Bool + public let mappingsPath: String? + + public static let disabled = BiofeedbackConfiguration(osc: nil, midi: false, includeRawEEG: false, perChannel: false, mappingsPath: nil) + + public init(osc: OSC?, midi: Bool, includeRawEEG: Bool, perChannel: Bool, mappingsPath: String?) { + self.osc = osc + self.midi = midi + // Raw EEG rides on OSC only; without OSC the flag has nothing to + // carry it and is dropped here so no later check can be fooled. + self.includeRawEEG = includeRawEEG && osc != nil + self.perChannel = perChannel + self.mappingsPath = mappingsPath + } + + public var isEnabled: Bool { osc != nil || midi } + + public var tier: Tier { + if let osc { + return osc.isLoopback ? .loopback : .lan + } + return midi ? .midiOnly : .off + } + + /// Short badge text for the top bar. + public var badgeLabel: String { + switch tier { + case .off: return "" + case .midiOnly: return "Biofeedback: MIDI" + case .loopback: return midi ? "Biofeedback: MIDI + OSC loopback" : "Biofeedback: OSC loopback" + case .lan: return midi ? "Biofeedback: MIDI + OSC LAN" : "Biofeedback: OSC LAN" + } + } + + /// One line per transport for the expanded Network row. + public var statusLines: [String] { + var lines: [String] = [] + if midi { + lines.append("Biofeedback out: MIDI virtual source (in-machine)") + } + if let osc { + lines.append("Biofeedback out: OSC \(osc.endpoint) (\(osc.isLoopback ? "loopback" : "LAN"))") + } + if includeRawEEG { + lines.append("Raw /muse/eeg re-broadcast ON") + } + return lines + } + + /// Resolve from the launch environment. Never throws; a malformed OSC + /// value disables OSC and the caller logs the raw string. + public static func resolve(environment: [String: String]) -> BiofeedbackConfiguration { + let osc = parseOSC(environment["NEURALCOMPOSE_BIOFEEDBACK_OSC"]) + let midi = isOn(environment["NEURALCOMPOSE_BIOFEEDBACK_MIDI"]) + let raw = isOn(environment["NEURALCOMPOSE_BIOFEEDBACK_RAW_EEG"]) + let perChannel = isOn(environment["NEURALCOMPOSE_BIOFEEDBACK_PER_CHANNEL"]) + let mappings = environment["NEURALCOMPOSE_BIOFEEDBACK_MAPPINGS"]? + .trimmingCharacters(in: .whitespacesAndNewlines) + return BiofeedbackConfiguration( + osc: osc, + midi: midi, + includeRawEEG: raw, + perChannel: perChannel, + mappingsPath: (mappings?.isEmpty ?? true) ? nil : mappings + ) + } + + /// `1`, `true`, `loopback` → loopback:7000; a bare port → loopback:port; + /// `host:port` → that host; anything else → nil. + static func parseOSC(_ raw: String?) -> OSC? { + guard let value = raw?.trimmingCharacters(in: .whitespacesAndNewlines), !value.isEmpty else { return nil } + switch value.lowercased() { + case "0", "false", "off", "no": + return nil + case "1", "true", "on", "yes", "loopback", "localhost": + return OSC() + default: + break + } + if let port = UInt16(value), port > 0 { + return OSC(port: port) + } + // host:port, with IPv6 literals in brackets: [::1]:7000 + guard let colon = value.lastIndex(of: ":") else { return nil } + var host = String(value[.. 0, !host.isEmpty else { return nil } + if host.hasPrefix("["), host.hasSuffix("]") { + host = String(host.dropFirst().dropLast()) + } + return OSC(host: host, port: port) + } + + static func isOn(_ raw: String?) -> Bool { + guard let value = raw?.trimmingCharacters(in: .whitespacesAndNewlines).lowercased() else { return false } + return ["1", "true", "on", "yes"].contains(value) + } + + /// Load a mapping set from a JSON file (`[BiofeedbackMapping]`). + public static func loadMappings(at path: String) throws -> [BiofeedbackMapping] { + let url = URL(fileURLWithPath: (path as NSString).expandingTildeInPath) + let data = try Data(contentsOf: url) + return try JSONDecoder().decode([BiofeedbackMapping].self, from: data) + } +} diff --git a/Sources/NeuralComposeApp/ContentView.swift b/Sources/NeuralComposeApp/ContentView.swift index b9c81f1..13066de 100644 --- a/Sources/NeuralComposeApp/ContentView.swift +++ b/Sources/NeuralComposeApp/ContentView.swift @@ -57,6 +57,7 @@ struct ContentView: View { hypnagogicMode: $viewModel.hypnagogicMode, hypnagogicRuntimePreference: $viewModel.hypnagogicRuntimePreference, hypnagogicRuntimeDiagnostics: viewModel.hypnagogicRuntimeDiagnostics, + biofeedback: viewModel.container.biofeedbackConfiguration, health: viewModel.healthSnapshot, onReconnectMuse: { Task { await viewModel.reconnectLiveEEG() } } ) diff --git a/Sources/NeuralComposeApp/PrivacyIndicatorView.swift b/Sources/NeuralComposeApp/PrivacyIndicatorView.swift index b7d6a3c..dcf859d 100644 --- a/Sources/NeuralComposeApp/PrivacyIndicatorView.swift +++ b/Sources/NeuralComposeApp/PrivacyIndicatorView.swift @@ -58,6 +58,10 @@ struct PrivacyIndicatorView: View { @Binding var hypnagogicMode: HypnagogicMode @Binding var hypnagogicRuntimePreference: HypnagogicRuntimePreference var hypnagogicRuntimeDiagnostics: HypnagogicRuntimeDiagnostics + /// Biofeedback egress tier resolved at launch (ADR-011, registry entry + /// 10). Read-only here: it is env-var configured until the mapping UI + /// lands. `.disabled` hides the badge and the Network row line. + var biofeedback: BiofeedbackConfiguration = .disabled /// Latest app-watchdog snapshot for the degraded badge (read-only display). var health: HealthSnapshot? = nil var onReconnectMuse: () -> Void = {} @@ -78,6 +82,7 @@ struct PrivacyIndicatorView: View { worldModelDemoBadge spokenLoopBadge hypnagogicLoopBadge + biofeedbackBadge voiceBadge cmdBadge if !isReconnecting && (mode.acquisition == .synthetic || lastError != nil) { @@ -135,13 +140,24 @@ struct PrivacyIndicatorView: View { } GridRow { Text("Network").bold() - if hypnagogicLoopEnabled { + if hypnagogicLoopEnabled || biofeedback.isEnabled { VStack(alignment: .leading, spacing: 2) { - Text("\(hypnagogicRuntimeDiagnostics.configuration.providerLabel) active — Hypnagogic (\(hypnagogicMode.label))") - .foregroundStyle(hypnagogicRuntimeDiagnostics.configuration.runtimeName.lowercased() == "ollama" ? .orange : .red) - Text(hypnagogicRuntimeEgressDescription) - .font(.caption2) - .foregroundStyle(.secondary) + if hypnagogicLoopEnabled { + Text("\(hypnagogicRuntimeDiagnostics.configuration.providerLabel) active — Hypnagogic (\(hypnagogicMode.label))") + .foregroundStyle(hypnagogicRuntimeDiagnostics.configuration.runtimeName.lowercased() == "ollama" ? .orange : .red) + Text(hypnagogicRuntimeEgressDescription) + .font(.caption2) + .foregroundStyle(.secondary) + } + // Biofeedback egress lines (ADR-011): MIDI and + // loopback stay on the machine (orange, like a + // local runtime); a LAN host and the raw EEG + // toggle are the two things worth red. + ForEach(biofeedback.statusLines, id: \.self) { line in + Text(line) + .font(.caption2) + .foregroundStyle(biofeedbackLineColor(line)) + } } } else { Text("Disabled at runtime").foregroundStyle(.green) @@ -510,6 +526,29 @@ struct PrivacyIndicatorView: View { } } + /// Biofeedback egress badge. Orange for the in-machine tiers (MIDI, + /// OSC loopback), red for a LAN destination or when raw EEG is being + /// re-broadcast; hidden when the feature is off. + @ViewBuilder + private var biofeedbackBadge: some View { + if biofeedback.isEnabled { + let hot = biofeedback.tier == .lan || biofeedback.includeRawEEG + Label(biofeedback.badgeLabel, systemImage: "waveform.path") + .font(.caption) + .foregroundStyle(hot ? Color.red : Color.orange) + .padding(.horizontal, 8) + .padding(.vertical, 3) + .background((hot ? Color.red : Color.orange).opacity(0.15)) + .cornerRadius(4) + .help(biofeedback.statusLines.joined(separator: "\n")) + } + } + + private func biofeedbackLineColor(_ line: String) -> Color { + if line.hasPrefix("Raw ") || line.hasSuffix("(LAN)") { return .red } + return .orange + } + /// Transient, event-driven badge — visible only while the mic is /// actually open (push-to-talk held) or speech is playing, and gone the /// instant either stops. Deliberately not folded into `PipelineMode`: diff --git a/Tests/BCIBiofeedbackTests/BiofeedbackCoordinatorTests.swift b/Tests/BCIBiofeedbackTests/BiofeedbackCoordinatorTests.swift new file mode 100644 index 0000000..2cf338f --- /dev/null +++ b/Tests/BCIBiofeedbackTests/BiofeedbackCoordinatorTests.swift @@ -0,0 +1,220 @@ +import XCTest +import BCICore +import BCIEEG +@testable import BCIBiofeedback + +/// Drives the coordinator with hand-built windows, intents and IMU samples +/// through a `RecordingBiofeedbackSink` and asserts on what reached the +/// sink. No networking, no CoreMIDI. +final class BiofeedbackCoordinatorTests: XCTestCase { + + private let sampleRate = 256.0 + + private func sinusoid(hz: Double, amplitude: Float, offset: Float = 800, count: Int = 256) -> [Float] { + (0.. EEGWindow { + EEGWindow( + samples: [ + sinusoid(hz: 10, amplitude: 20), + [Float](repeating: 800, count: 256), + [Float](repeating: 800, count: 256), + [Float](repeating: 800, count: 256), + ], + sampleRate: sampleRate, + endTimestamp: t, + sequence: sequence + ) + } + + private func address(_ outputs: [BiofeedbackOutput], _ address: String) -> [OSCMessage] { + outputs.compactMap(\.oscMessage).filter { $0.address == address } + } + + // MARK: - channelHealth + + func testChannelHealthFromRawWindow() { + let window = EEGWindow( + samples: [ + sinusoid(hz: 10, amplitude: 20), // RMS ~14 µV: healthy + [Float](repeating: 800, count: 256), // RMS 0: dead + sinusoid(hz: 10, amplitude: 400), // RMS ~283 µV: saturated + [1, Float.nan, 3] + [Float](repeating: 0, count: 253), // non-finite: unknown + ], + sampleRate: sampleRate, endTimestamp: 2.5, sequence: 1 + ) + let states = BiofeedbackCoordinator.channelHealth(for: window) + XCTAssertEqual(states.map(\.channel), EEGChannel.allCases) + XCTAssertEqual(states.map(\.status), [.healthy, .dead, .saturated, .unknown]) + XCTAssertEqual(states[0].rms, 20 / Float(2).squareRoot(), accuracy: 0.2) + XCTAssertEqual(states[3].rms, 0) + XCTAssertTrue(states.allSatisfy { $0.timestamp == 2.5 && $0.samples == 256 }) + } + + func testChannelHealthIgnoresRowsBeyondChannelList() { + let window = EEGWindow(samples: [sinusoid(hz: 10, amplitude: 20)], sampleRate: sampleRate, endTimestamp: 0, sequence: 0) + XCTAssertEqual(BiofeedbackCoordinator.channelHealth(for: window).map(\.channel), [.tp9]) + } + + // MARK: - Window ticks + + func testWindowTickEmitsMirrorWithHealthAndPowers() async { + let sink = RecordingBiofeedbackSink() + let coordinator = BiofeedbackCoordinator(sink: sink, options: .init(mirror: MindMonitorMirror(perChannel: true))) + await coordinator.ingest(window: alphaOnTP9Window()) + let outputs = await sink.outputs + + let horseshoe = address(outputs, "/muse/elements/horseshoe").first?.floatArguments + XCTAssertEqual(horseshoe, [1, 4, 4, 4], "TP9 healthy, three flat channels dead") + + let alpha = address(outputs, "/muse/elements/alpha_absolute").first?.floatArguments ?? [] + XCTAssertEqual(alpha.count, 4) + XCTAssertEqual(alpha[0], log10(200), accuracy: 0.02, "A²/2 = 200 µV² on TP9") + XCTAssertLessThan(alpha[1], -5, "flat channel sits at the power floor") + + XCTAssertTrue(address(outputs, "/muse/elements/blink").isEmpty, "window ticks never carry events") + XCTAssertTrue(address(outputs, "/muse/eeg").isEmpty, "raw EEG is not derivable from a window") + let count = await coordinator.windowCount + XCTAssertEqual(count, 1) + } + + func testProvidedHealthOverridesRawEstimate() async { + let sink = RecordingBiofeedbackSink() + let coordinator = BiofeedbackCoordinator(sink: sink) + let stale = EEGChannel.allCases.map { ChannelHealthState(channel: $0, status: .stale, rms: 10, samples: 256, timestamp: 1) } + await coordinator.ingest(window: alphaOnTP9Window(), health: stale) + let outputs = await sink.outputs + XCTAssertEqual(address(outputs, "/muse/elements/horseshoe").first?.floatArguments, [4, 4, 4, 4]) + } + + func testContinuousMappingRunsOnWindowsOnly() async { + let sink = RecordingBiofeedbackSink() + let mappings = [ + BiofeedbackMapping(feature: .bandAbsolute(.alpha, channel: .tp9), target: .osc(address: "/nc/alpha"), inputLow: 1, inputHigh: 3), + BiofeedbackMapping(feature: .blink, target: .midiNote(note: 60, channel: 0, velocity: 100, gate: 0.5), inputLow: 0, inputHigh: 1), + ] + let coordinator = BiofeedbackCoordinator(sink: sink, mappings: mappings, options: .init(mirror: nil)) + await coordinator.ingest(window: alphaOnTP9Window()) + let outputs = await sink.outputs + let alpha = address(outputs, "/nc/alpha").first?.floatArguments.first + XCTAssertEqual(alpha ?? -1, (log10(Float(200)) - 1) / 2, accuracy: 0.01) + XCTAssertTrue(outputs.compactMap(\.midiEvent).isEmpty, "event mapping does not fire on a window tick") + let all = await coordinator.mappings + XCTAssertEqual(all.count, 2) + } + + func testMirrorDisabledEmitsOnlyMappings() async { + let sink = RecordingBiofeedbackSink() + let coordinator = BiofeedbackCoordinator(sink: sink, options: .init(mirror: nil)) + await coordinator.ingest(window: alphaOnTP9Window()) + let outputs = await sink.outputs + XCTAssertTrue(outputs.isEmpty, "no mirror, no mappings, nothing emitted") + } + + // MARK: - Intent ticks + + func testBlinkIntentEmitsEventMessageAndNoteGate() async { + let sink = RecordingBiofeedbackSink() + let note = BiofeedbackMapping(feature: .blink, target: .midiNote(note: 60, channel: 0, velocity: 100, gate: 0.5), inputLow: 0, inputHigh: 1) + let coordinator = BiofeedbackCoordinator(sink: sink, mappings: [note]) + await coordinator.ingest(window: alphaOnTP9Window(at: 1)) + await sink.clear() + + await coordinator.note(intent: .singleBlink, at: 1.05) + var outputs = await sink.outputs + XCTAssertEqual(address(outputs, "/muse/elements/blink").first?.arguments, [OSCArgument.int32(1)]) + XCTAssertTrue(address(outputs, "/muse/elements/alpha_absolute").isEmpty, "event tick does not re-send bands") + XCTAssertEqual(outputs.compactMap(\.midiEvent), [.noteOn(channel: 0, note: 60, velocity: 100)]) + await sink.clear() + + await coordinator.note(intent: .rest, at: 1.1) + outputs = await sink.outputs + XCTAssertTrue(address(outputs, "/muse/elements/blink").isEmpty) + XCTAssertEqual(outputs.compactMap(\.midiEvent), [.noteOff(channel: 0, note: 60)], "rest closes the gate") + let events = await coordinator.eventCount + XCTAssertEqual(events, 1) + } + + func testJawClenchAndSelectSemantics() async { + let sink = RecordingBiofeedbackSink() + let coordinator = BiofeedbackCoordinator(sink: sink) + await coordinator.note(intent: .jawClench, at: 0.5) + var outputs = await sink.outputs + XCTAssertEqual(address(outputs, "/muse/elements/jaw_clench").count, 1) + XCTAssertTrue(address(outputs, "/muse/elements/blink").isEmpty) + await sink.clear() + + await coordinator.note(intent: .select, at: 0.6) + outputs = await sink.outputs + XCTAssertTrue(outputs.isEmpty, "select is a composed FSM state, not a physiological event") + } + + func testIntentBeforeAnyWindowStillEmitsEvents() async { + let sink = RecordingBiofeedbackSink() + let coordinator = BiofeedbackCoordinator(sink: sink) + await coordinator.note(intent: .doubleBlink, at: 0.1) + let outputs = await sink.outputs + XCTAssertEqual(address(outputs, "/muse/elements/blink").count, 1) + } + + // MARK: - IMU and raw EEG + + func testMovementIsCachedIntoNextWindowFrame() async { + let sink = RecordingBiofeedbackSink() + let coordinator = BiofeedbackCoordinator(sink: sink) + await coordinator.ingest(movement: MovementSample(timestamp: 0.9, kind: .accel, x: 0.1, y: 0.2, z: 0.97)) + await coordinator.ingest(movement: MovementSample(timestamp: 0.95, kind: .gyro, x: -1, y: 2, z: -3)) + await coordinator.ingest(window: alphaOnTP9Window(at: 1)) + let outputs = await sink.outputs + XCTAssertEqual(address(outputs, "/muse/acc").first?.floatArguments, [0.1, 0.2, 0.97]) + XCTAssertEqual(address(outputs, "/muse/gyro").first?.floatArguments, [-1, 2, -3]) + } + + func testRawEEGIsForwardedOnlyWhenEnabled() async { + let sample = EEGSample(timestamp: 0.5, channels: [801, 802, 803, 804]) + + let off = RecordingBiofeedbackSink() + let disabled = BiofeedbackCoordinator(sink: off, options: .init(includeRawEEG: false)) + XCTAssertFalse(disabled.includesRawEEG) + await disabled.ingest(sample: sample) + let offOutputs = await off.outputs + XCTAssertTrue(offOutputs.isEmpty) + + let on = RecordingBiofeedbackSink() + let enabled = BiofeedbackCoordinator(sink: on, options: .init(includeRawEEG: true)) + XCTAssertTrue(enabled.includesRawEEG) + await enabled.ingest(sample: sample) + let onOutputs = await on.outputs + XCTAssertEqual(address(onOutputs, "/muse/eeg").first?.floatArguments, [801, 802, 803, 804]) + } + + // MARK: - Mapping management + + func testReplaceMappingsResplitsByFeature() async { + let sink = RecordingBiofeedbackSink() + let coordinator = BiofeedbackCoordinator(sink: sink, options: .init(mirror: nil)) + let cc = BiofeedbackMapping(feature: .bandRelative(.alpha, channel: nil), target: .midiControl(controller: 1, channel: 0, fourteenBit: false), inputLow: 0, inputHigh: 1) + let gate = BiofeedbackMapping(feature: .jawClench, target: .midiNote(note: 62, channel: 0, velocity: 90, gate: 1), inputLow: 0, inputHigh: 1) + await coordinator.replaceMappings([cc, gate]) + + await coordinator.ingest(window: alphaOnTP9Window(at: 1)) + var outputs = await sink.outputs + XCTAssertEqual(outputs.count, 1) + if case .midi(.controlChange(let channel, let controller, _))? = outputs.first { + XCTAssertEqual(channel, 0) + XCTAssertEqual(controller, 1) + } else { + XCTFail("expected a control change, got \(outputs)") + } + await sink.clear() + + await coordinator.note(intent: .jawClench, at: 1.05) + outputs = await sink.outputs + XCTAssertEqual(outputs.compactMap(\.midiEvent), [.noteOn(channel: 0, note: 62, velocity: 90)]) + } +} diff --git a/Tests/NeuralComposeAppTests/BiofeedbackConfigurationTests.swift b/Tests/NeuralComposeAppTests/BiofeedbackConfigurationTests.swift new file mode 100644 index 0000000..00219ae --- /dev/null +++ b/Tests/NeuralComposeAppTests/BiofeedbackConfigurationTests.swift @@ -0,0 +1,121 @@ +import XCTest +import BCIBiofeedback +@testable import NeuralComposeApp + +final class BiofeedbackConfigurationTests: XCTestCase { + + func testAbsentEnvironmentIsDisabled() { + let configuration = BiofeedbackConfiguration.resolve(environment: [:]) + XCTAssertEqual(configuration, .disabled) + XCTAssertFalse(configuration.isEnabled) + XCTAssertEqual(configuration.tier, .off) + XCTAssertEqual(configuration.badgeLabel, "") + XCTAssertTrue(configuration.statusLines.isEmpty) + } + + func testOSCFlagDefaultsToLoopback7000() { + for value in ["1", "true", "loopback", " on "] { + let configuration = BiofeedbackConfiguration.resolve(environment: ["NEURALCOMPOSE_BIOFEEDBACK_OSC": value]) + XCTAssertEqual(configuration.osc, BiofeedbackConfiguration.OSC(host: "127.0.0.1", port: 7000), value) + XCTAssertEqual(configuration.tier, .loopback, value) + XCTAssertTrue(configuration.isEnabled, value) + } + } + + func testBarePortStaysOnLoopback() { + let configuration = BiofeedbackConfiguration.resolve(environment: ["NEURALCOMPOSE_BIOFEEDBACK_OSC": "7001"]) + XCTAssertEqual(configuration.osc, BiofeedbackConfiguration.OSC(host: "127.0.0.1", port: 7001)) + XCTAssertEqual(configuration.tier, .loopback) + XCTAssertEqual(configuration.statusLines, ["Biofeedback out: OSC 127.0.0.1:7001 (loopback)"]) + } + + func testHostAndPortIsLAN() { + let configuration = BiofeedbackConfiguration.resolve(environment: ["NEURALCOMPOSE_BIOFEEDBACK_OSC": "192.168.1.20:7000"]) + XCTAssertEqual(configuration.osc, BiofeedbackConfiguration.OSC(host: "192.168.1.20", port: 7000)) + XCTAssertEqual(configuration.tier, .lan) + XCTAssertEqual(configuration.badgeLabel, "Biofeedback: OSC LAN") + XCTAssertEqual(configuration.statusLines, ["Biofeedback out: OSC 192.168.1.20:7000 (LAN)"]) + } + + func testIPv6LiteralInBrackets() { + let configuration = BiofeedbackConfiguration.resolve(environment: ["NEURALCOMPOSE_BIOFEEDBACK_OSC": "[::1]:7000"]) + XCTAssertEqual(configuration.osc, BiofeedbackConfiguration.OSC(host: "::1", port: 7000)) + XCTAssertEqual(configuration.tier, .loopback) + } + + func testOffValuesAndMalformedValuesDisableOSC() { + for value in ["0", "false", "off", "", " ", "nonsense", "host:", ":7000", "host:notaport", "host:0", "0"] { + let configuration = BiofeedbackConfiguration.resolve(environment: ["NEURALCOMPOSE_BIOFEEDBACK_OSC": value]) + XCTAssertNil(configuration.osc, "\"\(value)\" should not resolve to an OSC destination") + XCTAssertFalse(configuration.isEnabled, value) + } + } + + func testMIDIOnlyTier() { + let configuration = BiofeedbackConfiguration.resolve(environment: ["NEURALCOMPOSE_BIOFEEDBACK_MIDI": "1"]) + XCTAssertTrue(configuration.midi) + XCTAssertNil(configuration.osc) + XCTAssertEqual(configuration.tier, .midiOnly) + XCTAssertEqual(configuration.badgeLabel, "Biofeedback: MIDI") + XCTAssertEqual(configuration.statusLines, ["Biofeedback out: MIDI virtual source (in-machine)"]) + } + + func testMIDIPlusOSCLabels() { + let configuration = BiofeedbackConfiguration.resolve(environment: [ + "NEURALCOMPOSE_BIOFEEDBACK_MIDI": "1", + "NEURALCOMPOSE_BIOFEEDBACK_OSC": "1", + ]) + XCTAssertEqual(configuration.tier, .loopback) + XCTAssertEqual(configuration.badgeLabel, "Biofeedback: MIDI + OSC loopback") + XCTAssertEqual(configuration.statusLines, [ + "Biofeedback out: MIDI virtual source (in-machine)", + "Biofeedback out: OSC 127.0.0.1:7000 (loopback)", + ]) + } + + func testRawEEGRequiresOSC() { + let withoutOSC = BiofeedbackConfiguration.resolve(environment: [ + "NEURALCOMPOSE_BIOFEEDBACK_MIDI": "1", + "NEURALCOMPOSE_BIOFEEDBACK_RAW_EEG": "1", + ]) + XCTAssertFalse(withoutOSC.includeRawEEG, "MIDI cannot carry raw EEG; the flag is dropped") + + let withOSC = BiofeedbackConfiguration.resolve(environment: [ + "NEURALCOMPOSE_BIOFEEDBACK_OSC": "1", + "NEURALCOMPOSE_BIOFEEDBACK_RAW_EEG": "1", + ]) + XCTAssertTrue(withOSC.includeRawEEG) + XCTAssertEqual(withOSC.statusLines.last, "Raw /muse/eeg re-broadcast ON") + } + + func testPerChannelAndMappingsPath() { + let configuration = BiofeedbackConfiguration.resolve(environment: [ + "NEURALCOMPOSE_BIOFEEDBACK_OSC": "1", + "NEURALCOMPOSE_BIOFEEDBACK_PER_CHANNEL": "yes", + "NEURALCOMPOSE_BIOFEEDBACK_MAPPINGS": " ~/maps.json ", + ]) + XCTAssertTrue(configuration.perChannel) + XCTAssertEqual(configuration.mappingsPath, "~/maps.json") + + let blank = BiofeedbackConfiguration.resolve(environment: ["NEURALCOMPOSE_BIOFEEDBACK_MAPPINGS": " "]) + XCTAssertNil(blank.mappingsPath) + } + + func testLoadMappingsRoundTrip() throws { + let mappings = [ + BiofeedbackMapping(feature: .bandAbsolute(.alpha, channel: nil), target: .midiControl(controller: 1, channel: 0, fourteenBit: false), inputLow: 0, inputHigh: 2, smoothingTau: 0.5), + BiofeedbackMapping(feature: .blink, target: .midiNote(note: 60, channel: 0, velocity: 100, gate: 0.2), inputLow: 0, inputHigh: 1), + ] + let url = FileManager.default.temporaryDirectory.appendingPathComponent("biofeedback-mappings-\(UUID().uuidString).json") + try JSONEncoder().encode(mappings).write(to: url) + defer { try? FileManager.default.removeItem(at: url) } + + let loaded = try BiofeedbackConfiguration.loadMappings(at: url.path) + XCTAssertEqual(loaded, mappings) + } + + func testMakeBiofeedbackIsNilWhenDisabled() async { + let coordinator = await AppContainer.makeBiofeedback(configuration: .disabled) + XCTAssertNil(coordinator) + } +} diff --git a/docs/architecture/decision-log/ADR-011-biofeedback-egress.md b/docs/architecture/decision-log/ADR-011-biofeedback-egress.md index 7b74997..59aa57d 100644 --- a/docs/architecture/decision-log/ADR-011-biofeedback-egress.md +++ b/docs/architecture/decision-log/ADR-011-biofeedback-egress.md @@ -63,9 +63,13 @@ reproducible from a recording. - *OSC to a LAN host*: any other host. Surfaced in the privacy indicator with the destination, and logged at `.notice` on start, mirroring what ADR-004 requires of the inbound listener. - The feature as a whole is off by default; while off, the app wires - `NullBiofeedbackSink` so the mapper path stays exercised with nothing - leaving the process. + The feature as a whole is off by default. While off, the app + constructs no coordinator at all (`AppContainer.biofeedback == nil`): + no band powers are computed and no sink exists, so there is nothing to + exercise and nothing to leak. `NullBiofeedbackSink` is the protocol's + stub for tests and previews. (Amended 2026-11-07 by the PR 2 wiring; + the original text had the app wire the null sink while off, which + would have spent an FFT per window for no consumer.) 4. **Health gating is mandatory and lives in one place.** Every `BiofeedbackMapping` carries a `HealthPolicy` (`holdLast` by default, @@ -189,6 +193,16 @@ with the fixtures as acceptance. Rejected for now. recording and composite sinks. - `Sources/BCIBiofeedback/OSCUDPSender.swift`, `CoreMIDIVirtualSource.swift`: the two transports. +- `Sources/BCIBiofeedback/BiofeedbackCoordinator.swift`: the one object + that holds a mapper and a sink; raw window in, intent in, IMU in, and the + single runtime call site of `MindMonitorMirror.rawEEG(_:)`. +- `Sources/NeuralComposeApp/BiofeedbackConfiguration.swift`: env-var + resolution (`NEURALCOMPOSE_BIOFEEDBACK_OSC`, `_MIDI`, `_RAW_EEG`, + `_PER_CHANNEL`, `_MAPPINGS`), tier and indicator strings. +- `Sources/NeuralComposeApp/AppContainer.swift` (`makeBiofeedback`), + `AppViewModel.swift` (four call sites: raw window, classifier intent, + IMU, gated raw sample), `PrivacyIndicatorView.swift` (badge and Network + row), `Scripts/run-biofeedback-osc.sh`. - `Sources/BCIEEG/OSC/OSCEncoder.swift`: the production encoder, mirror of `MuseOSCDecoder`. - Tests: `Tests/BCIBiofeedbackTests/*`, `Tests/BCIEEGTests/OSCEncoderTests.swift`.