first commit

docs/media/audio/audio-decode-wav/src/error-codes/error-codes.md

@@ -0,0 +1,66 @@
+# `error-codes`
+
+<!-- begin:auto-docs -->
+_(no submodules)_
+<!-- end:auto-docs -->
+
+## Purpose
+
+This module is the canonical registry of every error code raised by `@suaveplan/audio-decode-wav`, alongside the structured `AudioDecodeWavError` class that carries discriminants for filtering. The registry is the contract — every code is reachable from a real call site exercised by the test suite, per `AGENTS.md` §2c. The error class extends `@suaveplan/error`'s `SuaveplanError` so it threads through the repo-wide error machinery (OTel span event adapter, redaction, i18n resolver, Zod-validated wire format) without bespoke wiring.
+
+## Features
+
+- Seven codes via `defineCodes("AUDIO_DECODE.WAV", […])`: `INVALID_INPUT`, `UNSUPPORTED_FORMAT`, `CORRUPT_HEADER`, `TRUNCATED_BODY`, `ABORTED`, `RESAMPLE_UNSUPPORTED`, `STREAM_INVARIANT_VIOLATION`.
+- `AudioDecodeWavError` carries six dimension-specific discriminants: `format` (for `UNSUPPORTED_FORMAT`), `decodedSampleRate` + `requestedSampleRate` (for `RESAMPLE_UNSUPPORTED`), `op` (every error), `bytesAvailable` + `bytesDeclared` (for `TRUNCATED_BODY`).
+- `AudioFormatType` union covers the WAV format codes recognised at the inspect layer: `pcm`, `ieee-float`, `alaw`, `mulaw`, `ima-adpcm`, `ms-adpcm`, `extensible`, `unknown`.
+- Registry is frozen at module load; `Object.values(AUDIO_DECODE_WAV_CODES)` is the authoritative list for exhaustion tests.
+
+## Usage: Basic
+
+```ts
+import {
+    AUDIO_DECODE_WAV_CODES,
+    AudioDecodeWavError,
+} from "@suaveplan/audio-decode-wav";
+
+throw new AudioDecodeWavError(
+    AUDIO_DECODE_WAV_CODES.INVALID_INPUT,
+    "WAV byte buffer is empty",
+    { op: "decodeWav" }
+);
+```
+
+## Usage: Advanced
+
+```ts
+import {
+    AUDIO_DECODE_WAV_CODES,
+    AudioDecodeWavError,
+    decodeWav,
+} from "@suaveplan/audio-decode-wav";
+
+try {
+    await decodeWav(bytes, { targetSampleRate: 48000 });
+} catch (err) {
+    if (
+        err instanceof AudioDecodeWavError &&
+        err.code === AUDIO_DECODE_WAV_CODES.RESAMPLE_UNSUPPORTED
+    ) {
+        console.warn(
+            `cannot decode-and-resample: ${err.decodedSampleRate} → ${err.requestedSampleRate}`
+        );
+    }
+}
+```
+
+## API Reference
+
+- `const AUDIO_DECODE_WAV_CODES` — `{ INVALID_INPUT: "AUDIO_DECODE.WAV.INVALID_INPUT", … }`. Frozen.
+- `type AudioDecodeWavErrorCode` — union of every code's string value.
+- `type AudioFormatType` — `"pcm" | "ieee-float" | "alaw" | "mulaw" | "ima-adpcm" | "ms-adpcm" | "extensible" | "unknown"`.
+- `interface AudioDecodeWavErrorOptions extends SuaveplanErrorOptions` — adds `format`, `decodedSampleRate`, `requestedSampleRate`, `op`, `bytesAvailable`, `bytesDeclared`.
+- `class AudioDecodeWavError extends SuaveplanError<AudioDecodeWavErrorCode>` — exposes every option above as a readonly field; `name === "AudioDecodeWavError"`.
+
+## Implementation Notes
+
+The registry uses `defineCodes` so the code-string format is uniform across the project (`<namespace>.<reason>`), making OTel attribute filtering by code prefix trivial. The error class follows the same discriminant-surface pattern as `BundleUriError` in `@suaveplan/storage-uri-plugin-bundle` — every dimension a downstream observer might filter on is a typed readonly field rather than buried in the message string. `RESAMPLE_UNSUPPORTED` deliberately carries both rates so the failing call can be replayed against a downstream resampler without re-decoding to discover the source rate.