x-gql

Parent: Open-Source Ecosystem

@a0n/x-gql projects Gnosis .gg topologies into GraphQL execution surfaces. It turns a 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.

The important boundary is that 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 into that topology while preserving the fork/race/fold semantics, UCAN capability annotations, federation proofs, runtime continuation state, and mesh-policy gates that live below GraphQL.

Stack context: Gnosis, x-gnosis, and x-gql. Source map: src/README.md.

Why It Matters

GraphQL normally starts from application schema design. In this stack, schema design is downstream of topology. A .gg file already encodes process edges, folds, races, forks, vents, options, variants, and authorization metadata. x-gql projects those objects into the GraphQL tools that teams already know without making GraphQL the canonical model.

That changes the failure mode. If the SDL, OpenAPI document, Postman collection, Apollo server, Yoga server, Worker handler, and federation queries all come from the same topology source, drift becomes easier to detect. The question changes from "did someone update every API artifact?" to "does this projection still preserve the topology contract?"

Projection Ledgers

Domain Map

GGL To GraphQL Mapping

Public API

Proof And Runtime Boundaries

Examples

Generate And Execute From Topology

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

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

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

console.log(server.toGraphQLSDL());
console.log(result.data);

Export SDL, OpenAPI, And Postman

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

const server = createGqlServer({
  topologies: ['./app.gg'],
  name: 'Topology API',
  baseUrl: 'https://api.example.test',
});

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

console.log(sdl);
console.log(openapi);
console.log(postman);

Apollo And Yoga Transports

import express from 'express';
import Fastify from 'fastify';
import { createServer } from 'node:http';
import {
  createApolloExpressMiddleware,
  createApolloFastifyPlugin,
  createApolloServer,
  createYogaHttpServer,
  createYogaNodeRequestListener,
  createYogaServer,
} from '@a0n/x-gql';

const apollo = createApolloServer({ topologies: ['./app.gg'] });
const yoga = createYogaServer(
  { topologies: ['./app.gg'], graphqlEndpoint: '/graphql' },
  { landingPage: false }
);

const expressApp = express();
expressApp.use(express.json());
expressApp.use('/graphql', await createApolloExpressMiddleware(apollo));

const fastifyApp = Fastify();
await fastifyApp.register(
  createApolloFastifyPlugin(apollo, { path: '/graphql' })
);

const yogaHttpServer = createYogaHttpServer(yoga);
const yogaListenerServer = createServer(createYogaNodeRequestListener(yoga));

console.log(Boolean(yogaHttpServer));
console.log(Boolean(yogaListenerServer));

Worker Fetch Handler

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 };

Federation Projection

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

const federation = buildFederationProjectionLayer({
  federationChain: async (id) => lookupChainRecord(id),
  federationLookup: async (from, to) => lookupRoute(from, to),
  federationSnapshot: async () => currentSignedSnapshot(),
  issuerPublicKeys,
});

const server = createGqlServer({
  schema: federation.schema,
  resolvers: federation.resolvers,
});

const result = await server.executeOperation({
  query: '{ federationSnapshot { epoch digest recordCount } }',
});

console.log(result.data);

Optional Tracing

x-gql supports optional tracing for direct fetch handlers and Apollo Express/Fastify adapters through @a0n/telemetry.

• Enable explicitly with X_GQL_TRACING_ENABLED=true.
• Or auto-enable by setting OTEL_EXPORTER_OTLP_ENDPOINT or OTEL_EXPORTER_OTLP_TRACES_ENDPOINT.
• Datadog agentless OTLP can be resolved from DD_API_KEY plus DATADOG_SITE or DD_SITE.
• Debug spans can be printed with DEBUG_TELEMETRY=true.

CLI

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

# Generate OpenAPI spec
gnode x-gql openapi ./app.gg --out openapi.json

# Generate Postman collection
gnode x-gql postman ./app.gg --out collection.json

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

Architecture

.gg topology --> Betty compiler --> Graph AST --> x-gql projection
                                                   |-- GraphQL SDL
                                                   |-- GraphQLSchema
                                                   |-- OpenAPI 3.1
                                                   |-- Postman collection
                                                   |-- Apollo Server
                                                   |-- Apollo Express/Fastify
                                                   |-- GraphQL Yoga
                                                   |-- Node http helpers
                                                   |-- Worker fetch handler
                                                   |-- federation projection
                                                   |-- runtime IO projection

Development

Source files live in src. Focused test coverage lives in src/tests.

Use the repository-owned a0 target from the monorepo root:

pnpm run a0 -- run @a0n/x-gql:test
pnpm run a0 -- run @a0n/x-gql:typecheck
pnpm run a0 -- run @a0n/x-gql:lint

For README-only changes, validate local Markdown links and keep the parent and child README links intact.