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

Tasks — Enterprise Migration: @suaveplan/audio-engine

Every checkbox MUST reflect work actually done in this change.

1. Spec authoring

• 1.1 Read ../suaveplan/enterprise/audio-engine.md end-to-end
• 1.2 Read openspec/AGENTS.md Sections 13 and 14
• 1.3 Draft proposal.md
• 1.4 Fill ## Source mapping table
• 1.5 Draft specs/audio-engine/spec.md
• 1.6 Every requirement carries **Verified by:** with concrete it(...) titles

2. Scaffold

• 2.1 Create packages/audio/audio-engine/ with src/, tests/, src/__benchmarks__/
• 2.2 Write package.json at 0.1.0, sideEffects: false, exports map
• 2.3 Write tsconfig.json, vitest.config.ts, vite.config.ts
• 2.4 Add lint/typecheck/test/test:coverage/build scripts

3. Types + errors

• 3.1 Write src/types/common.ts — AudioEngineConfig, AudioEngineState, PerformanceMetrics, AudioEngineStateInfo, PluginState, PluginConfig, PluginMetadata, AudioPluginDescriptor, PluginParameter, PluginMetrics, AudioGraphConnection, AudioGraphNode, AudioGraphSerialized, AudioWorkletNodeOptions, WorkletNodeInfo, WorkletModuleInfo, AudioEngineEventMap
• 3.2 Write Zod schemas for AudioEngineConfig, PluginMetadata, AudioPluginDescriptor
• 3.3 Write src/error-codes.ts — AUDIO_ENGINE_CODES, AudioEngineError, AUDIO_ENGINE_ERROR_METADATA
• 3.4 Write src/types/common.md
• 3.5 Write src/error-codes.md

4. Core engine

• 4.1 Write src/engine/engine-state.ts — AudioEngineState enum, state transition helpers
• 4.2 Write src/engine/engine-metrics.ts — PerformanceMetrics, OTel instruments
• 4.3 Write src/engine/engine.ts — AudioEngine class (≤300 lines)
• 4.4 Write src/engine/engine.test.ts and engine.spec-conformance.test.ts
• 4.5 Write src/engine/engine.md

5. Audio graph

• 5.1 Write src/graph/graph.ts — AudioGraph class (≤300 lines)
• 5.2 Write src/graph/graph-connect.ts — connection helpers, cycle detection
• 5.3 Write src/graph/graph-traverse.ts — topological sort, BFS path, source/sink detection
• 5.4 Write src/graph/graph.test.ts and graph.spec-conformance.test.ts
• 5.5 Write src/graph/graph.md

6. Plugin base + registry

• 6.1 Write src/plugin/plugin-base.ts — AudioPlugin abstract class, definePlugin
• 6.2 Write src/plugin/plugin-base.test.ts
• 6.3 Write src/registry/plugin-registry.ts — PluginRegistry class
• 6.4 Write src/registry/plugin-registry.test.ts
• 6.5 Write src/plugin/plugin-base.md and src/registry/plugin-registry.md

7. Worklet manager

• 7.1 Write src/worklet/worklet-loader.ts — module loading, URL allow-list
• 7.2 Write src/worklet/worklet-messaging.ts — send/receive/broadcast
• 7.3 Write src/worklet/worklet-registry.ts — node create/destroy, statistics
• 7.4 Write src/worklet/worklet-manager.ts — facade re-exporting the three sub-modules
• 7.5 Write src/worklet/worklet-manager.test.ts and worklet-manager.spec-conformance.test.ts
• 7.6 Write src/worklet/worklet-manager.md

8. Queue engine

• 8.1 Write src/queue-engine/cue.ts — AudioProcessingTask, task data types
• 8.2 Write src/queue-engine/scheduler.ts — serial/parallel chain execution, retry
• 8.3 Write src/queue-engine/queue-engine.ts — AudioQueueEngine class (≤300 lines)
• 8.4 Write src/queue-engine/queue-engine.test.ts
• 8.5 Write src/queue-engine/queue-engine.md

9. Event bus

• 9.1 Write src/event-bus/event-bus.ts — typed wrapper with error isolation
• 9.2 Write src/event-bus/event-bus.test.ts
• 9.3 Write src/event-bus/event-bus.md

10. Integration + purity

• 10.1 Write tests/integration.test.ts — full round-trip
• 10.2 Write tests/purity.test.ts — zero side effects on import
• 10.3 Write tests/exports.test.ts — every public export is reachable

11. Benchmarks

• 11.1 Write src/__benchmarks__/graph.bench.ts
• 11.2 Write src/__benchmarks__/worklet.bench.md

12. Root docs

• 12.1 Write README.md with quick-start, plugin lifecycle state diagram, module links
• 12.2 Write src/index.ts with explicit named re-exports only

13. Pre-archive 5-gate triple

• 13.1 bun run check — Biome 0/0/0 across monorepo
• 13.2 bunx turbo lint typecheck test --filter=@suaveplan/audio-engine — green
• 13.3 bunx turbo test:coverage --filter=@suaveplan/audio-engine — 100/100/100/100
• 13.4 bun scripts/openspec-conformance.ts @suaveplan/audio-engine — exit 0
• 13.5 bunx turbo build --filter=@suaveplan/audio-engine — green

14. Pre-archive 7-row checklist

• 14.1 Generics threaded; expectTypeOf assertions on literal-type claims
• 14.2 Zod schemas wired at every declared boundary
• 14.3 Every error code thrown by at least one production path
• 14.4 Strict-mode behaviors tested both on and off
• 14.5 OTel instruments emitted and asserted with real MeterProvider
• 14.6 Lifecycle dedup tested (in-flight Promise, idempotent set/load)
• 14.7 No retroactive tick

15. Archive

• 15.1 Fold spec delta into openspec/specs/audio-engine/spec.md
• 15.2 Move openspec/changes/enterprise-audio-engine/ → openspec/archive/YYYY-MM-DD-enterprise-audio-engine/
• 15.3 Update STATUS.md row to ✅
• 15.4 Regenerate MANIFEST.md