first commit

docs/media/audio/audio-codec-ffmpeg-native/src/error-codes/error-codes.md

@@ -0,0 +1,90 @@
+# `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.