suaveplan/openspec/archive/2026-05-15-superseded-enterprise-audio-engine/design.md

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:

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)