first commit

docs/media/audio/audio-analysis-loudness/src/error-codes/error-codes.md

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