# 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/`.