# `error-codes` — `GRAPHQL_UI_ALTAIR.*` registry

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

## Purpose

`error-codes` is the package's single source of truth for the two stable
error codes the Altair UI plugin emits. Centralising the codes here lets
the factory, the asset map, and any downstream observability tooling
import the literal strings from one location — no string-typos, no
divergence between the wire format and the registry. The registry is
frozen at module init and validated against the umbrella `defineCodes`
contract from `@suaveplan/error` so accidental drift is caught at type
check time, not at runtime.

## Features

- Two codes: `GRAPHQL_UI_ALTAIR.ASSET_MISSING`,
  `GRAPHQL_UI_ALTAIR.ENDPOINT_COLLISION`.
- Concrete `GraphqlUiAltairError` class extending `SuaveplanError`.
- `altairCode` narrows to `GraphqlUiAltairErrorCode` for exhaustive
  switch statements.
- Compatible with the umbrella redaction + i18n + OTel span-event
  adapters shipped by `@suaveplan/error`.

## Usage: Basic

```ts
import {
    GRAPHQL_UI_ALTAIR_CODES,
    GraphqlUiAltairError,
} from "@suaveplan/api-graphql-ui-altair/error-codes";

throw new GraphqlUiAltairError(
    GRAPHQL_UI_ALTAIR_CODES.ASSET_MISSING,
    "Asset not present in bundled map",
    { context: { path: "/graphql/ui/assets/missing.js" } }
);
```

## Usage: Advanced

```ts
import {
    GRAPHQL_UI_ALTAIR_CODES,
    GraphqlUiAltairError,
} from "@suaveplan/api-graphql-ui-altair/error-codes";

function handle(err: unknown): number {
    if (err instanceof GraphqlUiAltairError) {
        switch (err.altairCode) {
            case GRAPHQL_UI_ALTAIR_CODES.ASSET_MISSING:
                return 404;
            case GRAPHQL_UI_ALTAIR_CODES.ENDPOINT_COLLISION:
                return 409;
        }
    }
    return 500;
}
```

## API Reference

- `GRAPHQL_UI_ALTAIR_CODES` — frozen record `{ ASSET_MISSING, ENDPOINT_COLLISION }`.
- `GraphqlUiAltairErrorCode` — discriminated union of the two literal
  strings.
- `class GraphqlUiAltairError extends SuaveplanError<GraphqlUiAltairErrorCode>`
  — owns the `altairCode` accessor.

## Implementation Notes

`defineCodes("GRAPHQL_UI_ALTAIR", ...)` produces the prefixed literal
strings — agents must not hand-build the strings to avoid prefix drift.
The error class delegates entirely to `SuaveplanError` for context
serialisation, cause chains, and the wire-format adapter; the only
local responsibility is preserving `altairCode` for `instanceof`
narrowing in operator-facing error handlers. The two-code surface is
intentionally minimal: the asset path is the only failure mode at HTTP
boundary, and endpoint collision is the only failure mode at mount
boundary. Adding a code requires an OpenSpec change so the registry
shape never drifts silently between the spec and the runtime.