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

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

## Purpose

`error-codes` defines the stable `GRAPHQL_APOLLO.*` namespace plus the
`GraphqlApolloError` class consumed by every other module in the
`@suaveplan/api-graphql-apollo` package. It sits in the same shape as the
sibling `@suaveplan/api-graphql` registry so callers can write a single
`instanceof SuaveplanError` discriminator and narrow further on
`error.code`.

The registry covers ten codes — request-document parse and validation
failures, depth and complexity guard rejections, schema-build failures
inside Apollo, the missing-transport case for subscriptions, request
timeouts, introspection-denied responses, persisted-query lookup misses,
and the resolver-attach catch-all. Every code is thrown by a production
path; the conformance harness enforces that empirically.

## Features

- Frozen `defineCodes("GRAPHQL_APOLLO", […])` registry — no untyped string
  ever escapes the package.
- `GraphqlApolloError` exposes the code via both the inherited `error.code`
  and a narrowed `graphqlApolloCode` field; either narrows downstream code
  to the union of ten possible values.
- Constructor preserves `cause` and `context` per the `SuaveplanError`
  contract — wrappers can attach the raw `cause: Error` for crash dumps.
- The class sets `this.name = "GraphqlApolloError"` so logs surface the
  concrete subclass.

## Usage: Basic

```ts
import {
    GRAPHQL_APOLLO_CODES,
    GraphqlApolloError,
} from "@suaveplan/api-graphql-apollo/error-codes";

throw new GraphqlApolloError(
    GRAPHQL_APOLLO_CODES.PARSE_FAILED,
    "request document failed to parse"
);
```

## Usage: Advanced

Attach a cause and a context payload that the OTel span recorder will
attach as event attributes:

```ts
import { GraphqlApolloError } from "@suaveplan/api-graphql-apollo/error-codes";

try {
    JSON.parse(maybeJson);
} catch (cause) {
    throw new GraphqlApolloError(
        "GRAPHQL_APOLLO.PARSE_FAILED",
        "persisted-query manifest is not valid JSON",
        { cause: cause as Error, context: { path: "./pq.json" } }
    );
}
```

## API Reference

- `GRAPHQL_APOLLO_CODES` — frozen object mapping each short name to its
  fully-qualified code string.
- `GraphqlApolloErrorCode` — union of every code value resolved through
  `GRAPHQL_APOLLO_CODES`.
- `class GraphqlApolloError extends SuaveplanError<GraphqlApolloErrorCode>`.
  - `constructor(code, message, options?)`
  - `graphqlApolloCode` — convenience accessor pre-narrowed to the
    `GraphqlApolloErrorCode` union.

## Implementation Notes

The codes intentionally mirror the design-doc §10.5 list. Adding a new
code requires (a) appending it to the `defineCodes` array, (b) wiring at
least one production throw site, and (c) extending the conformance
checklist. The `name` field is set so structured logs see
`GraphqlApolloError` rather than the generic `SuaveplanError`. The class
extends the abstract `SuaveplanError` directly — no intermediate base.