Skip to content

Add opt-in NormalizedDocument and remove executable normalization - #4562

Draft
andimarek wants to merge 3 commits into
masterfrom
codex/normalized-document
Draft

andimarek wants to merge 3 commits into
masterfrom
codex/normalized-document

Conversation

@andimarek

@andimarek andimarek commented Nov 14, 2026 •

Copy link
Copy Markdown
Member

Build an immutable NormalizedDocument during validation when explicitly enabled. It stores all operations, shared fragment references, source fields, symbolic conditions and type guards. Lookahead collects fields for the current execution and resolves arguments when requested.

Creation is off by default. There is no lazy construction fallback. The preparsed entry retains the graph, including through serialization and execution-context copies.

Breaking changes and migration

  • Lookahead inspection now throws when creation is disabled or a preparsed cache has discarded the graph. Set NormalizedDocument.ENABLED to true in ExecutionInput's GraphQLContext before validation. Retain complete preparsed entries and invalidate/repopulate existing AST-only caches; cache keys must distinguish schema/version and creation options.
  • Remove ExecutableNormalizedField, ExecutableNormalizedOperation, ExecutableNormalizedOperationFactory, the old graphql.normalized.nf APIs, and NormalizedDeferredExecution. Use ParseAndValidateResult.getNormalizedDocument() / ExecutionContext.getNormalizedDocument() for the validated graph and selection sets for lookahead. Remove calls to getNormalizedQueryTree() and overrides of ExecutionStrategy.getNormalizedField().
  • Remove ExecutableNormalizedOperationToAstCompiler and VariablePredicate without replacement.
  • Lookahead entries represent one concrete parent type and response key. Ordering, conditional flags and parent references follow this view rather than a recursively merged operation tree.
  • Lookahead enumeration now throws IllegalStateException when it exceeds QueryComplexityLimits.maxFieldOccurrences (default 100,000). Request settings override JVM defaults. Raise this threshold when needed, or use QueryComplexityLimits.NONE to disable the bound.

Examples for a Pet interface implemented by Cat and Dog:

  • pet { name }: returns Cat.name and Dog.name, instead of one [Cat, Dog].name entry.
  • pet { ... on Cat { label: name } ... on Dog { label: nickname } }: two entries share result key label, with different field definitions.
  • pet { ... on Cat { child { name } child { lives } } }: one Cat.child entry combines the two child contributions; its children are collected when inspected.

The migration guide includes cache examples and details of paths, ordering, arguments, parents and conditional flags.

Bounded lookahead

The occurrence threshold separately bounds concrete field paths during lookahead. With Node implemented by A and B, both exposing next: Node and value: String, { node { next { next { value } } } } has 4 validation occurrences but 14 lookahead entries below node (2 + 4 + 8). A limit of 13 accepts validation and rejects full lookahead.

Immediate inspection counts only immediate entries. Full inspection, glob matching and result-key grouping count all descendant entries, including non-matches. Active duplicate selections merge per concrete parent type and response key. Cached child lists still count; exceeding the limit throws without returning a truncated result.

Validation

Tests cover exact enumeration boundaries, nested interfaces with exponentially many potential paths, wide child batches, cached retries, concurrent reads, request overrides and disabling the bound. They also cover conditional fragments, aliases, concrete types and defaults, concurrent cache reuse, serialization, multiple operations, disabled lookahead, a 1,501-fragment chain on a 1 MiB stack, and shared diamond fragments. The large fixture stores 5,687 fields without execution variables; its existing validation limits remain unchanged. Independent input-value and AST tests replace coverage previously supplied by the removed normalization suites. The coverage baseline changes only for ten unchanged utility classes whose incidental coverage came from those deleted suites (debug strings, builder helpers, collection helpers and traversal callbacks).

Local validation: the full Java 25 main suite (5,864 tests) and reactive-streams suite (190 tests) passed with only expected skips. Build checks, Javadoc and the per-class coverage gate passed, with no additional baseline changes. CI passed for Java 17, 21 and 25, including the per-class coverage gate, build checks, concurrency stress tests and Javadoc.

…cument

# Conflicts:
#	src/main/java/graphql/execution/directives/QueryDirectives.java
#	src/test/groovy/graphql/execution/directives/QueryDirectivesIntegrationTest.groovy
@github-actions

github-actions Bot commented Nov 14, 2026 •

Copy link
Copy Markdown
Contributor

Test Report

Test Results

Java Version Total Passed Failed Errors Skipped
Java 17 6054 (-315 🔴) 5999 (-315 🔴) 0 (±0) 0 (±0) 55 (±0)
Java 21 6054 (-315 🔴) 5999 (-315 🔴) 0 (±0) 0 (±0) 55 (±0)
Java 25 6054 (-315 🔴) 5999 (-315 🔴) 0 (±0) 0 (±0) 55 (±0)
jcstress 32 (±0) 32 (±0) 0 (±0) 0 (±0) 0 (±0)
Total 18194 (-945 🔴) 18029 (-945 🔴) 0 (±0) 0 (±0) 165 (±0)

Code Coverage (Java 25)

Metric Covered Missed Coverage vs Master
Lines 25584 2450 91.3% +0.4% 🟢
Branches 7249 1024 87.6% +0.8% 🟢
Methods 7207 1006 87.8% +0.6% 🟢

Changed Class Coverage (78 classes)

Class Line Branch Method
g.c.ImmutableKit -10.8% 🔴 -7.7% 🔴 -6.7% 🔴
g.e.c.ConditionalNodes +1.5% 🟢 +6.8% 🟢 +10.0% 🟢
g.e.Execution +0.1% 🟢 ±0.0% ±0.0%
g.e.ValuesResolver +1.5% 🟢 +3.8% 🟢 +6.3% 🟢
g.e.ValuesResolverConversion +2.2% 🟢 +2.9% 🟢 +3.7% 🟢
g.l.Field +1.6% 🟢 ±0.0% +3.8% 🟢
g.l.FloatValue +4.0% 🟢 ±0.0% ±0.0%
g.l.FragmentDefinition +2.1% 🟢 ±0.0% +5.6% 🟢
g.l.InlineFragment +2.1% 🟢 ±0.0% +5.3% 🟢
g.l.InlineFragment
$Builder
-11.8% 🔴 ±0.0% -16.7% 🔴
g.l.ListType -4.0% 🔴 ±0.0% -7.1% 🔴
g.l.NonNullType -4.0% 🔴 ±0.0% -7.1% 🔴
g.l.NullValue +5.3% 🟢 ±0.0% ±0.0%
g.n.ArgumentMaker removed removed removed
g.n.ENFMerger removed removed removed
g.n.ExecutableNormalizedField removed removed removed
g.n.ExecutableNormalizedField
$Builder
removed removed removed
g.n.ExecutableNormalizedOperation removed removed removed
g.n.ExecutableNormalizedOperationFactory removed removed removed
g.n.ExecutableNormalizedOperationFactory
$ExecutableNormalizedOperationFactoryImpl
removed removed removed
g.n.ExecutableNormalizedOperationFactory
$ExecutableNormalizedOperationFactoryImpl
$CollectedField
removed removed removed
g.n.ExecutableNormalizedOperationFactory
$ExecutableNormalizedOperationFactoryImpl
$CollectedFieldGroup
removed removed removed
g.n.ExecutableNormalizedOperationFactory
$ExecutableNormalizedOperationFactoryImpl
$PossibleMerger
removed removed removed
g.n.ExecutableNormalizedOperationFactory
$Options
removed removed removed
g.n.ExecutableNormalizedOperationToAstCompiler removed removed removed
g.n.ExecutableNormalizedOperationToAstCompiler
$CompilerResult
removed removed removed
g.n.ExecutableNormalizedOperationToAstCompiler
$ExecutionFragmentDetails
removed removed removed
g.n.i.NormalizedDeferredExecution removed removed removed
g.n.n.NormalizedDocument removed removed removed
g.n.n.NormalizedDocument
$NormalizedOperationWithAssumedSkipIncludeVariables
removed removed removed
g.n.n.NormalizedDocumentFactory removed removed removed
g.n.n.NormalizedDocumentFactory
$NormalizedDocumentFactoryImpl
removed removed removed
g.n.n.NormalizedDocumentFactory
$NormalizedDocumentFactoryImpl
$CollectedField
removed removed removed
g.n.n.NormalizedDocumentFactory
$NormalizedDocumentFactoryImpl
$CollectedFieldGroup
removed removed removed
g.n.n.NormalizedDocumentFactory
$NormalizedDocumentFactoryImpl
$PossibleMerger
removed removed removed
g.n.n.NormalizedDocumentFactory
$Options
removed removed removed
g.n.n.NormalizedField removed removed removed
g.n.n.NormalizedField
$Builder
removed removed removed
g.n.n.NormalizedFieldsMerger removed removed removed
g.n.n.NormalizedOperation removed removed removed
g.n.n.NormalizedOperationToAstCompiler removed removed removed
g.n.n.NormalizedOperationToAstCompiler
$CompilerResult
removed removed removed
g.n.NormalizedDocument +61.1% 🟢 ±0.0% +85.7% 🟢
g.n.NormalizedDocument
$Builder
+100.0% 🟢 ±0.0% +100.0% 🟢
g.n.NormalizedField +60.0% 🟢 ±0.0% +83.3% 🟢
g.n.NormalizedField
$Builder
+100.0% 🟢 ±0.0% +100.0% 🟢
g.n.NormalizedFieldCollector +98.0% 🟢 +93.3% 🟢 +90.0% 🟢
g.n.NormalizedInputValue -3.3% 🔴 ±0.0% -7.7% 🔴
g.n.NormalizedOperation +50.0% 🟢 ±0.0% +60.0% 🟢
g.n.NormalizedOperation
$Builder
+100.0% 🟢 ±0.0% +100.0% 🟢
g.n.NormalizedSelectionScope +61.1% 🟢 ±0.0% +85.7% 🟢
g.n.NormalizedSelectionScope
$Builder
+100.0% 🟢 ±0.0% +100.0% 🟢
g.n.NormalizedSelectionSet +55.6% 🟢 ±0.0% +75.0% 🟢
g.n.NormalizedSelectionSet
$Builder
+100.0% 🟢 ±0.0% +100.0% 🟢
g.n.ValueToVariableValueCompiler removed removed removed
g.n.VariableAccumulator removed removed removed
g.n.VariablePredicate removed removed removed
g.n.VariableValueWithDefinition removed removed removed
g.ParseAndValidate +0.4% 🟢 ±0.0% ±0.0%
g.ParseAndValidateResult +0.3% 🟢 ±0.0% ±0.0%
g.s.GraphqlIDCoercing +2.5% 🟢 ±0.0% +7.1% 🟢
g.s.DataFetchingFieldSelectionSetImpl +7.0% 🟢 +8.4% 🟢 +4.3% 🟢
g.s.DataFetchingFieldSelectionSetImpl
$1
removed removed removed
g.s.DataFetchingFieldSelectionSetImpl
$SelectedFieldImpl
removed removed removed
g.s.GraphQLEnumType +3.5% 🟢 +4.2% 🟢 +2.7% 🟢
g.s.i.TypeUtil +5.3% 🟢 +12.5% 🟢 +14.3% 🟢
g.s.LookaheadFieldBudget +100.0% 🟢 +100.0% 🟢 +100.0% 🟢
g.s.SelectedFieldImpl +93.9% 🟢 +100.0% 🟢 +90.9% 🟢
g.s.UnavailableFieldSelectionSet +100.0% 🟢 ±0.0% +100.0% 🟢
g.u.FpKit -5.5% 🔴 -8.1% 🔴 -2.7% 🔴
g.u.LinkedHashMapFactory -1.2% 🔴 ±0.0% -8.3% 🔴
g.u.TraverserVisitor -100.0% 🔴 ±0.0% -100.0% 🔴
g.u.TraverserVisitorStub -66.7% 🔴 ±0.0% -66.7% 🔴
g.u.TreeTransformer
$1
-16.7% 🔴 ±0.0% -25.0% 🔴
g.v.DocumentValidationResult +100.0% 🟢 ±0.0% +100.0% 🟢
g.v.NormalizedDocumentBuilder +100.0% 🟢 +100.0% 🟢 +100.0% 🟢
g.v.OperationValidator ±0.0% +0.4% 🟢 ±0.0%
g.v.Validator ±0.0% +100.0% 🟢 ±0.0%
ImmutableKit — method details
Method Line Branch
mapToSet 0.0% (-100.0% 🔴) 0.0% (-100.0% 🔴)
InlineFragment.Builder — method details
Method Line Branch
comments 0.0% (-100.0% 🔴) —
directive 0.0% (-100.0% 🔴) —
ListType — method details
Method Line Branch
toString 0.0% (-100.0% 🔴) —
NonNullType — method details
Method Line Branch
toString 0.0% (-100.0% 🔴) —
NormalizedInputValue — method details
Method Line Branch
toString 0.0% (-100.0% 🔴) —
FpKit — method details
Method Line Branch
filterSet 0.0% (-100.0% 🔴) 0.0% (-100.0% 🔴)
intersection 100.0% 80.0% (-20.0% 🔴)
LinkedHashMapFactory — method details
Method Line Branch
of 0.0% (-100.0% 🔴) —
TraverserVisitor — method details
Method Line Branch
backRef 0.0% (-100.0% 🔴) —
TraverserVisitorStub — method details
Method Line Branch
<init> 0.0% (-100.0% 🔴) —
leave 0.0% (-100.0% 🔴) —
TreeTransformer.1 — method details
Method Line Branch
backRef 0.0% (-100.0% 🔴) —

Full HTML report: build artifact jacoco-html-report

Updated: 2026-11-15 00:08:57 UTC

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant