# Enterprise Migration: @suaveplan/audio-engine

**Package**: `@suaveplan/audio-engine`
**Status**: PROPOSED
**Type**: new-package (migration from suaveplan)

## Why

`@suaveplan/audio-engine` is the core browser-side Web Audio engine used by every audio surface in the monorepo. It owns the `AudioContext` lifecycle, typed plugin system (`AudioPlugin` + `PluginRegistry`), `AudioGraph` node-routing, `AudioWorkletManager`, `AudioQueueEngine`, and `EventBus`. Migrating it to genesis is a prerequisite for `audio-plugins-fx`, `audio-controllers`, and all `react-audio*` packages. The upstream version lacks tests for graph / queue / worklet / registry, exceeds file-size caps, uses plain `Error` throws, and has no OTel or Zod boundaries.

## What changes

- ADDED: `AudioEngine` class with `AudioContext` injection seam — initialize, resume, suspend, destroy, plugin lifecycle, metrics.
- ADDED: `AudioGraph` class — node add/remove, connect/disconnect with cycle detection, topological sort, BFS path finding, serialization.
- ADDED: `AudioQueueEngine` class — extends `AudioEngine` with `@suaveplan/queue`-based serial/parallel plugin chains, retry, rate limiting.
- ADDED: `AudioWorkletManager` class — module loading, node creation, messaging, statistics.
- ADDED: `PluginRegistry` class — constructor + descriptor registration, dependency validation, search, instantiation.
- ADDED: `EventBus` class — typed wrapper around `@suaveplan/events` with per-listener error isolation.
- ADDED: `AudioPlugin` abstract base class — state machine, metadata, parameters, node accessors.
- ADDED: Error codes via `@suaveplan/error` (`AUDIO_ENGINE_STATE_INVALID`, `PLUGIN_NOT_FOUND`, `GRAPH_CYCLE_DETECTED`, `WORKLET_LOAD_FAILED`, etc.).
- ADDED: Zod boundary schemas for `AudioEngineConfig`, `PluginMetadata`, `AudioPluginDescriptor`.
- ADDED: OTel counters/histograms for plugin loads, engine latency, worklet round-trip, graph connect duration.
- ADDED: Plugin quarantine — a crashing plugin is marked `ERROR` without tearing down the engine or other plugins.
- ADDED: Worklet module URL allow-list gate.
- ADDED: Co-located `.md` docs for every exported symbol.
- ADDED: Benchmarks for graph traversal and worklet messaging.

## Out of scope

- Plugin hot-swap with crossfade ramp — new feature, not in upstream; deferred to follow-up change.
- Latency budget enforcement / watchdog — new feature; deferred.
- MIDI clock source transport — new feature; deferred.
- Sample-accurate parameter automation curves — new feature; deferred.
- `SharedArrayBuffer`-backed meter/analyser — new feature; deferred.
- Worklet hot-reload for dev-time — new feature; deferred.
- `OfflineAudioContext` render-on-demand mode — new feature; deferred.
- `ScriptProcessorNode` fallback for non-worklet browsers — upstream uses `standardized-audio-context` which handles this; we retain the upstream abstraction level without adding a new fallback layer.

## Source mapping

This change derives from `../suaveplan/enterprise/audio-engine.md`.

| Requirement | Source lines | Notes |
|---|---|---|
| Split files over 300-line cap | L46 | engine → engine + state + metrics; graph → graph + connect + traverse; queue → queue + cue + scheduler; worklet → loader + messaging + registry |
| Unit tests for every module | L47 | graph, queue, worklet, registry, plugin base, event-bus |
| AudioContext injection seam | L48 | constructor accepts pre-built context |
| Typed event map | L49 | replaces `AudioEngineEvents` enum |
| OTel metrics | L50 | counters + histograms |
| Worklet URL allow-list | L52 | security gate |
| Plugin lifecycle docs | L53 | state diagram in README + per-symbol `.md` |
| Coverage ≥ 95 % | L57 | genesis policy is 100 % |
| File budget 250/300/500 | L59 | enforced |
| No `any` / `ts-ignore` | L64 | enforced |
| Zod schemas at boundaries | L65 | `PluginMetadata`, `AudioPluginDescriptor` |
| Error hierarchy | L66 | via `@suaveplan/error` |
| Plugin quarantine | L111 | error isolation per plugin |

### Requirements with no source line

| Requirement | Justification |
|---|---|
| 100 % Istanbul coverage threshold | Genesis-wide policy (AGENTS.md §5, §13) |
| No direct `vitest` imports | Genesis-wide policy (AGENTS.md §7) |
| `export *` banned in feature barrels | Genesis-wide policy (AGENTS.md §6a) |
| `sideEffects: false` retained | Genesis-wide policy |

## Verification approach

- `src/engine/engine.test.ts` — AudioEngine lifecycle, state transitions, plugin load/unload, metrics, destruction.
- `src/engine/engine.spec-conformance.test.ts` — OTel instrument assertions, Zod boundary rejection, typed event map.
- `src/graph/graph.test.ts` — node management, connect/disconnect, cycle detection, topological sort, path finding, serialization.
- `src/graph/graph.spec-conformance.test.ts` — strict-mode error paths, graph stats, clone round-trip.
- `src/queue-engine/queue-engine.test.ts` — serial/parallel chain processing, retry, rate limit, queue status.
- `src/worklet/worklet-manager.test.ts` — module load/unload, node create/destroy, messaging, statistics.
- `src/worklet/worklet-manager.spec-conformance.test.ts` — URL allow-list rejection, OTel round-trip histogram.
- `src/registry/plugin-registry.test.ts` — constructor/descriptor registration, dependency validation, search, instantiation.
- `src/event-bus/event-bus.test.ts` — subscribe/unsubscribe, emit, listener error isolation.
- `src/plugin/plugin-base.test.ts` — AudioPlugin abstract class, state machine, parameter get/set.
- `tests/purity.test.ts` — zero import-time side effects, no global mutation.
- `tests/integration.test.ts` — full engine + graph + registry round-trip.
- `src/__benchmarks__/graph.bench.ts` — graph traversal performance.
- `src/__benchmarks__/worklet.bench.ts` — worklet messaging round-trip.

## Migration impact

Packages awaiting this dependency:
- `@suaveplan/audio-plugins-fx`
- `@suaveplan/audio-controllers`
- `@suaveplan/react-audio`
- `@suaveplan/react-audio-player`
- `@suaveplan/react-audio-stream`
- `@suaveplan/r3f-audio`

None are yet migrated, so impact is sequencing-only.