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

Tasks: enterprise-audio-transport

Change ID: enterprise-audio-transport Package: @suaveplan/audio-transport Target path: packages/audio/audio-transport Prerequisite packages on Verdaccio: @suaveplan/timing, @suaveplan/events, @suaveplan/fsm, @suaveplan/types, @suaveplan/error

---

1. Scaffold

• Create directory packages/audio/audio-transport/ with src/, tests/, src/__benchmarks__/, and all feature subdirectories per the layout in proposal.md.
• Write package.json at version 0.1.0 with "type": "module", "sideEffects": false, full exports map, deps: @suaveplan/timing workspace:^, @suaveplan/events workspace:^, @suaveplan/fsm workspace:^, @suaveplan/types workspace:^, @suaveplan/error workspace:^, zod catalog:forms.
• Write tsconfig.json extending @suaveplan/typescript-config/library.json.
• Write vitest.config.ts using createTestConfig() from @suaveplan/testing/config.
• Add lint, typecheck, test, test:coverage, build, docs:check scripts.

---

2. Types + errors

• Write src/transport/transport.types.ts — TransportOptions, TransportTime, Ticks, BarsBeatsSixteenths, BPM, Subdivision, TransportCallback, TransportEventMap.
• Write src/scheduler/scheduler.types.ts — SchedulerState.
• Write src/tick-source/tick-source.types.ts — TickSourceState.
• Write src/signal/signal.types.ts — SignalConfig.
• Write src/time/time.types.ts — TimeToken, TimeParseResult.
• Write co-located .md files for each types module (≥200 words).
• Write src/error-codes.ts — TransportErrorCode, AUDIO_TRANSPORT_ERROR_METADATA, registerTransportErrorCodes().
• Write Zod schemas: TransportOptionsSchema, TransportTimeSchema, TicksSchema, BarsBeatsSixteenthsSchema.

---

3. Signal module

• Implement src/signal/signal.ts — Signal<BPM> wrapper around @suaveplan/timing Signal with ramp/hold curves for tempo automation.
• Write signal.test.ts and signal.md.

---

4. Time parsing

• Implement src/time/time.ts — parse musical time strings ("4n", "8t", "1m", "2:1:0", "+1", "@4m"), convert to seconds and ticks, toSeconds, toTicks, toBarsBeatsSixteenths.
• Write time.test.ts and time.md.

---

5. TickSource

• Implement TickSource in src/tick-source/tick-source.ts:
  • getTicksAtTime, getTimeOfTick, setTicksAtTime with tempo curve support.
  • start, stop, pause with offset handling.
  • forEachTickBetween iterating ticks between two audio times, invoking callback with sample-accurate time and ticks.
• Write tick-source.test.ts and tick-source.md.

---

6. TransportScheduler

• Implement TransportScheduler in src/scheduler/scheduler.ts:
  • Constructor takes Transport and Clock.
  • start() begins the ~100Hz lookahead loop via @suaveplan/timing createScheduler.
  • stop() halts the scheduler.
  • On each tick: emit FSM state changes between last update and now, then invoke tickSource.forEachTickBetween to fire scheduled callbacks with sample-accurate times.
• Write scheduler.test.ts and scheduler.md.

---

7. Transport

• Implement Transport in src/transport/transport.ts:
  • Constructor accepts TransportOptions; initializes TickSource, FSM state machine (stopped → playing → paused), and internal event list.
  • start, stop, pause drive FSM transitions and tick source.
  • schedule, scheduleRepeat, scheduleOnce return numeric event IDs; store callbacks in a priority queue.
  • cancel removes event by ID; cancelAfter removes all events after a given time.
  • bpm as Signal<BPM> with ramp/hold support.
  • swing (0..1) and swingSubdivision applied per-tick during _processTick() using sine-based offset.
  • toSeconds, toTicks, toBarsBeatsSixteenths delegate to time module.
  • loop, loopStart, loopEnd — when enabled, transport jumps to loopStart after crossing loopEnd.
  • Events: start, stop, pause, loop, bpm via @suaveplan/events.
  • dispose() cancels all events, stops scheduler, and cleans up.
• Write transport.test.ts (≤500 lines): start/stop/pause, schedule/cancel, loop region, tempo ramp, swing application, time conversion round-trip.
• Write transport.md.

---

8. Benchmarks

• Write src/__benchmarks__/transport.bench.ts — schedule 1 000 callbacks, 100 BPM ramps, 10 000 tick iterations.

---

9. Integration tests

• Write tests/integration.test.ts — full transport lifecycle with FakeClock: start, schedule repeated callback, verify callback times are sample-accurate, loop jump, cancel after time, tempo automation curve.

---

10. Docs + verify + publish

• All co-located .md files (≥200 words each).
• Write README.md at package root.
• bunx turbo lint typecheck test --filter=@suaveplan/audio-transport — green.
• bunx turbo test:coverage --filter=@suaveplan/audio-transport — 100%.
• bun scripts/publish.ts --package @suaveplan/audio-transport.
• Fold specs/audio-transport/spec.md into openspec/specs/audio-transport/spec.md.
• Archive to openspec/archive/2026-05-14-enterprise-audio-transport/.