first commit

docs/media/audio/midi/src/error-codes/error-codes.md

@@ -0,0 +1,57 @@
+# error-codes
+
+<!-- begin:auto-docs -->
+_(no submodules)_
+<!-- end:auto-docs -->
+
+## Purpose
+
+Defines the `MidiError` class and the `MIDI_CODES` namespaced registry used by every `@suaveplan/midi` module that raises faults. The registry exists so consumers can pattern-match on stable strings rather than `instanceof` checks against transient class identities, and so dashboards can attribute incidents to the exact failure mode without scraping freeform messages.
+
+The codes themselves are produced by `defineCodes` from `@suaveplan/error`, which guarantees the resulting object is `Object.freeze`-d and that every value is a fully-qualified `MIDI.<REASON>` string. `MidiError` extends `SuaveplanError` so cause chains, OTel span events, and i18n message resolution work uniformly with the rest of the platform.
+
+## Features
+
+- Five stable codes: `INVALID_MESSAGE`, `INVALID_SYSEX`, `BUFFER_UNDERRUN`, `UNSUPPORTED_UMP_VARIANT`, `NRPN_INCOMPLETE`.
+- Frozen `MIDI_ERROR_METADATA` registry exposing a description and severity tag for every code.
+- `MidiError` subclass with `category: "midi"` tag and runtime-checkable `name: "MidiError"`.
+- Cause-chain support via the optional `options.cause` constructor argument.
+
+## Usage: Basic
+
+```ts
+import { MidiError, MIDI_CODES } from "@suaveplan/midi";
+
+if (something.invalid) {
+  throw new MidiError(MIDI_CODES.INVALID_MESSAGE);
+}
+```
+
+## Usage: Advanced
+
+```ts
+import { MidiError, MIDI_CODES, MIDI_ERROR_METADATA } from "@suaveplan/midi";
+
+try {
+  // ...decode logic
+} catch (cause) {
+  throw new MidiError(MIDI_CODES.BUFFER_UNDERRUN, "midi.decode.short_input", {
+    cause,
+    context: { offset: 12 },
+  });
+}
+
+// Build a dashboard label.
+const label = MIDI_ERROR_METADATA[MIDI_CODES.BUFFER_UNDERRUN].description;
+```
+
+## API Reference
+
+- `MIDI_CODES: Readonly<{ INVALID_MESSAGE: "MIDI.INVALID_MESSAGE", ... }>` — frozen namespaced lookup table.
+- `MidiErrorCode` — string-literal union of every value in `MIDI_CODES`.
+- `MIDI_ERROR_METADATA: Readonly<Record<MidiErrorCode, { description: string; severity: "warning" | "error" }>>` — per-code metadata for UI surfaces.
+- `class MidiError extends SuaveplanError<MidiErrorCode>` — constructor `(code, messageKey?, options?)`; carries `category: "midi"` and `name: "MidiError"`.
+
+## Implementation Notes
+
+`MidiError` defaults `messageKey` to the code itself when none is supplied; this means an unhandled raise still produces a useful i18n key without forcing every call site to invent one. The base class clock is the platform `defaultClock`, so timestamps line up across packages without per-package configuration. The metadata object is frozen at module load to prevent ad-hoc mutation; downstream packages compose dialect-specific metadata by spreading rather than mutating in place.