# Design — @suaveplan/audio-engine

## Architecture overview

The package is a layered audio engine:

```
┌─────────────────────────────────────────────────────────┐
│  AudioQueueEngine  (extends AudioEngine + queue logic)  │
├─────────────────────────────────────────────────────────┤
│  AudioEngine  (context lifecycle, plugin map, metrics)  │
├─────────────────────────────────────────────────────────┤
│  AudioGraph   (plugin node connections, DAG algorithms) │
│  PluginRegistry (constructor + descriptor registration) │
│  AudioWorkletManager (module load, node lifecycle)      │
│  EventBus     (typed wrapper over @suaveplan/events)    │
├─────────────────────────────────────────────────────────┤
│  AudioPlugin  (abstract base: state, metadata, params)  │
└─────────────────────────────────────────────────────────┘
```

All layers depend downward. `AudioQueueEngine` is the only class that extends another; everything else uses composition.

## File layout

```
src/
  index.ts                          # explicit named re-exports only
  error-codes.ts                    # defineCodes + AudioEngineError
  error-codes.md
  types/
    common.ts                       # all public types + Zod schemas
    common.md
  engine/
    engine-state.ts                 # AudioEngineState enum (~20 lines)
    engine-metrics.ts               # OTel meter instruments (~40 lines)
    engine.ts                       # AudioEngine class (~280 lines)
    engine.test.ts
    engine.spec-conformance.test.ts
    engine.md
  graph/
    graph-connect.ts                # connect/disconnect + cycle detection (~100 lines)
    graph-traverse.ts               # topological sort, BFS, source/sink (~100 lines)
    graph.ts                        # AudioGraph class facade (~120 lines)
    graph.test.ts
    graph.spec-conformance.test.ts
    graph.md
  plugin/
    plugin-base.ts                  # AudioPlugin abstract class + definePlugin (~180 lines)
    plugin-base.test.ts
    plugin-base.md
  registry/
    plugin-registry.ts              # PluginRegistry class (~280 lines)
    plugin-registry.test.ts
    plugin-registry.md
  worklet/
    worklet-loader.ts               # loadModule, URL allow-list (~100 lines)
    worklet-messaging.ts            # sendMessage, setMessageListener (~80 lines)
    worklet-registry.ts             # createNode, destroyNode, stats (~120 lines)
    worklet-manager.ts              # facade re-exporting sub-modules (~60 lines)
    worklet-manager.test.ts
    worklet-manager.spec-conformance.test.ts
    worklet-manager.md
  queue-engine/
    cue.ts                          # AudioProcessingTask + task data types (~140 lines)
    scheduler.ts                    # serial/parallel chain, retry (~160 lines)
    queue-engine.ts                 # AudioQueueEngine class (~180 lines)
    queue-engine.test.ts
    queue-engine.md
  event-bus/
    event-bus.ts                    # EventBus class (~120 lines)
    event-bus.test.ts
    event-bus.md
  __benchmarks__/
    graph.bench.ts
    graph.bench.md
```

## Key design decisions

### AudioContext injection seam

`AudioEngine` accepts an optional `audioContext` in `AudioEngineConfig`. If provided, the engine skips `new AudioContext()` and uses the injected instance. This lets tests supply a mock or `standardized-audio-context` shim without patching globals.

### Error isolation (plugin quarantine)

When `loadPlugin`, `activatePlugin`, or `unloadPlugin` throws, the engine catches the error, emits an `ERROR` event, and marks the plugin state as `PluginState.ERROR`. The plugin is removed from the active set but not deleted from the map, so callers can inspect `getPlugin(id)?.state === 'error'` and decide whether to retry or remove.

### OTel instrumentation strategy

All instruments are created lazily on first access via a private `getMeter()` helper. If no `MeterProvider` is registered, the calls are no-ops (OTel API inertness guarantee). Counters:
- `audio_engine.plugin_loaded_total` — incremented on successful `loadPlugin`
- `audio_engine.plugin_failed_total` — incremented on failed `loadPlugin`
- `audio_engine.worklet_module_loaded_total` — incremented on successful `loadModule`

Histograms:
- `audio_engine.latency_ms` — recorded in `getMetrics()`
- `audio_engine.worklet_roundtrip_ms` — recorded around `sendMessage` + reply
- `audio_engine.graph_connect_ms` — recorded around `AudioGraph.connect`

### Worklet URL allow-list

`AudioWorkletManager` constructor accepts an optional `allowedOrigins: string[]`. `loadModule` rejects URLs whose origin is not in the list. Default allow-list is `['self']` (same-origin only). This prevents dynamic worklet injection attacks.

### Zod boundaries

Three schemas are validated at runtime:
- `AudioEngineConfigSchema` — parsed in `AudioEngine` constructor
- `PluginMetadataSchema` — parsed in `AudioPlugin` constructor
- `AudioPluginDescriptorSchema` — parsed in `PluginRegistry.registerDescriptor`

All other types are TypeScript-only (no runtime validation) because they are internal or consumed only by typed callers.

### No `standardized-audio-context`

The upstream imported `AudioContext` from `standardized-audio-context`. In genesis we use native Web Audio API types directly. The API surface is identical for consumers (both expose `AudioContext` and `AudioNode`). This removes a runtime dependency.

### Typed event map

`AudioEngineEventMap` replaces the upstream `AudioEngineEvents` enum:

```ts
interface AudioEngineEventMap {
  stateChanged: { previousState: AudioEngineState; currentState: AudioEngineState };
  pluginLoaded: { pluginId: string; metadata: PluginMetadata };
  // ...
}
```

`EventBus` is generic over `EventMap extends Record<string, unknown>` so that `subscribe<K>(type: K, listener: (data: EventMap[K]) => void)` is fully typed.

### Test strategy

- **Engine tests**: inject a mock `AudioContext` (minimal object with `createGain`, `destination`, `state`, `resume`, `suspend`, `close`, `sampleRate`, `currentTime`). No real browser required.
- **Graph tests**: pure logic, no audio nodes needed. Use a mock `AudioPlugin` with fake `inputNode`/`outputNode` objects.
- **Worklet tests**: mock `audioWorklet.addModule` and `AudioWorkletNode`.
- **Queue tests**: mock `@suaveplan/queue` types or use the real in-memory queue (it's lightweight).
- **Registry tests**: pure logic, no audio nodes.
- **EventBus tests**: use `@suaveplan/events` `EventEmitter` directly.

## Dependencies

- `@suaveplan/events` ✅
- `@suaveplan/logger` ✅
- `@suaveplan/queue` ✅
- `@suaveplan/error` ✅
- `@suaveplan/types` ✅
- `zod` (catalog:forms)
- `@opentelemetry/api` (catalog:observability)