Echelon Architecture Alignment Brief

Echelon Architecture Alignment Brief

## Purpose
- Align the new Rust-based performance instrument plan with existing Computational Studio capabilities and Episode 1 assets before parallel implementation starts.
- Document reuse targets, gaps, and decision points so engine, AI, UI, and ops teams can execute in lockstep.

## Product Scope & Surface
- Target the Standalone Rust DAW as the primary experience to deliver the differentiated real-time control surface, while preserving a clear integration path for the Serato/Ableton bridge as outlined in the product tiers (`Echelon.md` lines 190-206).
- Maintain compatibility hooks for the future cloud rehearsal companion so nightly training loops can progress without blocking the on-device release (`Echelon.md` lines 207-214, 236-239).
- Frame the user journey around rehearsal → preparation → live performance → computational rehearsal so feature priorities reflect the promised flow (`Echelon.md` lines 219-238).

## Workspace Layout (Rust)
- `apps/studio` orchestrates threads and runtime wiring.
- Core crates: `audio-engine`, `scheduler`, `ui-shell`, `control-bus`, `media`, `midi-osc`, `dsp-utils`, `link-clock`, `ts-shift`, `shmem-ipc`, `viz`.
- `xtask` hosts developer tooling; `docs/` captures plans/to-dos; configs live under `apps/studio/src/config`.
- Sidecars will reside in `sidecars/` and are bridged via `shmem-ipc` once implemented.

## Visualization Concept (crates/viz)
- Follow `docs/visualize.md` to render the latent manifold, beat phase, solver residual, slow attractor, and limb energies without disturbing the audio thread.
- Default projector weights live at `configs/visualization/projector.json`; override via `ECHELON_VIZ_PROJECTOR`.
- Extend `control-bus` with `FastState`, `SlowState`, and `Telemetry` snapshots; scheduler publishes decimated frames to a dedicated ring buffered for the viz subscriber.
- Provide both embedded (egui widget) and standalone window modes so Studio can ship headless or with an instrument-grade monitor.

## Current Assets & Reuse
- Computational Studio already hits real-time fusion, audio bridge, and telemetry targets (<10 ms pipeline, multi-device sensor handling, OSC/Ableton integration) that form the backbone for Echelon control and monitoring (`computational-studio/README.md` lines 9-99, 121-125).
- Episode 1 delivered 35+ modules, logging/replay infrastructure, and the DELL motion interpreter that can be wrapped rather than rewritten (`EPISODE1_OVERVIEW.py` lines 27-84, 59-62, 74-82).
- The DJ Agent work provides mature safety policies, action scheduling, and automation tests that should be ported into Rust to accelerate quantization and deck protection (`COMPLETE_IMPLEMENTATION_SUMMARY.txt` lines 21-49, 63-74, 144-149).

## Rust ↔ AI Boundary
- Keep the audio engine callback allocation-free and lock-free, confining clip playback, mixer, FX, and mastering to Rust real-time threads (`Echelon.md` lines 25-31, 35-39).
- Run ASR, diffusion, ANN search, and phrase planning as external sidecars communicating through ring buffers/IPC so stalls never compromise playback (`Echelon.md` lines 13-21, 19-20, 153-155).
- Treat DELL motion features, voice intent decoding, and phrase selection as services that emit quantized intents to the scheduler, mirroring the patterns already proven in the Python runtime (`EPISODE1_OVERVIEW.py` lines 35-48, 68-76; `COMPLETE_IMPLEMENTATION_SUMMARY.txt` lines 21-27).

## Workstreams & Milestones
- Milestone 1 – Engine Bring-up: Stand up the cpal/cubeb driver, dual deck playback, and limiter; validate latency budgets before layering control logic (`Echelon.md` lines 133-135).
- Milestone 2 – Scheduler + Link: Implement transport, beat quantization, and Link sync, adopting existing DJ Agent action masks for safety (`Echelon.md` lines 136-141; `COMPLETE_IMPLEMENTATION_SUMMARY.txt` lines 144-148).
- Milestone 3 – Human Interfaces: Deliver MIDI learn, motion, and voice integrations built on Episode 1 telemetry and DELL pipelines (`Echelon.md` lines 149-150; `EPISODE1_OVERVIEW.py` lines 35-48, 68-76).
- Milestone 4 – Phrase Intelligence: Expose the phrase database and ANN tooling with latency guarantees, tied into the rehearsal-driven crate builder (`Echelon.md` lines 142-147, 224-228).
- Milestone 5 – Computational Rehearsal: Reuse logging/replay services to automate post-show training loops and close the feedback cycle (`Echelon.md` lines 151-154, 236-239; `EPISODE1_OVERVIEW.py` lines 59-62, 68-76).

## Open Decisions & Immediate Actions
- Finalize the minimal standalone UI scope (deck view, phrase browser, automation curves) and assign design owner.
- Confirm the IPC protocol between Rust engine and Python sidecars (ring buffer vs shared memory vs gRPC) to unblock interface definitions.
- Produce a dependency audit for external libraries (Ableton Link SDK, Rubber Band, whisper-rs) and start legal/licensing review.
- Schedule the cross-functional kickoff to validate this brief, then spin the Rust workspace and CI harness aligned with the milestones above.