Skip to content

feat(biofeedback): wire the egress into the app (ADR-011 PR 2) - #78

Merged
aurascoper merged 1 commit into
mainfrom
feat/biofeedback-wiring
Nov 8, 2026
Merged

aurascoper merged 1 commit into
mainfrom
feat/biofeedback-wiring

Conversation

@aurascoper

Copy link
Copy Markdown
Owner

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 FeatureMapper instances and a BiofeedbackSink. Four inputs, each from the pipeline stage that already produces it:

  • ingest(window:) takes the raw window before substituteBadChannels, so a lifted electrode is visible to the horseshoe and to every HealthPolicy. Health is computed per channel from the raw window (demeaned RMS against ChannelHealthThresholds) 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. .rest is sent too, because it is what closes an open note gate. .select is 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 unless includeRawEEG, and the single runtime call site of MindMonitorMirror.rawEEG(_:).

Mappings are split by feature: .blink and .jawClench run on intent ticks, everything else on window ticks. Two FeatureMappers ensure window ticks never double-emit bands and event ticks never re-send the mirror's band messages (MindMonitorMirror.eventMessages split out additively).

App Wiring (NeuralComposeApp)

  • BiofeedbackConfiguration resolves NEURALCOMPOSE_BIOFEEDBACK_OSC (1 | port | host:port, loopback 7000 default), _MIDI, _RAW_EEG (dropped without OSC), _PER_CHANNEL, and _MAPPINGS (JSON [BiofeedbackMapping]).
  • AppContainer.makeBiofeedback builds OSCUDPSender and/or CoreMIDIVirtualSource, logs each destination at .notice, and returns nil when 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.
  • PrivacyIndicatorView shows a badge (orange for MIDI and loopback, red for LAN or raw EEG) and one Network-row line per transport.
  • Scripts/run-biofeedback-osc.sh mirrors run-osc-remote.sh and 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

  • Compiled and executed on Apple M4 (macOS 14+, Swift 6):
    • BiofeedbackCoordinatorTests: 12/12 passed
    • BiofeedbackConfigurationTests: 12/12 passed
    • BCIBiofeedbackTests total: 69/69 passed (57 PR 1 + 12 PR 2)
    • NeuralComposeAppTests total: 138/138 passed
    • Full swift test suite across all 9 test bundles: 730 executed, 0 failures
    • Scripts/check_adr_references.py: PASS (0 warnings)
    • bash -n Scripts/run-biofeedback-osc.sh: PASS

Manual Acceptance Checklist (Issue 3)

  • ./Scripts/run-biofeedback-osc.sh with Mind Monitor stopped and Muse Port on port 7000: band bars and horseshoe move from synthetic EEG on the same Mac.
  • --raw-eeg on: /muse/eeg appears in a Protokol or udpdump capture; off: absent.
  • Feature disabled (no env vars): zero datagrams on UDP 7000 from the app.
  • --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 .rest window.

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
aurascoper force-pushed the feat/biofeedback-wiring branch from 4726783 to 1431c45 Compare November 8, 2026 03:23
@aurascoper
aurascoper merged commit 7645e6b into main Nov 8, 2026
0 of 2 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant