skills/plugins/document-navigator/docs/api-stack/api/api-graphql/README.md

@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.

Documentation tree

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

Surface

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