# @suaveplan/api-graphql — abstract GraphQL contract for the Suaveplan API plugin system. Owns the GraphqlRegistry / Resolver / LoaderFactory / SubscriptionResolver re-exports, federation SDL merger with collision detection + plugin namespace wrapping, @auth + @rateLimit directive descriptors, the GraphqlEngine lifecycle interface, the GRAPHQL_CODES registry, and the runGraphqlEngineConformance harness. No concrete engine — Yoga / Apollo land  packages and implement the contract.

Stage-1 abstract GraphQL contract for the Suaveplan API plugin system.

Plugins contribute SDL + resolvers via a small abstract surface; the host
federates a single schema across every plugin and dispatches via a
swappable engine. Concrete engines (`api-graphql-yoga` default,
`api-graphql-apollo` alternative) live  and implement the
`GraphqlEngine` contract published from this package.

<!-- begin:auto-docs -->
## Documentation tree

- [directives](./src/directives/directives.md) — Host-supplied GraphQL directive descriptors that engine adapters install at schema-build time. The contract layer ships…
  - [directives](./src/directives/directives.md) — Host-supplied GraphQL directive descriptors that engine adapters install at schema-build time. The contract layer ships…
- [error-codes](./src/error-codes/error-codes.md) — Stable error-code registry for `@suaveplan/api-graphql`. Every public failure path raises a `GraphqlError` carrying one…
  - [error-codes](./src/error-codes/error-codes.md) — Stable error-code registry for `@suaveplan/api-graphql`. Every public failure path raises a `GraphqlError` carrying one…
- [merge-sdl](./src/federation/merge-sdl.md) — Federate one or more plugin SDL contributions into a single merged schema. This is the engine-agnostic federation step…
- [namespace](./src/federation/namespace.md) — Apply the `graphql.namespace` wrapper to a plugin's parsed SDL blocks. Plugins that declare `namespace: "Billing"` in t…
- [parse-sdl](./src/federation/parse-sdl.md) — Minimal SDL parser used by the federation merger to locate `type Name { ... }` and `extend type Name { ... }` blocks pl…
- [registry](./src/registry/registry.md) — Concrete accumulator-style `GraphqlRegistry` implementation. The host hands each plugin one of these during the GraphQL…
  - [registry](./src/registry/registry.md) — Concrete accumulator-style `GraphqlRegistry` implementation. The host hands each plugin one of these during the GraphQL…
- [subscription](./src/subscription/subscription.md) — Validate incoming `graphql-ws` subscription envelopes and surface a typed "transport unavailable" failure when `api-ws`…
  - [subscription](./src/subscription/subscription.md) — Validate incoming `graphql-ws` subscription envelopes and surface a typed "transport unavailable" failure when `api-ws`…
- [testing](./src/testing/conformance.md) — `runGraphqlEngineConformance` is the cross-engine test harness every concrete GraphQL engine (`api-graphql-yoga`, `api-…
  - [conformance](./src/testing/conformance.md) — `runGraphqlEngineConformance` is the cross-engine test harness every concrete GraphQL engine (`api-graphql-yoga`, `api-…
- [validators](./src/validators/validators.md) — Pre-build validators concrete GraphQL engines call after `registry.freeze()` and before `buildSchema`. The contract lay…
  - [validators](./src/validators/validators.md) — Pre-build validators concrete GraphQL engines call after `registry.freeze()` and before `buildSchema`. The contract lay…
<!-- end:auto-docs -->

## Surface

- [`./registry`](./src/registry/registry.md) — abstract `GraphqlRegistry`
  accumulator (`addTypes` / `addResolvers` / `addLoader`) + `freeze()`.
- [`./resolver`](./src/resolver/resolver.types.ts) — `Resolver` (re-exported
  from `@suaveplan/api-types`) and the keyed `ResolverMap` / `ResolverFieldMap`.
- [`./loader`](./src/loader/loader.types.ts) — `LoaderFactory`
  (re-exported) and the `BatchFn` signature.
- [`./subscription`](./src/subscription/subscription.md) —
  `SubscriptionResolver` (re-exported) + Zod-validated `graphql-ws`
  envelope + transport-availability assertion.
- [`./federation`](./src/federation/merge-sdl.md) — `mergeSdl` collision
  detector + `graphql.namespace` wrapper + minimal SDL parser.
- [`./directives`](./src/directives/directives.md) — `@auth(scope: String!)`
  and `@rateLimit(rpm: Int!)` descriptors + `HOST_DIRECTIVES` lookup.
- [`./engine`](./src/engine/engine.types.ts) — abstract `GraphqlEngine`
  lifecycle interface implemented by Stage-7 packages.
- [`./capability-id`](./src/capability-id/capability-id.types.ts) —
  re-export of `"graphql"` literal + `GRAPHQL_CAPABILITY_ID` runtime
  constant.
- [`./error-codes`](./src/error-codes/error-codes.md) — `GRAPHQL_CODES`
  registry + `GraphqlError` class.
- [`./validators`](./src/validators/validators.md) —
  `validateResolvers`, `lookupDirective`, `lookupLoader` pre-build checks.
- [`./testing`](./src/testing/conformance.md) —
  `runGraphqlEngineConformance` cross-engine harness.

## Error codes (`GRAPHQL.*`)

| Code | When |
| --- | --- |
| `SCHEMA_COLLISION` | Two plugins declare the same `Type.field`. |
| `RESOLVER_MISSING` | SDL declares a root field with no resolver. |
| `LOADER_DUPLICATE_NAME` | Two `addLoader` calls registered the same name. |
| `LOADER_NOT_REGISTERED` | Request references an unknown loader. |
| `DIRECTIVE_UNKNOWN` | SDL references an uninstalled directive. |
| `SUBSCRIPTION_TRANSPORT_UNAVAILABLE` | Subscriptions used without `api-ws`. |
| `NAMESPACE_REQUIRED` | Strict-mode federation missing namespace. |

## Stage

Contracts. No concrete GraphQL engine; Yoga / Apollo / GraphiQL /
Altair packages land .

## Dependencies

- `@suaveplan/api-types` — type-level contract surface.
- `@suaveplan/error` — `defineCodes` + `SuaveplanError` base.
- `zod` — subscription protocol envelope validation.
- `tslib` — TypeScript helper functions.