# `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.