# `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.