first commit

docs/api-stack/api/api-graphql/README.md

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