Repository navigation
feat(biofeedback): wire the egress into the app (ADR-011 PR 2) - #78
Merged
Merged
Conversation
Adds BiofeedbackCoordinator to BCIBiofeedback: the one object holding a FeatureMapper and a BiofeedbackSink. It takes the RAW window from the windowing stage (before substituteBadChannels, so a lifted electrode is visible to the horseshoe and to every HealthPolicy), the Track A intent on the classifier's own tick (events reach the DAW with classifier latency, not one stride later), IMU samples, and, only behind the explicit toggle, raw EEG samples. Mappings are split by feature so window ticks never double-emit band mappings and event ticks never re-send bands. Health is computed per channel from the raw window with ChannelHealthThresholds unless provider states are passed. App side: BiofeedbackConfiguration resolves NEURALCOMPOSE_BIOFEEDBACK_OSC (1 | port | host:port), _MIDI, _RAW_EEG, _PER_CHANNEL and _MAPPINGS the way PeerBridgeConfiguration does; AppContainer.makeBiofeedback builds OSCUDPSender (loopback 7000 by default) and/or CoreMIDIVirtualSource and is nil when nothing is enabled; AppViewModel gains four call sites; PrivacyIndicatorView gets a badge and Network-row lines that name the tier (MIDI, loopback, LAN) and the raw toggle; run-biofeedback-osc.sh mirrors run-osc-remote.sh and defaults to synthetic EEG for a dry run into Muse Port. ADR-011 section 3 and registry entry 10 amended: while off, no coordinator is constructed (the earlier text had the app wire a null sink, which would spend an FFT per window for no consumer). Tests: BiofeedbackCoordinatorTests (12) and BiofeedbackConfigurationTests (12) compiled and verified on M4 alongside the full 730-test Swift suite. Refs: ADR-011, decision_registry.md entry 10, ADR-004, PRINCIPLES.md 1, 4, 5, 6. Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01QapsKF5C619kjbak7vTmRK
aurascoper
force-pushed
the
feat/biofeedback-wiring
branch
from
November 8, 2026 03:23
4726783 to
1431c45
Compare
Open
5 tasks done
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
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.
Summary
Stacks on #77 (
feat/biofeedback-egress,d9c8d8a) and closes the Issue 2 / Issue 3 wiring items from #76.BiofeedbackCoordinator(BCIBiofeedback)The single actor that holds two
FeatureMapperinstances and aBiofeedbackSink. Four inputs, each from the pipeline stage that already produces it:ingest(window:)takes the raw window beforesubstituteBadChannels, so a lifted electrode is visible to the horseshoe and to everyHealthPolicy. Health is computed per channel from the raw window (demeaned RMS againstChannelHealthThresholds) unless provider states are passed.note(intent:at:)takes the Track A decision on the classifier's own tick. Blink and jaw clench reach the DAW with classifier latency rather than one window stride later..restis sent too, because it is what closes an open note gate..selectis ignored (FSM state, not a physiological event).ingest(movement:)caches the latest accel and gyro for the next frame.ingest(sample:)is the raw EEG re-broadcast: a no-op unlessincludeRawEEG, and the single runtime call site ofMindMonitorMirror.rawEEG(_:).Mappings are split by feature:
.blinkand.jawClenchrun on intent ticks, everything else on window ticks. TwoFeatureMappers ensure window ticks never double-emit bands and event ticks never re-send the mirror's band messages (MindMonitorMirror.eventMessagessplit out additively).App Wiring (
NeuralComposeApp)BiofeedbackConfigurationresolvesNEURALCOMPOSE_BIOFEEDBACK_OSC(1| port |host:port, loopback 7000 default),_MIDI,_RAW_EEG(dropped without OSC),_PER_CHANNEL, and_MAPPINGS(JSON[BiofeedbackMapping]).AppContainer.makeBiofeedbackbuildsOSCUDPSenderand/orCoreMIDIVirtualSource, logs each destination at.notice, and returnsnilwhen nothing is enabled or every transport failed to open.AppViewModel.start()gains four call sites; the 256 Hz sample loop hops to the actor only when raw egress is on.PrivacyIndicatorViewshows a badge (orange for MIDI and loopback, red for LAN or raw EEG) and one Network-row line per transport.Scripts/run-biofeedback-osc.shmirrorsrun-osc-remote.shand defaults to synthetic EEG so the first run streams into Muse Port with no hardware.ADR-011 Section 3 & Registry Entry 10 Amendment
While off, no coordinator is constructed (
AppContainer.biofeedback == nil): no band powers are computed and no sink exists, avoiding an unnecessary FFT per window when no consumer is active.Verification
macOS 14+, Swift 6):BiofeedbackCoordinatorTests: 12/12 passedBiofeedbackConfigurationTests: 12/12 passedBCIBiofeedbackTeststotal: 69/69 passed (57 PR 1 + 12 PR 2)NeuralComposeAppTeststotal: 138/138 passedswift testsuite across all 9 test bundles: 730 executed, 0 failuresScripts/check_adr_references.py: PASS (0 warnings)bash -n Scripts/run-biofeedback-osc.sh: PASSManual Acceptance Checklist (Issue 3)
./Scripts/run-biofeedback-osc.shwith Mind Monitor stopped and Muse Port on port 7000: band bars and horseshoe move from synthetic EEG on the same Mac.--raw-eegon:/muse/eegappears in a Protokol orudpdumpcapture; off: absent.--host <LAN ip>: badge turns red, Network row says(LAN).--midi:"NeuralCompose Biofeedback"appears in Audio MIDI Setup and Live's MIDI preferences; a blink triggers a mapped pad and releases on the next.restwindow.