# `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.