Emit polymorphic payloads as unions of sealed arms

[ruudk]

Summary

Replace blended array{name: string, 'login'?: string, 'url'?: string, ...} payload shapes for polymorphic GraphQL selections with array{__typename: 'User', name: string, login: string} | array{__typename: 'Application', name: string, url: string} — a union of sealed arms, one per concrete type, discriminated by __typename.

Before

/**
 * @param array{
 *     '__typename': string,
 *     'login'?: string,
 *     'name': string,
 *     'url'?: string,
 *     ...,
 * } $data
 */

After

/**
 * @param array{
 *     '__typename': 'Application',
 *     'name': string,
 *     'url': string,
 * }|array{
 *     '__typename': 'User',
 *     'login': string,
 *     'name': string,
 * } $data
 */

Variant getters lose their array_key_exists guards — PHPStan narrows on __typename literal alone, so the variant subclass's required fields are provably present.

How the planner produces the union

• Concrete-type fragments (... on User { login }) add a variant arm keyed by the concrete type name.
• Abstract-type fragments (... on Person { firstName, lastName } where Person is an interface) distribute their fields to every concrete implementor. Abstract type names never appear as arms — __typename only holds a concrete object type at runtime.
• Schema enumeration — even when only one fragment is written, every concrete type in the parent's union/interface is emitted as an arm (empty body for the unwritten ones). This stops __typename === 'X' from becoming always-true on single-fragment queries against multi-member abstract types.
• Nested variants — ... on Employee { role } inside ... on Person contributes role to the Developer / Manager arms (both implement Employee) but not to RegularUser. PayloadShape::addVariant() collapses matching nested variants into the destination so this resolves correctly.
• Conditional fragments (@include / @skip) demote their contributed variant fields to optional via withFieldsOptional().

Trade-off you signed off on

No explicit "fallback arm" with a wide __typename: string. If the server returns a concrete __typename the client didn't write a fragment for and you didn't include that type in the schema, the type system says "impossible" — but runtime stays safe because the variant getters still return null on mismatched __typename. For closed union schema members this is exact; for open interface implementors it's a small fiction.

Test plan

• All 179 unit tests pass.
• PHPStan max passes (no errors).
• All 39 generated fixtures (tests/*/Generated/, examples/Generated/) regenerated and round-trip via --ensure-sync.
• tests/Planner/PayloadShapeBuilderTest.php expectations updated for the 8 polymorphic-selection tests.
• Hand-checked InlineFragments, InlineFragmentTypename, QueryObjectTypename, HooksInUnionVariant, Optimization, ExplicitTypename, Fragments generated outputs.

https://claude.ai/code/session_01WwMs8ZS9JBdXD6ZzwREpzF

---

Generated by Claude Code