Echelon Implementation Plan

Echelon Implementation Plan

## Summary
- Translate the architecture alignment brief into actionable engineering work, ensuring the Rust engine, scheduler, AI sidecars, and UI land in lockstep with the 24-week delivery timeline.
- This plan tracks sprint-level execution with explicit dependencies, acceptance criteria, and hand-off milestones.

Phased Execution

### Phase 0 – Kickoff (Week 0)
- Confirm workstream leads and staffing matrix.
- Stand up new Rust workspace CI (lint, fmt, unit tests) and latency profiling harness.
- Baseline decision log: IPC protocol choice, UI framework (egui vs iced), licensing plan for external libs.

### Phase 1 – Engine Bring-up (Weeks 1-6)
- Audio IO Layer
- Implement `cpal` backend for macOS; stub Linux/Windows modules.
- Add real-time audio callback with double-buffered channel ring.
- Acceptance: sine test tone with measured round-trip latency <10 ms.
- Sample Graph & Deck Nodes
- Define lock-free node arena and preallocation strategy.
- Implement dual deck players with cue points, crossfade envelope.
- Acceptance: load two test WAVs, perform seamless crossfade under profiler.
- Mixer & Mastering
- Add per-deck EQ, filter stubs, master limiter using proven coefficients.
- Run continuous profiling to confirm no allocations on the audio thread.

### Phase 2 – Scheduler & Safety (Weeks 7-12)
- Transport & Link
- Integrate Ableton Link SDK; expose beat clock and transport state.
- Implement quantized action executor with configurable beat resolution.
- Safety Policies
- Port DJ Agent deck lock, cooldown, and action mask logic into Rust.
- Mirror Python regression tests with Rust property-based tests.
- MIDI & External Control
- Create virtual MIDI port and learning hooks; map baseline actions.
- Acceptance: manual MIDI controller triggers quantized play/loop without violating safety constraints.

### Phase 3 – AI & Human Interfaces (Weeks 13-18)
- Motion & Voice
- Wrap DELL bridge (FFI or IPC) to stream normalized motion features.
- Integrate `whisper-rs` command recognizer with confirmation UX.
- Phrase Intelligence
- Expose Episode 1 embeddings and ANN search as Rust service or IPC sidecar.
- Implement crate builder suggestions aligned with rehearsal flow.
- UI Surface
- Build egui/iced performance deck (two decks, phrase browser, automation curves, telemetry meters).
- Conduct usability sessions; fix critical feedback before Beta sign-off.
- Visualization
- Implement `crates/viz` library per `docs/visualize.md` with PCA/parametric projection, beat-phase halo, residual glow, attractor disk, and limb satellites.
- Extend `control-bus` with `FastState`, `SlowState`, and `Telemetry` structs plus decimated SPSC ring for visualization subscribers.
- Embed viz as optional egui widget and standalone window; guard behind `viz` cargo feature in Studio.

### Phase 4 – Computational Rehearsal & Release Prep (Weeks 19-24)
- Rehearsal Automation
- Reuse logging/replay services to run nightly critic evaluations.
- Provide UI visualization for rehearsal outcome deltas.
- Packaging & Telemetry
- Produce macOS/Windows installers (codesigned) and integrate crash telemetry.
- Pilot Rollout
- Onboard pilot DJs, capture feedback, and triage for v1.1 backlog.

## Cross-Cutting Tasks
- Performance benchmarking every sprint; target audio thread CPU <30
- Security/privacy review for motion/audio logging.
- Documentation updates each milestone (developer setup, performer quick start).

## Key Dependencies
- Ableton Link SDK license, Rubber Band/SoundTouch redistribution approval, whisper-rs model availability.
- Hardware lab access (low-latency interface, motion wearables).
- Cloud compute budget for rehearsal pipelines.

## Reporting Cadence
- Weekly engineering sync; milestone demos at phase exits.
- Latency & stability dashboard updated nightly.
- Decision log stored in repo (`docs/decisions/*.md`) with RFC process for major changes.

## Acceptance Summary
- Prototype demo: dual deck crossfade under 10 ms latency.
- Alpha demo: quantized controls + safety harness verified.
- Beta demo: motion/voice inputs driving live mix; phrase suggestions operational.
- Release candidate: computational rehearsal loop completes within 24 h with actionable updates.