# `error-codes`

<!-- begin:auto-docs -->
_(no submodules)_
<!-- end:auto-docs -->

## Purpose

This module owns the stable, namespaced error-code registry for
`@suaveplan/audio-codec-ffmpeg-native`. Every operational failure raised by the
package — binary-resolution mishaps, spawn/IO errors, codec-level decode/encode
failures, lifecycle events (timeout, abort) and input-validation rejections —
flows through a single `AudioCodecFfmpegNativeError` typed subclass whose code
field is narrowed to the union of `AUDIO_CODEC_FFMPEG_NATIVE.*` strings.

This centralisation lets consumers do exhaustive `switch (err.code)` dispatch
with TypeScript checking, and it gives observability the canonical label set to
attribute span events and metric counters against without per-call-site
stringly-typed labels.

## Features

- Eight stable codes covering binary, spawn, decode, encode, timeout, abort,
  unsupported-codec and invalid-PCM failure modes.
- `defineCodes("AUDIO_CODEC_FFMPEG_NATIVE", [...])` produces frozen
  `<namespace>.<reason>` constants and a precise literal-union type.
- `AudioCodecFfmpegNativeError` subclass of `SuaveplanError` preserves
  `cause`, `context`, `traceId`, and the inherited timestamp.
- `AUDIO_CODEC_FFMPEG_NATIVE_ERROR_METADATA` records per-code description +
  severity for human-readable surfacing (logs, dashboards).

## Usage: Basic

```ts
import {
    AUDIO_CODEC_FFMPEG_NATIVE_CODES,
    AudioCodecFfmpegNativeError,
} from "@suaveplan/audio-codec-ffmpeg-native/error-codes";

throw new AudioCodecFfmpegNativeError(
    AUDIO_CODEC_FFMPEG_NATIVE_CODES.BINARY_MISSING,
    "ffmpeg-native.binary.missing",
);
```

## Usage: Advanced

```ts
import {
    AUDIO_CODEC_FFMPEG_NATIVE_CODES,
    AUDIO_CODEC_FFMPEG_NATIVE_ERROR_METADATA,
    AudioCodecFfmpegNativeError,
} from "@suaveplan/audio-codec-ffmpeg-native/error-codes";

try {
    await someFfmpegOperation();
} catch (cause) {
    const code = AUDIO_CODEC_FFMPEG_NATIVE_CODES.DECODE_FAILED;
    throw new AudioCodecFfmpegNativeError(code, "ffmpeg-native.decode.failed", {
        cause,
        context: {
            severity: AUDIO_CODEC_FFMPEG_NATIVE_ERROR_METADATA[code].severity,
            stderr: "...last 4 KiB of ffmpeg stderr...",
        },
    });
}
```

## API Reference

- `AUDIO_CODEC_FFMPEG_NATIVE_CODES` — frozen record of namespaced codes.
- `AudioCodecFfmpegNativeErrorCode` — string-literal union of all codes.
- `AUDIO_CODEC_FFMPEG_NATIVE_ERROR_METADATA` — `Record<Code, { description, severity }>`.
- `AudioCodecFfmpegNativeError` — concrete `SuaveplanError` subclass; constructor
  takes `(code, messageKey, options)`; `options.context.stderr` carries the
  ffmpeg stderr tail when available.

## Implementation Notes

The eight codes are intentionally minimal: spec-level failure scenarios collapse
into one of these eight. `BINARY_MISSING` is reserved for the resolution
preflight, `SPAWN_FAILED` for `child_process.spawn` errors before any output is
read, and `DECODE_FAILED` / `ENCODE_FAILED` are the post-spawn ffmpeg-exit
failures. `TIMEOUT` and `ABORTED` share the SIGTERM-then-SIGKILL escalation
path; only their code distinguishes the trigger.

`AudioCodecFfmpegNativeError` deliberately mirrors the `AudioCodecsError`
shape (public constructor + `category` literal + `name` override) so that
multi-codec error funnels can discriminate by `category` without
runtime-importing every package.