GraphQL · OpenAPI · Postman · Apollo · Yoga · Worker — all from one .gg

x-gql

Project .gg topologies into GraphQL — without making GraphQL the authority.

x-gql turns a Gnosis .gg topology file into GraphQL SDL, a runtime GraphQLSchema, Apollo and GraphQL Yoga adapters, OpenAPI/Postman exports, Worker fetch handlers, and federation/runtime-IO query layers. GraphQL is a projection layer; the topology stays the source structure.

$ pnpm add @a0n/x-gql

Get started Browse the source

graphql 16 schema from .gg apollo yes yoga yes license MIT

Features

Everything you need. Nothing you don't own.

Topology-to-schema projection

GGL nodes become types, PROCESS edges become queries, FOLD becomes mutations, FORK becomes subscriptions, RACE becomes unions, and VENT becomes nullable/error surfaces. Schema design is downstream of topology, not the canonical model.

One source, every API artifact

GraphQL SDL, a runtime GraphQLSchema, an OpenAPI 3.1 document, and a Postman collection all come from the same .gg topology — so drift becomes easy to detect instead of silently diverging.

Apollo and Yoga transports

Real Apollo Server construction plus Express and Fastify adapter glue, and real GraphQL Yoga servers with fetch adapter, Node request listener, and HTTP server helpers — not stubs.

Mesh-gated Worker handler

createXGqlWorker() and wrapWithXGqlMesh() build a Web Fetch handler behind a compiled mesh-policy gate, routing /graphql and /health for Worker deployments.

Federation projection

buildFederationProjectionLayer() projects a signed knot-federation chain, N1 lookup, route proof, and snapshot records into GraphQL, with route/snapshot verification and fail-closed tests.

Runtime IO projection

buildRuntimeIoProjectionLayer() exposes mutate, query, subscribe, poll, gate, workflow, pause, handoff, resume, and resolve surfaces for DTN runtime and continuation lifecycle.

Quickstart

From .gg to GraphQL

import { createGqlServer } from '@a0n/x-gql';

const server = createGqlServer({
  topologies: ['./app.gg'],
  resolvers: { Query: { scanResult: async (_s, a) => ({ id: a.repo, status: 'complete' }) } },
});

const result = await server.executeOperation({
  query: 'query Scan($repo: String!) { scanResult(repo: $repo) { id status } }',
  variables: { repo: 'x-gql' },
});

import { createGqlServer } from '@a0n/x-gql';

const server = createGqlServer({ topologies: ['./app.gg'] });

const sdl = server.toGraphQLSDL();
const openapi = server.toOpenAPI();
const postman = server.toPostmanCollection();

import { createXGqlWorker } from '@a0n/x-gql/worker';

const worker = createXGqlWorker({
  gql: {
    source: '(Scan:Result { status: "String" }) (Request)-[:PROCESS { auth: "scan/read" }]->(Scan)',
    graphqlEndpoint: '/graphql',
  },
});

export default { fetch: worker };

# generate GraphQL SDL from .gg
gnode x-gql generate ./app.gg --out schema.graphql

# generate OpenAPI + Postman
gnode x-gql openapi ./app.gg --out openapi.json
gnode x-gql postman ./app.gg --out collection.json

# serve a playground
gnode x-gql serve ./app.gg --port 4000

FAQ

Common questions

No. GraphQL is a projection layer, not the authority. The .gg topology remains the source structure; x-gql gives conventional GraphQL clients a typed entry point while preserving fork/race/fold semantics, UCAN capability annotations, federation proofs, runtime continuation state, and mesh-policy gates that live below GraphQL.

Apollo Server (with Express and Fastify adapters) and GraphQL Yoga (with fetch adapter, Node request listener, and HTTP server helper), plus a mesh-gated Web Fetch handler for Worker runtimes. The README documents real server wrappers and transport-helper tests for each.

Nodes map to types, node properties to field arguments or input types, PROCESS edges to query resolvers, FOLD to mutations, FORK to subscription streams, RACE to union types, VENT to nullable fields or error surfaces, and Result/Option/Variant to unions, nullable fields, or enums.

Optional. x-gql supports tracing for direct fetch handlers and Apollo Express/Fastify adapters through @a0n/telemetry. Enable it with X_GQL_TRACING_ENABLED=true, or auto-enable via OTEL_EXPORTER_OTLP_ENDPOINT. Datadog agentless OTLP can be resolved from DD_API_KEY plus DATADOG_SITE or DD_SITE.

It surfaces UCAN and mesh policy, but host applications still own policy data, keys, and resolver behavior. The formal topology authority lives in Gnosis; x-gql projects it but does not replace it.