suaveplan/openspec/archive/2026-05-23-enterprise-audio-codec-ffmpeg-native/tasks.md

# Tasks: enterprise-audio-codec-ffmpeg-native

Implementation checklist for `@suaveplan/audio-codec-ffmpeg-native`. Tasks are ordered;
each section must be complete before the next begins. Every `### Requirement` and
`#### Scenario` from `specs/audio-codec-ffmpeg-native/spec.md` is enumerated in §0c
working notes and checked off as implementation lands.

---

## 1. Scaffold

- [ ] Create `packages/media/audio/audio-codec-ffmpeg-native/` with `package.json`,
      `tsconfig.json`, `vitest.config.ts` (use `createTestConfig()` from
      `@suaveplan/testing/config`; `pool: 'forks'`).
- [ ] `package.json` declares `"engines": { "node": ">=20" }`, no `"browser"` field,
      `"sideEffects": false`, `"type": "module"`, and `version: "0.1.0"`.
- [ ] `dependencies`: `@suaveplan/audio-codecs workspace:^`,
      `@suaveplan/audio-core workspace:^`, `@suaveplan/streams workspace:^`,
      `@suaveplan/error workspace:^`, `@suaveplan/types workspace:^`,
      `fluent-ffmpeg catalog:audio`, `zod catalog:forms`,
      `@opentelemetry/api catalog:observability`, `tslib catalog:build`.
- [ ] `optionalDependencies`: `@ffmpeg-installer/ffmpeg catalog:audio`.
- [ ] `devDependencies`: `@suaveplan/testing workspace:^`, `vitest catalog:testing`,
      `@vitest/coverage-istanbul catalog:testing`, `fast-check catalog:testing`,
      `mitata catalog:testing`, `@types/fluent-ffmpeg catalog:types`.
- [ ] If `fluent-ffmpeg`, `@ffmpeg-installer/ffmpeg`, or `@types/fluent-ffmpeg` are
      not yet in the root `package.json` catalog block, add them under
      `catalog.audio` / `catalog.types` and re-run `bun install`.
- [ ] Declare subpath `exports` for every feature module listed in `proposal.md`
      "Module layout" plus the root barrel — every entry resolves to a typed
      `import` condition under `dist/`.
- [ ] Add per-package `tsconfig.json` extending the shared preset.

## 2. Types + error codes

- [ ] `src/error-codes.ts` — `defineCodes` with the eight
      `AUDIO_CODEC_FFMPEG_NATIVE.*` codes; export
      `AudioCodecFfmpegNativeError extends SuaveplanError`,
      `AUDIO_CODEC_FFMPEG_NATIVE_ERROR_METADATA`,
      `registerAudioCodecFfmpegNativeErrorCodes()`.
- [ ] `src/error-codes.test.ts` — assert each code is thrown by at least one call
      site (this test cross-references the per-feature tests once they exist).
- [ ] `src/error-codes.md` — Purpose / Features / Basic / Advanced / API / Notes.
- [ ] `src/constants/index.ts` — supported format lists, MIME types, default
      timeouts, default concurrency.

## 3. Binary resolver

- [ ] `src/binary/binary.ts` — `resolveBinary(opts): Promise<string>` implementing
      the 4-step discovery order; cache result on success.
- [ ] `src/binary/binary.types.ts` — `BinaryResolverOptions`,
      `ResolvedBinary` shapes.
- [ ] `src/binary/binary.test.ts` — covers `binaryProvider` precedence, explicit
      `binaryPath`, dynamic-import fallback, and `BINARY_MISSING` throw path.
- [ ] `src/binary/binary.md`.
- [ ] `src/binary/index.ts` — explicit named exports.

## 4. Semaphore

- [ ] `src/semaphore/semaphore.ts` — ~30-line FIFO semaphore with `acquire` /
      `release`; no external dep.
- [ ] `src/semaphore/semaphore.types.ts`.
- [ ] `src/semaphore/semaphore.test.ts` — concurrency cap, FIFO ordering,
      slot-release on error.
- [ ] `src/semaphore/semaphore.md`, `index.ts`.

## 5. Subprocess runner (the only place `node:child_process` / `fluent-ffmpeg` is imported)

- [ ] `src/runner/runner.ts` — `runDecode(opts)` and `runEncode(opts)`. Owns spawn,
      stdin pipe, stdout drain (chunk-by-chunk, no full-output `Buffer.concat`),
      stderr ring buffer, exit handling, timeout enforcement, semaphore release.
- [ ] `src/runner/runner.types.ts` — `RunDecodeOptions`, `RunEncodeOptions`,
      `RunnerCallbacks`, `RunnerHandles`.
- [ ] `src/runner/runner.test.ts` — happy path, non-zero exit → `_DECODE_FAILED`
      with stderr context, spawn failure → `_SPAWN_FAILED`, timeout →
      `_TIMEOUT` with SIGTERM/SIGKILL escalation observed.
- [ ] `src/runner/runner.md`, `index.ts`.

## 6. Decode pipeline

- [ ] `src/decode/decode.ts` — `decodeOneShot(bytes, opts)` orchestrating
      `runDecode` + per-channel `Float32Array` accumulators + interleave splitter.
- [ ] `src/decode/decode.types.ts`.
- [ ] `src/decode/decode.test.ts` — well-formed `DecodeResult`,
      chunk-by-chunk assertion (instrument runner to count `Buffer.concat`),
      `_DECODE_FAILED` with stderr in context, `canDecode` delegation.
- [ ] `src/decode/decode.md`, `index.ts`.

## 7. Encode pipeline

- [ ] `src/encode/encode.ts` — `encodeOneShot(pcm, opts)` with PCM-shape validation,
      interleaver writing into a 64 KiB working buffer, runner invocation.
- [ ] `src/encode/encode.types.ts`.
- [ ] `src/encode/encode.test.ts` — round-trip through decode, `_INVALID_PCM` for
      ragged channels, `_UNSUPPORTED_CODEC` for unknown format and for WMA encode.
- [ ] `src/encode/encode.md`, `index.ts`.

## 8. Streaming adapters

- [ ] `src/stream/stream-decoder.ts` — `createDecoder(opts)` returning
      `StreamingDecoder`; `createDecodeTransform(opts)` returning a
      `@suaveplan/streams` `TransformStream<Uint8Array, AudioPage>`.
- [ ] `src/stream/stream-encoder.ts` — `createEncoder(opts)` returning
      `StreamingEncoder`; `createEncodeTransform(opts)` returning a
      `TransformStream<Float32Array[], Uint8Array>`.
- [ ] Sibling `.types.ts`, `.test.ts`, `.md` for each; tests cover chunked-write
      equivalence, TransformStream composition, encoder yielding before flush.
- [ ] `src/stream/index.ts` — explicit named exports.

## 9. AbortSignal wiring

- [ ] `src/abort/abort.ts` — `attachAbort(child, signal, semaphoreRelease)`:
      sends `SIGTERM`, starts 1 s timer, escalates to `SIGKILL`, releases slot,
      rejects with `_ABORTED`. Short-circuit path for pre-aborted signals.
- [ ] `src/abort/abort.types.ts`.
- [ ] `src/abort/abort.test.ts` — pre-aborted short-circuit (no spawn observed),
      mid-decode SIGTERM → SIGKILL escalation under a child that ignores SIGTERM.
- [ ] `src/abort/abort.md`, `index.ts`.

## 10. OpenTelemetry instrumentation

- [ ] `src/otel/otel.ts` — span / counter / histogram / inflight-gauge helpers;
      inert without exporter; no import-time side effects.
- [ ] `src/otel/otel.types.ts`, `otel.test.ts` (in-memory `MeterProvider` +
      `TracerProvider`), `otel.md`, `index.ts`.

## 11. Codec class + register helper

- [ ] `src/codec/codec.ts` — `FfmpegNativeCodec` implementing `AudioCodec`. Owns
      the per-instance semaphore, the cached binary path, the OTel handles, and
      delegates to `decode/`, `encode/`, `stream/` modules.
- [ ] `src/codec/codec.schemas.ts` — `FfmpegNativeCodecOptionsSchema`,
      `EncodeOptsSchema` (Zod).
- [ ] `src/codec/codec.types.ts`, `codec.test.ts` (constructor Zod validation,
      `canDecode` rejection without spawn, WMA encode short-circuit, full
      `DecodeResult` shape), `codec.md`, `index.ts`.
- [ ] `src/register/register.ts` — `register(registry, options?)` idempotent
      installer.
- [ ] `src/register/register.test.ts`, `register.types.ts`, `register.md`,
      `index.ts`.

## 12. Root barrel

- [ ] `src/index.ts` — explicit named re-exports of every public symbol from each
      feature module. No `export *` (rule 10 / §6a).

## 13. Tests — purity, integration, exports

- [ ] `tests/purity.test.ts` — built dist has no browser globals; `child_process`
      imported only from `src/runner/runner.ts`; package import mutates no global
      OTel state.
- [ ] `tests/integration.test.ts` — full round-trip across every declared
      encodable format using the bundled `@ffmpeg-installer/ffmpeg` binary.
- [ ] `tests/exports.test.ts` — every feature module has a working subpath export
      entry and is independently importable.
- [ ] Every test file imports runner primitives from
      `@suaveplan/testing/runner` (rule 11 / §7).

## 14. Benchmarks

- [ ] `src/__benchmarks__/codec.bench.ts` — mitata suite: decode 10 s WAV,
      decode 10 s MP3, encode 10 s WAV→MP3, concurrent-decode at `concurrencyLimit`
      = 4. Use `--cpu-prof-md` / `--heap-prof-md` for LLM-assisted analysis.
- [ ] Publish baseline numbers in `README.md`.

## 15. Documentation

- [ ] Every `.ts` (excluding `.test.ts`, `.types.ts`, `.schemas.ts`, barrel
      `index.ts`) has a sibling `.md` meeting §4: ≥200 words, Purpose / Features
      / Basic / Advanced / API Reference / Implementation Notes.
- [ ] `README.md` at package root: name, one-paragraph description, install,
      quick-start, Modules section linking every `src/<feature>/<feature>.md`,
      format support matrix from `design.md`, baseline benchmark numbers.

## 16. Pre-publish gates (§13)

- [ ] Step 0 — Spec reconciliation: walk every requirement and `Verified by` from
      the spec delta; confirm every symbol, span, counter, error code, and test
      name exists verbatim in `src/`. STOP if any item is unmatched.
- [ ] `bunx turbo lint typecheck test --filter=@suaveplan/audio-codec-ffmpeg-native`.
- [ ] `bun run check` (biome).
- [ ] `bunx turbo test:coverage --filter=@suaveplan/audio-codec-ffmpeg-native`
      reports 100 / 100 / 100 / 100 (istanbul).
- [ ] `bunx turbo build --filter=@suaveplan/audio-codec-ffmpeg-native`.
- [ ] Banned-pattern scan: zero hits for `@deprecated`, `TODO`, `FIXME`,
      `ts-ignore`, `ts-expect-error`, `.skip`, `.only`, bare `any`, `console.log`.
- [ ] Barrel scan (§13 step 4a): zero `export *` in feature barrels.
- [ ] Test-runner import scan (§13 step 4b): zero direct
      `from "vitest"` / `from "bun:test"` imports.
- [ ] Missing-`.md` scan returns zero output.
- [ ] `README.md` present.
- [ ] Bare-version scan returns zero output.
- [ ] Subpath-export count matches feature-module count.
- [ ] Security scan for hardcoded secrets returns zero output.
- [ ] (Not a foundation package — dependent sweep optional; run it anyway since
      this is a fresh public surface.)

## 17. Root-doc refresh + markdownlint (§13b)

- [ ] `bun scripts/folder-reorg/generate-manifest.ts` → refresh `MANIFEST.md`.
- [ ] `bun scripts/generate-missing.ts` → refresh `MISSING.yml`.
- [ ] Move the package row from Pending → Completed in `STATUS.md`.
- [ ] Add the per-package paragraph in `SUMMARY.md`.
- [ ] `bunx markdownlint-cli2 --fix`; resolve any remaining violations by hand.

## 18. Fold spec into canonical location

- [ ] Fold
      `openspec/changes/enterprise-audio-codec-ffmpeg-native/specs/audio-codec-ffmpeg-native/spec.md`
      into `openspec/specs/audio-codec-ffmpeg-native/spec.md` per §14.

## 19. Archive

- [ ] Move `openspec/changes/enterprise-audio-codec-ffmpeg-native/` to
      `openspec/archive/2026-05-15-enterprise-audio-codec-ffmpeg-native/`.