Initial Commit

packages/ui/react/react-audio-stream/src/error-codes/error-codes.md

@@ -0,0 +1,104 @@
+# `error-codes`
+
+<!-- begin:auto-docs -->
+_(no submodules)_
+<!-- end:auto-docs -->
+
+## Purpose
+
+The error-codes module is the canonical source of truth for every
+failure mode published by `@suaveplan/react-audio-stream`. It declares
+the seven dotted codes under the `REACT_AUDIO_STREAM.` namespace via
+`defineCodes`, the frozen metadata table, and the `ReactAudioStreamError`
+class — every error thrown by the package extends this class and carries
+one of these codes. Consumers discriminate failures with `instanceof
+ReactAudioStreamError` or by matching on the stable `error.code` string
+without needing to know which sub-feature originated the throw.
+
+The codes line up one-to-one with the Requirement 9 surface of the
+parent OpenSpec change so the human-authored spec can be cross-checked
+against runtime reality: a test asserts every entry in
+`REACT_AUDIO_STREAM_ERROR_METADATA` is reachable from at least one
+production call site.
+
+## Features
+
+- Seven stable, lexically sorted codes: `NO_PROVIDER`, `INVALID_STATE`,
+  `SIGNALLING_FAILED`, `PEER_NOT_FOUND`, `MEDIA_PERMISSION_DENIED`,
+  `RECONNECT_EXHAUSTED`, `INVALID_OPTIONS`.
+- `ReactAudioStreamError extends SuaveplanError` — inherits structured
+  context, cause-chain support, and serialization to the shared wire
+  format.
+- Idempotent `registerReactAudioStreamErrorCodes()` registration hook
+  for symmetry with sibling Suaveplan packages.
+- `Object.freeze`-d metadata table — mutation attempts throw in strict
+  mode and a test guards the invariant.
+
+## Usage: Basic
+
+```ts
+import {
+  REACT_AUDIO_STREAM_CODES,
+  ReactAudioStreamError,
+} from "@suaveplan/react-audio-stream/error-codes";
+
+throw new ReactAudioStreamError(
+  REACT_AUDIO_STREAM_CODES.NO_PROVIDER,
+  "react-audio-stream.no-provider",
+);
+```
+
+## Usage: Advanced
+
+```ts
+import {
+  REACT_AUDIO_STREAM_CODES,
+  REACT_AUDIO_STREAM_ERROR_METADATA,
+  ReactAudioStreamError,
+} from "@suaveplan/react-audio-stream/error-codes";
+
+try {
+  await session.join();
+} catch (err) {
+  if (err instanceof ReactAudioStreamError) {
+    const meta = REACT_AUDIO_STREAM_ERROR_METADATA[err.code];
+    logger.warn({
+      code: err.code,
+      severity: meta.severity,
+      description: meta.description,
+      context: err.context,
+    }, "stream session failure");
+  }
+  throw err;
+}
+```
+
+## API Reference
+
+- `REACT_AUDIO_STREAM_CODES` — frozen object literal keyed by short
+  code, value is the dotted string (`"REACT_AUDIO_STREAM.NO_PROVIDER"`).
+- `ReactAudioStreamErrorCode` — derived union of every value in the
+  code registry.
+- `ReactAudioStreamErrorMetadata` — `{ description, severity }` pair
+  per code.
+- `REACT_AUDIO_STREAM_ERROR_METADATA` — `Record<ReactAudioStreamErrorCode,
+  ReactAudioStreamErrorMetadata>`, `Object.freeze`-d at module load.
+- `ReactAudioStreamError` — `SuaveplanError<ReactAudioStreamErrorCode>`
+  subclass; `category` is the literal `"react-audio-stream"`.
+- `registerReactAudioStreamErrorCodes(): void` — idempotent no-op
+  retained for parity with sibling registries.
+
+## Implementation Notes
+
+`defineCodes` literally typesetting the runtime values means the
+`ReactAudioStreamErrorCode` union is derived without a second
+hand-maintained declaration. Adding a code requires only an entry in
+both `REACT_AUDIO_STREAM_CODES` and `REACT_AUDIO_STREAM_ERROR_METADATA`
+— the metadata test fails otherwise. Severity is currently `error` on
+every entry; the field exists so future warning-class diagnostics
+(deprecated transport probes, lossy fallbacks) slot in without a
+schema change. The class extends the foundation `SuaveplanError`
+directly — the parent OpenSpec change references an `AudioError` from
+`@suaveplan/audio-core` but the chunk-A dep allowlist excludes that
+package, so we follow the same pattern as sibling `@suaveplan/react-audio`
+which also extends the foundation base.