first commit

docs/api-stack/api/api-graphql-ui-altair/src/error-codes/error-codes.md

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