# error-codes

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

## Purpose

Defines the stable `SPESSASYNTH.*` error-code namespace used by every other module in `@suaveplan/audio-fx-plugin-spessasynth`. The codes are surfaced through `defineCodes` from `@suaveplan/error`, which makes them discoverable to wire-format consumers (the API gateway, the OpenTelemetry span-event adapter, the i18n message resolver) without importing this package directly.

Every operational failure raised by the loader, MIDI router, parameter surface, voice manager, or the `SpessaSynthPlugin` orchestrator carries one of these codes plus a stable message key. The codes are intentionally narrow — load-failure vs parse-failure vs unsupported-format vs voice-limit vs initialisation vs MIDI/parameter validation vs module-unavailable — so that consumers can pattern-match on `error.code` and decide whether to retry, fall back to a smaller SoundFont, or surface a permanent error to the operator.

## Features

- `SPESSASYNTH_CODES` — closed enum of nine codes registered via `defineCodes` so cross-package consumers can refer to them by literal string.
- `SPESSASYNTH_ERROR_METADATA` — frozen record giving every code a one-line human description and a severity (`warning` for `VOICE_LIMIT_EXCEEDED`, `error` for the rest).
- `SpessaSynthError` — `SuaveplanError` subclass with a `category: "audio-fx-spessasynth"` discriminator and a descriptive `name` derived from the code's severity, suitable for log-aggregation grouping.
- Re-exported through the package barrel and the `./error-codes` subpath so consumers tree-shake to just the codes they need.

## Usage: Basic

```ts
import {
    SpessaSynthError,
    SPESSASYNTH_CODES,
} from "@suaveplan/audio-fx-plugin-spessasynth/error-codes";

throw new SpessaSynthError(
    SPESSASYNTH_CODES.NOT_INITIALIZED,
    "spessasynth.process-before-init"
);
```

## Usage: Advanced

```ts
import {
    SpessaSynthError,
    SPESSASYNTH_CODES,
    SPESSASYNTH_ERROR_METADATA,
} from "@suaveplan/audio-fx-plugin-spessasynth/error-codes";

try {
    await plugin.init({ soundFontBytes });
} catch (err) {
    if (err instanceof SpessaSynthError) {
        const meta = SPESSASYNTH_ERROR_METADATA[err.code];
        logger[meta.severity]("spessasynth init failed", {
            code: err.code,
            description: meta.description,
            cause: err.cause,
        });
        if (err.code === SPESSASYNTH_CODES.SOUNDFONT_PARSE_FAILED) {
            // attempt a known-good fallback SF2
        }
    }
}
```

## API Reference

- `SPESSASYNTH_CODES` — `Record<Code, "SPESSASYNTH.<Code>">`.
- `SpessaSynthErrorCode` — string-literal union of every code.
- `SPESSASYNTH_ERROR_METADATA[code]: { description, severity }`.
- `class SpessaSynthError extends SuaveplanError<SpessaSynthErrorCode>` — constructor takes `(code, messageKey, options?)` with optional `cause`/`context`.

## Implementation Notes

The constructor reads `SPESSASYNTH_ERROR_METADATA[code]` to populate `this.name`, which serves the secondary purpose of guaranteeing the constructor body is not elided by `noUselessConstructor` lint. The metadata table is `Object.freeze`d so consumers can't accidentally mutate it; the codes themselves are an `as const` tuple supplied to `defineCodes`, so changing them requires editing the source — no run-time mutation is possible. The class extends `SuaveplanError` directly (no intermediate base) so the redaction, span-event, and i18n hooks defined on `SuaveplanError` apply uniformly.