feat: expose costs (#2470)

Integrate static and dynamic cost calculation into the router. 
Expose the static (estimated) cost value in the modules.
Expose both costs via telemetry and response headers.

Metrics for costs should be enabled individually in the corresponding telemetry section.

Composition was reviewed in another PR and merged here.

End-to-end benchmark for a big query to measure the impact of cost control:

     │ SequentialBig │     SequentialBigCostAnalysis      │
     │    sec/op     │   sec/op     vs base               │
*-14     584.1µ ± 0%   586.7µ ± 0%  +0.45% (p=0.000 n=40)

     │ SequentialBig │      SequentialBigCostAnalysis      │
     │      B/s      │     B/s       vs base               │
*-14    5.527Mi ± 0%   5.503Mi ± 0%  -0.43% (p=0.000 n=40)

     │ SequentialBig │   SequentialBigCostAnalysis    │
     │     B/op      │     B/op      vs base          │
*-14    456.1Ki ± 0%   456.1Ki ± 0%  ~ (p=0.822 n=40)

     │ SequentialBig │     SequentialBigCostAnalysis      │
     │   allocs/op   │  allocs/op   vs base               │
*-14     6.444k ± 0%   6.452k ± 0%  +0.12% (p=0.000 n=40)

Fixes ENG-8844
Fixes ENG-8986

Co-authored-by: Aenimus <47415099+Aenimus@users.noreply.github.com>
Co-authored-by: StarpTech <deusdustin@gmail.com>

Author: 3 people

cli/src/commands/router/commands/compose.ts

@@ -112,6 +112,7 @@ function constructRouterSubgraph(result: FederationSuccess, s: SubgraphMetadata,
   const subgraphConfig = result.subgraphConfigBySubgraphName.get(s.name);
   const schema = subgraphConfig?.schema;
   const configurationDataByTypeName = subgraphConfig?.configurationDataByTypeName;
+  const costs = subgraphConfig?.costs;
 
   if (s.kind === SubgraphKind.Standard) {
     const composedSubgraph: ComposedSubgraph = {
@@ -125,6 +126,7 @@ function constructRouterSubgraph(result: FederationSuccess, s: SubgraphMetadata,
       websocketSubprotocol: s.websocketSubprotocol,
       schema,
       configurationDataByTypeName,
+      costs,
     };
     return composedSubgraph;
   }
@@ -141,6 +143,7 @@ function constructRouterSubgraph(result: FederationSuccess, s: SubgraphMetadata,
       version: s.version,
       schema,
       configurationDataByTypeName,
+      costs,
     };
     return composedSubgraphPlugin;
   }
@@ -155,6 +158,7 @@ function constructRouterSubgraph(result: FederationSuccess, s: SubgraphMetadata,
     mapping: s.mapping,
     schema,
     configurationDataByTypeName,
+    costs,
   };
   return composedSubgraphGRPC;
 }
@@ -648,6 +652,7 @@ async function buildFeatureFlagsConfig(
         const subgraphConfig = featureResult.subgraphConfigBySubgraphName.get(s.name);
         const schema = subgraphConfig?.schema;
         const configurationDataByTypeName = subgraphConfig?.configurationDataByTypeName;
+        const costs = subgraphConfig?.costs;
 
         const composedSubgraph: ComposedSubgraph = {
           kind: SubgraphKind.Standard,
@@ -660,6 +665,7 @@ async function buildFeatureFlagsConfig(
           websocketSubprotocol: s.websocketSubprotocol,
           schema,
           configurationDataByTypeName,
+          costs,
         };
         return composedSubgraph;
       }),

composition-go/index.global.js

@@ -0,0 +1,326 @@
+# Composition Architecture and Onboarding (TypeScript)
+
+This is a beginner-friendly guide to the `composition` package.
+
+Scope:
+
+- In scope: `composition/*`
+- Out of scope: `composition-go/*`
+
+## Who this is for
+
+Use this doc if you are:
+
+- new to this repository,
+- trying to understand where composition errors come from,
+- adding or shipping custom directives.
+
+## 1. What this package produces
+
+Given one or more subgraph SDLs, composition produces:
+
+- a federated router schema,
+- a federated client schema,
+- router configuration metadata,
+- warnings and errors.
+
+Main API exports:
+
+- `composition/src/index.ts`
+
+Main functions:
+
+- `federateSubgraphs(...)`
+- `federateSubgraphsWithContracts(...)`
+- `federateSubgraphsContract(...)`
+- `normalizeSubgraph(...)`
+- `batchNormalize(...)`
+
+## 2. Mental model (simple)
+
+Think of composition as a 4-stage pipeline:
+
+1. Normalize each subgraph.
+2. Batch-check all normalized subgraphs together.
+3. Merge everything into one federated model.
+4. Validate resolvability and emit final schemas.
+
+```mermaid
+flowchart LR
+  A["Subgraph SDLs"] --> B["NormalizationFactory<br/>(per subgraph)"]
+  B --> C["batchNormalize<br/>(cross-subgraph checks)"]
+  C --> D["FederationFactory<br/>(merge + build schemas)"]
+  D --> E["Graph.validate<br/>(resolvability)"]
+  E --> F["FederationResult<br/>AST + schema + config + warnings/errors"]
+```
+
+## 3. Where each stage lives
+
+### Stage 1: Normalize one subgraph
+
+Main files:
+
+- `composition/src/v1/normalization/normalization-factory.ts`
+- `composition/src/v1/normalization/walkers.ts`
+- `composition/src/v1/normalization/utils.ts`
+
+What happens here:
+
+- Parse and validate SDL and directives.
+- Build internal type/field model (`ParentDefinitionData`, `FieldData`, etc.).
+- Validate federation directives (`@key`, `@requires`, `@provides`, `@override`, etc.).
+- Build type-level router configuration (`ConfigurationData`).
+- Record graph edges for later resolvability checks.
+
+### Stage 2: Batch normalization
+
+Main file:
+
+- `composition/src/v1/normalization/normalization-factory.ts` (`batchNormalize`)
+
+What happens here:
+
+- Validate subgraph naming/uniqueness.
+- Normalize each subgraph into shared structures.
+- Merge cross-subgraph metadata (entities, auth, overrides, coordinates).
+- Produce `internalSubgraphBySubgraphName` used by federation.
+
+### Stage 3: Federation merge
+
+Main file:
+
+- `composition/src/v1/federation/federation-factory.ts`
+
+What happens here:
+
+- Merge all normalized types and fields.
+- Reconcile incompatible shapes and directive usage.
+- Build router/client schema definitions.
+- Build final field configuration output.
+
+### Stage 4: Resolvability validation
+
+Main files:
+
+- `composition/src/resolvability-graph/graph.ts`
+- `composition/src/resolvability-graph/graph-nodes.ts`
+
+What happens here:
+
+- Validate that required field paths are actually reachable.
+- Return errors if fields cannot be resolved across subgraphs.
+
+## 4. Request flow from public API
+
+Top-level function:
+
+- `composition/src/federation/federation.ts`
+
+Current compatibility:
+
+- only version `"1"` is supported (`composition/src/router-compatibility-version/router-compatibility-version.ts`).
+
+Effective flow:
+
+1. `federateSubgraphs(...)`
+2. `initializeFederationFactory(...)`
+3. `batchNormalize(...)`
+4. `FederationFactory.federateSubgraphData()`
+5. `FederationFactory.buildFederationResult()`
+
+## 5. Core data structures (quick glossary)
+
+Result types:
+
+- `composition/src/federation/types.ts`
+- `composition/src/normalization/types.ts`
+- `composition/src/subgraph/types.ts`
+
+Most important internals:
+
+- `InternalSubgraph`: normalized per-subgraph state fed into federation.
+- `ParentDefinitionData`: canonical representation of a type in normalization/federation.
+- `PersistedDirectiveDefinitionData`: executable directive definition info considered for federated schema persistence.
+- `ConfigurationData`: per-type router configuration source.
+
+## 6. Directives: how the system is designed
+
+There are two broad categories:
+
+1. Built-in directives with composition semantics.
+2. Custom executable directives that can be validated and persisted.
+
+### Built-in directives
+
+Definition and registration:
+
+- `composition/src/v1/constants/directive-definitions.ts`
+- `composition/src/v1/constants/constants.ts`
+- `composition/src/v1/constants/strings.ts`
+- `composition/src/utils/string-constants.ts`
+
+Normalization uses a directive registry (`directiveDefinitionDataByName`) to validate use sites and arguments.
+
+### Custom directives
+
+During normalization, unknown directive definitions are treated as custom:
+
+- parsed and validated,
+- added to normalized directive maps,
+- included in normalized subgraph AST.
+
+Key implementation points:
+
+- `upsertDirectiveSchemaAndEntityDefinitions(...)`
+- `addDirectiveDefinitionDataByNode(...)`
+
+Both are in:
+
+- `composition/src/v1/normalization/normalization-factory.ts`
+- `composition/src/v1/normalization/walkers.ts`
+
+### Directive persistence across subgraphs
+
+During federation, executable directive definitions are only persisted when compatible across subgraphs.
+
+Compatibility rules (important):
+
+- The definition must exist consistently across participating subgraphs.
+- Executable locations are intersected (must remain non-empty).
+- Argument definitions must merge cleanly.
+- Repeatability must remain compatible.
+
+Core methods:
+
+- `upsertPersistedDirectiveDefinitionData(...)`
+- `addValidPersistedDirectiveDefinitionNodeByData(...)`
+
+Files:
+
+- `composition/src/v1/federation/federation-factory.ts`
+- `composition/src/schema-building/utils.ts`
+
+### Caveat: `@composeDirective`
+
+`@composeDirective` is declared but currently unimplemented in behavior.
+
+Reference:
+
+- `composition/src/v1/constants/directive-definitions.ts`
+
+Treat it as not available for feature design right now.
+
+## 7. Shipping a custom directive (practical playbook)
+
+If you want a custom executable directive to survive composition:
+
+1. Define the directive in every relevant subgraph SDL.
+2. Keep argument names/types/defaults compatible.
+3. Keep executable locations compatible.
+4. Use it where needed.
+5. Compose and verify in the federated output.
+
+Validation checklist:
+
+- Definition exists in federated schema.
+- Usages appear on expected nodes.
+- No invalid repeatability errors.
+- No cross-subgraph definition merge errors.
+
+Best tests to copy:
+
+- `composition/tests/v1/directives/directives.test.ts`
+- `composition/tests/v1/normalization.test.ts`
+
+## 8. Adding a new built-in directive (when persistence is not enough)
+
+Use this path if you need new behavior (not just persistence), for example router config generation.
+
+Implementation sequence:
+
+1. Add directive name constants.
+2. Add canonical directive definition node.
+3. Add directive definition data (arg/location validation model).
+4. Register in directive maps.
+5. Add validation/extraction behavior in normalization.
+6. Add federation persistence/merge behavior.
+7. Add dependencies for helper scalars/inputs if needed.
+8. Add tests (invalid, valid, merge, config impact).
+
+Files usually touched:
+
+- `composition/src/utils/string-constants.ts`
+- `composition/src/v1/constants/directive-definitions.ts`
+- `composition/src/v1/normalization/directive-definition-data.ts`
+- `composition/src/v1/constants/constants.ts`
+- `composition/src/v1/constants/strings.ts`
+- `composition/src/v1/normalization/normalization-factory.ts`
+- `composition/src/v1/federation/federation-factory.ts`
+- `composition/tests/v1/directives/*.test.ts`
+
+## 9. Contracts in one minute
+
+`federateSubgraphsWithContracts(...)` flow:
+
+1. Build the base federated graph.
+2. Clone federation state per contract.
+3. Apply tag include/exclude options per contract.
+4. Return one result per contract.
+
+If base federation fails, contracts are not attempted.
+
+Main implementation:
+
+- `composition/src/v1/federation/federation-factory.ts`
+
+## 10. Debugging workflow for beginners
+
+When composition fails:
+
+1. Start at API entry:
+
+- `composition/src/federation/federation.ts`
+
+2. Reproduce with minimal SDL in tests:
+
+- `composition/tests/v1/directives/*`
+
+3. Inspect normalization output first:
+
+- `directiveDefinitionByName`
+- `parentDefinitionDataByTypeName`
+- `configurationDataByTypeName`
+
+4. Inspect federation state second:
+
+- `parentDefinitionDataByTypeName`
+- `potentialPersistedDirectiveDefinitionDataByDirectiveName`
+- `referencedPersistedDirectiveNames`
+- `errors` / `warnings`
+
+5. If merge looks fine but final result fails, inspect resolvability:
+
+- `Graph.validate()` path in `composition/src/resolvability-graph/graph.ts`
+
+## 11. Recommended reading order (first week)
+
+1. `composition/src/federation/federation.ts`
+2. `composition/src/v1/federation/federation-factory.ts` (start from exported functions at the bottom, then move upward)
+3. `composition/src/v1/normalization/normalization-factory.ts`
+4. `composition/src/v1/normalization/walkers.ts`
+5. `composition/src/resolvability-graph/graph.ts`
+6. `composition/tests/v1/directives/*`
+
+## 12. Quick FAQ
+
+### Why do I get normalization errors before federation errors?
+
+Because federation only runs after batch normalization succeeds. Normalization is the gate.
+
+### Why did my custom directive disappear from federated output?
+
+Usually because the definition is incompatible across subgraphs (locations, args, repeatability, or presence).
+
+### Can I rely on `@composeDirective` behavior?
+
+Not yet. It is declared, but composition behavior for it is not implemented.

composition/ARCHITECTURE.md

@@ -5,6 +5,12 @@
 The WunderGraph composition library facilitates the federation of multiple subgraph schemas into a
 single federated GraphQL schema.
 
+## Architecture and onboarding
+
+For an implementation-level walkthrough of the composition pipeline and extension points (including shipping custom directives), see:
+
+- [ARCHITECTURE.md](./ARCHITECTURE.md)
+
 ### Prerequisites
 
 - [Node.js 16 LTS or higher](https://nodejs.dev/en/about/releases/)