[oryan-block]

Why

Agents working in graphql-java-tools keep repeating the same mistakes, and the repo should change so a change that looks right from one file is right for the whole repo. Resolver return values are one of the worst spots for that. Three places walked the same declared type: TypeClassMatcher.PotentialMatch.unwrap for the class the schema build binds, GenericTypeResolver.resolve (called again from MethodFieldResolver for the value class) and ReturnValueUnwrapper for what the data fetcher unwraps. So a fix to how a return type is unwrapped had to land in more than one file. E.g. d60c8520 (a DataFetcherResult inside an Optional) had to change both TypeClassMatcher and ReturnValueUnwrapper.

Checklist

• Pull requests follows the contribution guide
• New or modified functionality is covered by tests

Description

New resolver/TypeShape.kt walks a return or parameter type against its GraphQL type once and keeps both results: the leaf TypeClassMatcher binds and the layers TypeShape.Unwrapper unwraps a method's value through. GenericTypeResolver.kt, resolver/ReturnValueUnwrapper.kt and PotentialMatch / Unwrapping / Unwrapped are gone.

• DataFetcherResult and Optional are one private enum the walk iterates. Each entry has an abstract placement rule and value step, so a new container doesn't compile without both
• a new entry also fails ReturnValueUnwrappingTest with a MODEL ERROR until the bounded check has a Container for it. Before, an entry with a stubbed step passed every test, since Check.java keeps its own container list
• both generic wrapper rules live in one class, side by side: exact declared type at schema build, most specific instance at fetch. They differ on purpose and stay that way
• the subscription Publisher view is taken inside TypeShape, next to the rule that leaves a subscription's events alone
• the value class (what a top-level Future is checked against) comes from the same walk instead of a second resolve. It's still only computed for methods, since an untyped Map's value type is a Classmate ResolvedType that TypeUtils.getRawType throws on
• resolveTypeVariables stays a separate top-level function, since argument conversion needs wrappers, wildcards and primitives kept. The raw class and assignability helpers became plain TypeUtils calls in the three files that used them
• scanForMatches returns a lazy Sequence, so each shape is still walked only when the scanner gets to it, like PotentialMatch.unwrapping was. Otherwise a schema with two errors could report a different one first
• property and Map fields match through TypeShape and still return their raw values. The next PR routes them through the unwrapper and deletes the known findings
• the verify-return-value-unwrapping skill named the deleted classes in its trigger, coverage table and sync command. It now points at TypeShape.kt, so a change there triggers it and shows up in its staleness check
• the AGENTS.md rule table names TypeShape for "a resolver method's return value is unwrapped by one rule"
• merged agent-friendly after Merge each SDL type with its extensions once #951: TypeClassMatcher now takes MergedDefinitions and matches the TypeShape leaf against MergedDefinitions.resolve. TypeShape never reads SDL definitions, so DefinitionsBoundaryTest passes over it unchanged

Two spots still work out type facts on their own and are left for the resolver plan PR: subscription Publisher detection in FieldResolverScanner.kt (resolverMethodReturnsPublisher) and the argument type checks in MethodFieldResolver.kt (the Optional check and isConcreteScalarType).

No release note, nothing changes for library users.

Testing:

• mise exec java@temurin-17.0.21+9 -- mvn -B -ntp clean verify passes at this head, 480 tests (this PR adds no test methods, the 10 new ones are DefinitionsBoundaryTest and TypeKindRecipeTest from Merge each SDL type with its extensions once #951), and japicmp prints No changes. against 15.0.0
• mvn -B -ntp clean verify on JDK 25 passes at this head too
• the bounded check prints the same five known findings with the same counts (448, 896, 234, 1,254, 18), and the same 5,655 accepted and 1,365 rejected return types and 226,277 executions as on agent-friendly (run on both). check.sh --rejected lists the same rejected return types with the same build errors on both
• ResolverCompatibilityTest, CompatTest, DefinitionsBoundaryTest and TypeKindRecipeTest pass unchanged. NestedGenericWrapperTest and TypeClassMatcherTest only swap PotentialMatch for TypeShape
• the verify-tools probe gives the same schema, results, warnings and errors at agent-friendly and this head for all 40 scenarios. Only stack frames differ, e.g. optional-results-nested's build error is now thrown from TypeShape instead of TypeClassMatcher$PotentialMatch, with the same text word for word
• a scratch ContainerKind entry with a placement rule but no step doesn't compile (Enum entry 'ContainerKind.SCRATCH' does not implement abstract member). One with a stubbed step fails ReturnValueUnwrappingTest in under a second with MODEL ERROR: TypeShape.kt has a ContainerKind for these classes, but no Container in Check.java builds them and its class, and check.sh exits 2
• rg -n "fun resolve\(" src/main prints SourceResolver.resolve in FieldResolver.kt and MergedDefinitions.resolve, which looks a type definition up by name. Both are unrelated (the plan expected nothing outside TypeShape.kt)
• the first version computed the value class for every return type and ResolverCompatibilityTest caught it: untyped Map fields stopped building (unknown type: java.lang.Object), the build rejected 85 more return types and three known findings went STALE

[sonarqubecloud]

Quality Gate passed

Issues
2 New issues
0 Accepted issues

Measures
0 Security Hotspots
0.0% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud