# error-codes

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

## Purpose

This module owns the stable, machine-readable error-code registry for
`@suaveplan/audio-analysis-loudness`. Every fault raised by the loudness
analyser is reported through a single `AudioAnalysisLoudnessError` subclass of
`SuaveplanError`, carrying a code drawn from `AUDIO_ANALYSIS_LOUDNESS_CODES`
and rich context such as Zod issue lists or abort reasons.

The registry exists so downstream observability, alerting, and i18n layers
can bind to stable string identifiers instead of fragile message strings.
Codes never change once shipped — new fault classes get new codes, never
re-purposed old ones.

## Features

- Three stable codes: `INVALID_OPTIONS`, `EMPTY_DOCUMENT`, `ABORTED`.
- Frozen metadata table (`description`, `severity`) keyed by code.
- `AudioAnalysisLoudnessError` subclass with public constructor and a
  `category` discriminant that satisfies the no-suppression-comment rule
  without any `// biome-ignore`.
- Idempotent `registerAudioAnalysisLoudnessErrorCodes()` hook.

## Usage: Basic

```ts
import {
  AUDIO_ANALYSIS_LOUDNESS_CODES,
  AudioAnalysisLoudnessError,
} from "@suaveplan/audio-analysis-loudness/error-codes";

throw new AudioAnalysisLoudnessError(
  AUDIO_ANALYSIS_LOUDNESS_CODES.EMPTY_DOCUMENT,
  "audio-analysis-loudness.empty-document",
  { context: { sourceLength: 0 } },
);
```

## Usage: Advanced

```ts
import {
  AUDIO_ANALYSIS_LOUDNESS_CODES,
  AUDIO_ANALYSIS_LOUDNESS_ERROR_METADATA,
  registerAudioAnalysisLoudnessErrorCodes,
} from "@suaveplan/audio-analysis-loudness/error-codes";

registerAudioAnalysisLoudnessErrorCodes();

for (const code of Object.values(AUDIO_ANALYSIS_LOUDNESS_CODES)) {
  const meta = AUDIO_ANALYSIS_LOUDNESS_ERROR_METADATA[code];
  console.log(code, meta.severity, meta.description);
}
```

## API Reference

- `AUDIO_ANALYSIS_LOUDNESS_CODES` — frozen object mapping reason names to
  namespaced code strings.
- `AudioAnalysisLoudnessErrorCode` — union of every code string.
- `AUDIO_ANALYSIS_LOUDNESS_ERROR_METADATA` — frozen lookup keyed by code.
- `AudioAnalysisLoudnessError` — `SuaveplanError` subclass.
- `registerAudioAnalysisLoudnessErrorCodes()` — idempotent startup hook.

## Implementation Notes

`defineCodes` produces both the runtime object and the literal type union; the
returned object is frozen, so attempts to mutate codes at runtime fail in
strict mode. The metadata table is independently `Object.freeze`-d so consumers
cannot mutate descriptions or severities. The `category` field on the error
class is what keeps the subclass "non-trivial" enough for the static
analyser — without it, biome flags the override as useless.