Initial Commit

packages/api-stack/api/api-graphql-apollo/src/federation/federation.md

@@ -0,0 +1,70 @@
+# `federation` — multi-plugin SDL merger
+
+<!-- begin:auto-docs -->
+_(no submodules)_
+<!-- end:auto-docs -->
+
+## Purpose
+
+`federation` is the engine's facade over the canonical `mergeSdl`
+function from `@suaveplan/api-graphql`. Apollo doesn't see federated
+plugin contributions directly — the engine collects every plugin's
+SDL via the abstract `GraphqlRegistry`, federates them through this
+module, and feeds the merged SDL to `buildSchema()`. Collision
+detection, namespace wrapping, and strict-mode policy come for free
+because all three are owned by the abstract merger.
+
+The module is intentionally a one-line passthrough; it exists so the
+package surface signals "yes, Apollo federates the same way Yoga
+does — `GRAPHQL.SCHEMA_COLLISION` is the canonical code on either
+engine".
+
+## Features
+
+- 1:1 delegation to `@suaveplan/api-graphql.mergeSdl` — no shape
+  change, no behaviour change.
+- Same collision semantics as Yoga — `GRAPHQL.SCHEMA_COLLISION` is
+  raised, NOT a `GRAPHQL_APOLLO.*` code.
+- Strict-mode propagation — `strictNamespace: true` requires every
+  plugin to declare a `graphql.namespace`.
+- Returns the canonical `MergedSchema` shape so engine internals stay
+  assignable to the abstract contract.
+
+## Usage: Basic
+
+```ts
+import { federateForApollo } from "@suaveplan/api-graphql-apollo/federation";
+
+const merged = federateForApollo([
+    { plugin: "billing", typeDefs: ["type Query { invoice: String! }"] },
+    { plugin: "users", typeDefs: ["extend type Query { me: String! }"] },
+]);
+console.log(merged.sdl);
+```
+
+## Usage: Advanced
+
+Enable strict-mode federation across all plugins to enforce a
+namespace contract before the host even compiles:
+
+```ts
+import { federateForApollo } from "@suaveplan/api-graphql-apollo/federation";
+
+federateForApollo(contributions, { strictNamespace: true });
+// → throws GRAPHQL.NAMESPACE_REQUIRED if any plugin omitted namespace
+```
+
+## API Reference
+
+- `federateForApollo(contributions, options?): MergedSchema`
+  - delegates to `@suaveplan/api-graphql.mergeSdl`.
+
+## Implementation Notes
+
+The function exists primarily so the package's TypeScript exports
+expose a `federateForApollo` symbol that mirrors the sibling
+`federateForYoga` (when the Yoga adapter lands). The behavioural
+contract is owned by the abstract `mergeSdl`. Tests verify that
+`GRAPHQL.SCHEMA_COLLISION` and `GRAPHQL.NAMESPACE_REQUIRED` are raised
+through this wrapper — concrete proof that Apollo and Yoga agree on
+the federation contract.