Initial Commit

packages/media/audio-fx/audio-fx-plugin-spessasynth/src/error-codes/error-codes.md

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