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