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
8 changes: 4 additions & 4 deletions Evaluation/reports/decision_registry.md
Original file line number Diff line number Diff line change
Expand Up @@ -107,7 +107,7 @@ Each entry:
- **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 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. 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) -->
- **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`), `BiofeedbackCoordinatorTests.swift` (12 tests), `Tests/NeuralComposeAppTests/BiofeedbackConfigurationTests.swift` (12 tests), `Tests/BCIEEGTests/OSCEncoderTests.swift`, `Tests/BCIBiofeedbackTests/GoldenEgressReplayTests.swift` (`Fixtures/golden_egress_v1.json`, 303 windows), and `Tests/BCIBiofeedbackTests/MuseValidationAlphaTests.swift` (`Fixtures/muse_validation_alpha_v1.json`, 6 sessions).
- **Confidence:** High for the egress core, app wiring, and deterministic replay: the design is isolated and all 78 unit/replay tests across `BCIBiofeedbackTests`, `BiofeedbackConfigurationTests`, and `OSCEncoderTests` compiled and passed on M4 under Swift 6.0; validated against the golden recording and the six `muse_validation_converted` sessions.
- **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. PR 5 replay evidence landed: 303 golden windows pinned; eyes-closed alpha doubles on TP9 and TP10 only in 014223 (+0.4615 / +0.5651 Bels median rise) and 015723 (+0.4277 / +0.3716 Bels median rise); 013820 fails as the expected negative (+0.0616 / +0.2422 Bels). Live DAW acceptance (issues 3 and 4) still pending.
<!-- Last updated: 2026-11-07T20:44:00-06:00 (entry 10: PR 5 replay evidence landed; golden_egress_v1.json + muse_validation_alpha_v1.json committed) -->
6 changes: 5 additions & 1 deletion Package.swift
Original file line number Diff line number Diff line change
Expand Up @@ -393,7 +393,11 @@ let package = Package(
// BCIEEG for the OSCMessage type and MuseOSCDecoder, which the
// encoder round-trip and mirror tests decode against.
dependencies: ["BCIBiofeedback", "BCICore", "BCIEEG"],
path: "Tests/BCIBiofeedbackTests"
path: "Tests/BCIBiofeedbackTests",
// Fixtures/*.json are read by file path (relative to #filePath)
// like BCIEEGTests' reference_pipeline.json, so they are excluded
// rather than bundled as SwiftPM resources.
exclude: ["Fixtures"]
),
.testTarget(
name: "WorldModelDemoTests",
Expand Down
20 changes: 20 additions & 0 deletions Tests/BCIBiofeedbackTests/Fixtures/README.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,20 @@
# Biofeedback egress fixtures

Derived artifacts only. The recordings they are computed from
(`Recordings/golden/*.eeg.csv`, `Recordings/muse_validation_converted/`,
`Recordings/muse_validation_*.json`) are gitignored and never leave the
machine that recorded them; what is committed here is band powers in
Bels, health codes, and the OSC/MIDI the egress produced from them.

| File | Produced by | Regenerate with |
|---|---|---|
| `golden_egress_v1.json` | `GoldenEgressReplayTests` | `NEURALCOMPOSE_REGENERATE_REFERENCE=1 swift test --filter GoldenEgressReplayTests` |
| `muse_validation_alpha_v1.json` | `MuseValidationAlphaTests` | `NEURALCOMPOSE_REGENERATE_REFERENCE=1 swift test --filter MuseValidationAlphaTests` |

Note on `muse_validation_20260710-004345`: this earliest session has a `-12.19 s` backwards timestamp jump at the `open` to `closed` boundary (`openClosedBoundaryGap = -12.186603`, a ring-buffer read-back of samples already recorded rather than a pause) and has no QC sidecar. It is marked as **overlapping segments, excluded from physiology claims** and is retained in `muse_validation_alpha_v1.json` only as a structural record of the raw directory.

Regeneration is a deliberate act after a DSP or mapping change: inspect
the diff, confirm it is the change you meant, and commit. When the
recordings are absent (fresh checkout, CI) both tests skip; when the
recordings are present and a fixture is absent, the test still runs its
hard-coded pins and then skips with the regenerate instruction.
Loading
Loading