compilers/graphql: revive the GraphQL SDL and Federation compiler from #20 against the current contract

[fuad-daoud]

What exists

A complete GraphQL SDL compiler, covering plain schemas and Apollo Federation v1/v2 subgraphs, was drafted in #20 (branch feat/graphql-compiler, head d05f37f, +9,090 lines across 58 files). It parses at the SDL level through github.com/vektah/gqlparser/v2 so extend occurrences and federation directives arrive as written, and lowers: objects and interfaces to Model (with Implements), input objects to InputOnly models and @oneOf inputs to key-tagged exclusive unions, union types to __typename-tagged unions with an internal discriminator, enums, custom scalars (with @specifiedBy), ID as a distinct named scalar, field arguments onto Property.Args, every [T!]! layering onto Required + Nullable per layer, root types onto one service with query/mutation/subscription groups and a GraphQLBinding per field, and directive applications preserved in order under the graphql: namespace. Conformance corpus under testdata/conformance/graphql, goldens under testdata/golden/graphql. The PR body is the design record; read it before starting over.

It was opened 2026-07-21, last pushed 2026-07-23, and has not been reviewed. README milestone 5 places the GraphQL compiler after AsyncAPI, so this is the tracking issue for that row, not a request to land the draft now. The Protobuf counterpart is #469.

Why the draft cannot land as it stands

Measured against main at e1e92a0 (161 commits ahead of the draft's base):

• Contract. compilers.Compiler now requires Formats, Detect and Compile (compilers/compilers.go, added by feat(engine)!: let compilers own format detection and options #341). The draft implements Formats and Compile only, so it does not build.
• IR version. Every golden the draft ships writes "irVersion": "0.1.0"; main is at 0.4.0 after three breaking revisions (feat(ir)!: add Payload.Required and Parameter.Provenance #437–feat(ir)!: bump IRVersion to 0.4.0 for the stack's shape changes #442, feat(ir)!: land the IR 0.4.0 stack #464). The lowering targets struct shapes that no longer exist — ErrorCase is a response, exclusive bounds are carried separately, Payload.Required and Parameter.Provenance exist, and so on.
• Package layout. The draft predates the micro-compiler restructure (docs/micro-compiler-design.md) and is one flat package with its own ids.go and diag.go. internal/archtest's rules map, the 20-method cap on compiler types, and the per-package allowlists all postdate it; the arch_test.go conflict is that map having been rewritten underneath it.
• Shared grammar. canonicalWords and the identifier grammar were extracted into compilers/compile by compilers/compile: own the identifier grammar shared by every compiler #162/compilers/compile: own the canonical naming grammar #163/refactor: move the naming and ID grammars into the framework #183 because this draft's copy was byte-identical to the OpenAPI one and Protobuf's had diverged (compilers: canonical naming grammar diverges across the three compilers #161). The draft still carries its own.
• go.sum conflicts, and the last gate run on the branch (2026-07-21) failed at the gofmt step before reaching anything else.

What reviving it needs

1. Rebase is not the shape of the work — start a fresh branch from main and port the lowering, using the draft as the reference for the SDL→IR mapping decisions, in particular the nullability layering and the two union shapes.
2. Implement Detect (an SDL source is recognisable from a top-level type/schema/extend/directive keyword; bounded sniff, same discipline as compilers/openapi/detect.go).
3. Lay it out as compilers/graphql + compilers/graphql/internal/*, each internal package with its own archtest rules entry; use compilers/compile for naming and IDs rather than a local grammar.
4. Regenerate the goldens at the current IRVersion and re-derive the conformance matrix witnesses (docs/ir-spec-matrix.md row keys) for the rows GraphQL can express.
5. Run the full oracle sweep: go run ./cmd/morphic-harness testdata/conformance/graphql.

Decision needed

Whether #20 stays open as a draft or is closed with this issue as its pointer. Either way the branch should not be deleted — the design work in it is the asset.

Refs #20.